systems/input_frame_visualizer

Goal

Understand the InputFrame data model by watching raw keyboard, mouse, and gamepad state update in real time on a diagnostic dashboard.

Why this tutorial exists

Every SimScene.tick() receives an InputFrame snapshot. Before wiring action maps or intent systems you need to see what data is available each frame:

  • keys_held, keys_pressed, keys_released

  • mouse_pos, mouse_buttons_held, mouse_buttons_pressed

  • axes, buttons (gamepad)

This visualizer renders every field as live text so you can press keys and see the frame-level effect immediately.

Source map

  • Settings profile: examples/settings/systems/input_frame_visualizer.yml

  • Example builder: examples/catalog/systems/input_frame_visualizer/main.py

  • Scene: examples/catalog/systems/input_frame_visualizer/scenes/scene.py

  • Shared runner: examples/_shared/runner.py

What to verify

On screen you should see four labelled columns:

  1. Keys — held/pressed/released sets update as you type

  2. Mouse — position tracks the cursor; button sets react to clicks

  3. Axes — gamepad analog stick values (if a controller is connected)

  4. Buttons — gamepad digital buttons

Behavior checks:

  • pressing a key adds it to keys_pressed for exactly one frame, then it appears in keys_held until released

  • mouse_pos reflects virtual-coordinate-mapped position

  • column labels stay visible even with no input

Run

mini-arcade run --example systems/input_frame_visualizer
mini-arcade run --example systems/input_frame_visualizer --pass-through --backend pygame
mini-arcade run --example systems/input_frame_visualizer --pass-through --backend native

Common mistakes

  • Confusing keys_pressed (edge, one frame) with keys_held (level).

  • Forgetting that mouse_pos is in virtual coordinates, not window pixels.

  • Expecting gamepad data without a connected controller.

Next step