window/screen_to_virtual_input

Goal

Map raw screen-space input into virtual coordinates reliably across viewport modes and resize changes.

Why this tutorial exists

Gameplay logic runs in virtual coordinates. Mouse/touch input arrives in screen coordinates. This mapping must be correct or aiming/clicking drifts.

Source map

  • Settings profile: examples/settings/window/screen_to_virtual_input.yml

  • Example builder: examples/catalog/window/screen_to_virtual_input/main.py

  • Scene: examples/catalog/window/screen_to_virtual_input/scenes/scene.py

  • Input adapter: packages/mini-arcade-core/src/mini_arcade_core/runtime/input/input_adapter.py

  • Window adapter mapping: packages/mini-arcade-core/src/mini_arcade_core/runtime/window/window_adapter.py

  • Viewport mapping math: packages/mini-arcade-core/src/mini_arcade_core/engine/render/viewport.py

Runtime flow

  1. Backend emits mouse motion events in screen coordinates.

  2. InputAdapter stores mouse_pos in InputFrame.

  3. Scene calls: services.window.screen_to_virtual(screen_x, screen_y).

  4. Window adapter applies logical->drawable scaling and viewport transform inverse.

  5. Scene uses mapped coordinates in world-space rendering.

What to verify

  1. move mouse and compare screen mouse vs virtual mouse.

  2. switch FIT/FILL with 1/2; virtual mapping changes accordingly.

  3. in FIT, moving inside letterbox bars can yield out-of-bounds virtual values.

  4. virtual trail follows mapped world coordinates, not screen coordinates.

Run

mini-arcade run --example window/screen_to_virtual_input

mini-arcade run --example window/screen_to_virtual_input --pass-through --backend native

Controls

  • Move mouse -> updates mapping

  • 1 -> FIT

  • 2 -> FILL

  • C -> clear virtual trail

  • F1 -> debug overlay

  • ESC -> quit