Add devtools

This commits adds only basic functionality:

* pausing/resuming the game by hitting F12
* screen inspector: showing the cursor coordinates and pixel color

Author: elgopher

README.md

@@ -10,7 +10,7 @@ The retro game development engine for Go, inspired by [Pico-8](https://www.lexal
 
 ### Is this a new fantasy console?
 
-No, it's not. It's rather a game development library with some additional tools (like a console) which make it simple (and fun!) to write retro games in Go.
+No, it's not. It's rather a game development library with dev-tools which make it simple (and fun!) to write retro games in Go.
 
 ### What is a retro game?
 

devtools/control.go

@@ -0,0 +1,25 @@
+// (c) 2022 Jacek Olszak
+// This code is licensed under MIT license (see LICENSE for details)
+
+package devtools
+
+import (
+	"github.com/elgopher/pi/devtools/internal/snapshot"
+	"github.com/elgopher/pi/vm"
+)
+
+var (
+	paused         bool
+	timeWhenPaused float64
+)
+
+func pauseGame() {
+	paused = true
+	timeWhenPaused = vm.TimeSeconds
+	snapshot.Take()
+}
+
+func resumeGame() {
+	paused = false
+	vm.TimeSeconds = timeWhenPaused
+}

devtools/devtools.go

@@ -0,0 +1,52 @@
+// (c) 2022 Jacek Olszak
+// This code is licensed under MIT license (see LICENSE for details)
+
+package devtools
+
+import (
+	"github.com/elgopher/pi"
+	"github.com/elgopher/pi/vm"
+)
+
+var (
+	// BgColor is used to draw background behind the text
+	BgColor byte = 1
+	// FgColor is used to print text, draw icons etc.
+	FgColor byte = 7
+)
+
+// MustRun runs the game using backend, similarly to pi.MustRun.
+//
+// Any time you can pause them game by pressing F12. This will
+// show screen inspector. F12 again resumes the game.
+func MustRun(runBackend func() error) {
+	update := pi.Update
+	draw := pi.Draw
+
+	pi.Update = func() {
+		updateDevTools()
+
+		if !paused && update != nil {
+			update()
+			handleStoppedGame()
+		}
+	}
+
+	pi.Draw = func() {
+		if !paused && draw != nil {
+			draw()
+			handleStoppedGame()
+		} else {
+			drawDevTools()
+		}
+	}
+
+	pi.MustRun(runBackend)
+}
+
+func handleStoppedGame() {
+	if vm.GameLoopStopped {
+		pauseGame()
+		vm.GameLoopStopped = false
+	}
+}

devtools/draw.go

@@ -0,0 +1,48 @@
+// (c) 2022 Jacek Olszak
+// This code is licensed under MIT license (see LICENSE for details)
+
+package devtools
+
+import (
+	"fmt"
+
+	"github.com/elgopher/pi"
+	"github.com/elgopher/pi/devtools/internal/icons"
+	"github.com/elgopher/pi/devtools/internal/snapshot"
+	"github.com/elgopher/pi/vm"
+)
+
+func drawDevTools() {
+	snapshot.Draw()
+	drawBar()
+	drawPointer()
+}
+
+func drawBar() {
+	mouseX, mouseY := pi.MousePos()
+	barY := vm.ScreenHeight - 7
+	if mouseY > vm.ScreenHeight/2 {
+		barY = 0
+	}
+
+	pi.RectFill(0, barY, vm.ScreenWidth, barY+6, BgColor)
+
+	mostX := printCoords(mouseX, mouseY, 1, barY+1)
+	color := pi.Pget(mouseX, mouseY)
+	printPixelColor(color, mostX+4, barY+1)
+}
+
+func printCoords(mouseX int, mouseY int, x, y int) int {
+	coords := fmt.Sprintf("%d %d", mouseX, mouseY)
+	return pi.Print(coords, x, y, FgColor)
+}
+
+func printPixelColor(color byte, x int, y int) int {
+	c := fmt.Sprintf("%d", color)
+	return pi.Print(c, x, y, color)
+}
+
+func drawPointer() {
+	x, y := pi.MousePos()
+	icons.Draw(icons.Pointer, x, y, FgColor)
+}

devtools/internal/icons/icons.go

@@ -0,0 +1,35 @@
+// (c) 2022 Jacek Olszak
+// This code is licensed under MIT license (see LICENSE for details)
+
+package icons
+
+import (
+	_ "embed"
+	"fmt"
+
+	"github.com/elgopher/pi"
+	"github.com/elgopher/pi/font"
+)
+
+const (
+	Pointer = "\u0000"
+)
+
+//go:embed icons.png
+var iconsPng []byte
+
+var icons = pi.Font{
+	Width:        4,
+	WidthSpecial: 8,
+	Height:       8,
+}
+
+func init() {
+	if err := font.Load(iconsPng, icons.Data[:]); err != nil {
+		panic(fmt.Sprintf("problem loading devtools icons %s", err))
+	}
+}
+
+func Draw(icon string, x, y int, color byte) {
+	icons.Print(icon, x, y, color)
+}

devtools/internal/icons/icons.png

@@ -0,0 +1,21 @@
+// (c) 2022 Jacek Olszak
+// This code is licensed under MIT license (see LICENSE for details)
+
+package snapshot
+
+import (
+	"github.com/elgopher/pi/vm"
+)
+
+var snapshot []byte
+
+func Take() {
+	if snapshot == nil {
+		snapshot = make([]byte, len(vm.ScreenData))
+	}
+	copy(snapshot, vm.ScreenData)
+}
+
+func Draw() {
+	copy(vm.ScreenData, snapshot)
+}

devtools/internal/snapshot/snapshot.go

@@ -0,0 +1,16 @@
+// (c) 2022 Jacek Olszak
+// This code is licensed under MIT license (see LICENSE for details)
+
+package devtools
+
+import "github.com/elgopher/pi/key"
+
+func updateDevTools() {
+	if key.Btnp(key.F12) {
+		if !paused {
+			pauseGame()
+		} else {
+			resumeGame()
+		}
+	}
+}

devtools/update.go

@@ -30,12 +30,18 @@
 * [ ] Menu screen
   * [ ] controller mapping editor
   * [ ] keyboard mapping editor 
-* [ ] Development console
-    * [ ] stopping, resuming the game
+* [ ] Development tools
+    * [x] controlling the game
+        * [x] pausing, resuming
         * [x] add a programmatic way to stop the game
-        * [ ] resume the game using console command
-    * [ ] scripting (running π functions)
-    * [ ] screen inspector
+    * [ ] taking screenshots
+    * [x] screen inspector
+      * [x] presenting pixel coords and color
+      * [ ] zoom-in, zoom-out
+      * [ ] drawing on the screen using Pi functions such as Pset, shapes, Spr etc.
+        * [ ] storing function calls in the clipboard and history file 
+    * [ ] palette inspector
+      * [ ] display, draw palette
     * [ ] sprite-sheet editor
     * [ ] map editor
     * [ ] sound editor

docs/ROADMAP.md

@@ -4,26 +4,35 @@ package main
 import (
 	"embed"
 
-	"github.com/elgopher/pi"
-	"github.com/elgopher/pi/ebitengine"
+	"github.com/elgopher/pi"            // core package used to draw, print and control the input
+	"github.com/elgopher/pi/devtools"   // tools used only during development
+	"github.com/elgopher/pi/ebitengine" // engine capable of rendering the game on multiple operating systems
 )
 
+// Tell Go compiler to embed sprite-sheet file inside binary:
+//
 //go:embed sprite-sheet.png
 var resources embed.FS
 
 func main() {
+	// Tell Pi to use resources embedded inside binary:
 	pi.Resources = resources
+	// Pi runs the game in a loop. 30 times per second, Pi
+	// asks the game to draw a frame. This callback function
+	// can be set by following code:
 	pi.Draw = func() {
+		// Clear entire screen each frame with color 0 (black):
 		pi.Cls()
 		// Draw "HELLO WORLD". Each letter is a different sprite.
 		// Sprite 0 is H, 1 is E, 2 is L etc.
 		for i := 0; i < 12; i++ {
-			// calculate the position of letter on screen:
+			// Calculate the position of letter on screen:
 			x := 20 + i*8
 			y := pi.Cos(pi.Time()+float64(i)/64) * 60
-			// draw sprite:
+			// Draw sprite:
 			pi.Spr(i, x, 60+int(y))
 		}
 	}
-	pi.MustRun(ebitengine.Backend)
+	// Run game with devtools (Hit F12 to show screen inspector)
+	devtools.MustRun(ebitengine.Backend)
 }

examples/hello/main.go

@@ -49,7 +49,7 @@ var (
 	// ScreenHeight specifies the height of the screen (in pixels).
 	ScreenHeight = defaultScreenHeight
 
-	Resources fs.ReadFileFS // Resources contains files like sprite-sheet.png
+	Resources fs.ReadFileFS // Resources contains files like sprite-sheet.png, custom-font.png
 )
 
 var booted bool
@@ -184,9 +184,9 @@ func MustBoot() {
 	}
 }
 
-// Stop will stop the game loop after Update is finished, but before Draw.
-// For now the entire app will be closed, but later it will show a dev console instead,
-// where developer will be able to resume the game.
+// Stop will stop the game loop after Update or Draw is finished.
+// If you are using devtools, the game will be paused. Otherwise, the game
+// will be closed.
 func Stop() {
 	vm.GameLoopStopped = true
 }

pi.go

@@ -3,7 +3,7 @@
 
 // Package vm is low-level package for directly accessing virtual machine data,
 // such as screen pixels, sprite-sheet, fonts or buttons state.
-// This data can be manipulated by backend, console, utility functions, or
+// This data can be manipulated by backend, devtools, utility functions, or
 // a game itself. It is very useful for writing custom tools, new backends or
 // even entire new API to be used by games. Code using vm package directly
 // could be very fast, because it can use low-level Go functions such as copy.