config/backend_swap

Goal

Validate backend parity by running the same scene and config envelope on:

  • pygame

  • native

This tutorial is about confidence in backend interchangeability for core runtime behavior.

What this tutorial demonstrates

It uses:

  1. Shared example defaults: examples/settings/settings.yml

  2. Example-specific profile: examples/settings/config/backend_swap.yml

  3. Example builder: examples/catalog/config/backend_swap/main.py

  4. Runtime scene: examples/catalog/config/backend_swap/scenes/scene.py

Runtime behavior (actual)

build_example(**kwargs):

  • loads engine/scene/backend defaults from settings

  • reads allowed backends from backend_swap.backends

  • normalizes --backend and falls back to first allowed backend if invalid

  • builds one EngineConfig + one SceneConfig

  • injects backend-dependent title suffix ((... pygame) or (... native))

The scene then renders runtime values (backend class, fps, virtual resolution, viewport), so parity checks are visible without extra tooling.

YAML backend selection (not only CLI)

This tutorial can choose backend without CLI overrides by setting profile YAML:

examples/settings/config/backend_swap.yml

backend:
  provider: native

If you change that to pygame, default tutorial execution switches backend:

mini-arcade run --example config/backend_swap

CLI --backend remains an override on top of YAML for quick parity testing.

Parity scope

This tutorial validates:

  • window opens/closes cleanly

  • virtual resolution is applied equally

  • viewport scaling telemetry is coherent

  • clear/background behavior is equivalent

  • keyboard controls (F1, ESC) behave the same

This tutorial does not validate:

  • game-specific rendering feature parity (sprites/effects in complex games)

  • performance parity

  • capture/audio parity under heavy load

Run

Default (uses backend.provider from profile):

mini-arcade run --example config/backend_swap

Force pygame:

mini-arcade run --example config/backend_swap --pass-through --backend pygame

Force native:

mini-arcade run --example config/backend_swap --pass-through --backend native

Override timing/resolution:

mini-arcade run --example config/backend_swap --pass-through --fps 75 --virtual-width 960 --virtual-height 540

Acceptance checklist

Run both backends and compare:

  1. runtime backend line changes as expected.

  2. virtual_resolution line is identical for both runs.

  3. window and viewport scale are coherent after resize.

  4. No crash/hang on close.

  5. ESC exits and F1 toggles debug overlay in both.

Invalid backend behavior

If --backend value is not in backend_swap.backends, builder logic falls back to first allowed backend instead of crashing. This is intentional for robust demos.

Useful extensions

To harden parity testing:

  • add deterministic input playback and compare screenshots

  • add a scripted resize sequence and assert viewport metrics

  • add backend-specific logs for font/text metrics and draw timings

Developer internals:

Common pitfalls

  • Forgetting --pass-through: backend override is not forwarded to example builder.

  • Mistaking title suffix for real backend state: trust the rendered backend class name line, not window title alone.

  • Comparing only startup: include resize, debug overlay toggle, and clean shutdown.

Controls

  • F1: toggle built-in debug overlay

  • ESC: exit

Next step