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¶

simvx examples run ports_snkrx
simvx export web main.py -o snkrx.html

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

simvx examples run ports_snkrx --test

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

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 InputMap belongs to a scene tree and none exists before run().

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.	358
`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).	342
`nodes/buy_screen.py`	Build / upgrade screen: between rounds.	234
`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.	109
`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.	82
`nodes/particles.py`	CPU 2D particle pool: SNKRX-style hit sparks, death bursts, projectile trails.	162
`nodes/projectile.py`	Player projectiles: pierce shots from archers, AOE bursts from mages.	88
`nodes/units.py`	Player snake: head plus a chain of follower units.	277

Source¶

#!/usr/bin/env python3
# /// simvx
# tags = ["port", "tier-1"]
# upstream = "https://github.com/a327ex/SNKRX"
# web = { width = 1280, height = 720, responsive = true }
# ///
"""SNKRX: Wave-based arena, particles, screenshake, slow-motion, bloom.

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

    simvx examples run ports_snkrx

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

    simvx examples run ports_snkrx --test

Web export::

    simvx export web main.py -o 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

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

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, Mouse, 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: run_headless resets input state, so a
        # --test mode loses anything registered before it.
        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.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.pressed("left") or Input.pressed("right"):
                self._mouse_aiming = False
            elif Input.mouse_delta.length() > 0 or Input.is_mouse_button_pressed(Mouse.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.pressed("left"):
                    steer -= 1.0
                if Input.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.just_pressed("start") or Input.is_mouse_button_just_pressed(Mouse.LEFT):
            self.start.emit()

    def on_draw(self, renderer):
        w, h = self.viewport_size
        w, h = int(w), int(h)
        renderer.rect((0, 0), (w, h), fill=BG)
        title = "VICTORY" if self.victory else "DEFEAT"
        c = GREEN if self.victory else RED
        tw = renderer.text_width(title, 12)
        renderer.text(title, (w // 2 - tw // 2, int(h * 0.28)), fill=c, scale=12)

        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.text(line, (w // 2 - lw // 2, int(h * 0.53) + i * 50), fill=FG, scale=3)

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


# --------------------------------------------------------------------- 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)
    root = SNKRXRoot()
    sim = InputSimulator(root)

    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()