update claude.md

Signed-off-by: Jason Hall <jason@chainguard.dev>

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-**Terminus** is a Go-based terminal FPS engine inspired by Wolfenstein 3D that renders 3D scenes using raycasting and ANSI escape codes. The project implements a complete 3D game engine that runs in the terminal with real-time movement, projectile physics, dynamic lighting, and a debug HUD.
+**Terminus** is a multiplayer SSH-based terminal FPS engine inspired by Wolfenstein 3D that renders 3D scenes using raycasting and ANSI escape codes. The project implements a complete multiplayer 3D game engine accessible via SSH, featuring real-time player interaction, wandering NPCs, projectile physics, dynamic lighting, and a debug HUD.
 
 ## Architecture
 
@@ -15,12 +15,14 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - `player.go` - Player state including position, direction, camera plane, and movement methods with collision detection
 - `world.go` - Map loading system that reads `.map` files with integer grids (0=empty, 1-8=wall types)
 - `projectile.go` - Projectile physics system with fireballs, dynamic lighting, and lifecycle management
+- `npc.go` - NPC system with random walk AI, collision detection, and wandering behavior
 
 **Rendering System (`renderer/`):**
 - `renderer.go` - Raycasting engine that projects 3D scenes to 2D using DDA algorithm
   - Wall rendering with distance-based shading and lighting effects
-  - Sprite rendering for projectiles with proper 3D positioning
+  - Advanced sprite rendering for projectiles, players, and NPCs with Z-buffer depth testing
   - Dynamic lighting system that affects wall brightness
+  - Proper sprite sorting and perspective projection for multiplayer visibility
 
 **Display System (`screen/`):**
 - `screen.go` - Screen buffer and HUD system with ANSI positioning
@@ -28,19 +30,29 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
   - Efficient ANSI rendering that positions cursor instead of scrolling
   - Color management with RGB support
 
-**Main Loop (`main.go`):**
-- Terminal size detection and raw input handling
-- 30 FPS game loop with delta time calculations
+**SSH Server & Main Loop (`main.go`):**
+- SSH server on port 2222 with persistent host key generation
+- Per-player game session management with goroutines
+- Terminal size detection from SSH PTY and input handling
+- 30 FPS shared game loop with delta time calculations
 - Map file loading with command-line selection
-- Debug information display in HUD
+
+**Multiplayer Server (`server/`):**
+- `server.go` - GameServer with thread-safe player and NPC management
+  - Shared world state with up to 10 concurrent players
+  - Random spawn point generation for players and NPCs
+  - NPC spawning and lifecycle management (3-5 NPCs per map)
 
 ### Rendering Pipeline
 
 1. **Raycasting**: For each screen column, cast a ray from player position through camera plane
 2. **DDA Algorithm**: Step ray through map grid until wall intersection
 3. **Wall Rendering**: Calculate wall height based on distance, apply lighting and shading
-4. **Sprite Rendering**: Project 3D projectile positions to 2D screen coordinates
-5. **Screen Output**: Use ANSI positioning to efficiently update display
+4. **Z-Buffer Population**: Store wall distances for proper sprite depth testing
+5. **Sprite Collection**: Gather all sprites (projectiles, other players, NPCs) visible to current player
+6. **Sprite Sorting**: Sort sprites by distance (painter's algorithm)
+7. **Sprite Rendering**: Project 3D sprite positions to 2D with Z-buffer testing for proper occlusion
+8. **Screen Output**: Use ANSI positioning to efficiently update display
 
 ### Map System
 
@@ -52,22 +64,27 @@ Maps are text files with space-separated integers:
 
 ## Development Commands
 
-### Build and Run
+### Build and Run SSH Server
 ```bash
-go build                    # Build the executable
-./terminus                 # Run with default maze.map
-./terminus cave.map        # Run with specific map file
-go run main.go maze.map    # Run directly with Go
+go build                    # Build the SSH server
+./terminus                 # Start SSH server with default maze.map on port 2222
+./terminus cave.map        # Start SSH server with cave.map
+go run . cave.map          # Run SSH server directly with Go
+```
+
+### Connect to Server
+```bash
+ssh -p 2222 localhost      # Connect to local server
 ```
 
 ### Map Selection
-Maps are loaded at startup via command line argument. The game automatically selects spawn positions based on map type.
+Maps are loaded at server startup via command line argument. Players spawn at random empty locations.
 
-## Controls
+## Controls (per SSH client)
 
 - `W/A/S/D` - Movement and strafing with collision detection
 - `Q/E` - Rotate left/right
-- `SPACE` - Shoot fireball projectiles with dynamic lighting
+- `SPACE` - Shoot fireball projectiles with dynamic lighting (visible to all players)
 - `ESC` or `Ctrl+C` - Exit
 
 ## Key Implementation Details
@@ -77,6 +94,19 @@ Maps are loaded at startup via command line argument. The game automatically sel
 - Player direction vector defines facing direction
 - Camera plane vector (perpendicular to direction) defines FOV (~60 degrees)
 
+### Multiplayer Architecture
+- **SSH Server**: Handles up to 10 concurrent connections on port 2222
+- **Per-Player Sessions**: Each SSH connection gets isolated game loop goroutine
+- **Shared State**: Map, projectiles, and NPCs shared across all players
+- **Thread Safety**: Mutex protection for concurrent access to shared data
+
+### Sprite System
+- **Players**: Large green `@` symbols (1.2x scale, 75% width-to-height ratio)
+- **NPCs**: Medium blue `◐` symbols (1.0x scale, 50% width) with random walk AI
+- **Projectiles**: Orange `●` symbols (0.5x scale) with circular fade patterns
+- **Z-Buffer Testing**: Proper depth testing so sprites hide behind walls
+- **Coordinate Transformation**: Proper 3D-to-2D projection using camera plane
+
 ### Lighting System
 - Fireballs create `LightSource` objects with position, radius, intensity
 - Wall colors are modified by distance-based fog and dynamic lighting
@@ -84,10 +114,13 @@ Maps are loaded at startup via command line argument. The game automatically sel
 
 ### Screen Management
 - Game area uses `screen.GameHeight` (total height - 2 for HUD)
-- HUD shows real-time debug info: player position, active projectiles, etc.
+- HUD shows real-time debug info: player position, player count, active projectiles
 - ANSI escape codes used for cursor positioning and true-color support
+- Per-player rendering with terminal resize support
 
 ### Performance
-- 30 FPS with delta time for smooth movement
+- 30 FPS server-side game loop with delta time for smooth movement
+- 30 FPS per-player rendering loops
 - Efficient raycasting with DDA algorithm
 - Optimized ANSI rendering with color change detection
+- Thread-safe concurrent player and NPC updates