debug
game/debug provides development-only diagnostics for NSGo games: a key-toggled frame-time graph, a live scene/layer inspector, and world-space collision and sprite-bounds wireframes — all stripped to zero-cost no-ops with -tags release.
import "github.com/nsgo-dev/game/packages/game/debug"
Wiring the overlay and frame-time graph
Create an *Overlay with debug.New, wrap your game.Loop with WrapLoop, and mount overlay.View(cx) alongside your game canvas:
overlay := debug.New(debug.Options{
ToggleKey: "F3", // default when empty
TargetFPS: 60, // reference line on the frame graph
LineWidth: 1,
Scenes: func() []debug.SceneSnapshot {
return []debug.SceneSnapshot{
{
Name: "world",
Layers: []debug.LayerSnapshot{
{Name: "terrain", Space: "world", Objects: 1},
{Name: "actors", Space: "world", Objects: len(actorsBatch.Sprites)},
{Name: "hud", Space: "screen", Objects: 3},
},
},
}
},
})
overlay.WrapLoop(loop)
loop.Run(cx)
return core.View{
Style: core.Style{FlexGrow: 1, FlexShrink: 1},
Children: []core.Node{
gameCanvas,
overlay.View(cx), // returns nil under -tags release
},
}
WrapLoop(l)wrapsl.Updateandl.Drawto time each frame and callRecordFrame(total, update, draw)into the fixed-sizeFrameStatsring buffer (FrameHistory = 120samples, zero per-frame heap allocations).overlay.Stats()exposesFPS(),Average(),Latest(),MaxTotal(),Len(),At(i),Samples(dst),Reset(), andDrawGraph(d, size, targetFPS)if you want to embed metrics elsewhere.- Toggling: press
ToggleKey(default"F3") or calloverlay.Toggle()/overlay.SetVisible(true). Readingoverlay.Visible()inside a reactive view orCanvas.Drawsubscribes automatically.
Drawing collision and sprite-bounds wireframes
Draw world-space debug wireframes inside core.Canvas.Draw while your camera/viewport transform is active. ShapeOverlay automatically divides LineWidth by the drawing's active scale so wireframes stay crisp at any camera zoom:
d.Save()
cam.Apply(d)
worldScene.Draw(d)
// Only executes when the overlay is visible; subscribes the canvas to toggles
overlay.DrawShapes(d, func(s *debug.ShapeOverlay) {
s.DrawBox(d, playerBounds, core.RGB(0x22c55e))
s.DrawCircle(d, aggroX, aggroY, aggroRadius, core.RGB(0xf59e0b))
s.DrawBatchBounds(d, actorsBatch, core.RGB(0x38bdf8))
})
d.Restore()
Convenience shortcuts overlay.DrawBox, overlay.DrawCircle, overlay.DrawSpriteBounds, and overlay.DrawBatchBounds are also available directly on *Overlay.
Scene inspector
Supply live scene structure in either of two ways:
- Pull via
Options.Scenes: if the callback reads NSGo signals, the inspector updates reactively; otherwise it refreshes on recorded frames and whenever you calloverlay.RefreshScenes(). - Push via
overlay.SetScenes(snapshots): updates the inspector immediately whenOptions.Scenesis nil.
Stripping debug code in release builds
Build release binaries with -tags release:
go build -tags release ./...
Under -tags release, debug.Enabled() returns false, Overlay.View(cx) returns nil, and every Overlay, FrameStats, and ShapeOverlay method compiles to an empty no-op — so none of the overlay UI, frame graph, or wireframe drawing code is linked into your shipping binary.