commands/custom_scene_commands

Goal

Learn how to define custom Command subclasses that execute game-specific side effects through the scene command queue.

Why this tutorial exists

The command pattern decouples “what should happen” from “when it happens”. Instead of mutating state inline during tick(), you enqueue command objects that the scene processes after the simulation step. This tutorial shows:

  • defining AddScoreCommand and ResetCounterCommand as Command subclasses

  • enqueuing them from a system or tick handler

  • a log panel that records every executed command

Source map

  • Settings profile: examples/settings/commands/custom_scene_commands.yml

  • Example builder: examples/catalog/commands/custom_scene_commands/main.py

  • Scene: examples/catalog/commands/custom_scene_commands/scenes/scene.py

  • Shared runner: examples/_shared/runner.py

What to verify

You should see:

  1. a score counter that increments when you press Space

  2. pressing R enqueues a ResetCounterCommand that zeroes the score

  3. a scrolling log panel showing each command as it executes

  4. the log entries include timestamps

Controls

Key

Action

Space

Add score +10

R

Reset counter

ESC

Quit

Run

mini-arcade run --example commands/custom_scene_commands
mini-arcade run --example commands/custom_scene_commands --pass-through --backend pygame
mini-arcade run --example commands/custom_scene_commands --pass-through --backend native

Common mistakes

  • Mutating state directly instead of going through commands — bypasses the command log and any undo/replay infrastructure.

  • Forgetting to register commands with the scene’s command processor.

  • Creating commands with side effects in __init__ instead of execute().

Next step