Dodge the Creeps¶

Godot’s first 2D tutorial, wandering mobs, top-down dodge.

Upstream: https://github.com/godotengine/godot-demo-projects/tree/master/2d/dodge_the_creeps

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

A from-scratch re-implementation of the Godot “Your first 2D game” demo on SimVX. Survive as long as you can: creeps spawn at the screen edges twice a second and drift across the play field, and your score ticks up once per second until one of them touches you.

Controls: WASD or the arrow keys to move; Space, Enter, or a click to start and restart; Escape to quit. On touch screens, press and hold to steer towards your finger.

What it demonstrates:

Node hierarchy with signals (Player.hit, HUD.start_game) and groups
AnimatedSprite2D flipbook animation stitched from individual PNG frames
Timer nodes plus a coroutine (wait, wait_signal) driving game over
Anchored Control / Label UI that survives window resizing
Action-based input (InputMap, Input.get_vector) shared by desktop, web and touch
A game-over cue synthesised at load time with AudioSynth, so no third-party sound file is bundled

Run: uv run python examples/ports/dodge_the_creeps/main.py uv run python examples/ports/dodge_the_creeps/main.py –test # headless smoke run

Art by Kenney (CC0); music “House In a Forest Loop” by HorrorPen (CC-BY 3.0). See ATTRIBUTION.md for the full upstream credits and licences.

Source files¶

File	Summary	Lines
`main.py`	Dodge the Creeps: Godot’s first 2D tutorial, wandering mobs, top-down dodge.	367
`capture.py`	Headless screenshot capture for Dodge the Creeps.	31
`nodes/__init__.py`	Node modules for the Dodge the Creeps SimVX port.	1
`nodes/audio.py`	Procedural audio: built on the engine’s AudioSynth API.	67
`nodes/hud.py`	HUD: anchored Label widgets for score / message / start prompt.	88
`nodes/mob.py`	Mob: fly/walk/swim creep that drifts across the screen at a fixed velocity.	74
`nodes/player.py`	Player: moves with WASD/arrows, plays walk/up animations, emits `hit`.	142
`nodes/sprite_sheets.py`	Build horizontal sprite-sheet ndarrays from individual PNG files.	64

Source¶

#!/usr/bin/env python3
"""Dodge the Creeps: Godot's first 2D tutorial, wandering mobs, top-down dodge.

# /// simvx
# tags = ["port", "tier-0"]
# upstream = "https://github.com/godotengine/godot-demo-projects/tree/master/2d/dodge_the_creeps"
# web = { width = 480, height = 720, responsive = true }
# ///

A from-scratch re-implementation of the Godot "Your first 2D game" demo on SimVX.
Survive as long as you can: creeps spawn at the screen edges twice a second and
drift across the play field, and your score ticks up once per second until one of
them touches you.

Controls: WASD or the arrow keys to move; Space, Enter, or a click to start and
restart; Escape to quit. On touch screens, press and hold to steer towards your
finger.

What it demonstrates:

- Node hierarchy with signals (``Player.hit``, ``HUD.start_game``) and groups
- ``AnimatedSprite2D`` flipbook animation stitched from individual PNG frames
- ``Timer`` nodes plus a coroutine (``wait``, ``wait_signal``) driving game over
- Anchored ``Control`` / ``Label`` UI that survives window resizing
- Action-based input (``InputMap``, ``Input.get_vector``) shared by desktop, web
  and touch
- A game-over cue synthesised at load time with ``AudioSynth``, so no
  third-party sound file is bundled

Run:
    uv run python examples/ports/dodge_the_creeps/main.py
    uv run python examples/ports/dodge_the_creeps/main.py --test   # headless smoke run

Art by Kenney (CC0); music "House In a Forest Loop" by HorrorPen (CC-BY 3.0).
See ATTRIBUTION.md for the full upstream credits and licences.
"""

# /// script
# requires-python = ">=3.14"
# dependencies = [
#     "simvx-core",
#     "simvx-graphics",
#     "numpy",
#     "pillow",
# ]
# ///

from __future__ import annotations

import math
import random
import sys
from pathlib import Path

# Allow running this file directly (without an installed package) by exposing
# the `nodes` subpackage as a top-level module group.
sys.path.insert(0, str(Path(__file__).resolve().parent))

from nodes.audio import make_gameover  # noqa: E402
from nodes.hud import HUD  # noqa: E402
from nodes.mob import Mob  # noqa: E402
from nodes.player import Player  # noqa: E402

from simvx.core import (  # noqa: E402
    AudioClip,
    AudioPlayer,
    Camera2D,
    Input,
    InputMap,
    Key,
    MouseButton,
    Node,
    Timer,
    Vec2,
)
from simvx.core.ui import AnchorPreset, Panel  # noqa: E402
from simvx.graphics import App  # noqa: E402

WIDTH, HEIGHT = 480, 720
ASSETS = Path(__file__).resolve().parent / "assets"


# ---------------------------------------------------------------------------
# Background: a solid colour rectangle behind everything else, anchored to
# the full viewport so it scales with the window. Mirrors the Godot demo's
# ColorRect at (0.219608, 0.372549, 0.380392).
# ---------------------------------------------------------------------------


class Background(Panel):
    BG = (0.219608, 0.372549, 0.380392, 1.0)

    def __init__(self, **kwargs):
        super().__init__(name="Background", **kwargs)
        self.set_anchor_preset(AnchorPreset.FULL_RECT)
        self.bg_colour = self.BG


# ---------------------------------------------------------------------------
# Main scene
# ---------------------------------------------------------------------------


class Main(Node):
    """Root scene. Owns the player, mob spawner, score timer, and HUD."""

    SPAWN_INTERVAL = 0.5  # seconds; Godot MobTimer.wait_time
    SCORE_INTERVAL = 1.0  # seconds; Godot ScoreTimer default
    START_DELAY = 2.0  # seconds; Godot StartTimer.wait_time
    MOB_SPEED_RANGE = (150.0, 250.0)
    START_POSITION = Vec2(WIDTH / 2, HEIGHT - 270)  # ~(240, 450)

    def __init__(self, **kwargs):
        super().__init__(name="Main", **kwargs)
        self.score = 0
        self._game_active = False

    def on_ready(self):
        # Input map: must live in on_ready so the web exporter picks it up.
        InputMap.add_action("move_left", [Key.A, Key.LEFT])
        InputMap.add_action("move_right", [Key.D, Key.RIGHT])
        InputMap.add_action("move_up", [Key.W, Key.UP])
        InputMap.add_action("move_down", [Key.S, Key.DOWN])
        InputMap.add_action("start_game", [Key.SPACE, Key.ENTER])
        InputMap.add_action("restart_click", [MouseButton.LEFT])
        # Mobile / touch: left-click-and-hold steers the player toward the
        # cursor. Touches surface as MouseButton.LEFT in the web runtime.
        InputMap.add_action("touch_move", [MouseButton.LEFT])
        InputMap.add_action("quit", [Key.ESCAPE])

        # Background (anchored, scales with window).
        self.add_child(Background())

        # Camera: keeps the world in screen pixels.  Position is updated each
        # frame in on_update so the world centres on the live window.
        self.camera = self.add_child(Camera2D(name="Camera", position=Vec2(WIDTH / 2, HEIGHT / 2)))

        # Player: registered first so HUD draws on top of it.
        self.player = self.add_child(Player(screen_size=Vec2(WIDTH, HEIGHT), name="Player"))
        self.player.hit.connect(self._on_player_hit)

        # HUD: anchored Control widgets (Label).
        self.hud = self.add_child(HUD())
        self.hud.start_game.connect(self._new_game)

        # Audio: bundled music streams from disk; the death cue is synthesised
        # at load time (no third-party sound file is bundled).
        self.music = self._make_audio("House In a Forest Loop.ogg", loop=True, volume_db=-8.0)
        self.death_sound = self.add_child(
            AudioPlayer(
                stream=make_gameover(),
                loop=False,
                autoplay=False,
                volume_db=-2.0,
                name="death_sound",
            )
        )

        # Mob spawn / score timers.
        self.mob_timer = self.add_child(Timer(self.SPAWN_INTERVAL, one_shot=False, name="MobTimer"))
        self.mob_timer.timeout.connect(self._on_mob_timer)

        self.score_timer = self.add_child(Timer(self.SCORE_INTERVAL, one_shot=False, name="ScoreTimer"))
        self.score_timer.timeout.connect(self._on_score_timer)

        self.start_timer = self.add_child(Timer(self.START_DELAY, one_shot=True, name="StartTimer"))
        self.start_timer.timeout.connect(self._on_start_timer)

        # The root's on_draw renders the splash from the HUD's plain-attribute
        # state (message_text / message_visible / show_prompt), which the HUD
        # mutates on its OWN schedule -- a message-fade Timer and the game-over
        # coroutine -- with no Property write to auto-dirty this node. Those
        # cross-node pokes can't cleanly reach the root, so mark the root
        # `dynamic`: its on_draw re-captures every frame (a cheap per-node patch
        # of a few text ops; the rest of the scene still frame-skips) and the
        # splash can never freeze mid-transition.
        self.dynamic = True

        # Splash screen, identical to Godot's: title visible, prompt visible,
        # waiting for input.
        self.player.kill()
        self.hud.message_text = "Dodge the Creeps"
        self.hud.message_visible = True
        self.hud.show_prompt = True

    # ------------------------------------------------------------------
    # Audio helpers
    # ------------------------------------------------------------------

    def _make_audio(self, name: str, *, loop: bool, volume_db: float) -> AudioPlayer | None:
        path = ASSETS / name
        if not path.exists():
            return None
        try:
            stream = AudioClip(str(path))
        except Exception:
            return None
        return self.add_child(
            AudioPlayer(
                stream=stream,
                loop=loop,
                autoplay=False,
                volume_db=volume_db,
                name=path.stem.replace(" ", "_"),
            )
        )

    # ------------------------------------------------------------------
    # Game flow
    # ------------------------------------------------------------------

    def _live_size(self):
        """Current window dimensions in pixels."""
        if self.tree:
            return float(self.tree.screen_size[0]), float(self.tree.screen_size[1])
        return float(WIDTH), float(HEIGHT)

    def _new_game(self):
        if self._game_active:
            return
        # Clear any leftover mobs from a previous run.
        for mob in list(self.tree.group("mobs")):
            mob.destroy()
        self.score = 0
        self.hud.update_score(self.score)
        self.hud.hide_start_prompt()
        self.hud.show_message("Get Ready")
        # Start position derived from current window size, not the baked WIDTH/HEIGHT.
        sw, sh = self._live_size()
        self.player.start(Vec2(sw / 2, sh - 270))
        self._game_active = True
        self.start_timer.start()
        if self.music is not None:
            self.music.play()

    def _on_start_timer(self):
        self.mob_timer.start()
        self.score_timer.start()

    def _on_score_timer(self):
        self.score += 1
        self.hud.update_score(self.score)

    def _on_mob_timer(self):
        # Pick a random edge: 0=top, 1=right, 2=bottom, 3=left, then a random
        # offset along that edge. Direction is the inward normal plus a small
        # random spread. Bounds come from the live window size.
        sw, sh = self._live_size()
        edge = random.randrange(4)
        if edge == 0:
            pos = Vec2(random.uniform(0, sw), -40)
            direction = math.pi / 2  # downward
        elif edge == 1:
            pos = Vec2(sw + 40, random.uniform(0, sh))
            direction = math.pi  # leftward
        elif edge == 2:
            pos = Vec2(random.uniform(0, sw), sh + 40)
            direction = -math.pi / 2  # upward
        else:
            pos = Vec2(-40, random.uniform(0, sh))
            direction = 0.0  # rightward
        direction += random.uniform(-math.pi / 4, math.pi / 4)
        speed = random.uniform(*self.MOB_SPEED_RANGE)
        mob = Mob(screen_size=Vec2(sw, sh), name="Mob")
        self.add_child(mob)
        mob.configure(pos, direction, speed)

    def _on_player_hit(self):
        # Triggered by Main when overlap is detected; the player has already
        # been hidden via kill().
        if not self._game_active:
            return
        self._game_active = False
        self.mob_timer.stop()
        self.score_timer.stop()
        self.hud.show_game_over()
        if self.music is not None:
            self.music.stop()
        if self.death_sound is not None:
            self.death_sound.play()
        # `show_game_over` re-raises the restart prompt once its coroutine has
        # run its course, and the HUD only emits `start_game` while the prompt
        # is up, so restart input re-enables itself with no extra timer here.

    # ------------------------------------------------------------------
    # Per-frame logic
    # ------------------------------------------------------------------

    def on_fixed_update(self, dt: float):
        # Player-mob collision via a circle-overlap test over the "mobs" group.
        if self._game_active and self.player.overlapping_mobs():
            self.player.kill()
            self.player.hit()

    def on_update(self, dt: float):
        # Keep the camera centred on the live window so resize works.
        if self.tree:
            sw, sh = self._live_size()
            self.camera.position = Vec2(sw / 2, sh / 2)

        if Input.is_action_just_pressed("quit"):
            self.app.quit()

    HINT_COLOUR = (0.70, 0.70, 0.70, 1.0)
    WHITE = (1.0, 1.0, 1.0, 1.0)

    def on_draw(self, renderer):
        if self.tree is None:
            return
        sw, sh = float(self.tree.screen_size[0]), float(self.tree.screen_size[1])

        def line_h(s):
            return s * 16

        def fit(text: str, target_w: float, max_scale: int) -> int:
            for s in range(max_scale, 0, -1):
                if renderer.text_width(text, s) <= target_w:
                    return s
            return 1

        def draw_centered(text: str, scale: int, y: float, colour=self.WHITE):
            w = renderer.text_width(text, scale)
            renderer.draw_text(text, (sw / 2 - w / 2, y), scale=scale, colour=colour)

        # Splash text: title + (optional) prompt, vertically stacked, centred.
        if self.hud.message_visible and self.hud.message_text:
            title_scale = fit(self.hud.message_text, target_w=sw * 0.85, max_scale=6)
            prompt_scale = fit("Press [Space] / Click", target_w=sw * 0.9, max_scale=2)
            block_h = line_h(title_scale)
            if self.hud.show_prompt:
                block_h += 24 + line_h(prompt_scale)
            y = sh / 2 - block_h / 2
            draw_centered(self.hud.message_text, title_scale, y, colour=self.WHITE)
            y += line_h(title_scale) + 24
            if self.hud.show_prompt:
                draw_centered("Press [Space] / Click", prompt_scale, y, colour=self.HINT_COLOUR)

        # Controls panel: bottom-right, vertical, left-justified.
        lines = ["WASD/ARROWS: MOVE", "SPACE: START", "ESC: QUIT"]
        widest = max(lines, key=len)
        scale = fit(widest, target_w=sw * 0.30, max_scale=2)
        widest_w = renderer.text_width(widest, scale)
        panel_x = sw - widest_w - 8
        y = sh - line_h(scale) * len(lines) - 8
        for line in lines:
            renderer.draw_text(line, (panel_x, y), scale=scale, colour=self.HINT_COLOUR)
            y += line_h(scale)


# ---------------------------------------------------------------------------
# Entry point
# ---------------------------------------------------------------------------


def main():
    test_mode = "--test" in sys.argv
    app = App(width=WIDTH, height=HEIGHT, title="Dodge the Creeps", visible=not test_mode)
    if test_mode:
        # Render N frames headlessly, then exit cleanly.
        app.run_headless(Main(), frames=120)
        # No app.quit() needed; run_headless tears down the app on return.
    else:
        app.run(Main())


if __name__ == "__main__":
    main()