Entity inspector (#21)

* add inspector drawer for entity inspection
* allow to toggle types, names, etc. using the keyboard
* add feature list to README, update screenshot, update dependencies

Author: mlange-42

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [[v0.2.0]](https://github.com/mlange-42/arche-pixel/compare/v0.1.0...v0.2.0)
+
+### Features
+
+* New drawer `Inspector` for inspecting entities (#21)
+
 ## [[v0.1.0]](https://github.com/mlange-42/arche-pixel/compare/v0.0.3...v0.1.0)
 
 ### Features

README.md

@@ -8,7 +8,20 @@
 
 *Arche Pixel* provides OpenGL graphics and live plots for the [Arche](https://github.com/mlange-42/arche) Entity Component System (ECS) using the [Pixel](https://github.com/faiface/pixel) game engine.
 
-![Screenshot](https://user-images.githubusercontent.com/44003176/230742745-d7adee93-8c70-4e32-b031-7258185aa2b1.png)
+<div align="center" width="100%">
+
+![Screenshot](https://user-images.githubusercontent.com/44003176/232126308-60299642-0490-478d-82a5-48d862da6703.png)  
+*Screenshot showing Arche Pixel features, visualizing an evolutionary forest model.*
+</div>
+
+## Features
+
+* Free 2D drawing using a convenient OpenGL interface.
+* Live time series plots using unified observers.
+* ECS engine monitor for detailed performance statistics.
+* Entity inspector for debugging and inspection.
+* Simulation controls to pause or limit speed interactively.
+* User input handling for interactive simulations.
 
 ## Installation
 

go.mod

@@ -5,8 +5,8 @@ go 1.20
 require (
 	github.com/faiface/pixel v0.10.0
 	github.com/mazznoer/colorgrad v0.9.1
-	github.com/mlange-42/arche v0.6.3
-	github.com/mlange-42/arche-model v0.1.0
+	github.com/mlange-42/arche v0.7.0
+	github.com/mlange-42/arche-model v0.2.0
 	github.com/stretchr/testify v1.8.1
 	golang.org/x/image v0.5.0
 	gonum.org/v1/plot v0.12.0

go.sum

@@ -51,10 +51,10 @@ github.com/mazznoer/colorgrad v0.9.1 h1:MB80JYVndKWSMEM1beNqnuOowWGhoQc3DXWXkFp6
 github.com/mazznoer/colorgrad v0.9.1/go.mod h1:WX2R9wt9B47+txJZVVpM9LY+LAGIdi4lTI5wIyreDH4=
 github.com/mazznoer/csscolorparser v0.1.2 h1:/UBHuQg792ePmGFzTQAC9u+XbFr7/HzP/Gj70Phyz2A=
 github.com/mazznoer/csscolorparser v0.1.2/go.mod h1:Aj22+L/rYN/Y6bj3bYqO3N6g1dtdHtGfQ32xZ5PJQic=
-github.com/mlange-42/arche v0.6.3 h1:VYADSGU2BXBLJtjqN+7UqH2FW0Tmdpnms7TBm/Sa4fM=
-github.com/mlange-42/arche v0.6.3/go.mod h1:cgOiMHWCbNAb5L5mCihS2yzdk1Zll1IoBJL+3wVm0AM=
-github.com/mlange-42/arche-model v0.1.0 h1:F9PnAruRgxO4LJfzFORVHujNUGhQYk98TDO3IyK+jz0=
-github.com/mlange-42/arche-model v0.1.0/go.mod h1:VftJXB24OjILidg0GXPdP8sZbB3wn2eCWx/i9NMIM+I=
+github.com/mlange-42/arche v0.7.0 h1:66HmSfVQFIYx7PyQtOjmWuGCzBX0fhefYqpDkWpyy6E=
+github.com/mlange-42/arche v0.7.0/go.mod h1:cgOiMHWCbNAb5L5mCihS2yzdk1Zll1IoBJL+3wVm0AM=
+github.com/mlange-42/arche-model v0.2.0 h1:JrGKLIGDMKumsYeddKw9S5RlUk0OOzUQH7GkkZGj1YM=
+github.com/mlange-42/arche-model v0.2.0/go.mod h1:VSOVJBHjw6gQm9B1vOVLsteFtXvZgJmNCOKQoh1jqYc=
 github.com/phpdave11/gofpdf v1.4.2/go.mod h1:zpO6xFn9yxo3YLyMvW8HcKWVdbNqgIfOOp2dXMnm1mY=
 github.com/phpdave11/gofpdi v1.0.12/go.mod h1:vBmVV0Do6hSBHC8uKUQ71JGW+ZGQq74llk/7bXwjDoI=
 github.com/phpdave11/gofpdi v1.0.13/go.mod h1:vBmVV0Do6hSBHC8uKUQ71JGW+ZGQq74llk/7bXwjDoI=

plot/inspector.go

@@ -0,0 +1,129 @@
+package plot
+
+import (
+	"fmt"
+	"io"
+	"reflect"
+
+	px "github.com/faiface/pixel"
+	"github.com/faiface/pixel/pixelgl"
+	"github.com/faiface/pixel/text"
+	"github.com/mlange-42/arche-model/resource"
+	"github.com/mlange-42/arche/ecs"
+	"github.com/mlange-42/arche/generic"
+)
+
+// Inspector drawer for inspecting entities.
+//
+// Shows information of the entity indicated by the SelectedEntity resource ([github.com/mlange-42/arche-model/resource.SelectedEntity]).
+// Entity selection is to be done by another system, e.g. by user input.
+//
+// Details can be adjusted using the HideXxx fields.
+// Further, keys F, T, V and N can be used to toggle details during a running simulation.
+type Inspector struct {
+	HideFields  bool // Hides components fields.
+	HideTypes   bool // Hides field types.
+	HideValues  bool // Hides field values.
+	HideNames   bool // Hide field names of nested structs.
+	selectedRes generic.Resource[resource.SelectedEntity]
+	text        *text.Text
+	helpText    *text.Text
+}
+
+// Initialize the system
+func (m *Inspector) Initialize(w *ecs.World, win *pixelgl.Window) {
+	m.selectedRes = generic.NewResource[resource.SelectedEntity](w)
+
+	m.text = text.New(px.V(0, 0), font)
+	m.helpText = text.New(px.V(0, 0), font)
+
+	fmt.Fprint(m.helpText, "Toggle [f]ields, [t]ypes, [v]alues or [n]ames")
+}
+
+// Update the drawer.
+func (m *Inspector) Update(w *ecs.World) {}
+
+// UpdateInputs handles input events of the previous frame update.
+func (m *Inspector) UpdateInputs(w *ecs.World, win *pixelgl.Window) {
+	if win.JustPressed(pixelgl.KeyF) {
+		m.HideFields = !m.HideFields
+		return
+	}
+	if win.JustPressed(pixelgl.KeyT) {
+		m.HideTypes = !m.HideTypes
+		return
+	}
+	if win.JustPressed(pixelgl.KeyV) {
+		m.HideValues = !m.HideValues
+		return
+	}
+	if win.JustPressed(pixelgl.KeyN) {
+		m.HideNames = !m.HideNames
+		return
+	}
+}
+
+// Draw the system
+func (m *Inspector) Draw(w *ecs.World, win *pixelgl.Window) {
+	m.helpText.Draw(win, px.IM.Moved(px.V(10, 10)))
+
+	if !m.selectedRes.Has() {
+		return
+	}
+	sel := m.selectedRes.Get().Selected
+	if sel.IsZero() {
+		return
+	}
+
+	height := win.Canvas().Bounds().H()
+	x0 := 10.0
+	y0 := height - 20.0
+
+	m.text.Clear()
+	fmt.Fprintf(m.text, "Entity %+v\n\n", sel)
+
+	if !w.Alive(sel) {
+		fmt.Fprint(m.text, "  dead entity")
+		m.text.Draw(win, px.IM.Moved(px.V(x0, y0)))
+		return
+	}
+
+	mask := w.Mask(sel)
+	bits := mask.TotalBitsSet()
+
+	for i := 0; i < ecs.MaskTotalBits && bits > 0; i++ {
+		id := ecs.ID(i)
+		if mask.Get(id) {
+			tp, _ := w.ComponentType(id)
+			ptr := w.Get(sel, id)
+			val := reflect.NewAt(tp, ptr).Elem()
+
+			fmt.Fprintf(m.text, "  %s\n", tp.Name())
+
+			if !m.HideFields {
+				for i := 0; i < val.NumField(); i++ {
+					m.printField(m.text, tp, tp.Field(i), val.Field(i))
+				}
+				fmt.Fprint(m.text, "\n")
+			}
+			bits--
+		}
+	}
+
+	m.text.Draw(win, px.IM.Moved(px.V(x0, y0)))
+}
+
+func (m *Inspector) printField(w io.Writer, tp reflect.Type, field reflect.StructField, value reflect.Value) {
+	fmt.Fprintf(w, "    %-20s ", field.Name)
+	if !m.HideTypes {
+		fmt.Fprintf(w, "    %-16s ", value.Type())
+	}
+	if !m.HideValues {
+		if m.HideNames {
+			fmt.Fprintf(w, "= %v", value.Interface())
+		} else {
+			fmt.Fprintf(w, "= %+v", value.Interface())
+		}
+	}
+	fmt.Fprint(m.text, "\n")
+}

plot/perf_stats.go

@@ -27,60 +27,60 @@ type PerfStats struct {
 }
 
 // Initialize the system
-func (m *PerfStats) Initialize(w *ecs.World, win *pixelgl.Window) {
-	if m.SampleInterval <= 0 {
-		m.SampleInterval = time.Second
+func (p *PerfStats) Initialize(w *ecs.World, win *pixelgl.Window) {
+	if p.SampleInterval <= 0 {
+		p.SampleInterval = time.Second
 	}
-	m.lastPlotUpdate = time.Now()
-	m.startTime = m.lastPlotUpdate
+	p.lastPlotUpdate = time.Now()
+	p.startTime = p.lastPlotUpdate
 
-	m.drawer = *imdraw.New(nil)
+	p.drawer = *imdraw.New(nil)
 
-	m.summary = text.New(px.V(0, 0), font)
+	p.summary = text.New(px.V(0, 0), font)
 
-	m.step = 0
+	p.step = 0
 
 	st := w.Stats()
-	m.stats.Entities = st.Entities.Used
-	m.stats.Mem = st.Memory
+	p.stats.Entities = st.Entities.Used
+	p.stats.Mem = st.Memory
 }
 
 // Update the drawer.
-func (m *PerfStats) Update(w *ecs.World) {
+func (p *PerfStats) Update(w *ecs.World) {
 	t := time.Now()
-	m.frameTimer.Update(m.step, t)
+	p.frameTimer.Update(p.step, t)
 
-	if t.Sub(m.lastPlotUpdate) >= m.SampleInterval {
+	if t.Sub(p.lastPlotUpdate) >= p.SampleInterval {
 		st := w.Stats()
-		m.stats.Entities = st.Entities.Used
-		m.stats.Mem = st.Memory
-		m.lastPlotUpdate = t
+		p.stats.Entities = st.Entities.Used
+		p.stats.Mem = st.Memory
+		p.lastPlotUpdate = t
 	}
 
-	m.step++
+	p.step++
 }
 
 // UpdateInputs handles input events of the previous frame update.
-func (m *PerfStats) UpdateInputs(w *ecs.World, win *pixelgl.Window) {}
+func (p *PerfStats) UpdateInputs(w *ecs.World, win *pixelgl.Window) {}
 
 // Draw the system
-func (m *PerfStats) Draw(w *ecs.World, win *pixelgl.Window) {
-	m.summary.Clear()
-	mem, units := toMemText(m.stats.Mem)
+func (p *PerfStats) Draw(w *ecs.World, win *pixelgl.Window) {
+	p.summary.Clear()
+	mem, units := toMemText(p.stats.Mem)
 	fmt.Fprintf(
-		m.summary, "Tick: %7d\nEnt.: %7d\nTPS: %8.1f\nTPT: %6.2fms\nMem: %6.1f%s\nTime: %7s",
-		m.step, m.stats.Entities, m.frameTimer.FPS(),
-		float64(m.frameTimer.FrameTime().Microseconds())/1000,
-		mem, units, time.Since(m.startTime).Round(time.Second),
+		p.summary, "Tick: %7d\nEnt.: %7d\nTPS: %8.1f\nTPT: %6.2fms\nMem: %6.1f%s\nTime: %7s",
+		p.step, p.stats.Entities, p.frameTimer.FPS(),
+		float64(p.frameTimer.FrameTime().Microseconds())/1000,
+		mem, units, time.Since(p.startTime).Round(time.Second),
 	)
 
-	dr := &m.drawer
+	dr := &p.drawer
 	height := win.Canvas().Bounds().H()
 	x0 := 10.0
 	y0 := height - 20.0
 
-	v1 := px.V(x0+m.summary.Bounds().Min.X-5, y0+m.summary.Bounds().Min.Y-5)
-	v2 := px.V(x0+m.summary.Bounds().Max.X+5, y0+m.summary.Bounds().Max.Y+5)
+	v1 := px.V(x0+p.summary.Bounds().Min.X-5, y0+p.summary.Bounds().Min.Y-5)
+	v2 := px.V(x0+p.summary.Bounds().Max.X+5, y0+p.summary.Bounds().Max.Y+5)
 
 	dr.Color = color.Black
 	dr.Push(v1, v2)
@@ -94,7 +94,7 @@ func (m *PerfStats) Draw(w *ecs.World, win *pixelgl.Window) {
 	dr.Reset()
 	dr.Clear()
 
-	m.summary.Draw(win, px.IM.Moved(px.V(x0, y0)))
+	p.summary.Draw(win, px.IM.Moved(px.V(x0, y0)))
 
 }