commands/effect_and_debug_hotkeys

Goal

Bind function keys and letter keys to toggle visual effects and debug overlays, and see a live status panel reflect each toggle.

Why this tutorial exists

Debug tools and visual effects are typically toggled via hotkeys during development and playtesting. This example demonstrates:

  • using keys_pressed to detect single-frame key edges

  • toggling boolean flags for bounding boxes, grid overlay, FPS counter

  • cycling through background colours

  • rendering conditional overlays based on toggle state

Source map

  • Settings profile: examples/settings/commands/effect_and_debug_hotkeys.yml

  • Example builder: examples/catalog/commands/effect_and_debug_hotkeys/main.py

  • Scene: examples/catalog/commands/effect_and_debug_hotkeys/scenes/scene.py

  • Shared runner: examples/_shared/runner.py

What to verify

You should see:

  1. three coloured rectangles on the canvas

  2. a status panel showing each hotkey and its ON/OFF state

  3. pressing F1 draws yellow bounding boxes around the rectangles

  4. pressing F2 shows a grid overlay across the entire viewport

  5. pressing F3 shows an FPS counter in the top-right corner

  6. pressing B cycles the background colour through five presets

Controls

Key

Action

F1

Toggle bounding boxes

F2

Toggle grid overlay

F3

Toggle FPS display

B

Cycle background colour

ESC

Quit

Run

mini-arcade run --example commands/effect_and_debug_hotkeys
mini-arcade run --example commands/effect_and_debug_hotkeys --pass-through --backend pygame
mini-arcade run --example commands/effect_and_debug_hotkeys --pass-through --backend native

Common mistakes

  • Using keys_held for toggles — the flag flips every frame the key is held. Use keys_pressed for edge detection.

  • Hardcoding pixel positions without accounting for virtual resolution scaling.

  • Drawing debug overlays in the SIMULATION phase instead of RENDERING — they get overwritten.

Next step

This is the last tutorial in Group E. Continue to the rendering pipeline tutorials when they become available, or revisit: