SurvivalOfTheSnippest/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**Survival of the Snippest** — a 3D multiplayer gladiator arena survival roguelike built in Godot 4.5.
Outfit a gladiator with banked gold, enter the colosseum, survive escalating enemy waves, earn gold
from kills and wave clears, and either retire alive (keep everything) or die (keep 10% of your total
value, floored at the 500-gold fresh start). Uses ENet client-server networking.

## Key Commands

### Running the Game
- Open the project in Godot Editor and press F5, or: `godot --path . res://level/scenes/level.tscn`
- Headless script-error check: `godot --headless --path . --quit`

### Testing Multiplayer Locally
1. Run one instance, click ENTER ARENA to host (port 8080)
2. Run a second instance, click JOIN FRIEND to connect (IP 127.0.0.1)

### In-Game Debug Keys
- `N` — start next enemy wave (server only)
- `H` — toggle hitbox/hurtbox debug visualization (off by default)

## The Core Loop

1. **Outfitting screen** (main menu): armory shop on the left/middle, Character Sheet in preview
   mode on the right showing the pending loadout live. Buy weapons with banked gold; hand rules
   enforced (two-handers and off-hands displace each other).
2. **Arena run**: chosen loadout auto-equips on spawn. Waves spawn on a timer; kills pay gold
   (server-credited to the killer's peer), wave clears pay a bonus to all players.
3. **Run end**:
   - **Death** (permadeath, no respawn): results screen; keep `max(500, 10% of total value)`;
     gear and loadout liquidated.
   - **Retire** (escape menu, or quitting alive): bank 100% of run gold, keep all gear.

## Architecture

### Autoloads (singletons)
- **Network** (`level/scripts/network.gd`) — ENet setup, host/join, `players` dict keyed by peer_id
  (`{"nick": String, "skin": Character.SkinColor}`). Server = peer 1, MAX_PLAYERS = 10.
- **GameState** (`level/scripts/game_state.gd`) — the economy. Persists `banked_gold`,
  `owned_items`, `selected_loadout` to `user://save.cfg`. Per-run: `run_gold`, `current_wave`,
  `kills_this_run`, `run_active`. Key API: `buy_item`, `equip_loadout_item`, `start_run`,
  `end_run` (death settlement, double-call guarded), `retire_run` (bank everything),
  `server_credit_kill/gold` (server → owning peer RPCs), `server_sync_wave`.
  No compile-time dependency on Network — keep it that way (testable standalone via `--script`).
- **HUD** (`level/ui/scripts/hud_manager.gd`) — builds all in-run UI for the local player
  (action bar, unit frame, character sheet, arena status wave/gold readout, escape menu,
  run results on death). `reset()` tears everything down when returning to the menu —
  autoload children survive scene reloads, so always reset before `reload_current_scene()`.

### Class hierarchy
- **BaseUnit** (`base_unit.gd`) — health, damage, death, respawn, passive regen. Server validates
  all damage. NOTE: `died` can fire twice on the host (direct emit + call_local sync) — guard
  anything expensive hooked to it.
- **Character** (`player.gd`, class_name Character) — player: movement, dash, attacks, blocking,
  weapon equip/drop/pickup. `can_respawn = false` (death ends the run). Attacks snap the body to
  camera facing and lock direction for startup+active (`_lock_facing_to_camera`); dash locks
  direction for its duration.
- **BaseEnemy** (`base_enemy.gd`) — targeting, `gold_reward` (basic 10, armed 25). Enemies are
  server-authoritative (authority = 1).
  - **BasicEnemy** — melee chaser; `can_respawn = false`, despawns after death, 40% health orb drop.
  - **ArmedEnemy** — player-model enemy that seeks/equips weapons and drops them on death.
    `can_respawn = false` (respawning would be a gold farm). Practice dummies DO respawn and
    deliberately pay no gold.

### Weapons
- **WeaponData** (`weapon_data.gd`) — Resource in `level/resources/*.tres`: combat stats, hand type
  (MAIN_HAND / OFF_HAND / TWO_HAND), block stats, `cost`/`tier` for the shop, `icon` (optional —
  weapon slots fall back to name text when missing).
- **BaseWeapon** — equipped instance on a hand bone; **WorldWeapon** — pickable RigidBody3D.
- No free floor weapons: manually placed WorldWeapons in level.tscn are removed at init on the
  server (`_remove_manual_weapons_on_server`). Gear enters play via the shop or enemy drops only.
- The shop catalog is auto-discovered: any WeaponData `.tres` in `level/resources/` appears in
  the armory (`outfitting_screen.gd`).

### UI
- `character_sheet.gd` has two modes: live player (Tab in-game) and `preview_mode` (embedded in
  the outfitting screen, rendering from a loadout dictionary). Keep both paths working.
- UI is largely built in code; match that style for new components.

### RPC Patterns
- `@rpc("any_peer", "reliable")` — server-validated actions (damage, heal); server checks
  `multiplayer.is_server()` inside.
- `@rpc("any_peer", "call_local", "reliable")` — state sync to all peers (spawns, equips, health).
- `@rpc("authority", ...)` — server-initiated (GameState credits, wave sync).
- Use `rpc_id(peer_id, ...)` for targeted sync (late-join). When the server targets itself
  (peer 1), call the method directly instead of `rpc_id(1, ...)`.
- Late-join sync lives in `level.gd _on_player_connected` — new networked object types must be
  added there (players, weapons, enemies, orbs, equipped gear all have precedents).

### Scene Structure (level.tscn)
- Containers the code expects by name: `PlayersContainer`, `WeaponsContainer`, `EnemiesContainer`,
  `OrbsContainer`, `PlayerSpawnPoints`, `EnemySpawner` (spawn points are its children named
  `EnemySpawnPoint*`).
- Networked nodes are named deterministically for lookup: players by peer_id, `WorldWeapon_<id>`,
  `Enemy_<wave>_<n>`, `ArmedEnemy_<n>`, `HealthOrb_<id>`.

### Physics Layers
1 player · 2 world · 3 weapon · 4 hitbox · 5 hurtbox

### Input Actions (project.godot)
`move_left/right/forward/backward` (WASD), `jump` (Space), `shift` (sprint), `dash` (F),
`attack` (LMB), `block` (RMB), `pickup` (E), `toggle_character_sheet` (Tab),
`toggle_chat` (F12), `quit` (Esc).

## Development Guidelines

### Git Commits
When creating git commits, do NOT include "🤖 Generated with [Claude Code]" or
"Co-Authored-By: Claude" in commit messages. Keep commit messages clean and professional.

### Verification
- Always run `godot --headless --path . --quit` after script changes and check for SCRIPT ERROR.
  (Pre-existing "invalid UID" warnings on mesh/theme assets are known noise.)
- Economy logic can be tested standalone: a SceneTree script that instantiates
  `game_state.gd` and exercises the API (`--script` mode; autoload `_ready` doesn't fire there,
  call `load_save()` manually). Restore the default save afterwards.
- Test multiplayer with 2 instances (host + client); check late joins and death/retire flows.

### Adding Content
- **New weapon**: create a WeaponData `.tres` in `level/resources/` with `cost`/`tier` — the shop
  picks it up automatically.
- **New enemy**: extend BaseEnemy, set `gold_reward`, decide `can_respawn` (respawning enemies
  must not pay gold), add scene to the EnemySpawner pool or spawn via level.gd (connect its
  `died` signal for gold there).
- **Multiplayer state changes**: server validates, then syncs via RPC; check
  `is_multiplayer_authority()` before processing input.