Monolith to Composed

Structure a game as small, single-purpose nodes.

▶ Run in browser

Tags: tutorial architecture signals

Monolith to Composed

You can build games now. This last tutorial is about building them well: how to structure a game so it stays easy to change. The game itself is tiny, a dodge game where you slide a paddle along the bottom (arrow keys, A/D, or hold the pointer) to avoid falling blocks. The point is the shape of the code.

main.py is the composed version. The full before/after refactor, starting from one giant node that does everything, is the walkthrough in From Monolithic to Composed.

The idea: one node, one job

The tempting first draft is a single DodgeGame node that tracks the player’s x, runs a spawn timer, holds the score, draws everything, and checks collisions. It works, but every change touches the same 80-line method and nothing can be tested or reused in isolation.

The fix is to give each concern its own node:

node	its one job
Player	read input, move, clamp, draw itself
Enemy	fall, and announce when it escapes off the bottom
Spawner	a timer that emits each new enemy
ScoreLabel	hold the score and draw it
World	a bare Node2D that holds one round, so it can be frozen or torn down as a unit
DodgeGame (root)	own the graph and the one thing only it can see: collision

Signals connect them

Each node declares its signals at class scope, exactly like it declares its properties, and stays ignorant of who is listening. The root does the wiring:

class Spawner(Node2D):
    spawned = Signal(Enemy)        # declared once; each instance gets its own

...

self.spawner.spawned.connect(self._on_spawned)   # new enemy -> root places it

def _on_spawned(self, enemy):
    enemy.escaped.connect(lambda: self.score.add(1))   # dodged -> +1
    self.world.add_child(enemy)

The signal-pairing rule: every signal has an emitter and a listener. Here Spawner.spawned, Enemy.escaped, and ScoreLabel.changed are all paired. A signal with no listener (or a global reached for instead of a signal) is a smell that the structure is wrong.

Composition makes “stop the game” one line

The monolith froze on death for free: one node, one if alive guard. Split into five nodes, that guard only stops the root, and the spawner keeps spawning behind the Game Over text. The composed answer is not five guards, it is one grouping node: every gameplay node is a child of a World node, so tree.paused = True freezes the whole subtree at once. The root sets update_mode = UpdateMode.ALWAYS so it keeps ticking through the pause and can hear the restart, and World sets UpdateMode.PAUSABLE so it does not inherit that exemption.

The payoff

The root’s on_update shrinks to pure game flow (alive check, restart, collision sweep). Per-entity behaviour lives in the entity. Each node is small enough to test on its own with a SceneRunner, and reusable in the next game.

Run it

# In your own copy of this directory
python main.py

# From the root of a repository checkout
uv run python examples/tutorials/monolith_to_composed/main.py

Source

"""Monolith to Composed: Structure a game as small, single-purpose nodes.

The capstone of the basics track. This is the *composed* version of a tiny dodge
game: move the paddle along the bottom with the arrow keys (or A/D, or by holding
the pointer) and avoid the falling blocks; each block you dodge scores a point.
The lesson is the structure, not the game: instead of one giant node that does
input, spawning, scoring, and collision, every concern is its own node, and they
talk through signals.

Read the README for the before/after refactor; this file is the after.

# /// simvx
# tags = ["tutorial", "architecture", "signals"]
# web = { root = "DodgeGame", width = 800, height = 600, responsive = true }
# ///

## What you will learn

- **One node, one job** -- `Player`, `Enemy`, `Spawner`, and `ScoreLabel` each own a
  single concern, so each is short and testable in isolation.
- **Paired signals** -- signals are declared at class scope (`escaped = Signal()`),
  and every one here is emitted by one node and connected by another:
  `Spawner.spawned`, `Enemy.escaped`, `ScoreLabel.changed`. A signal with no
  listener (or a listener with no emitter) is a smell.
- **The root owns the graph, not the state** -- `DodgeGame` only decides which nodes
  exist and which signals wire to which slots, plus the one thing only it can see:
  player-versus-enemy collision.
- **One flag freezes the whole game** -- death sets `tree.paused`, which stops the
  whole gameplay subtree at once, while the root keeps ticking (`UpdateMode.ALWAYS`)
  so it can still hear the restart.

Run: uv run python examples/tutorials/monolith_to_composed/main.py
Headless self-check: uv run python examples/tutorials/monolith_to_composed/main.py --test
"""

import random

from simvx.core import Input, Key, MouseButton, Node2D, Property, Signal, UpdateMode, Vec2
from simvx.graphics import App

WIDTH, HEIGHT = 800, 600
PLAYER_W, PLAYER_H = 80, 16
ENEMY_W, ENEMY_H = 40, 40


class Player(Node2D):
    """Owns its position and its one input concern: move left/right, clamped."""

    speed = Property(360.0, range=(50, 800))

    def on_update(self, dt: float):
        dx = Input.get_strength("right") - Input.get_strength("left")
        if Input.is_mouse_button_pressed(MouseButton.LEFT):
            # Hold (or drag) the pointer to steer; a touch reads as the left button.
            dx = max(-1.0, min(1.0, (Input.mouse_position.x - self.position.x) / 32.0))
        new_x = self.position.x + dx * self.speed * dt
        self.position = Vec2(max(PLAYER_W / 2, min(WIDTH - PLAYER_W / 2, new_x)), self.position.y)

    def on_draw(self, renderer):
        renderer.draw_rect(
            (self.position.x - PLAYER_W / 2, self.position.y - PLAYER_H / 2),
            (PLAYER_W, PLAYER_H),
            colour=(0.5, 0.9, 1.0, 1),
            filled=True,
        )


class Enemy(Node2D):
    """Falls straight down and announces when it escapes off the bottom."""

    speed = Property(220.0, range=(50, 600))

    escaped = Signal()  # the player dodged it

    def on_update(self, dt: float):
        self.position = Vec2(self.position.x, self.position.y + self.speed * dt)
        if self.position.y > HEIGHT + ENEMY_H:
            self.escaped.emit()
            self.destroy()

    def on_draw(self, renderer):
        renderer.draw_rect(
            (self.position.x - ENEMY_W / 2, self.position.y - ENEMY_H / 2),
            (ENEMY_W, ENEMY_H),
            colour=(1.0, 0.4, 0.3, 1),
            filled=True,
        )


class Spawner(Node2D):
    """No drawing: just a timer that emits each new enemy for the root to place."""

    min_delay = Property(0.4)
    max_delay = Property(0.9)

    spawned = Signal(Enemy)  # carries the new Enemy node

    def on_ready(self):
        self._timer = 0.0

    def on_update(self, dt: float):
        self._timer -= dt
        if self._timer <= 0:
            self._timer = random.uniform(self.min_delay, self.max_delay)
            self.spawned.emit(
                Enemy(speed=random.uniform(150.0, 300.0), position=Vec2(random.uniform(20, WIDTH - 20), -ENEMY_H))
            )


class ScoreLabel(Node2D):
    """Owns the score and its rendering; announces when it changes."""

    score = Property(0)

    changed = Signal(int)

    def add(self, n: int = 1):
        self.score += n
        self.changed.emit(self.score)

    def on_draw(self, renderer):
        renderer.draw_text(f"Score: {self.score}", (20, 20), scale=2, colour=(1, 1, 1, 1))


class DodgeGame(Node2D):
    """Root: owns the graph (which nodes exist, which signals wire to which slots)
    and the one thing only it can see, player-versus-enemy collision."""

    input_actions = {
        "left": [Key.A, Key.LEFT],
        "right": [Key.D, Key.RIGHT],
        "restart": [Key.ENTER, MouseButton.LEFT],
    }

    def on_ready(self):
        # Death pauses the tree. The root has to keep ticking through that to
        # notice the restart, so it opts out of the pause and the gameplay
        # subtree opts back in (see ``_start``).
        self.update_mode = UpdateMode.ALWAYS
        self._start()

    def _start(self):
        self.alive = True
        self.tree.paused = False
        self.queue_redraw()  # alive flipped (restart) -> clear the "Game Over" text from on_draw
        # Everything that plays lives under one node, so one flag freezes it all
        # and one destroy() tears the round down.
        self.world = self.add_child(Node2D(name="World"))
        self.world.update_mode = UpdateMode.PAUSABLE
        self.player = self.world.add_child(Player(position=Vec2(WIDTH / 2, HEIGHT - 60)))
        self.spawner = self.world.add_child(Spawner())
        self.score = self.world.add_child(ScoreLabel())
        self.spawner.spawned.connect(self._on_spawned)
        self.score.changed.connect(self._on_score_changed)

    def _on_spawned(self, enemy: Enemy):
        # The root decides where the enemy lives, and pairs its escape to a point.
        enemy.escaped.connect(lambda: self.score.add(1))
        self.world.add_child(enemy)

    def _on_score_changed(self, score: int):
        # A rising score ramps the difficulty: the root tightens the spawn delay.
        self.spawner.min_delay = max(0.12, 0.4 - score * 0.01)
        self.spawner.max_delay = max(0.3, 0.9 - score * 0.02)

    def on_update(self, dt: float):
        if not self.alive:
            if Input.is_action_just_pressed("restart"):
                self.world.destroy()
                self._start()
            return
        px, py = self.player.position
        for child in list(self.world.children):
            if (
                isinstance(child, Enemy)
                and abs(child.position.x - px) < (PLAYER_W + ENEMY_W) / 2
                and abs(child.position.y - py) < (PLAYER_H + ENEMY_H) / 2
            ):
                self.alive = False
                # One flag stops the spawner, the falling enemies, and the scoring:
                # nothing keeps simulating behind the "Game Over" text.
                self.tree.paused = True
                self.queue_redraw()  # alive flipped (death) -> the retained renderer redraws "Game Over"
                return

    def on_draw(self, renderer):
        renderer.draw_rect((0, 0), (WIDTH, HEIGHT), colour=(0.05, 0.05, 0.08, 1), filled=True)
        if not self.alive:
            renderer.draw_text(
                "Game Over: Enter or tap to restart", (WIDTH / 2 - 190, HEIGHT / 2), scale=2, colour=(1, 1, 0.3, 1)
            )


def _selftest() -> bool:
    """Headless: play a round -- dodge, die, restart -- and check the structure holds.

    The paddle is only ever steered by holding the pointer, which is one of the two
    routes the Player reads, so the round is played rather than simulated. What is
    checked is what the lesson teaches: that each signal has an emitter and a
    listener at the other end, that one paused flag freezes the whole gameplay
    subtree while the root keeps ticking, and that a restart rebuilds it.
    """
    from simvx.core.testing import InputSimulator
    from simvx.graphics.testing import assert_not_blank, save_png

    DODGE_UNTIL = 4  # points to score by dodging before deliberately colliding
    FROZEN_FOR = 30  # frames to watch after death, to see that nothing moves
    TOTAL = 1800

    random.seed(5)
    app = App(title="Monolith to Composed", width=WIDTH, height=HEIGHT, visible=False)
    scene = DodgeGame(name="DodgeGame")
    sim = InputSimulator()
    seen: dict[str, object] = {}
    pointing = False

    def steer(x: float) -> None:
        nonlocal pointing
        sim.move_mouse(max(0.0, min(WIDTH, x)), HEIGHT - 60.0)
        if not pointing:
            sim.press_mouse(MouseButton.LEFT)
            pointing = True

    def let_go() -> None:
        nonlocal pointing
        if pointing:
            sim.release_mouse(MouseButton.LEFT)
            pointing = False

    def enemies() -> list[Enemy]:
        return [c for c in scene.world.children if isinstance(c, Enemy)]

    def on_frame(idx: int, _t: float) -> bool:
        if idx == 1:
            seen["world_children"] = sorted(
                {type(c).__name__ for c in scene.world.children if not isinstance(c, Enemy)}
            )
            seen["first_world"] = id(scene.world)
            seen["delays_at_zero"] = (scene.spawner.min_delay, scene.spawner.max_delay)
            seen["enemies_in_world"] = True

        if idx > 0 and not all(e.parent is scene.world for e in enemies()):
            seen["enemies_in_world"] = False

        if scene.alive and "died_at" not in seen:
            threats = [e for e in enemies() if e.position.y > HEIGHT / 2]
            if scene.score.score < DODGE_UNTIL:
                # Dodging: stand as far from the nearest threat as the court allows.
                if threats:
                    nearest = min(threats, key=lambda e: abs(e.position.x - scene.player.position.x))
                    steer(0.0 if nearest.position.x > WIDTH / 2 else WIDTH)
                else:
                    steer(scene.player.position.x)
            else:
                if "delays_after_dodging" not in seen:
                    seen["delays_after_dodging"] = (scene.spawner.min_delay, scene.spawner.max_delay)
                    seen["score_from_dodging"] = scene.score.score
                # Now stand under one, on purpose.
                if threats:
                    steer(float(min(threats, key=lambda e: -e.position.y).position.x))
        elif "died_at" not in seen:
            let_go()
            seen["died_at"] = idx
            seen["paused"] = scene.tree.paused
            seen["score_at_death"] = scene.score.score
            seen["frozen_from"] = [(id(e), float(e.position.y)) for e in enemies()]
        elif idx == seen["died_at"] + FROZEN_FOR:
            seen["frozen_to"] = [(id(e), float(e.position.y)) for e in enemies()]
            seen["score_after_freeze"] = scene.score.score
            sim.press_key(Key.ENTER)
        elif idx == seen["died_at"] + FROZEN_FOR + 1:
            sim.release_key(Key.ENTER)
            seen["restarted"] = (scene.alive, scene.tree.paused, id(scene.world), scene.score.score)
            return False
        return True

    frames = app.run_headless(scene, frames=TOTAL, on_frame=on_frame, capture_frames=[0])
    assert_not_blank(frames[0])
    save_png(frames[0], "/tmp/monolith_to_composed_test.png")

    ok = True

    def check(label: str, passed: bool, detail: str) -> None:
        nonlocal ok
        ok = ok and passed
        print(f"{'ok  ' if passed else 'FAIL'} {label}: {detail}")

    check(
        "the round is built from one node per job, all under a single World",
        seen["world_children"] == ["Player", "ScoreLabel", "Spawner"] and seen["enemies_in_world"],
        ", ".join(seen["world_children"]) + ", and the root files every spawned Enemy there too",
    )
    check(
        "dodging an enemy scores a point, so escaped reaches the score through the root",
        seen["score_from_dodging"] >= DODGE_UNTIL,
        f"{seen['score_from_dodging']} points scored by letting enemies fall past the paddle",
    )
    before, after = seen["delays_at_zero"], seen["delays_after_dodging"]
    check(
        "and the rising score tightens the spawner, which is the other end of changed",
        after[0] < before[0] and after[1] < before[1],
        f"spawn delay {before[0]:.2f}..{before[1]:.2f}s at 0 points, {after[0]:.2f}..{after[1]:.2f}s "
        f"at {seen['score_from_dodging']}",
    )
    check(
        "being hit ends the round and pauses the tree",
        seen["paused"],
        f"tree.paused = {seen['paused']} on the frame the collision was seen, at frame {seen['died_at']}",
    )
    still = [
        (y_from, y_to)
        for (id_from, y_from), (id_to, y_to) in zip(seen["frozen_from"], seen["frozen_to"], strict=True)
        if id_from == id_to
    ]
    check(
        "one flag freezes the whole gameplay subtree: nothing falls and nothing scores",
        bool(still) and all(a == b for a, b in still) and seen["score_after_freeze"] == seen["score_at_death"],
        f"{len(still)} enemies held their y for {FROZEN_FOR} frames, score held at {seen['score_at_death']}",
    )
    alive, paused, world, score = seen["restarted"]
    check(
        "the root keeps ticking through the pause, so Enter restarts into a fresh round",
        alive and not paused and world != seen["first_world"] and score == 0,
        f"alive again, unpaused, a new World, score back to {score}",
    )

    print("screenshot: /tmp/monolith_to_composed_test.png")
    print("SELFTEST:", "PASS" if ok else "FAIL")
    return ok


if __name__ == "__main__":
    import sys

    if "--test" in sys.argv:
        sys.exit(0 if _selftest() else 1)
    App(title="Monolith to Composed", width=WIDTH, height=HEIGHT).run(DodgeGame())