# Input Coordinate Mapping Internals

## Purpose

Explain how screen-space input (mouse) is converted into virtual-space
coordinates used by gameplay simulation.

## Core files

- `packages/mini-arcade-core/src/mini_arcade_core/runtime/input/input_adapter.py`
- `packages/mini-arcade-core/src/mini_arcade_core/runtime/window/window_adapter.py`
- `packages/mini-arcade-core/src/mini_arcade_core/engine/render/viewport.py`
- backend input ports:
  - `packages/mini-arcade-pygame-backend/src/mini_arcade_pygame_backend/ports/input.py`
  - `packages/mini-arcade-native-backend/src/mini_arcade_native_backend/mapping/events.py`

## Mapping pipeline

1. Backend emits mouse events with screen coordinates.
2. `InputAdapter` stores:
   - `mouse_pos`
   - `mouse_delta`
   in `InputFrame`.
3. Scene receives `InputFrame` each tick.
4. Scene calls:
   `services.window.screen_to_virtual(x, y)`.
5. Window adapter:
   - applies logical->drawable ratio
   - applies inverse viewport transform
6. Result is virtual-space coordinate for gameplay logic.

## Mapping math

Given viewport state `(offset_x, offset_y, scale)`:

- `virtual_x = (screen_x - offset_x) / scale`
- `virtual_y = (screen_y - offset_y) / scale`

In `FIT` mode, letterbox bars can produce values outside virtual bounds.
In `FILL` mode, mapping remains valid but visible region is cropped.

## Practical guidance

- run gameplay logic and collisions in virtual coordinates
- treat screen coordinates as presentation/input transport only
- clamp mapped coordinates only when game design requires it
- verify mapping in both `FIT` and `FILL`, and after resize

## Tutorial reference

- `docs/source/tutorials/window/screen_to_virtual_input.md`