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, the arrow keys, a controller’s left stick or the on-screen stick to move; Space, Enter, a tap or a controller’s A button to start and restart; Escape to quit.

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
One typed move action carried by the player’s own InputContext, fed by the keys, a controller’s stick and the drawn TouchController alike
A game-over cue synthesised at load time with AudioSynth, so no third-party sound file is bundled

Run: simvx examples run ports_dodge_the_creeps simvx examples run ports_dodge_the_creeps –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.	353
`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.	89
`nodes/mob.py`	Mob: fly/walk/swim creep that drifts across the screen at a fixed velocity.	73
`nodes/player.py`	Player: moves with keys, a stick or the drawn pad, and emits `hit`.	160
`nodes/sprite_sheets.py`	Build horizontal sprite-sheet ndarrays from individual PNG files.	64

Source¶

#!/usr/bin/env python3
# /// 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 }
# ///
"""Dodge the Creeps: Godot's first 2D tutorial, wandering mobs, top-down dodge.

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, the arrow keys, a controller's left stick or the on-screen stick
to move; Space, Enter, a tap or a controller's A button to start and restart;
Escape to quit.

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
- One typed ``move`` action carried by the player's own ``InputContext``, fed by
  the keys, a controller's stick and the drawn ``TouchController`` alike
- A game-over cue synthesised at load time with ``AudioSynth``, so no
  third-party sound file is bundled

Run:
    simvx examples run ports_dodge_the_creeps
    simvx examples run ports_dodge_the_creeps --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

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 AudioClip, AudioPlayer, Camera2D, Controller, Input, Key, Mouse, Node, Timer, Vec2
from simvx.core.ui import Anchor, Panel, PointerFilter, TouchController  # noqa: E402
from simvx.graphics import App  # noqa: E402

# Startup window size only. Nothing in the game reads these: layout and
# gameplay bounds come from the live `viewport_size`.
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", anchor=Anchor.FULL_RECT, **kwargs)
        self.bg_colour = self.BG
        # Nothing but scenery, so a tap passes through it to the game rather
        # than being swallowed by a full-screen panel.
        self.pointer_filter = PointerFilter.IGNORE


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


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

    # What the scene itself answers for. The tree registers these when it takes
    # the root, so a web export and a test that loads this scene both get them
    # without anything being declared from `main()`. Moving is the player's
    # own business and lives on the player (see `nodes/player.py`).
    #
    # Starting takes a tap as well as a key, because the web runtime delivers
    # touch as a left click, and a pad button, because a controller player has
    # to be able to get into the game.
    input_context = {
        "start": [Key.SPACE, Key.ENTER, Mouse.LEFT, Controller.A, Controller.START],
        "quit": [Key.ESCAPE],
    }

    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)
    SPAWN_HEIGHT = 270.0  # how far above the bottom edge the player starts

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

    def on_ready(self):
        # 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.
        width, height = self.viewport_size
        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(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)

        # The pad on the glass. It publishes a real controller, so the player's
        # `Controller.LEFT_STICK` binding and this scene's `Controller.A` already
        # read it and nothing further is wired. It removes itself the moment a
        # real controller is used.
        self.add_child(TouchController(buttons=(Controller.A,)))

        # 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(duration=self.SPAWN_INTERVAL, one_shot=False, name="MobTimer"))
        self.mob_timer.timeout.connect(self._on_mob_timer)

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

        self.start_timer = self.add_child(Timer(duration=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 _new_game(self):
        if self._game_active:
            return
        # Clear any leftover mobs from a previous run.
        for mob in 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")
        width, height = self.viewport_size
        self.player.start(Vec2(width / 2, height - self.SPAWN_HEIGHT))
        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.
        width, height = self.viewport_size
        edge = random.randrange(4)
        if edge == 0:
            pos = Vec2(random.uniform(0, width), -40)
            direction = math.pi / 2  # downward
        elif edge == 1:
            pos = Vec2(width + 40, random.uniform(0, height))
            direction = math.pi  # leftward
        elif edge == 2:
            pos = Vec2(random.uniform(0, width), height + 40)
            direction = -math.pi / 2  # upward
        else:
            pos = Vec2(-40, random.uniform(0, height))
            direction = 0.0  # rightward
        direction += random.uniform(-math.pi / 4, math.pi / 4)
        speed = random.uniform(*self.MOB_SPEED_RANGE)
        mob = Mob(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.emit()

    def on_update(self, dt: float):
        # Keep the camera centred on the live window so resize works.
        width, height = self.viewport_size
        self.camera.position = Vec2(width / 2, height / 2)

        if Input.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):
        sw, sh = self.viewport_size

        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.text(text, (sw / 2 - w / 2, y), fill=colour, scale=scale)

        # Splash text: title + (optional) prompt, vertically stacked, centred.
        if self.hud.message_visible and self.hud.message_text:
            prompt = "Tap, or press [Space] / [A]"
            title_scale = fit(self.hud.message_text, target_w=sw * 0.85, max_scale=6)
            prompt_scale = fit(prompt, 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(prompt, prompt_scale, y, colour=self.HINT_COLOUR)

        # Controls panel: top-left, vertical, left-justified. The bottom of the
        # screen belongs to the on-screen pad, so the help sits clear of it.
        lines = ["WASD/ARROWS/STICK: MOVE", "SPACE/TAP/A: START", "ESC: QUIT"]
        widest = max(lines, key=len)
        scale = fit(widest, target_w=sw * 0.45, max_scale=2)
        y = 8.0
        for line in lines:
            renderer.text(line, (8.0, y), fill=self.HINT_COLOUR, scale=scale)
            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()