debug

Documentation

Overview

Package debug provides developer-time inspection helpers: live value watches, FPS readout, and a minimal in-game overlay. Everything here is owner-bound and cheap to wire up — the cost of forgetting to clean up debug code in shipping builds is the cost of an extra `Subscribe` per watched value, which is tolerable.

For builds where every cycle counts, wrap calls in a build-tag guard:

//go:build debug

Phase 2 scope: Watch, FPS overlay registration. Hierarchical state visualisation, in-game console, and immediate-mode draw arrive in Phase 4 per the implementation plan.

Index

• func AttachFPS(owner Node.Instance)
• func Snapshot() map[string]string
• func Unwatch(label string)
• func Watch(label string, value any)
• func WatchFunc(label string, fn func() any)

Functions

func AttachFPS

func AttachFPS(owner Node.Instance)

AttachFPS starts a per-second printer that dumps watched values to the Godot console. Replaces the proper in-game overlay until Phase 4 ships the visual version.

// In one autoload component's Ready:
debug.AttachFPS(autoload.AsNode())

owner-bound: when owner exits the tree, the printer stops.

func Snapshot

func Snapshot() map[string]string

Snapshot returns the currently-watched label/value map. Intended for the FPS overlay autoload; user code rarely needs to call this directly.

Returns string-typed renderings of each value (via fmt.Sprint), so the overlay doesn't need to know about individual value types.

func Unwatch

func Unwatch(label string)

Unwatch removes a previously-registered watch.

func Watch

func Watch(label string, value any)

Watch registers a label/value pair to be rendered by the FPS overlay (or printed once per second to the Godot console if no overlay is attached). Use to make a live value visible while debugging without writing UI code.

debug.Watch("speed", player.Speed)
debug.Watch("hp", player.HP)

Watch writes the value at call time — call it inside Process / Tick to see continuous updates. For "let the watcher pull the value when it wants to," use WatchFunc.

func WatchFunc

func WatchFunc(label string, fn func() any)

WatchFunc registers a label whose value is computed by calling fn each time the overlay refreshes. Use when "the value" is computed (a derived quantity, a count of entities, etc.) and writing it every frame from the owner would be more invasive than letting the debugger pull it.

debug.WatchFunc("enemy count", func() any {
    return len(gogogd.Children[*Enemy](g.AsNode()))
})