Debug Overlay

the engine’s built-in on-screen diagnostic HUD.

▶ Run in browser

Tags: debug

The scene is an ordinary little UI (a panel of buttons, a dropdown, a couple of containers). On top of it sits the engine Debug overlay, a drop-in HUD you can toggle on any running game to inspect what the engine is doing.

Controls

F3 Toggle the debug overlay on/off F4 Cycle which overlay features are shown

What it demonstrates

  • Adding the overlay with Debug.create_node() and enabling it via Debug.enabled = True (here it starts on so there is something to see).

  • The overlay’s feature mix: frame/profiler timings, the bounding boxes of UI controls, on-screen labels, and a rolling event log.

  • That the overlay is non-intrusive: the underlying UI (buttons, panels, the disabled button, the dropdown) keeps working normally underneath it.

Run: uv run python examples/features/debug/overlay.py

Source

  1"""Debug Overlay: the engine's built-in on-screen diagnostic HUD.
  2
  3The scene is an ordinary little UI (a panel of buttons, a dropdown, a couple of
  4containers). On top of it sits the engine `Debug` overlay, a drop-in HUD you can
  5toggle on any running game to inspect what the engine is doing.
  6
  7## Controls
  8  F3   Toggle the debug overlay on/off
  9  F4   Cycle which overlay features are shown
 10
 11## What it demonstrates
 12  - Adding the overlay with `Debug.create_node()` and enabling it via
 13    `Debug.enabled = True` (here it starts on so there is something to see).
 14  - The overlay's feature mix: frame/profiler timings, the bounding boxes of
 15    UI controls, on-screen labels, and a rolling event log.
 16  - That the overlay is non-intrusive: the underlying UI (buttons, panels, the
 17    disabled button, the dropdown) keeps working normally underneath it.
 18
 19Run: uv run python examples/features/debug/overlay.py
 20"""
 21
 22from simvx.core import (
 23    AnchorPreset,
 24    Button,
 25    Debug,
 26    DropDown,
 27    HBoxContainer,
 28    Label,
 29    MarginContainer,
 30    Node,
 31    Panel,
 32    VBoxContainer,
 33    Vec2,
 34)
 35from simvx.graphics import App
 36
 37
 38class DebugDemo(Node):
 39    def on_ready(self):
 40        # Add the debug overlay node
 41        self.add_child(Debug.create_node())
 42        # Enable debug by default for this demo
 43        Debug.enabled = True
 44
 45        # Build a simple UI scene: anchored TOP_LEFT with a 50px gutter so
 46        # the panel keeps its top-left placement at any window size.
 47        root_panel = Panel(name="RootPanel")
 48        root_panel.set_anchor_preset(AnchorPreset.TOP_LEFT)
 49        root_panel.margin_left = 50
 50        root_panel.margin_top = 50
 51        root_panel.size = Vec2(400, 300)
 52        self.add_child(root_panel)
 53
 54        margin = MarginContainer(name="Margin")
 55        margin.margin_left = 10
 56        margin.margin_top = 10
 57        margin.size = Vec2(380, 280)
 58        root_panel.add_child(margin)
 59
 60        vbox = VBoxContainer(name="VBox")
 61        vbox.size = Vec2(360, 260)
 62        margin.add_child(vbox)
 63
 64        title = Label("Debug Overlay Demo", name="Title")
 65        title.size = Vec2(360, 30)
 66        vbox.add_child(title)
 67
 68        btn1 = Button("Click Me", name="Button1")
 69        btn1.size = Vec2(200, 30)
 70        btn1.on_press = lambda: print("Button 1 clicked!")
 71        vbox.add_child(btn1)
 72
 73        btn2 = Button("Another Button", name="Button2")
 74        btn2.size = Vec2(200, 30)
 75        btn2.on_press = lambda: print("Button 2 clicked!")
 76        vbox.add_child(btn2)
 77
 78        btn_disabled = Button("Disabled", name="DisabledBtn")
 79        btn_disabled.size = Vec2(200, 30)
 80        btn_disabled.disabled = True
 81        vbox.add_child(btn_disabled)
 82
 83        dropdown = DropDown(name="TestDropDown")
 84        dropdown.size = Vec2(200, 30)
 85        dropdown.items = ["Option A", "Option B", "Option C"]
 86        vbox.add_child(dropdown)
 87
 88        hbox = HBoxContainer(name="HBox")
 89        hbox.size = Vec2(360, 30)
 90        vbox.add_child(hbox)
 91
 92        for i in range(3):
 93            b = Button(f"Btn {i}", name=f"SmallBtn{i}")
 94            b.size = Vec2(100, 30)
 95            hbox.add_child(b)
 96
 97        # Bottom controls hint: anchored so it tracks the window on resize.
 98        hint = Label("F3: toggle overlay    F4: cycle features", name="Hint")
 99        hint.set_anchor_preset(AnchorPreset.BOTTOM_WIDE)
100        hint.margin_left = 12.0
101        hint.margin_bottom = 34.0
102        hint.font_size = 15.0
103        self.add_child(hint)
104
105
106if __name__ == "__main__":
107    app = App(title="SimVX Debug Demo", width=1280, height=720)
108    app.run(DebugDemo())