Cavern (Challacade)

Jetpack platformer, engine test only (BY-NC-ND assets).

📄 Docs only

Upstream: https://github.com/challacade/cavern

Tags: port tier-1

Cavern: SimVX Port (Engine Test Only)

SimVX port of Challacade/cavern, a 2D adventure platformer originally written in LÖVE 2D.

DO NOT REDISTRIBUTE. Source code is MIT, but the art and audio assets are licensed CC BY-NC-ND 4.0 by Challacade. This port exists solely as a SimVX engine integration test. See ../LICENSE_NOTICE.md for the full rules.

Run

# Desktop
uv run python ported_games/cavern/simvx_port/main.py

# Skip the menu and drop straight into gameplay
uv run python ported_games/cavern/simvx_port/main.py --game

# Headless capture (writes screenshots/frame_30.png, frame_60.png, frame_120.png)
uv run python ported_games/cavern/simvx_port/main.py --test

# Web export (outputs simvx_port/web/index.html)
uv run simvx export web ported_games/cavern/simvx_port/main.py \
    -o ported_games/cavern/simvx_port/web/index.html

All commands must run from /home/fezzik/dev/simvx (the workspace root); uv won’t resolve workspace-only packages from a port subdirectory.

Controls

Action	Binding
Move	WASD / Arrow keys
Jetpack thrust up	W / Up / Space
Aim weapon	Mouse
Fire blaster	Left mouse button
Back to menu	Esc

What’s faithful to upstream

• Three rooms (rm1, rm2, rm3) parsed from upstream’s STI Lua exports; same wall geometry, transitions, and spike-enemy placements.

• Player sprite stack: jetpack + body + helmet + arm, with Cavern’s exact artwork.

• Aim-with-mouse + LMB-fire blaster; camera follows player and clamps to room bounds.

• Music (cavern.ogg, menu.ogg) and sfx (laser.wav, itemGet.wav, blip.wav) wired through AudioStreamPlayer.

What’s reduced (engine-test scope)

• Only the blaster weapon (rocket launcher / spear gun / aquaPack are wired as pickup labels but don’t change behaviour).

• Jetpack approximation: simple gravity + thrust integrator instead of LÖVE’s Box2D solver. Feel is similar; tunables in nodes/config.py.

• Single enemy type (Spike); Cavern’s other enemies (flyer, fish, starfish, egg, boss) are out of scope.

• No water / drowning / aquaPack mechanic (Cavern’s underwater rooms behave like dry rooms here).

• No breakables, vines, or boss room.

• Menu is keyboard / mouse driven; the upstream rmMainMenu bespoke layout isn’t used.

Files

simvx_port/
├── main.py              entry point + test/capture mode
├── pyproject.toml       PEP 621 + [tool.simvx] root="CavernRoot"
├── nodes/
│   ├── lua_map.py       STI-Lua map parser (Walls/Transitions/Enemies/...)
│   ├── config.py        tuning constants
│   ├── room.py          Room + Pickup nodes (one per active map)
│   ├── player.py        Player, Bullet
│   ├── enemies.py       Spike, EnemyProjectile, spawn_enemy()
│   ├── hud.py           in-game HUD (health pips + room label + bottom strip)
│   ├── menu.py          MainMenu scene
│   ├── game.py          CavernGame: owns room + camera + collisions
│   └── root.py          CavernRoot scene container (web-export entry)
├── assets/
│   ├── sprites/         player, enemies, environment, items
│   ├── sounds/          laser, itemGet, blip
│   ├── music/           cavern.ogg, menu.ogg
│   └── maps/            rm1.lua, rm2.lua, rm3.lua, rmMainMenu.lua
├── screenshots/
└── web/

Source

#!/usr/bin/env python3
"""Cavern (Challacade): Jetpack platformer, engine test only (BY-NC-ND assets).

# /// simvx
# tags = ["port", "tier-1"]
# upstream = "https://github.com/challacade/cavern"
# web = { width = 1152, height = 768, responsive = true, disabled = true, reason = "Blocked on audio refactor (uses old 'Music' bus name; upstream art also under BY-NC-ND)." }
# ///

Source code MIT (Challacade); art and audio assets are CC BY-NC-ND 4.0.
Engine test only; see ``ported_games/cavern/LICENSE_NOTICE.md``.

Run desktop : uv run python ported_games/cavern/simvx_port/main.py
Headless    : uv run python ported_games/cavern/simvx_port/main.py --test
Web export  : uv run simvx export web ported_games/cavern/simvx_port/main.py \
                  -o ported_games/cavern/simvx_port/web/index.html
"""

# /// script
# requires-python = ">=3.13"
# dependencies = ["simvx-core", "simvx-graphics", "numpy", "pillow"]
# ///

from __future__ import annotations

import sys
from pathlib import Path

_PORT_DIR = Path(__file__).resolve().parent
sys.path.insert(0, str(_PORT_DIR))

from simvx.graphics import App  # noqa: E402

from nodes.root import CavernRoot  # noqa: E402

WINDOW_W = 1152
WINDOW_H = 768


def main() -> None:
    test_mode = "--test" in sys.argv
    skip_intro = "--game" in sys.argv

    app = App(
        width=WINDOW_W, height=WINDOW_H,
        title="Cavern (SimVX engine test)",
        visible=not test_mode,
    )

    start = "game" if skip_intro else "menu"

    if test_mode:
        from simvx.graphics import save_png
        out = _PORT_DIR / "screenshots"
        out.mkdir(exist_ok=True)
        capture_frames = [30, 60, 120]
        # Capture both menu and gameplay: 30 = menu, 60/120 = gameplay.
        captured = app.run_headless(
            CavernRoot(start_scene="game"),
            frames=150,
            capture_frames=capture_frames,
        )
        for idx, n in enumerate(capture_frames):
            if idx < len(captured):
                save_png(out / f"frame_{n}.png", captured[idx])
                print(f"wrote frame_{n}.png")
        app.quit()
        return

    app.run(CavernRoot(start_scene=start))


if __name__ == "__main__":
    main()