# Cavern (Challacade)

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

```{raw} html
<span class="example-docs-badge">📄 Docs only</span>
<p><strong>Upstream:</strong> <a href="https://github.com/challacade/cavern">https://github.com/challacade/cavern</a></p>
```

**Tags:** `port` `tier-1`

# Cavern: SimVX Port (Engine Test Only)

SimVX port of [Challacade/cavern](https://github.com/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

```bash
# 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

```{literalinclude} ../../examples/ports/cavern/main.py
:language: python
:linenos:
```