Mr. Rescue¶

Arcade firefighting in a procedurally generated burning building.

Upstream: https://github.com/SimonLarsen/mrrescue

Licence: this port's own code is offered under MIT, not the SimVX Examples Licence the rest of the gallery carries. See ATTRIBUTION.md for the upstream it re-implements, the terms of anything it bundles, and the credit each one requires.

Ports live in the repository only, not in the simvx-examples distribution, because each is a derivative work licensed individually against the game it re-implements. Read it with git clone https://git.simvx.com/simvx/simvx.

Tags: port tier-2

Mr. Rescue: SimVX port¶

A SimVX port of Mr. Rescue by Simon Larsen: an arcade firefighter platformer where you spray water at spreading fires and carry civilians out of a procedurally-stitched 3-storey building before your suit overheats.

Run¶

# from the repo root
uv run python examples/ports/mr_rescue/main.py            # interactive
uv run python examples/ports/mr_rescue/main.py --test     # headless capture (8 stages)
uv run simvx export web examples/ports/mr_rescue/main.py \
    -o /tmp/mr_rescue.html

Controls¶

Key	Action
Arrow keys / WASD	Move horizontally, climb ladders, aim gun up/down
Space	Jump
Shift	Spray water (drains the tank; it overloads when empty)
E	Grab a civilian / throw the carried one
Enter, Space or click	Confirm in menus
Esc	Quit

What it shows¶

Procedural everything. Tiles, characters, the night skyline and the building layout are generated at runtime as NumPy uint8 RGBA; the SFX and the ambient music bed are synthesized with AudioSynth. No asset files ship with the port.
Game feel. Coyote time and jump buffering on the tile-grid platforming, Camera2D follow with clamping and screenshake, and hitstop that freezes the gameplay subtree (via UpdateMode.DISABLED) on rescues and kills.
Scene structure. A root phase machine swaps title / game / end scenes and listens to Signals for victory and failure; the gameplay scene listens to the player’s, civilians’ and enemies’ own signals for score, audio and particles.
Screen-space UI. The HUD lives on the gameplay scene’s own CanvasLayer and lays out against the live framebuffer size, so it tracks a resized desktop window or a responsive web canvas.

Notes¶

The port keeps one enemy type (the fire bug) rather than upstream’s six, and leaves out the bosses, the lightmap, the on-screen joystick UI and the licensed music tracks. Fire spread, the heat/water economy, ladders and the carry-and- throw rescue loop all follow upstream’s design.

License: port code under MIT (see LICENSE). It mirrors upstream’s zlib gameplay design, with CC-BY-SA 3.0 attribution to Simon Larsen for the original concept and visual reference; no upstream art is reused, as every texture is procedural. See ATTRIBUTION.md.

Source files¶

File	Summary	Lines
`main.py`	Mr. Rescue: Arcade firefighting in a procedurally generated burning building.	213
`harness.py`	Scripted headless playthrough: the implementation behind `main.py --test`.	233
`nodes/__init__.py`		0
`nodes/audio.py`	Procedural audio for Mr. Rescue: synthesized SFX + a looping ambient bed.	213
`nodes/building.py`	Procedural multi-floor building generator.	328
`nodes/civilian.py`	Civilian: IDLE/WALK/PANIC/BURN/CARRIED/FLY state machine.	204
`nodes/colours.py`	Mr. Rescue palette: warm-on-charcoal arcade pixels.	94
`nodes/enemy.py`	FireBug: single enemy type (port collapses upstream’s 6 to one).	149
`nodes/fire.py`	Fire grid: sparse cell map of flames with health and spread timers.	221
`nodes/game.py`	Active gameplay scene: wires together grid, fires, player, civilians, enemies.	467
`nodes/hud.py`	HUD: top status strip + bottom water/heat/casualty bar.	198
`nodes/menu.py`	Title and end screens.	233
`nodes/particles.py`	CPU particle pool: water mist, smoke, sparkles, ash.	141
`nodes/player.py`	Firefighter player: state machine + water gun raycast.	693
`nodes/textures.py`	Procedural NumPy textures.	593
`nodes/tile_grid.py`	Tile grid + collision for the building.	188

Source¶

#!/usr/bin/env python3
"""Mr. Rescue: Arcade firefighting in a procedurally generated burning building.

A port of Simon Larsen's "Mr. Rescue": spray water at flames that spread cell to
cell, carry civilians out through the roof, and get clear before your suit
overheats. Everything is generated at runtime: NumPy pixel-art textures,
synthesized SFX and music, and a randomised three-storey building. Shows
tile-grid platforming with coyote time and jump buffering, Camera2D follow with
screenshake and hitstop, a CanvasLayer HUD, signal-driven scene flow
(menu, game, end), and bloom via WorldEnvironment.

# /// simvx
# tags = ["port", "tier-2"]
# upstream = "https://github.com/SimonLarsen/mrrescue"
# web = { width = 1024, height = 800, responsive = true }
# ///

Run interactively::

    uv run python examples/ports/mr_rescue/main.py

Headless smoke test (captures stage screenshots into ``screenshots/``)::

    uv run python examples/ports/mr_rescue/main.py --test

Web export::

    uv run simvx export web examples/ports/mr_rescue/main.py -o /tmp/mr_rescue.html

Controls
--------
- Arrow keys / WASD: move, aim the gun, climb ladders
- Space: jump
- Shift: spray water
- E: grab / throw the carried civilian
- Enter, Space or click / tap: confirm in menus
- Esc: quit
"""

from __future__ import annotations

import sys
from pathlib import Path

# Make the port folder importable in --test and direct runs alike.
_PORT_DIR = Path(__file__).resolve().parent
if str(_PORT_DIR) not in sys.path:
    sys.path.insert(0, str(_PORT_DIR))

from nodes import colours as C
from nodes.audio import get_sfx
from nodes.game import GameScene
from nodes.menu import EndScreen, TitleScreen

from simvx.core import (
    AudioPlayer,
    Input,
    InputMap,
    Key,
    MouseButton,
    Node,
)
from simvx.core.world_environment import WorldEnvironment
from simvx.graphics import App

WINDOW_W = 1024
WINDOW_H = 800


# ---------------------------------------------------------------------------- root


class MrRescueRoot(Node):
    """Phase machine: menu → game → end."""

    def __init__(self, *, seed: int | None = None, **kwargs):
        super().__init__(**kwargs)
        self.phase = "menu"
        self.section = 1
        self._seed = seed
        self.scene: Node | None = None
        self._menu_sfx = None

    def on_ready(self):
        # InputMap MUST live in on_ready (web exporter skips main()).
        InputMap.add_action("left", [Key.LEFT, Key.A])
        InputMap.add_action("right", [Key.RIGHT, Key.D])
        InputMap.add_action("up", [Key.UP, Key.W])
        InputMap.add_action("down", [Key.DOWN, Key.S])
        InputMap.add_action("jump", [Key.SPACE])
        InputMap.add_action("shoot", [Key.LEFT_SHIFT, Key.RIGHT_SHIFT])
        InputMap.add_action("grab", [Key.E])
        # Menus confirm on a click/tap too (touch arrives as MouseButton.LEFT on
        # web), so the responsive export is reachable without a keyboard.
        InputMap.add_action("start", [Key.ENTER, Key.SPACE, MouseButton.LEFT])
        InputMap.add_action("quit", [Key.ESCAPE])

        env = self.add_child(WorldEnvironment())
        env.sky_mode = "disabled"
        env.tonemap_mode = "aces"
        env.tonemap_exposure = 1.05
        env.bloom_enabled = True
        env.bloom_threshold = 0.78
        env.bloom_intensity = 0.52
        env.bloom_soft_knee = 0.5

        # One-shot menu confirm cue (gameplay SFX live on the GameScene's bank).
        self._menu_sfx = self.add_child(AudioPlayer(stream=get_sfx("menu_confirm"), bus="SFX"))

        # The HUD is owned by the GameScene (in its own CanvasLayer) so it is
        # created and destroyed with the game phase: clean lifecycle, with no HUD
        # state to reset between phases.
        self._enter_menu()

    # ----------------------------------------------------------- phase swaps

    def _drop_sub(self):
        # Destroying the sub-scene takes its Camera2D with it, and Camera2D's
        # teardown releases the tree's active-camera slot, so the menu phases
        # come back up in screen space with no extra bookkeeping here.
        if self.scene is not None:
            self.scene.destroy()
            self.scene = None

    def _enter_menu(self):
        self.phase = "menu"
        self._drop_sub()
        self.section = 1
        ts = TitleScreen()
        ts.start.connect(self._enter_game)
        self.add_child(ts)
        self.scene = ts

    def _play_menu_sfx(self):
        if self._menu_sfx is not None:
            self._menu_sfx.play()

    def _restart(self):
        self._play_menu_sfx()
        self._enter_menu()

    def _enter_game(self):
        self.phase = "game"
        self._play_menu_sfx()
        self._drop_sub()
        game = GameScene(
            viewport_w=WINDOW_W,
            viewport_h=WINDOW_H,
            section=self.section,
            level=1,
            seed=self._seed,
        )
        game.victory.connect(self._on_victory)
        game.failure.connect(self._on_failure)
        self.add_child(game)
        self.scene = game

    def _on_victory(self):
        self._enter_end(victory=True, reason="ALL CIVILIANS RESCUED")

    def _on_failure(self, reason: str):
        msg = {
            "casualty": "TOO MANY CIVILIANS LOST",
            "overheat": "YOUR SUIT OVERHEATED",
        }.get(reason, "")
        self._enter_end(victory=False, reason=msg)

    def _enter_end(self, *, victory: bool, reason: str):
        self.phase = "end"
        # Snapshot stats before we drop the game scene (only it ends the run).
        game = self.scene
        rescued = max(0, game.civilians_total - game.casualties - len(game.civilians))
        es = EndScreen(
            victory=victory,
            score=game.score,
            rescued=rescued,
            civilians_total=game.civilians_total,
            casualties=game.casualties,
            reason=reason,
        )
        self._drop_sub()
        es.restart.connect(self._restart)
        self.add_child(es)
        self.scene = es

    # ----------------------------------------------------------- update

    def on_update(self, dt: float):
        if Input.is_action_just_pressed("quit"):
            if self.app is not None:
                self.app.quit()


# --------------------------------------------------------------------- entry


def main():
    if "--test" in sys.argv:
        from harness import capture_playthrough

        capture_playthrough(
            MrRescueRoot,
            window_size=(WINDOW_W, WINDOW_H),
            bg_colour=C.BG,
            out_dir=_PORT_DIR / "screenshots",
        )
        return
    app = App(title="Mr. Rescue", width=WINDOW_W, height=WINDOW_H, bg_colour=C.BG)
    app.run(MrRescueRoot())


if __name__ == "__main__":
    main()