Squash the Creeps¶

a 3D arcade port of Godot’s first 3D game tutorial.

Upstream: https://github.com/godotengine/godot-demo-projects/tree/master/3d/squash_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 “Squash the Creeps”, the game built in Godot’s “Your First 3D Game” tutorial. Creeps march in from the arena edge; jump on one from above to squash it and score. Let one reach you on the ground, or wander off the arena yourself, and the run ends.

What it demonstrates:

A jump / gravity / bounce controller on CharacterBody3D.move_and_slide running against a static ground body
Collision layers plus a masked node.physics.overlap query for stomp and contact detection
Player, creeps and arena built entirely from procedural Mesh primitives
Timer-driven spawning and signal wiring (hit, squashed_mob)
A WorldEnvironment gradient sky with fog and ACES tonemapping, lit by a single directional sun
A resize-aware retained-2D HUD (on_draw plus queue_redraw) with text fitted to the window
Input latched on the frame clock so a tap survives the fixed physics step

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

Web export: uv run simvx export web examples/ports/squash_the_creeps/main.py -o /tmp/squash_the_creeps.html

Controls: WASD / arrows Move Drag Steer in the drag direction (mouse or touch) Space / tap Jump, and bounce when you land on a creep R / Enter / Space / tap Start, and restart after game over Esc Quit

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`	Squash the Creeps: a 3D arcade port of Godot’s first 3D game tutorial.	343
`nodes/__init__.py`	Squash the Creeps: node modules.	1
`nodes/arena.py`	Arena: static ground body, decorative pillars, lighting and sky.	182
`nodes/mob.py`	Mob: chases the player; dies when squashed or off-screen.	138
`nodes/player.py`	Player: a CharacterBody3D steered by keyboard or pointer, with jump and bounce.	260

Source¶

"""Squash the Creeps: a 3D arcade port of Godot's first 3D game tutorial.

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

A from-scratch re-implementation of "Squash the Creeps", the game built in
Godot's "Your First 3D Game" tutorial. Creeps march in from the arena edge;
jump on one from above to squash it and score. Let one reach you on the ground,
or wander off the arena yourself, and the run ends.

What it demonstrates:

- A jump / gravity / bounce controller on ``CharacterBody3D.move_and_slide``
  running against a static ground body
- Collision layers plus a masked ``node.physics.overlap`` query for stomp and
  contact detection
- Player, creeps and arena built entirely from procedural ``Mesh`` primitives
- ``Timer``-driven spawning and signal wiring (``hit``, ``squashed_mob``)
- A ``WorldEnvironment`` gradient sky with fog and ACES tonemapping, lit by a
  single directional sun
- A resize-aware retained-2D HUD (``on_draw`` plus ``queue_redraw``) with text
  fitted to the window
- Input latched on the frame clock so a tap survives the fixed physics step

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

Web export:
    uv run simvx export web examples/ports/squash_the_creeps/main.py -o /tmp/squash_the_creeps.html

Controls:
    WASD / arrows             Move
    Drag                      Steer in the drag direction (mouse or touch)
    Space / tap               Jump, and bounce when you land on a creep
    R / Enter / Space / tap   Start, and restart after game over
    Esc                       Quit

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

from __future__ import annotations

import os
import sys
from pathlib import Path

# Allow `python main.py` from anywhere: make the port directory importable
# so `nodes.player` etc. resolve regardless of cwd.
_PORT_DIR = Path(__file__).resolve().parent
if str(_PORT_DIR) not in sys.path:
    sys.path.insert(0, str(_PORT_DIR))

from nodes.arena import (  # noqa: E402
    CAMERA_FOV,
    PLAYER_MARGIN,
    Arena,
    camera_offset,
    is_off_arena,
    random_spawn_position,
)
from nodes.mob import Mob  # noqa: E402
from nodes.player import Player  # noqa: E402

from simvx.core import (  # noqa: E402
    AudioClip,
    AudioPlayer,
    Camera3D,
    Input,
    InputMap,
    Key,
    MouseButton,
    Node,
    Property,
    Text2D,
    Timer,
)
from simvx.graphics import App  # noqa: E402

ASSETS = _PORT_DIR / "assets"

VIEWPORT_W = 1024
VIEWPORT_H = 768

STATE_MENU = "menu"
STATE_PLAY = "play"
STATE_OVER = "over"

HINT_COLOUR = (0.70, 0.70, 0.70, 1.0)
# The controls panel sits over grass, sky and the bright arena edge strip, so
# it gets a dimming plate behind it rather than relying on the backdrop.
CONTROLS_COLOUR = (0.97, 0.97, 0.95, 1.0)
CONTROLS_PLATE = (0.0, 0.0, 0.0, 0.62)


class SquashTheCreeps(Node):
    """Top-level game scene."""

    spawn_interval = Property(
        0.5,
        range=(0.1, 5.0),
        hint="Seconds between mob spawns",
        on_change="_on_spawn_interval_changed",
    )

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self._score = 0
        self._state = STATE_MENU
        self._screen_w = VIEWPORT_W
        self._screen_h = VIEWPORT_H

        self._arena = self.add_child(Arena(name="Arena"))

        cam_pos, cam_target = camera_offset()
        self._camera = self.add_child(Camera3D(name="Camera", position=cam_pos, fov=CAMERA_FOV, far=120.0))
        self._camera.look_at(cam_target)

        self._player = self.add_child(Player(name="Player"))
        self._player.hit.connect(self._on_player_hit)
        self._player.squashed_mob.connect(self._on_mob_squashed)

        # Spawn timer: paused until the player leaves the menu.
        self._mob_timer = self.add_child(
            Timer(duration=self.spawn_interval, one_shot=False, autostart=False, name="MobTimer")
        )
        self._mob_timer.timeout.connect(self._on_mob_timer)

        # HUD: the score label is pinned to the top-left corner and only ever
        # has its text rewritten; the splash and controls overlay in on_draw is
        # the resize-aware half of the HUD.
        self._score_text = self.add_child(
            Text2D(
                name="Score",
                text="Score: 0",
                position=(16, 12),
                font_scale=2.4,
                colour=(1.0, 1.0, 1.0, 1.0),
            )
        )

        # Music: the loop bundled with the upstream tutorial, started with the run.
        self._music = self._make_music()

    def _make_music(self) -> AudioPlayer | None:
        """Add the bundled music loop, or None when it was not shipped."""
        path = ASSETS / "music_loop.ogg"
        if not path.exists():
            return None
        return self.add_child(
            AudioPlayer(
                name="Music",
                stream=AudioClip(str(path)),
                bus="Music",
                loop=True,
                autoplay=False,
                volume_db=-9.0,
            )
        )

    def _on_spawn_interval_changed(self) -> None:
        """Push a live edit of the tunable through to the running spawn timer."""
        self._mob_timer.duration = self.spawn_interval

    # -- lifecycle ----------------------------------------------------------

    def on_ready(self):
        # InputMap calls MUST live in the root's on_ready: module-scope
        # registration is silently dropped by the web exporter.
        InputMap.add_action("move_left", [Key.A, Key.LEFT])
        InputMap.add_action("move_right", [Key.D, Key.RIGHT])
        InputMap.add_action("move_forward", [Key.W, Key.UP])
        InputMap.add_action("move_back", [Key.S, Key.DOWN])
        # Jump is keyboard-only as an action: during a run the pointer is a
        # steering stick, so the Player itself decides whether a press was a
        # steering drag or a tap-to-jump (mouse press surfaces as touch on web).
        InputMap.add_action("jump", [Key.SPACE])
        InputMap.add_action("retry", [Key.R, Key.ENTER, Key.SPACE, MouseButton.LEFT])
        InputMap.add_action("quit", [Key.ESCAPE])

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

        # Track current window size for HUD positioning. A resize changes the
        # centred splash + controls-panel layout, so dirty the retained 2D
        # draw when (and only when) the screen size actually changes.
        if self.tree:
            sw, sh = float(self.tree.screen_size[0]), float(self.tree.screen_size[1])
            if (sw, sh) != (self._screen_w, self._screen_h):
                self._screen_w, self._screen_h = sw, sh
                self.queue_redraw()

        if self._state == STATE_MENU:
            if Input.is_action_just_pressed("retry"):
                self._begin_run()
            return

        if self._state == STATE_OVER:
            if Input.is_action_just_pressed("retry"):
                self._restart()
            return

        # Lose condition: the player strays past the marked boundary.
        if is_off_arena(self._player.position, margin=PLAYER_MARGIN):
            self._player.die()

        # Despawn mobs that wander too far.
        for mob in list(self.tree.group("mob")):
            if is_off_arena(mob.position):
                mob.destroy()

    def _begin_run(self) -> None:
        self._state = STATE_PLAY
        self._player.start()
        self._mob_timer.start()
        if self._music is not None:
            self._music.play()
        # State drives the on_draw splash text; dirty the retained 2D layer so
        # the title overlay is cleared once play begins.
        self.queue_redraw()

    # -- handlers -----------------------------------------------------------

    def _on_mob_timer(self):
        if self._state != STATE_PLAY:
            return
        spawn = random_spawn_position()
        mob = self.add_child(Mob(name="Mob"))
        mob.initialize(spawn, self._player.position)

    def _on_mob_squashed(self):
        self._score += 1
        self._score_text.text = f"Score: {self._score}"

    def _on_player_hit(self):
        self._state = STATE_OVER
        self._mob_timer.stop()
        if self._music is not None:
            self._music.stop()
        # Reveal the GAME OVER splash: state change must re-run on_draw.
        self.queue_redraw()

    # -- restart ------------------------------------------------------------

    def _restart(self):
        self.tree.change_scene(SquashTheCreeps())

    # -- per-frame HUD draw -------------------------------------------------

    def on_draw(self, renderer):
        sw, sh = self._screen_w, self._screen_h

        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 line_h(s):
            return s * 16

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

        # Splash text: title on menu, "GAME OVER + score" on lose.
        if self._state == STATE_MENU:
            title_scale = fit("SQUASH THE CREEPS", target_w=sw * 0.85, max_scale=6)
            prompt_scale = fit("PRESS [SPACE] OR TAP TO PLAY", target_w=sw * 0.85, max_scale=2)
            block_h = line_h(title_scale) + 24 + line_h(prompt_scale)
            y = sh / 2 - block_h / 2
            draw_centered("SQUASH THE CREEPS", title_scale, y, (1.0, 0.95, 0.4, 1.0))
            y += line_h(title_scale) + 24
            draw_centered("PRESS [SPACE] OR TAP TO PLAY", prompt_scale, y, HINT_COLOUR)
        elif self._state == STATE_OVER:
            game_over_scale = fit("GAME OVER", target_w=sw * 0.7, max_scale=6)
            score_scale = max(2, game_over_scale - 2)
            prompt_scale = fit("PRESS [SPACE] OR TAP TO RETRY", target_w=sw * 0.85, max_scale=2)
            block_h = line_h(game_over_scale) + 14 + line_h(score_scale) + 14 + line_h(prompt_scale)
            y = sh / 2 - block_h / 2
            draw_centered("GAME OVER", game_over_scale, y, (0.95, 0.4, 0.4, 1.0))
            y += line_h(game_over_scale) + 14
            draw_centered(f"SCORE  {self._score}", score_scale, y, (1.0, 1.0, 1.0, 1.0))
            y += line_h(score_scale) + 14
            draw_centered("PRESS [SPACE] OR TAP TO RETRY", prompt_scale, y, HINT_COLOUR)

        # Bottom-right vertical, left-justified controls panel.
        lines = [
            "MOVE: WASD / DRAG",
            "JUMP: SPACE / TAP",
            "QUIT: ESC",
        ]
        widest = max(lines, key=len)
        scale = fit(widest, target_w=sw * 0.30, max_scale=2)
        widest_w = renderer.text_width(widest, scale)
        pad = 6.0
        panel_w = widest_w + pad * 2
        panel_h = line_h(scale) * len(lines) + pad * 2
        panel_x = sw - panel_w - 8
        panel_y = sh - panel_h - 8
        renderer.draw_rect((panel_x, panel_y), (panel_w, panel_h), colour=CONTROLS_PLATE, filled=True)
        y = panel_y + pad
        for line in lines:
            renderer.draw_text(line, (panel_x + pad, y), scale=scale, colour=CONTROLS_COLOUR)
            y += line_h(scale)


def main() -> None:
    headless = "--test" in sys.argv or os.environ.get("SIMVX_HEADLESS") == "1"
    app = App(
        title="Squash the Creeps (SimVX)",
        width=VIEWPORT_W,
        height=VIEWPORT_H,
        physics_fps=60,
        visible=not headless,
    )
    if headless:
        from simvx.graphics import save_png

        out_dir = _PORT_DIR / "screenshots"
        out_dir.mkdir(parents=True, exist_ok=True)
        frames = app.run_headless(
            SquashTheCreeps(),
            frames=120,
            capture_frames=[60, 119],
        )
        for idx, frame_no in enumerate([60, 119]):
            save_png(frames[idx], str(out_dir / f"frame_{frame_no:03d}.png"))
        print(f"Headless screenshots written to {out_dir}")
        app.quit()
        return

    app.run(SquashTheCreeps())


if __name__ == "__main__":
    main()