SNKRX¶

Wave-based arena, particles, screenshake, slow-motion, bloom.

Upstream: https://github.com/a327ex/SNKRX

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

SNKRX (SimVX port)¶

SimVX port of a327ex/SNKRX, the snake auto-battler arena roguelite. Steer a snake made of your units around a walled arena: the units auto-attack whatever comes into range, enemies chase the head, and every cleared wave opens a shop where you add another unit to the tail. Five waves, with a boss on the last one.

Licensing: MIT, matching upstream. No upstream code, art or audio is reused: every visual is drawn from primitives. See ATTRIBUTION.md and UPSTREAM_LICENSE.md.

Run¶

uv run python examples/ports/snkrx/main.py
uv run simvx export web examples/ports/snkrx/main.py -o /tmp/snkrx.html

Headless smoke test (writes screenshots/frame_30.png and friends):

uv run python examples/ports/snkrx/main.py --test

Scripted capture of a whole run (writes screenshots/stage_*.png):

uv run python examples/ports/snkrx/harness.py

Controls¶

Action	Binding
Aim the snake head	Move the mouse, or drag on a touchscreen
Rotate the snake head	A / D, or Left / Right
Start, restart, pick a shop card	Enter / Space, or click
Reroll the shop offers (2 gold)	R, or click REROLL
Skip the shop	S, or click SKIP
Quit	Esc

What this shows about SimVX¶

A pooled CPU particle system. nodes/particles.py keeps every particle in one flat numpy structured array, advances the whole buffer with vector operations, and draws the live slice as circles from a single on_draw. Hit sparks, death bursts and muzzle flashes all come from that one pool, with no per-particle Node.
Camera2D follow and shake. The arena camera targets the snake head with smoothing=8.0, and camera.shake(intensity=..., duration=...) fires on melee connects, kills and boss deaths. Aiming converts the cursor through camera.screen_to_world(...), so hit-testing and rendering agree under pan and shake.
Slow motion from a scaled dt. Arena.on_update multiplies gameplay dt by time_scale, drops it to a floor on a big kill and ramps it back up. Spawn pacing keeps using wall-clock dt, so the wave schedule does not stretch with the effect.
HDR bloom via WorldEnvironment. The root enables ACES tonemapping and bloom on a WorldEnvironment, which is what gives the neon primitives their glow. The renderer is never touched directly.
A screen-space HUD in a CanvasLayer. The HUD sits in a CanvasLayer at layer 10, so it stays put while the camera moves, and it dirties its retained draw only when the state it shows actually changes.
Signal-driven scene flow. Title, arena, shop and end screens are separate nodes swapped by the root; each announces what happened through a Signal (finished, failed, chosen, skipped) rather than reaching into its parent.
Actions registered in the root’s ready path. InputMap.add_action calls live in SNKRXRoot.on_ready, not in main(), because the web export instantiates the root directly.

Upstream¶

The upstream Lua was used as a design reference only; all Python here was written from scratch.

Source files¶

File	Summary	Lines
`main.py`	SNKRX: Wave-based arena, particles, screenshake, slow-motion, bloom.	369
`harness.py`	Scripted headless harness: drive the SNKRX port through a full run and	103
`nodes/__init__.py`	SNKRX SimVX port: node modules.	1
`nodes/arena.py`	Arena round: snake vs enemy waves with juice (particles, screenshake, slow-mo).	353
`nodes/buy_screen.py`	Build / upgrade screen: between rounds.	247
`nodes/colours.py`	SNKRX palette: neon-on-dark.	24
`nodes/enemies.py`	Enemy types: chase the snake head, deal contact damage, drop XP on death.	131
`nodes/hud.py`	Arena HUD overlay: wave / kills / snake hp via on_draw.	117
`nodes/menu.py`	SNKRX title screen: neon block logo + start prompt.	85
`nodes/particles.py`	CPU 2D particle pool: SNKRX-style hit sparks, death bursts, projectile trails.	168
`nodes/projectile.py`	Player projectiles: pierce shots from archers, AOE bursts from mages.	104
`nodes/units.py`	Player snake: head plus a chain of follower units.	295

Source¶

#!/usr/bin/env python3
"""SNKRX: Wave-based arena, particles, screenshake, slow-motion, bloom.

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

A snake auto-battler arena roguelite: steer the snake head, your units
auto-attack whatever comes into range, survive five waves and grow the build
in the shop between rounds.

The port exercises a pooled numpy particle system drawn from ``on_draw``,
``Camera2D`` target-following plus ``shake()`` for impact feedback,
slow-motion by scaling the gameplay ``dt``, HDR bloom and ACES tonemapping
via ``WorldEnvironment``, a screen-space HUD in a ``CanvasLayer``, and
signal-driven scene flow between title, arena, shop and end screens.

Run interactively::

    uv run python examples/ports/snkrx/main.py

Headless smoke test (captures frames 30 / 60 / 120)::

    uv run python examples/ports/snkrx/main.py --test

Web export::

    uv run simvx export web examples/ports/snkrx/main.py -o /tmp/snkrx.html

Controls
--------
- MOUSE / TOUCH: aim the snake head toward the cursor
- A / D or LEFT / RIGHT: rotate the snake head
- ENTER / SPACE or CLICK: start, restart, and pick a card in the shop
- R: reroll the shop offers (costs 2 gold)
- S: skip the shop
- ESC: quit
"""

from __future__ import annotations

import sys
from pathlib import Path

# Make the port folder importable in --test and direct runs alike
_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 Arena
from nodes.buy_screen import BuyScreen
from nodes.colours import BG, FG, GREEN, RED, YELLOW
from nodes.hud import HUD
from nodes.menu import TitleScreen

from simvx.core import (
    CanvasLayer,
    Input,
    InputMap,
    Key,
    MouseButton,
    Node,
    Signal,
)
from simvx.core.world_environment import WorldEnvironment
from simvx.graphics import App

WINDOW_W = 1280
WINDOW_H = 720
TOTAL_WAVES = 5


# ---------------------------------------------------------------------------- root


class SNKRXRoot(Node):
    """Top-level scene: owns InputMap, the active sub-scene, and the WorldEnvironment.

    Sub-scene swaps happen in-place via ``_set_phase`` so we don't tear down
    the WorldEnvironment between rounds.
    """

    def __init__(self, **kwargs):
        super().__init__(name="SNKRXRoot", **kwargs)
        self.phase: str = "menu"  # menu | arena | buy | gameover | victory
        self.wave = 1
        self.gold = 0
        self.kills = 0
        self.build: list[tuple[str, int]] = [
            ("warrior", 1),
            ("archer", 1),
            ("mage", 1),
        ]
        self._sub: Node | None = None
        self._mouse_aiming = False
        # HUD lives in a CanvasLayer (layer=10) so it renders in screen-space,
        # above the camera-transformed gameplay scene.
        self._hud_layer = CanvasLayer(name="HUDLayer", layer=10)
        self.add_child(self._hud_layer)
        self._hud = HUD()
        self._hud_layer.add_child(self._hud)

    def on_ready(self):
        # InputMap MUST live in on_ready (web exporter skips main()).
        InputMap.add_action("start", [Key.ENTER, Key.SPACE])
        InputMap.add_action("left", [Key.A, Key.LEFT])
        InputMap.add_action("right", [Key.D, Key.RIGHT])
        InputMap.add_action("quit", [Key.ESCAPE])
        InputMap.add_action("skip", [Key.S])
        InputMap.add_action("reroll", [Key.R])

        # Bloom + tonemap for the neon SNKRX feel.
        # Sky is disabled so the 2D scene gets a true dark background.
        env = self.add_child(WorldEnvironment())
        env.sky_mode = "disabled"
        env.tonemap_mode = "aces"
        env.tonemap_exposure = 1.0
        env.bloom_enabled = True
        env.bloom_threshold = 0.85
        env.bloom_intensity = 0.55
        env.bloom_soft_knee = 0.4

        self._enter_menu()

    # ------------------------------------------------------------ phase swaps

    def _set_phase(self, phase: str) -> None:
        """Record the active phase and keep the HUD in step with it.

        Phase changes can land mid-frame (an arena finishing inside its own
        ``on_update``), so the HUD visibility has to move with the phase here
        rather than being polled once per frame from ``on_update``.
        """
        self.phase = phase
        self._hud.visible_hud = phase == "arena"

    def _drop_sub(self):
        if self._sub is not None:
            self._sub.destroy()
            self._sub = None

    def _enter_menu(self):
        self._set_phase("menu")
        self._drop_sub()
        self.wave = 1
        self.gold = 0
        self.kills = 0
        self.build = [("warrior", 1), ("archer", 1), ("mage", 1)]
        ts = TitleScreen()
        ts.start.connect(self._enter_arena)
        self.add_child(ts)
        self._sub = ts

    def _enter_arena(self):
        self._set_phase("arena")
        self._drop_sub()
        arena = Arena(level=self.wave, build=self.build)
        arena.finished.connect(self._on_arena_finished)
        arena.failed.connect(self._on_arena_failed)
        self.add_child(arena)
        self._sub = arena

    def _on_arena_finished(self, xp_gained: int, gold_gained: int):
        self.gold += gold_gained
        self.kills += getattr(self._sub, "kills", 0)
        self.wave += 1
        if self.wave > TOTAL_WAVES:
            self._enter_victory()
        else:
            self._enter_buy()

    def _on_arena_failed(self):
        self._enter_gameover()

    def _enter_buy(self):
        self._set_phase("buy")
        self._drop_sub()
        bs = BuyScreen(level=self.wave - 1, gold=self.gold, build=self.build)
        bs.chosen.connect(self._on_buy_chosen)
        bs.skipped.connect(self._enter_arena)
        self.add_child(bs)
        self._sub = bs

    def _on_buy_chosen(self, klass: str, lvl: int):
        if len(self.build) < 8:
            self.build.append((klass, lvl))
        # Subtract gold from the BuyScreen's running total
        self.gold = self._sub.gold if self._sub else self.gold
        self._enter_arena()

    def _enter_gameover(self):
        self._set_phase("gameover")
        self._drop_sub()
        # Reuse TitleScreen-style overlay would be ideal, keep simple here
        self._sub = _EndScreen(victory=False, wave=self.wave, kills=self.kills, gold=self.gold)
        self._sub.start.connect(self._enter_menu)
        self.add_child(self._sub)

    def _enter_victory(self):
        self._set_phase("victory")
        self._drop_sub()
        self._sub = _EndScreen(victory=True, wave=self.wave - 1, kills=self.kills, gold=self.gold)
        self._sub.start.connect(self._enter_menu)
        self.add_child(self._sub)

    # ---------------------------------------------------------------- updates

    def on_update(self, dt: float):
        # Global ESC → quit. Easy to relocate to per-screen later.
        if Input.is_action_just_pressed("quit"):
            if self.app is not None:
                self.app.quit()
            return

        # Arena phase: forward steering input + populate HUD
        if self.phase == "arena" and isinstance(self._sub, Arena):
            arena: Arena = self._sub  # type: ignore[assignment]
            # Mouse steering latches on the first cursor movement (or a click,
            # which is how a touchscreen reports a drag) and releases again the
            # moment a keyboard steering key is used.
            if Input.is_action_pressed("left") or Input.is_action_pressed("right"):
                self._mouse_aiming = False
            elif Input.mouse_delta.length() > 0 or Input.is_mouse_button_pressed(MouseButton.LEFT):
                self._mouse_aiming = True

            if self._mouse_aiming:
                # ``Input.mouse_position`` is screen-space and the arena camera
                # follows the snake head, so convert before aiming at a world point.
                target = arena.camera.screen_to_world(Input.mouse_position, self.tree.screen_size)
                arena.snake.aim_at(target)
            else:
                # Keyboard fallback steering
                arena.snake.aim_at(None)
                steer = 0.0
                if Input.is_action_pressed("left"):
                    steer -= 1.0
                if Input.is_action_pressed("right"):
                    steer += 1.0
                arena.snake.steer(steer)

            # HUD state
            self._hud.set_state(
                wave=self.wave,
                total_waves=TOTAL_WAVES,
                kills=arena.kills,
                gold=self.gold + arena.gold_gained,
                snake_hp=sum(u.hp for u in arena.snake.units if u.alive) if arena.snake.units else 0,
                snake_max_hp=sum(u.max_hp for u in arena.snake.units) if arena.snake.units else 1,
                time_scale=arena.time_scale,
            )
        else:
            # Outside the arena the HUD is hidden by ``_set_phase``; reset its
            # per-round counters so the next wave starts from a clean slate.
            self._hud.set_state(
                wave=self.wave,
                total_waves=TOTAL_WAVES,
                kills=0,
                gold=self.gold,
                snake_hp=0,
                snake_max_hp=1,
                time_scale=1.0,
            )


# ---------------------------------------------------------------- end screens


class _EndScreen(Node):
    """Game-over / victory scene with continue prompt."""

    start = Signal()

    # The continue prompt pulses every frame from ``self._t``, so ``on_draw``
    # genuinely produces new geometry each frame: declare it dynamic.
    dynamic = True

    def __init__(self, *, victory: bool, wave: int, kills: int, gold: int, **kwargs):
        super().__init__(name="EndScreen", **kwargs)
        self.victory = victory
        self.wave = wave
        self.kills = kills
        self.gold = gold
        self._t = 0.0

    def on_update(self, dt: float):
        self._t += dt
        # Keyboard or click/tap both restart, so the end screen is reachable
        # for a mouse- or touch-only player.
        if Input.is_action_just_pressed("start") or Input.is_mouse_button_just_pressed(MouseButton.LEFT):
            self.start.emit()

    def on_draw(self, renderer):
        w, h = self.tree.screen_size if self.tree is not None else (WINDOW_W, WINDOW_H)
        w, h = int(w), int(h)
        renderer.draw_rect((0, 0), (w, h), colour=BG, filled=True)
        title = "VICTORY" if self.victory else "DEFEAT"
        c = GREEN if self.victory else RED
        tw = renderer.text_width(title, 12)
        renderer.draw_text(title, (w // 2 - tw // 2, int(h * 0.28)), scale=12, colour=c)

        for i, line in enumerate(
            [
                f"WAVES SURVIVED  {self.wave}",
                f"KILLS           {self.kills}",
                f"GOLD            {self.gold}",
            ]
        ):
            lw = renderer.text_width(line, 3)
            renderer.draw_text(line, (w // 2 - lw // 2, int(h * 0.53) + i * 50), scale=3, colour=FG)

        if int(self._t * 2) % 2 == 0:
            prompt = "ENTER / CLICK  RESTART"
            pw = renderer.text_width(prompt, 3)
            renderer.draw_text(prompt, (w // 2 - pw // 2, int(h * 0.80)), scale=3, colour=YELLOW)


# --------------------------------------------------------------------- entry


def _capture(captures, frames):
    out_dir = _PORT_DIR / "screenshots"
    out_dir.mkdir(exist_ok=True)
    from simvx.graphics import save_png

    for idx, frame in zip(frames, captures, strict=False):
        path = out_dir / f"frame_{idx}.png"
        save_png(frame, path)
        print(f"saved {path}")


def _run_test():
    """Headless smoke test: auto-advance into the arena; capture frames 30/60/120."""
    from simvx.core import InputSimulator

    app = App(title="SNKRX (test)", width=WINDOW_W, height=WINDOW_H, visible=False, bg_colour=BG)
    sim = InputSimulator()
    root = SNKRXRoot()

    def _drive(idx, _t):
        # Auto-press Enter after a few frames so capture frame 60 / 120 show
        # actual arena gameplay rather than just the title screen.
        if idx == 20:
            sim.press_key(Key.ENTER)
        if idx == 22:
            sim.release_key(Key.ENTER)
        return None

    capture_frames = [30, 60, 120]
    captures = app.run_headless(
        root,
        frames=130,
        on_frame=_drive,
        capture_frames=capture_frames,
    )
    _capture(captures, capture_frames)


def main():
    if "--test" in sys.argv:
        _run_test()
        return
    app = App(title="SNKRX", width=WINDOW_W, height=WINDOW_H, bg_colour=BG)
    app.run(SNKRXRoot())


if __name__ == "__main__":
    main()