add fight caves env

[jordanbailey00]

Fight Caves

Adds Old School RuneScape's Fight Caves: survive 63 waves, then defeat TzTok-Jad. The agent needs to choose targets, find safe positions, manage run energy, and switch protection prayers before incoming hits.

The environment is implemented in C, with a shared simulator for training, manual play, and checkpoint replay.

Learning Performance

Final evaluations from four independently trained policies using seed 73 and the same configuration, with only the timestep budget changed. Each starts at wave 1 with the Twisted bow loadout and no food or prayer potions. The policy controls movement, attacks, and protection prayers, including 1-tick flicking.

Metric	100M budget	500M budget	750M budget	1000M budget
Evaluation episodes	10,406	10,129	10,124	10,194
Jad kill rate	0.00%	93.96%	92.74%	86.91%
Reached wave 63	0.00%	95.50%	94.66%	89.24%
Average wave reached	31.09	62.77	62.68	62.34
Average damage taken, HP	130.56	101.84	99.38	103.62
Average episode length, ticks	1,804	4,895	4,895	4,764
Attacked when cooldown was ready	87.58%	92.95%	92.88%	96.54%

These benchmark tables were recorded before the logging cleanup; damage taken and attack-readiness metrics are no longer emitted by the current version.

Episode averages include deaths; damage is reported in HP. These are single-seed results. A preliminary hyperparameter sweep was completed, but further sweeps are needed to improve performance and stability with the current mechanics.

Training Performance

Setting	Value
GPU	NVIDIA RTX 5070 Ti, 16 GB
CPU	Intel Core i7-14700F
Environment	Official PufferTank 4.0, native CUDA training
Model	MinGRU, about 2.5M parameters
Model size	3 layers, 512 hidden units
Policy input	286 observations + 34 action-mask values
Action heads	Movement: 17, attack: 9, prayer: 8
Parallel environments	4,096
CPU threads / rollout buffers	16 / 2
Rollout horizon / batch size	256 / 1,048,576
Minibatch size / replay ratio	32,768 / 2.055

Measurement	100M	500M	750M	1000M
Average training SPS	1,061,199	1,057,194	1,058,038	1,036,374
Median logged SPS after 10M steps	1,065,317	1,056,112	1,057,973	1,035,463
Peak logged SPS after 10M steps	1,088,314	1,087,519	1,110,494	1,080,451
Trainer-reported training time	1m 34s	7m 52s	11m 49s	16m 04s
W&B run time, including final evaluation	1m 50s	8m 19s	12m 15s	16m 30s

What's in scope?

• All 63 waves and 15 spawn rotations, with the full Fight Caves monster roster. That includes Tz-Kih prayer drain, Tz-Kek splitting, Yt-MejKot healing, and Jad's healers, which can be tagged and pulled away from him.
• Tile movement, walking and running, run-energy drain and recovery, click routing, NPC pursuit, body blocking, terrain collision and directional line of sight. Supports kiting and safespots.
• Ranged combat with accuracy and damage rolls, weapon speed and range, attack cooldowns, persistent targets, projectile travel and delayed hits. Accurate, rapid and longrange styles affect combat. Unequipping a weapon also supports unarmed attacks. HP regenerates over time.
• NPC melee, ranged and magic attacks, including the mages' close-range attacks and Jad's attack tells. Prayer is checked at the attack's actual protection window, with Jad's delayed prayer lock handled separately from projectile impact.
• Protect from Melee, Missiles and Magic, prayer bonuses, fractional prayer drain, switching and explicit 1t flicking. Flicking resets the drain counter.
• Sharks and prayer potions, inventory slots, potion doses and empty vials, healing/restoration caps, and separate eating and drinking cooldowns. The core also has a karambwan-style combo-eat action; a separate karambwan inventory item isn't implemented yet.
• Equipment requirements and bonuses, ammo compatibility and consumption, stack limits, loaded blowpipe darts, and inventory space checks. Gear switches handle two-handed weapons and shields, update the player model and stats together, and preserve attack cooldowns.
• Nine preset loadouts covering crossbows, the magic shortbow, blowpipe, Twisted bow and Bowfa. Twisted bow scaling uses the target's Magic stats, and crystal armour applies its per-piece Bowfa bonuses.
• Original OSRS cache exports for the models, animations, terrain, textures, UI sprites/fonts, and projectile and impact assets. The viewer renders these in Raylib. This includes equipment appearance, hitsplats, health bars, overhead prayers, the minimap, camera controls and right-click menus.

The current training policy uses fixed gear and no supplies. Consumables and equipment switching are available in the simulation and manual viewer, but aren't actions the policy can choose yet.

This is limited to the Fight Caves encounter. There's no open world, skilling, questing, banking, trading or PvP. Player spellcasting and a full melee weapon system aren't implemented in this PR (though I am also working on and building a full RSPS in C here https://github.com/jordanbailey00/RuneC-Testing). Neither are offensive prayers, special attacks, enchanted-bolt procs, blowpipe venom, Ava's ammo recovery or general gear degradation. Some of those controls appear in the OSRS interface, but they don't drive gameplay.

Things I'd still like to finish are varying the exact spawn tile within each spawn region, adding the large Tz-Kek's melee recoil, and checking Yt-MejKot's healing probability more closely against the game.

Debug Overlay

O toggles collision, line of sight, routes and attack range. The overlay also shows NPC footprints and prayer windows. Space pauses; Right Arrow advances one tick.

The event log records damage, healing, consumable use, kills and wave changes by tick.

The reward tab shows each reward component and the total for the current step.

Separate tabs show player state, cooldowns and action masks.

The manual-play control panel has target and wave selection, NPC health and distance, god mode, and speed controls from 0.25 to 60 TPS. Normal game speed is 5/3 TPS. Replay keeps the camera, diagnostics, pause and speed controls, but disables controls that would change gameplay.

Setup and usage

From an installed PufferLib checkout:

Train

./build.sh fight_caves
puffer train fight_caves

The included configuration uses a 750M-step budget. The build automatically downloads and verifies the required assets.

Play

./build.sh fight_caves --fast
unset __GLX_VENDOR_LIBRARY_NAME
./fight_caves

unset __GLX_VENDOR_LIBRARY_NAME removes PufferTank’s forced Mesa driver selection, which can cause CPU rendering instead of using the GPU.

The viewer starts paused. Press Space to begin, O for debug overlays, and Q to quit.

Replay

unset __GLX_VENDOR_LIBRARY_NAME
puffer eval fight_caves --load-model-path latest

Replay supports camera, pause, speed, and debug controls. Gameplay-changing controls are disabled.

Assets

The build downloads the pinned asset bundles into:

• resources/fight_caves/runtime/: collision, movement, and line-of-sight maps.
• resources/fight_caves/viewer/: models, animations, terrain, textures, UI sprites/fonts, and the minimap.

Archive and file hashes are verified, and valid installations are reused. Download or verification errors stop setup; missing required runtime data fails explicitly. No raw cache or reference repository is needed.

The exported OSRS assets are distributed separately from the source and are not covered by the software license; see ASSET_NOTICE.md.

[jordanbailey00]

Still working on integration with 5.0. Will have that ready in a few days

There is some additional in scope functionality i'll be adding to the core backend and frontend over the coming days as well (all combat spells, spellbook swapping, special attacks, special effects, etc)