Tower Defence¶

waves, tile-aligned turret placement, upgrades, and a shop panel.

Upstream: https://github.com/russs123/tower_defence_tut

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

Tower Defence (SimVX port)¶

SimVX port of russs123/tower_defence_tut (Coding With Russ YouTube tutorial; the upstream repo declares no licence, so nothing from it is redistributed here). Wave-based tower defence with an animated basic turret + four upgrade tiers, plus slow and sniper turret variants added by the port.

Licensing: clean re-implementation under MIT; the level is an original design and all art is Kenney CC0 or procedural, audio is synthesised. See ATTRIBUTION.md and LICENSE.

What this shows in SimVX¶

Node tree + scene swap – a root node that tears down the menu and builds the gameplay scene (main.py), with every input action registered once on the root so the browser export (which never calls main()) gets them too.
Properties – money, lives, level and game speed are Property descriptors with validated ranges, so an out-of-range write is clamped rather than silently wrong.
Signals – enemies emit died / escaped / damaged, turrets emit target_acquired (the world turns it into a tracer), and the world emits level_started / game_won / game_lost for whatever hosts it.
Node groups – turrets and enemies join "turrets" / "enemies", and targeting and cleanup iterate the group instead of keeping their own lists.
AnimatedSprite2D – the basic turret’s 8-frame fire cycle is driven from the turret’s cooldown, and an upgrade swaps the sheet by reassigning texture.
Text2D and on_draw – HUD labels are nodes; the panel plate, buttons, placement preview and end-game dialog are immediate-mode shapes with box-aligned text.
Procedural audio – the shot effect is synthesised into an AudioClip at load time (nodes/audio.py), so no audio files are bundled.
Headless capture – main.py --test renders frames without a visible window, and harness.py plays several waves through InputSimulator (simulated mouse and keyboard, never direct method calls) to screenshot each stage.

Run¶

All commands from the SimVX repo root (uv workspace requirement):

# Interactive
uv run python examples/ports/tower_defence_tut/main.py

# Headless smoke test (frame_30/60/120 captures)
uv run python examples/ports/tower_defence_tut/main.py --test

# Scripted harness (10 stage screenshots covering 3+ waves)
uv run python examples/ports/tower_defence_tut/harness.py

# Web export
uv run simvx export web examples/ports/tower_defence_tut/main.py -o /tmp/tower_defence.html

Controls¶

Action	Keyboard	Mouse
Start (menu)	`Enter` / `Space`	Click anywhere
Place BASIC turret	`1` / `B`	“BUY BASIC” panel button
Place SLOW turret	`2`	Cycle TYPE then “BUY”
Place SNIPER turret	`3`	Cycle TYPE then “BUY”
Cancel placement	`Esc`	“CANCEL” panel button
Select a placed turret	-	Click it (shows its range ring)
Begin wave	`Enter` / `Space`	“BEGIN WAVE” panel button
Fast-forward x2	`F`	“FAST x2” panel button
Upgrade selected turret	`U`	“UPGRADE -> Lx (100c)” panel button
Restart	`R`	“RESTART” panel button
Quit	`Q` / `Esc` (menu)	-

Touch / mobile¶

Tower placement is a single tap on a grass tile – the SimVX web runtime surfaces touchstart/end as MouseButton.LEFT, so the browser export is playable on mobile without code changes.

Tower types¶

Type	Cost	Range (L1)	DPS (L1)	Notes
Basic	200	120	~5.5	Animated turret (Kenney CC0 parts, baked 8-frame fire cycle)
Slow	250	70	~2.5	Applies a 0.5x slow debuff for 1 s on hit
Sniper	350	200	~5.8	Long range, slow rate, big single-shot damage

All three types support 4-tier upgrades.

Source files¶

File	Summary	Lines
`main.py`	Tower Defence: waves, tile-aligned turret placement, upgrades, and a shop panel.	209
`harness.py`	Scripted-input harness for the Tower Defence port.	208
`nodes/__init__.py`		0
`nodes/audio.py`	Procedural audio: built on the engine’s AudioSynth API.	37
`nodes/enemy.py`	Waypoint-following enemy.	129
`nodes/level_data.py`	Level data for the Tower Defence port.	264
`nodes/td_data.py`	Tower Defence constants + spawn / turret data tables.	128
`nodes/td_world.py`	TowerDefenceWorld – the main gameplay scene.	722
`nodes/turret.py`	Tower / turret node.	333

Source¶

"""Tower Defence: waves, tile-aligned turret placement, upgrades, and a shop panel.

A SimVX port of Coding With Russ's pygame tower-defence tutorial. Waypoint-following
enemies walk a hand-authored path; three turret types (basic, slow, sniper) with four
upgrade tiers each shoot back, paid for out of a wave-by-wave currency budget. Built on
the node tree, Properties, Signals, node groups, an AnimatedSprite2D fire cycle, and a
shot effect synthesised at load time.

# /// simvx
# tags = ["port", "tier-1"]
# upstream = "https://github.com/russs123/tower_defence_tut"
# web = { width = 1280, height = 720, responsive = true }
# ///

Run:
    uv run python examples/ports/tower_defence_tut/main.py
    uv run python examples/ports/tower_defence_tut/main.py --test     # headless capture
    uv run python examples/ports/tower_defence_tut/harness.py         # scripted run
    uv run simvx export web examples/ports/tower_defence_tut/main.py -o /tmp/tower_defence.html
"""

from __future__ import annotations

import sys
from pathlib import Path

_PORT_DIR = Path(__file__).parent
if str(_PORT_DIR) not in sys.path:
    sys.path.insert(0, str(_PORT_DIR))

from nodes.td_data import (  # noqa: E402
    WINDOW_HEIGHT,
    WINDOW_WIDTH,
)
from nodes.td_world import TowerDefenceWorld  # noqa: E402

from simvx.core import (  # noqa: E402
    Input,
    InputMap,
    Key,
    MouseButton,
    Node2D,
    Sprite2D,
    Text2D,
    Vec2,
)
from simvx.graphics import App  # noqa: E402

# ---------------------------------------------------------------------------
# Menu / Root wrapper
# ---------------------------------------------------------------------------


class _Menu(Node2D):
    """Simple menu screen -- press Enter to begin, Esc to quit.

    Every label is centred with ``Text2D.align="centre"`` on the window's mid-line,
    so the screen re-lays-out to whatever size the window is dragged to instead of
    relying on per-string pixel offsets.
    """

    def __init__(self, root: TowerDefenceRoot, **kwargs):
        super().__init__(**kwargs)
        self._root = root
        self._blink = 0.0
        self._laid_out: tuple[int, int] | None = None

        # Logo background -- the port's own logo, composed from the Kenney parts.
        self._logo = self.add_child(
            Sprite2D(
                texture=str(_PORT_DIR / "assets" / "images" / "gui" / "logo.png"),
                width=300,
                height=320,
            )
        )
        self._title = self.add_child(
            Text2D(text="TOWER DEFENCE", font_scale=2.4, align="centre", colour=(1.0, 1.0, 1.0, 1.0))
        )
        self._credit = self.add_child(
            Text2D(
                text="SimVX port of russs123/tower_defence_tut",
                font_scale=1.0,
                align="centre",
                colour=(0.8, 0.85, 0.9, 1.0),
            )
        )
        self._prompt = self.add_child(
            Text2D(
                text="PRESS ENTER OR CLICK TO START",
                font_scale=1.3,
                align="centre",
                colour=(1.0, 0.95, 0.7, 1.0),
            )
        )
        self._controls = self.add_child(
            Text2D(
                text="Controls: 1 / 2 / 3 = type select  -  U upgrade  -  R restart  -  Q quit",
                font_scale=0.9,
                align="centre",
                colour=(0.75, 0.78, 0.82, 1.0),
            )
        )

    def on_ready(self) -> None:
        self._layout()

    def _layout(self) -> None:
        """Place the labels for the current window size (a no-op until it changes)."""
        size = (int(self.app.width), int(self.app.height))
        if size == self._laid_out:
            return
        self._laid_out = size
        w, h = size
        self._logo.position = Vec2(w / 2, h / 2 - 40)
        self._title.position = Vec2(w / 2, 80)
        self._credit.position = Vec2(w / 2, 130)
        self._prompt.position = Vec2(w / 2, h - 130)
        self._controls.position = Vec2(w / 2, h - 70)

    def on_update(self, dt: float) -> None:
        self._layout()
        self._blink += dt
        self._prompt.colour = (1.0, 0.95, 0.7, 1.0 if int(self._blink * 2) % 2 == 0 else 0.55)
        if Input.is_action_just_pressed("menu_start") or Input.is_mouse_button_just_pressed(MouseButton.LEFT):
            self._root.start_game()
        if Input.is_action_just_pressed("menu_quit"):
            self.app.quit()


class TowerDefenceRoot(Node2D):
    """Top-level scene swap: menu -> game -> menu (on restart key)."""

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self._menu: _Menu | None = None
        self._world: TowerDefenceWorld | None = None
        self._show_menu = True

    def on_ready(self) -> None:
        # ALL InputMap actions live on the root, registered once. Re-entering
        # the menu and re-starting the world is therefore safe: no double
        # registration and no actions lost on world destroy.
        InputMap.add_action("menu_start", [Key.ENTER, Key.SPACE])
        InputMap.add_action("menu_quit", [Key.ESCAPE, Key.Q])
        InputMap.add_action("begin_wave", [Key.ENTER, Key.SPACE])
        InputMap.add_action("fast_forward", [Key.F])
        InputMap.add_action("place_basic", [Key.KEY_1, Key.B])
        InputMap.add_action("place_slow", [Key.KEY_2])
        InputMap.add_action("place_sniper", [Key.KEY_3])
        InputMap.add_action("cancel_place", [Key.ESCAPE])
        InputMap.add_action("upgrade", [Key.U])
        InputMap.add_action("restart", [Key.R])
        InputMap.add_action("quit", [Key.Q])
        self._show_menu_screen()

    def _show_menu_screen(self) -> None:
        for c in list(self.children):
            c.destroy()
        self._world = None
        self._menu = self.add_child(_Menu(self))

    def start_game(self) -> None:
        for c in list(self.children):
            c.destroy()
        self._menu = None
        # The world stays on screen after a win or a loss: it draws its own
        # end-game dialog and the RESTART button cycles its state in place.
        self._world = self.add_child(TowerDefenceWorld())


# ---------------------------------------------------------------------------
# Entry
# ---------------------------------------------------------------------------


def main() -> None:
    headless = "--test" in sys.argv
    if headless:
        from simvx.graphics import save_png

        capture_at = [30, 60, 120]
        app = App(
            width=WINDOW_WIDTH,
            height=WINDOW_HEIGHT,
            title="Tower Defence (SimVX)",
            visible=False,
        )
        frames = app.run_headless(
            TowerDefenceRoot(),
            frames=130,
            capture_frames=capture_at,
        )
        out_dir = _PORT_DIR / "screenshots"
        out_dir.mkdir(exist_ok=True)
        for idx, img in zip(capture_at, frames, strict=False):
            out_path = out_dir / f"frame_{idx}.png"
            save_png(img, out_path)
            print(f"saved {out_path}")
    else:
        app = App(
            width=WINDOW_WIDTH,
            height=WINDOW_HEIGHT,
            title="Tower Defence (SimVX)",
        )
        app.run(TowerDefenceRoot())


if __name__ == "__main__":
    main()