Monolith to Composed¶

Structure a game as small, single-purpose nodes.

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(Node):
    spawned = Signal(Enemy)        # declared once; each instance gets its own

    def spawn(self):
        self.spawned.emit(Enemy(...))   # fire the signal

...

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

def place_enemy(self, enemy):
    enemy.escaped.connect(self.score.add)   # 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 declares update_mode = Property(UpdateMode.ALWAYS) so it keeps ticking through the pause and can hear the restart, and World is built with update_mode=UpdateMode.PAUSABLE so it does not inherit that exemption.

The payoff¶

The root’s on_update shrinks to pure game flow (game-over 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

# Anywhere, with the example library installed
simvx examples run tutorials_monolith_to_composed

Source¶

# /// simvx
# tags = ["tutorial", "architecture", "signals"]
# web = { width = 800, height = 600, responsive = true }
# ///
"""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: slide the paddle along the bottom with the arrow keys, A/D or a stick, or
hold the pointer (a finger on a phone) where you want it to go, 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. The
README walks through the refactor from the monolith; this file is the result.

## What you will learn

- **One node, one job.** `Player` moves, `Enemy` falls, `Spawner` produces enemies
  on a `Timer`, and `ScoreLabel` holds and draws the score. Each is short and can
  be tested on its own.
- **Paired signals.** Signals are declared at class scope (`escaped = Signal()`)
  and emitted with `emit` (`self.escaped.emit()`). Every one here has an emitter
  and a listener: `Spawner.spawned` reaches the root, which places the enemy;
  `Enemy.escaped` reaches `ScoreLabel.add`; `ScoreLabel.changed` reaches the root,
  which shortens the spawn delay as the score rises. A signal with no listener,
  or a listener with no emitter, is a sign the structure is wrong.
- **The root owns the graph, not the state.** `DodgeGame` 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.** Every gameplay node lives under one
  `World` node with `update_mode=UpdateMode.PAUSABLE`, so a hit sets
  `tree.paused` and the spawner, the enemies and the scoring all stop at once.
  The root declares `update_mode = Property(UpdateMode.ALWAYS)`, so it keeps
  ticking through the pause and hears Enter or a tap, which destroys `World` and
  builds a fresh round.
"""

import random

from simvx.core import Axis1D, Controller, Input, Key, Node, Node2D, Pointer, Property, Signal, Timer, UpdateMode, Vec2
from simvx.graphics import App

PLAYER_SIZE = Vec2(80, 16)
ENEMY_SIZE = Vec2(40, 40)


class Player(Node2D):
    """Moves left and right, from the `move` action or toward a held pointer."""

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

    def on_update(self, dt: float):
        dx = Input.value("move")
        if Input.pressed("steer"):
            dx = max(-1.0, min(1.0, (Input.mouse_position.x - self.position.x) / 32.0))
        half = PLAYER_SIZE.x / 2
        x = max(half, min(self.viewport_size.x - half, self.position.x + dx * self.speed * dt))
        self.position = (x, self.position.y)

    def on_draw(self, renderer):
        renderer.rect(-PLAYER_SIZE / 2, PLAYER_SIZE, fill=(0.5, 0.9, 1.0, 1))


class Enemy(Node2D):
    """Falls straight down and announces when it leaves the bottom of the screen."""

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

    escaped = Signal()

    def on_update(self, dt: float):
        self.position += (0, self.speed * dt)
        if self.position.y > self.viewport_size.y + ENEMY_SIZE.y:
            self.escaped.emit()
            self.destroy()

    def on_draw(self, renderer):
        renderer.rect(-ENEMY_SIZE / 2, ENEMY_SIZE, fill=(1.0, 0.4, 0.3, 1))


class Spawner(Node):
    """Draws nothing: after each random delay it emits a new Enemy for the root to place."""

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

    spawned = Signal(Enemy)

    def on_ready(self):
        self.timer = self.add_child(Timer(duration=self.min_delay, one_shot=False, autostart=True))
        self.timer.timeout.connect(self.spawn)

    def spawn(self):
        x = random.uniform(20, self.viewport_size.x - 20)
        self.spawned.emit(Enemy(speed=random.uniform(150, 300), position=(x, -ENEMY_SIZE.y)))
        self.timer.duration = random.uniform(self.min_delay, self.max_delay)


class ScoreLabel(Node2D):
    """Holds the score and draws it; announces each change."""

    score = Property(0)

    changed = Signal(int)

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

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


class DodgeGame(Node2D):
    """Builds each round, wires its signals, and checks the one collision only it can see."""

    # Keeps ticking while the tree is paused, so it can hear the restart.
    update_mode = Property(UpdateMode.ALWAYS)
    game_over = Property(False)

    # `steer` and `restart` share the primary pointer, so a finger both plays and starts again.
    input_context = {
        "move": [Axis1D(low=Key.A, high=Key.D), Axis1D(low=Key.LEFT, high=Key.RIGHT), Controller.LEFT_X],
        "steer": [Pointer.PRIMARY],
        "restart": [Key.ENTER, Pointer.PRIMARY],
    }

    def on_ready(self):
        self.start_round()

    def start_round(self):
        self.game_over = False
        self.tree.paused = False
        # 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", update_mode=UpdateMode.PAUSABLE))
        width, height = self.viewport_size
        self.player = self.world.add_child(Player(position=(width / 2, height - 60)))
        self.score = self.world.add_child(ScoreLabel())
        self.spawner = self.world.add_child(Spawner())
        self.spawner.spawned.connect(self.place_enemy)
        self.score.changed.connect(self.ramp_difficulty)

    def place_enemy(self, enemy: Enemy):
        enemy.escaped.connect(self.score.add)
        self.world.add_child(enemy)

    def ramp_difficulty(self, score: int):
        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 self.game_over:
            if Input.just_pressed("restart"):
                self.world.destroy()
                self.start_round()
            return
        reach = (PLAYER_SIZE + ENEMY_SIZE) / 2
        for enemy in self.world.find_all(Enemy, direct=True):
            gap = abs(enemy.position - self.player.position)
            if gap.x < reach.x and gap.y < reach.y:
                self.game_over = True
                self.tree.paused = True
                return

    def on_draw(self, renderer):
        width, height = self.viewport_size
        renderer.rect((0, 0), (width, height), fill=(0.05, 0.05, 0.08, 1))
        if self.game_over:
            renderer.text(
                "Game Over: Enter or tap to restart",
                (width / 2, height / 2),
                fill=(1, 1, 0.3, 1),
                scale=2,
                align="centre",
            )


if __name__ == "__main__":
    App(title="Monolith to Composed", width=800, height=600).run(DodgeGame())