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
One typed move action fed by the keys, a controller stick and the drawn TouchController alike, declared by the nodes that read it

Run: simvx examples run ports_squash_the_creeps simvx examples run ports_squash_the_creeps –test # headless smoke run

Web export: simvx export web main.py -o squash_the_creeps.html

Controls: WASD / arrows / stick Move Space / A Jump, and bounce when you land on a creep R / Enter / Space / tap / A Start, and restart after game over Esc Quit

On a phone the drawn controller is the whole control scheme: its stick steers and its A button jumps. It leaves the screen as soon as a real controller is used.

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.	334
`nodes/__init__.py`	Squash the Creeps: node modules.	1
`nodes/arena.py`	Arena: static ground body, decorative pillars, lighting and sky.	180
`nodes/controls.py`	What the player can do, declared once and carried by the node that reads it.	32
`nodes/mob.py`	Mob: chases the player; dies when squashed or off-screen.	138
`nodes/player.py`	Player: a CharacterBody3D steered by keys, stick or the drawn pad, with jump and bounce.	214

Source¶

# /// 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 }
# ///
"""Squash the Creeps: a 3D arcade port of Godot's first 3D game tutorial.

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
- One typed ``move`` action fed by the keys, a controller stick and the drawn
  ``TouchController`` alike, declared by the nodes that read it

Run:
    simvx examples run ports_squash_the_creeps
    simvx examples run ports_squash_the_creeps --test   # headless smoke run

Web export:
    simvx export web main.py -o squash_the_creeps.html

Controls:
    WASD / arrows / stick         Move
    Space / A                     Jump, and bounce when you land on a creep
    R / Enter / Space / tap / A   Start, and restart after game over
    Esc                           Quit

On a phone the drawn controller is the whole control scheme: its stick steers and
its A button jumps. It leaves the screen as soon as a real controller is used.

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

_PORT_DIR = Path(__file__).resolve().parent

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

from simvx.core import (  # noqa: E402
    AudioClip,
    AudioPlayer,
    Camera3D,
    CanvasLayer,
    Controller,
    Input,
    Node,
    Property,
    Text2D,
    Timer,
)
from simvx.core.ui import TouchController  # noqa: E402
from simvx.graphics import App  # noqa: E402

ASSETS = _PORT_DIR / "assets"

# The window the game opens at. Layout reads the live size, never this.
WINDOW_W = 1024
WINDOW_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."""

    # 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 and
    # jumping are the player's own business and live on the player.
    input_context = SHELL

    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._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.
        # HUD text rides a CanvasLayer, pinned to the screen and out of the tonemap.
        self._hud_layer = self.add_child(CanvasLayer(name="HUD"))
        self._score_text = self._hud_layer.add_child(
            Text2D(
                name="Score",
                text="Score: 0",
                position=(16, 12),
                font_scale=2.4,
                colour=(1.0, 1.0, 1.0, 1.0),
            )
        )

        # The pad on the glass. It publishes a real controller, so the
        # player's stick and jump bindings and this scene's Controller.A
        # already read it and nothing further is wired. It leaves the screen
        # the moment a real controller is used.
        self.add_child(TouchController(buttons=(Controller.A,), name="TouchPad"))

        # 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_update(self, dt: float):
        if Input.just_pressed("quit"):
            self.app.quit()
            return

        if self._state == STATE_MENU:
            if Input.just_pressed("start"):
                self._begin_run()
            return

        if self._state == STATE_OVER:
            if Input.just_pressed("start"):
                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 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):
        # Deferred: a scene swapped from inside the frame walk detaches these
        # children while the walk is still visiting them.
        self.call_deferred(self.tree.change_scene, SquashTheCreeps())

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

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

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

        # 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, TAP OR (A) 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, TAP OR (A) 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, TAP OR (A) 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, TAP OR (A) TO RETRY", prompt_scale, y, HINT_COLOUR)

        # Bottom-right vertical, left-justified controls panel.
        lines = [
            "MOVE: WASD / STICK",
            "JUMP: SPACE / (A)",
            "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.rect((panel_x, panel_y), (panel_w, panel_h), fill=CONTROLS_PLATE)
        y = panel_y + pad
        for line in lines:
            renderer.text(line, (panel_x + pad, y), fill=CONTROLS_COLOUR, scale=scale)
            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=WINDOW_W,
        height=WINDOW_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()