window/fit_vs_fill

Goal

Compare FIT vs FILL viewport modes and understand letterbox vs crop tradeoffs.

Why this tutorial exists

This is a core decision for any game:

  • preserve full virtual frame (FIT)

  • or fill full window without bars (FILL)

Source map

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

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

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

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

Runtime flow

set_viewport_mode(...) updates Viewport.mode, then recomputes:

  • scale

  • viewport_w / viewport_h

  • offset_x / offset_y

The tutorial visualizes:

  • full virtual border

  • currently visible virtual bounds

So cropping in FILL is explicit.

What to verify

  1. 1 (FIT) shows all virtual edges, with bars if needed.

  2. 2 (FILL) removes bars but crops top/bottom or left/right.

  3. visible virtual bounds shrink in FILL.

  4. offset can become negative in FILL mode.

Run

mini-arcade run --example window/fit_vs_fill

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

Controls

  • 1 -> FIT

  • 2 -> FILL

  • F1 -> debug overlay

  • ESC -> quit

Next step