SHRIKE

top-down 3D space survival roguelike.

▶ Run in browser

Tags: 3d game roguelike survival procedural

SHRIKE

A top-down 3D space survival roguelike on the SimVX engine. Strip-mine dying sectors under a signature meter that your own greed fills, juggle fuel, oxygen, ammo and a starving capacitor, bank your haul or smelt it aboard a Refinery that lights you up like a flare, and flee the Shrike when the klaxon sounds; behind you a red front swallows the star chart, and ahead lie richer sectors, louder deaths, and eventually the night your build is strong enough to turn around and hunt it back to its roost. Every tuning number that shapes the game is in shrike/balance.py.

Run

uv run python examples/demos/shrike/main.py          # play
uv run python examples/demos/shrike/main.py --test   # headless self-check, exits on its own

--test mounts the entry scene, flies a fixed-seed slice of a whole run (mine a deposit, provoke the signature lock, survive a wave and an arrival, flee through the star chart, extract at the Deep Gate) and prints SELFTEST: PASS before exiting. It writes its saves to a throwaway directory, so it never touches a real profile.

Controls

The nose aims independently of the thrust vector: you fly one way and shoot another. On a pad the shield arc mirrors the right stick by default; on a keyboard Q and E rotate it continuously.

Action	Keyboard and mouse	Gamepad
Thrust	W A S D	Left stick
Aim	Mouse	Right stick
Fire primary	Left mouse	Right trigger
Mining beam	Right mouse	Left trigger
Rotate shield arc	Q / E	Left / right bumper (60 degree nudge; both re-centres on aim)
Afterburner	Shift (hold)	A (hold)
Interact	F	X
Jettison scrap	G	B
Silent running	C (toggle)	Y (toggle)
Solar wings	X	D-pad up
Generator	Z	D-pad down
Warp spool	R (toggle)	Left stick click (toggle)
Tractor scoop	Tab (toggle)	Right stick click (toggle)
Star chart	M	Back
Show or hide the controls bar	H	D-pad left
Pause menu	Esc	Start

Warp spool is a toggle rather than a hold: press once to start the channel, press again to cancel it. Loose salvage is scooped by flying through it, so a mote you touch is a mote you keep.

Interact is one button with three lengths, and the ship draws the hold as a radial fill:

Hold	Effect
Tap	Dock at a depot, grab salvage, trigger a signal event
1 second	Patch the nearest hull breach (costs scrap)
3 seconds	Start a Refinery batch, or sell your scrap while docked

Saves

Two files, both under the XDG data directory:

Path	Contents
$XDG_DATA_HOME/simvx/shrike/profile.sav	Cores, Fleet Doctrine, quills, fletchings, lure fragments, hulls, Hunt Rank, codex, milestones, per-hull bests
$XDG_DATA_HOME/simvx/shrike/suspend.sav	The single suspend slot, deleted as it is loaded

XDG_DATA_HOME falls back to ~/.local/share when unset or not absolute, so the usual location is ~/.local/share/simvx/shrike/. Setting SHRIKE_DATA_DIR overrides both, which is what the self-check and portable installs use. Nothing is ever written into the game directory.

Tests

uv run --package simvx-core pytest examples/demos/shrike/tests/test_foundation.py

Each module has its own test file under examples/demos/shrike/tests/; run one file at a time. They are headless logic tests: scenes run under SceneRunner and every player verb goes through InputSimulator, so the real action map and input pipeline are exercised rather than handlers called directly. No GPU, no windows.

tests/test_balance_bands.py is the tuning contract: it measures the design’s time-to-kill bands (mite under 0.5 s, lancer about 2 s, warden about 45 s, one Shrike fin about 15 s) by feeding each reference loadout’s DPS through the real damage router. A balance change that moves a band fails there first.

Source files

File	Summary	Lines
main.py	SHRIKE: top-down 3D space survival roguelike.	441
shrike/__init__.py	SHRIKE: a top-down 3D space survival roguelike on the SimVX engine.	20
shrike/artkit.py	Procedural art kit for SHRIKE: every mesh, material, sky and grade is generated.	2168
shrike/audio.py	SHRIKE’s audio: every sound synthesised at load, and the mix the power state drives.	893
shrike/balance.py	Every tuning number in SHRIKE, as named constants and small specs.	780
shrike/bounty.py	Notoriety, the run-level reputation dial, and the two set pieces it buys.	1018
shrike/chart.py	The star chart: a branching route eaten from behind, and the warp that pays for it.	1664
shrike/combat.py	The damage router and the collision-layer contract.	452
shrike/enemies/__init__.py	SHRIKE’s hostiles: shared steering, the enemy base, and the archetypes.	53
shrike/enemies/advanced.py	The advanced half of the enemy roster: support, siege, alarm, emplacement and herald.	1474
shrike/enemies/basic.py	The four common hostiles: Mites, Skimmers, Lancers and Mag-mines.	781
shrike/enemies/steering.py	Flow-field steering and the shared enemy base.	815
shrike/events.py	The signal-event deck: twelve cards a sector can deal you on arrival.	185
shrike/flow.py	The run lifecycle: the menu, the run, the Gate, the collapse and the ledger.	7469
shrike/hud.py	SHRIKE’s heads-up display: foveal arcs, a warming border and diegetic rings.	4500
shrike/hunter.py	The Shrike: the segmented hunter the whole economy is priced against.	977
shrike/juice.py	The feel layer: hit-stop, trauma-budgeted shake, punches and the scoop magnet.	690
shrike/meta.py	Fleet Doctrine, the milestone bounties, the hull trophies and the Hunt Ranks.	1500
shrike/modules.py	Hull sockets, the thirty-module catalogue, and the modules that act.	1292
shrike/onboarding.py	The staged first three runs: the HUD subtraction schedule and the safe arrival.	934
shrike/power.py	Power generation, life support, and the silent-running posture.	1064
shrike/roost.py	The endgame campaign: Lure fragments, Fletching pity, and the Roost duel.	653
shrike/runtime.py	The shared runtime spine of SHRIKE.	541
shrike/save.py	Persistence: the permanent meta profile and the one-slot suspend save.	528
shrike/sector.py	What a warp-in drops you into: one sector’s harvestable content.	1736
shrike/ship.py	The player ship: drift flight, the shield arc, hull breaches and the warp spool.	1104
shrike/signature.py	The signature meter: the bill this sector charges for everything you do.	203
shrike/trading.py	The scrap ledger, the drift depots, and the Broker barge.	1121
shrike/vfx.py	SHRIKE’s effects library: pooled bursts, the two live emitters and the dust.	1509
shrike/waves.py	The wave composer: what arrives every 35 to 55 seconds, and from where.	1105
shrike/weapons.py	Hardpoints, the ten-weapon roster, and everything they put in the air.	1315

Source

"""SHRIKE: top-down 3D space survival roguelike.

# /// simvx
# tags = ["3d", "game", "roguelike", "survival", "procedural"]
# screenshot_frame = 40
# web = { width = 1280, height = 720, root = "MainMenuScene", responsive = true }
# ///

Run:            uv run python examples/demos/shrike/main.py
Frame cap:      uv run python examples/demos/shrike/main.py --fps 60
Headless check: uv run python examples/demos/shrike/main.py --test

Controls (keyboard and mouse): WASD thrust, mouse aims the nose, LMB fires,
RMB mines, Q/E steer the shield arc, Shift afterburner, C silent running,
X solar wings, Z generator, F interact, G jettison, R warp spool, Tab scoop,
M star chart, Esc pause. Full gamepad mapping in shrike/runtime.py.
"""

import importlib.util
import math
import os
import sys
import tempfile

from shrike import balance
from shrike.runtime import (
    CAMERA_DISTANCE,
    CAMERA_PITCH_RADIANS,
    INPUT_ACTIONS,
    PLANE_Y,
    WINDOW_HEIGHT,
    WINDOW_WIDTH,
    CameraRig,
    Groups,
    move_input,
)

from simvx.core import (
    DirectionalLight3D,
    Input,
    Material,
    Mesh,
    MeshInstance3D,
    Node,
    Node3D,
    Quat,
    Vec2,
    Vec3,
    WorldEnvironment,
)

#: Re-exported so that the screenshot and web-export pipelines can reach the
#: front door by name: both resolve ``web.root`` as an attribute of this module,
#: and the run lifecycle otherwise only ever arrives through
#: :func:`create_entry_scene`. Guarded for the same reason that function is: a
#: tree without ``shrike.flow`` still has to import, and there ``FoundationScene``
#: is the entry and no menu exists to point a capture at.
try:
    from shrike.flow import MainMenuScene
except ImportError:  # pragma: no cover - only reachable without shrike.flow
    MainMenuScene = None

FOUNDATION_SHIP_SPEED = 26.0


class FoundationShip(Node3D):
    """Minimal flight probe: dampened drift movement on the flight plane.

    Stands in for the real player ship until ``shrike.ship`` provides one, and
    keeps the boot path and the headless self-check exercising real input,
    movement and camera-follow behaviour. The full flight model (nose-to-aim,
    afterburner, breaches) belongs to ``shrike.ship.PlayerShip``.
    """

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.velocity = Vec2(0.0, 0.0)

    def on_enter_tree(self):
        super().on_enter_tree()
        self.add_to_group(Groups.SHIP)

    def on_ready(self):
        self.add_child(
            MeshInstance3D(
                name="Hull",
                mesh=Mesh.cone(radius=0.6, height=1.8, segments=12),
                material=Material(colour=(0.75, 0.78, 0.82, 1.0), metallic=0.8, roughness=0.35),
                rotation=Quat.from_euler(math.radians(90), 0.0, 0.0),
            )
        )

    def on_fixed_update(self, dt: float):
        thrust = move_input()
        ax = float(thrust.x) * FOUNDATION_SHIP_SPEED
        az = float(thrust.y) * FOUNDATION_SHIP_SPEED
        damp = balance.INERTIAL_DAMPENING ** (dt * 60.0)
        self.velocity = Vec2(
            (float(self.velocity.x) + ax * dt) * damp,
            (float(self.velocity.y) + az * dt) * damp,
        )
        self.position = Vec3(
            float(self.position.x) + float(self.velocity.x) * dt,
            PLANE_Y,
            float(self.position.z) + float(self.velocity.y) * dt,
        )


class FoundationScene(Node):
    """The minimal run scene the game boots until ``shrike.flow`` takes over.

    Environment, sun, a flight probe on the plane, and the camera rig. Quits
    on the ``star_chart`` action; the flow module replaces that with the real
    pause and chart screens.
    """

    input_actions = INPUT_ACTIONS

    def on_ready(self):
        env = self.add_child(WorldEnvironment(name="Environment"))
        env.ambient_light_colour = (0.10, 0.12, 0.18, 1.0)
        env.ambient_light_energy = 1.0
        env.bloom_enabled = True

        sun = self.add_child(DirectionalLight3D(name="Sun"))
        sun.direction = Vec3(-0.5, -1.0, -0.4)
        sun.colour = (0.9, 0.92, 1.0)
        sun.intensity = 1.2

        self.ship = self.add_child(FoundationShip(name="Ship", position=Vec3(0.0, PLANE_Y, 0.0)))
        self.rig = self.add_child(CameraRig(name="CameraRig"))
        self.rig.set_target(self.ship)

    def on_update(self, dt: float):
        self.rig.set_aim(self._mouse_aim_point())
        if Input.is_action_just_pressed("star_chart"):
            self.app.quit()

    def _mouse_aim_point(self) -> Vec3:
        """Approximate flight-plane point under the mouse, relative to the ship.

        A screen-centre-relative mapping, good enough for the camera lead;
        the real ship module replaces this with a proper camera ray cast.
        """
        w, h = self.tree.screen_size
        m = Input.mouse_position
        dx = (float(m.x) - w / 2.0) / max(w, 1.0)
        dz = (float(m.y) - h / 2.0) / max(h, 1.0)
        reach = 30.0
        p = self.ship.position
        return Vec3(float(p.x) + dx * reach, PLANE_Y, float(p.z) + dz * reach)


def create_entry_scene() -> Node:
    """The scene the app boots into.

    ``shrike.flow`` owns the run lifecycle (main menu, run setup, the run
    itself) and is what boots in a complete tree. The foundation scene is the
    fallback for a tree without that module, where it keeps the game bootable
    and the ``--test`` smoke gate meaningful.
    """
    if importlib.util.find_spec("shrike.flow") is not None:
        from shrike.flow import create_entry_scene as flow_entry

        return flow_entry()
    return FoundationScene(name="FoundationScene")


#: Fixed seed for the scripted run slice, so the smoke gate is repeatable.
SELFTEST_SEED = 20260823
#: Run number past the onboarding schedule, so the chart answers the player.
SELFTEST_RUN_NUMBER = 4


def _fail(reason: str) -> bool:
    print(f"SELFTEST: FAIL ({reason})")
    return False


def _boot_check() -> bool:
    """Boot the entry scene headlessly and verify the front door.

    Runs without a GPU or a window: the scene is stepped by ``SceneRunner``.
    The game opens on the main menu, so the check is that the menu mounts,
    draws its centred panel inside the screen, and offers entries. Flight is
    checked by the run slice, which drives a live ship.
    """
    from shrike.flow import MainMenuScene

    from simvx.core.testing import SceneRunner

    runner = SceneRunner(screen_size=(WINDOW_WIDTH, WINDOW_HEIGHT))
    runner.load(create_entry_scene())
    runner.advance_frames(60)
    root = runner.root
    if root is None or not root.children:
        return _fail("entry scene mounted empty")
    if not isinstance(root, MainMenuScene):
        return _fail(f"entry scene is {type(root).__name__}, not the main menu")
    if root.menu is None or not root.menu.entries:
        return _fail("the main menu has no entries")
    panel = root.menu_panel()
    if panel is None:
        return _fail("the main menu drew no panel")
    x, y, width, height = panel.get_global_rect()
    if x < 0.0 or y < 0.0:
        return _fail("the menu panel hangs off the top-left of the screen")
    if x + width > WINDOW_WIDTH or y + height > WINDOW_HEIGHT:
        return _fail("the menu panel hangs off the bottom-right of the screen")
    entries = [text for text, _ in root.menu.entries]
    print(f"SELFTEST: boot ok ({runner.frame_count} frames, menu entries: {', '.join(entries)})")
    return True


def _run_slice() -> bool:
    """Fly one scripted slice of a real run, end to end, headlessly.

    Boot into a fixed-seed run, mine a deposit and grab the motes, provoke
    the signature lock, ride out a wave and the Shrike's arrival on the move,
    flee through the star chart once the lockout lifts, then extract at the
    Deep Gate and check the ledger that comes back.
    """
    from shrike.flow import LedgerScene, RunConfig, RunScene

    from simvx.core import JoyAxis, Key
    from simvx.core.testing import InputSimulator, SceneRunner

    runner = SceneRunner(screen_size=(WINDOW_WIDTH, WINDOW_HEIGHT))
    sim = InputSimulator(runner.tree)
    sim.reset()
    scene = RunScene(RunConfig(seed=SELFTEST_SEED, run_number=SELFTEST_RUN_NUMBER).as_dict())
    runner.load(scene)
    runner.advance_frames(10)
    if not scene.running or scene.ship is None or scene.sector is None:
        return _fail("run scene did not assemble")
    if not scene.sector.deposits:
        return _fail("start sector generated no deposits")

    # The spine first: thrust moves the ship on the flight plane and the
    # camera rig follows it. This used to live in the boot check, but the boot
    # scene is now the menu, which mounts no ship.
    ship = scene.ship
    start = Vec3(*ship.position)
    sim.press_key(Key.W)
    runner.advance_frames(90)
    sim.release_key(Key.W)
    runner.advance_frames(30)
    moved = float(abs(ship.position.z - start.z)) + float(abs(ship.position.x - start.x))
    if moved < 1.0:
        return _fail(f"thrust did not move the ship; moved {moved:.3f}")
    if abs(float(ship.position.y) - PLANE_Y) > 1e-4:
        return _fail(f"ship left the flight plane: y={float(ship.position.y):.4f}")
    rig = runner.find(CameraRig)
    if rig is None or rig.camera is None:
        return _fail("the run mounted no camera rig")
    cam_focus_z = float(rig.camera.position.z) - CAMERA_DISTANCE * math.cos(CAMERA_PITCH_RADIANS)
    if abs(cam_focus_z - float(ship.position.z)) > 20.0:
        return _fail("camera rig did not follow the ship")

    seen: set[str] = set()
    scene.waves.wave_spawned.connect(lambda count: seen.add("wave"))

    # Harvest: park west of a deposit, aim the pad stick at it, hold the beam,
    # then tap-grab the motes it sheds.
    deposit = scene.sector.deposits[0]
    ship.position = Vec3(float(deposit.position.x) - 6.0, PLANE_Y, float(deposit.position.z))
    sim.set_gamepad_axis(JoyAxis.RIGHT_X, 1.0)
    sim.set_gamepad_axis(JoyAxis.LEFT_TRIGGER, 1.0)
    runner.advance_time(6.0)
    sim.set_gamepad_axis(JoyAxis.LEFT_TRIGGER, 0.0)
    for _ in range(10):
        sim.tap_key(Key.F)
        runner.advance_frames(6)
    if float(scene.economy.scrap) <= 0.0:
        return _fail("mining and grabbing banked no scrap")

    # Provoke the Shrike, then flee the warning: burner lit, shield astern,
    # weaving so the wave that lands mid-telegraph cannot line up a shot.
    scene.signature.add(balance.SIGNATURE_MAX, "provocation")
    runner.advance_frames(3)
    hunter = scene.hunter_director.hunter
    if hunter is None:
        return _fail("signature lock raised no hunter")
    hunter.hunter_telegraph.connect(lambda stage: seen.add(f"telegraph_{stage}"))
    hunter.hunter_arrived.connect(lambda index: seen.add("arrived"))
    sim.set_gamepad_axis(JoyAxis.RIGHT_X, 0.0)
    sim.set_gamepad_axis(JoyAxis.RIGHT_Y, 1.0)
    sim.press_key(Key.W)
    sim.press_key(Key.LEFT_SHIFT)
    weave = (Key.A, Key.D)
    for step in range(60):
        side = weave[step % 2]
        sim.press_key(side)
        runner.advance_time(1.5)
        sim.release_key(side)
        if "arrived" in seen or scene.ended:
            break
    if "arrived" not in seen:
        return _fail("the Shrike never arrived")
    if "wave" not in seen:
        return _fail("no wave spawned before the arrival")
    for step in range(30):
        side = weave[step % 2]
        sim.press_key(side)
        runner.advance_time(1.0)
        sim.release_key(side)
        if not ship.warp_scrambled or scene.ended:
            break
    sim.release_key(Key.LEFT_SHIFT)
    if scene.ended or float(ship.hull) <= 0.0:
        return _fail("the ship did not survive the arrival")
    if ship.warp_scrambled:
        return _fail("the arrival lockout never lifted")

    # Flee through the star chart.
    sim.tap_key(Key.M)
    runner.advance_frames(2)
    chart = scene.chart_screen
    if not chart.is_open:
        return _fail("the star chart did not open")
    offered = [d for d in chart.destinations() if d.available]
    if not offered:
        return _fail("no affordable escape route on the chart")
    target = min(offered, key=lambda d: d.quote.total).node_id
    if not (chart.select(target) and chart.confirm()):
        return _fail("the chart refused the escape jump")
    if not runner.simulate_until(lambda _: scene.state.current_node_id == target, max_ticks=30 * 60):
        return _fail("the warp never completed")
    if not runner.simulate_until(lambda _: scene.hunter_director.hunter is None, max_ticks=30 * 60):
        return _fail("the Shrike did not depart after the jump")
    runner.advance_frames(30)
    sim.release_key(Key.W)
    if scene.sector is None or scene.state.ledger.arrivals_survived < 1:
        return _fail("the fled-to sector did not come up")

    # Extract at the Deep Gate and read the ledger back.
    gate = next((nid for nid, node in scene.state.chart.nodes.items() if node.is_deep_gate), "")
    if not gate:
        return _fail("the chart has no Deep Gate")
    scene.enter_sector(gate)
    runner.advance_frames(5)
    root = runner.root
    if not isinstance(root, LedgerScene):
        return _fail("extraction did not raise the ledger screen")
    ledger = root.ledger
    if ledger.outcome != "extraction" or not ledger.conversion or ledger.cores_total <= 0.0:
        return _fail("the extraction ledger did not settle")
    if not ledger.recap or not root.lines():
        return _fail("the ledger screen has nothing to say")

    stages = ", ".join(sorted(seen))
    print(f"SELFTEST: slice ok ({runner.frame_count} frames; {stages}; {ledger.cores_total:.1f} Cores)")
    return True


def _selftest() -> bool:
    """The full headless gate: the boot check, then the scripted run slice.

    Saves land in a throwaway directory unless ``SHRIKE_DATA_DIR`` is already
    set, so the gate never touches a real profile.
    """
    os.environ.setdefault("SHRIKE_DATA_DIR", tempfile.mkdtemp(prefix="shrike-selftest-"))
    if not _boot_check():
        return False
    if not _run_slice():
        return False
    print("SELFTEST: PASS")
    return True


#: The settings key holding the player's frame cap, in frames per second. Zero
#: (and an absent key) means "follow the display", which is what the game does
#: with no cap set: vsync-gated and otherwise uncapped.
FRAME_CAP_SETTING = "frame_cap"
#: The settings key holding vertical sync. Unlike the cap this one is live
#: (``App.set_vsync``), and the settings screen flips it there and then; it is
#: still read here so the window opens the way the player left it.
VSYNC_SETTING = "vsync"


def resolve_frame_cap(argv: list[str] | None = None) -> int:
    """The frame cap to run at: ``--fps`` if given, else the saved setting.

    Uncapped is not free. Without a cap the loop runs at whatever the panel
    refreshes at, so a 144 Hz laptop does two and a half times the work of a
    sixty-frame cap for a twin-stick game that reads no better for it, and
    spends the difference in heat and battery.

    Read from disk here so the window opens the way the player left it. That is
    all this does now: ``App.target_fps`` became writable mid-run, so the
    settings screen applies a new cap on the next frame and no longer has to
    wait for a relaunch to be honoured. This is the boot half of the same
    setting, not a workaround for a missing setter.
    """
    argv = list(sys.argv[1:] if argv is None else argv)
    if "--fps" in argv:
        index = argv.index("--fps")
        value = argv[index + 1] if index + 1 < len(argv) else ""
        if not value.isdigit():
            raise SystemExit("--fps expects a frame rate, for example --fps 60 (0 follows the display)")
        return int(value)
    from shrike import save

    try:
        return max(0, int(save.stored_settings().get(FRAME_CAP_SETTING, 0)))
    except (TypeError, ValueError):
        return 0


def resolve_vsync() -> bool:
    """Whether to open the window with vertical sync, off the saved setting.

    On by default and on for any profile that has never been asked, which is
    the setting a laptop panel wants; the settings screen can turn it off
    mid-session because this one the engine does expose a setter for.
    """
    from shrike import save

    return bool(save.stored_settings().get(VSYNC_SETTING, True))


def main(argv: list[str] | None = None) -> None:
    from simvx.graphics import App

    cap = resolve_frame_cap(argv)
    app = App(
        title="SHRIKE",
        width=WINDOW_WIDTH,
        height=WINDOW_HEIGHT,
        target_fps=cap or None,
        vsync=resolve_vsync(),
    )
    app.run(create_entry_scene())


if __name__ == "__main__":
    if "--test" in sys.argv:
        from simvx.core.testing import run_selftest

        sys.exit(run_selftest(_selftest))
    main()