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 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
`DodgeGame` (root)	own the graph and the one thing only it can see: collision

Signals connect them¶

Each node stays ignorant of the others; the root wires them with signals:

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.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.

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¶

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) 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** -- every signal 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.
"""

import random

from simvx.core import Input, Key, Node2D, Property, Signal, 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")
        new_x = self.position.x + dx * float(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."""

    def __init__(self, speed_value: float, **kwargs):
        super().__init__(**kwargs)
        self._speed = speed_value
        self.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)

    def on_ready(self):
        self._timer = 0.0
        self.spawned = Signal()  # carries the new Enemy node

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


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

    score = Property(0)

    def on_ready(self):
        self.changed = Signal()

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

    def on_draw(self, renderer):
        renderer.draw_text(f"Score: {int(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],
    }

    def on_ready(self):
        self._start()

    def _start(self):
        self.alive = True
        self.player = self.add_child(Player(position=Vec2(WIDTH / 2, HEIGHT - 60)))
        self.spawner = self.add_child(Spawner())
        self.score = self.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.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.clear_children()
                self._start()
            return
        px, py = self.player.position
        for child in list(self.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
                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 to restart", (WIDTH / 2 - 150, HEIGHT / 2), scale=2, colour=(1, 1, 0.3, 1)
            )


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