Verbatim/PLAN.md

# Verbatim — Development Plan

> ASCII physics RPG. Noita's cellular automaton + Caves of Qud's RPG depth.
> Every symbol is a material with physics. Every entity is a body with mass.

## Current State (June 2026)

### What Works

| System | Status | Details |
|--------|--------|---------|
| Cellular automaton | Working | 14 materials: sand, water, stone, lava, wood, flesh, bone, steam, fire, acid, smoke, grass, dirt, empty |
| Rigid entities | Working | AABB collider, sliding on surfaces, 27 sub-bodies (5x5 + arm), player + goblins |
| Ragdoll corpses | Working | Verlet constraints, death = rigid→ragdoll transition with inherited velocity |
| Terminal renderer | Working | Full terminal size, ANSI truecolor, diff-based rendering |
| AI pipe protocol | Working | JSON stdin/stdout, 16 commands, full state export |
| Test framework | Working | 28 Rust tests + 8 JSON scenarios, all passing |
| Replay system | Working | Seeded determinism, record/playback, play_until_tick |
| World generation | Basic | Sinusoidal terrain, water/lava/acid pools, wood structure, sand dune, stone wall |

### Architecture

```
Source of truth: text grid (250x250, char + material + temp)

Three entity types:
  1. Cellular  — materials in grid, per-cell CA rules
  2. Rigid     — alive entities, AABB collider, single velocity
  3. Ragdoll   — corpses, loose Verlet bodies, independent physics

Game loop: fixed 60Hz timestep
  Physics tick: CA step → rigid update → ragdoll update → damage
  Render: terminal (ANSI) or pipe (JSON) or headless (file dump)
```

### Numbers

- ~4600 lines Rust
- 28 integration tests, 8 JSON scenarios
- 11 git commits
- 0 compiler warnings

---

## Roadmap

### Phase 1: Combat & Interaction (next)

**Goal: entities can fight and affect each other**

- [ ] Melee combat: rigid entity AABB overlap → damage exchange
- [ ] Health bars in terminal render (colored indicator above entity)
- [ ] Death → ragdoll → corpse decomposition (flesh cells drop into grid over time)
- [ ] Projectile system: thrown objects (arrows, fireballs) as lightweight rigid bodies
- [ ] Material interaction with entities: entity walks through fire → ignites, acid → dissolves
- [ ] Knockback: damage applies velocity impulse to rigid body center
- [ ] Goblin AI: move toward player, attack when adjacent, flee when low HP

**Tests needed:**
- Melee damage between two entities
- Knockback direction correctness
- Corpse decomposition produces flesh cells in grid
- Projectile travels and deals damage on hit
- Goblin AI moves toward player

### Phase 2: World & Exploration

**Goal: explorable world with depth and variety**

- [ ] Chunk system: world divided into chunks (64x64), only active chunks simulated
- [ ] Chunk persistence: save/load chunks to disk
- [ ] Vertical descent: stairs/holes between depth levels
- [ ] Biomes: grassland, cave, lava cavern, ice, fungus forest — each with material palette
- [ ] Procedural dungeon generation: rooms, corridors, traps
- [ ] Camera zoom: +/- keys to change viewport scale (more or fewer cells visible)
- [ ] Minimap: ASCII overview of explored area
- [ ] Day/night cycle: ambient light affects rendering (dimmer at night)

**Tests needed:**
- Chunk save/load roundtrip preserves state
- Entity crossing chunk boundary continues correctly
- Dungeon generation produces connected rooms
- Biome materials match expected palette

### Phase 3: RPG Layer

**Goal: character progression, inventory, abilities**

- [ ] Stats: strength, agility, toughness, willpower — affect damage, speed, HP, etc.
- [ ] Inventory system: items as data structs, pick up by walking over, drop with key
- [ ] Equipment: weapon affects melee damage/range, armor affects damage reduction
- [ ] Items in world: weapons, potions, scrolls, food — rendered as distinct ASCII chars
- [ ] Mutations (Caves of Qud style): modify entity properties
  - "Silicon skin" → entity material becomes Stone, immune to acid
  - "Flame body" → entity emits fire cells, immune to fire
  - "Liquid form" → entity can squeeze through 1-cell gaps
  - "Multiple arms" → extra attack, can hold more items
- [ ] XP and leveling: kill entities → gain XP → level up → choose mutation
- [ ] Skills: active abilities on cooldown (dash, stomp, material blast)
- [ ] Status effects: burning, poisoned, frozen, bleeding — each with tick effect
- [ ] Dialogue: talk to NPCs, simple text tree

**Tests needed:**
- Stat modifiers affect combat correctly
- Item pickup/drop maintains inventory integrity
- Mutation changes entity material/properties
- XP accumulation triggers level up
- Status effect ticks deal correct damage

### Phase 4: Vulkan Renderer + Graphics Over ASCII

**Goal: 60+ FPS windowed rendering with GPU, graphics layered over ASCII grid**

- [ ] ash (Vulkan) bootstrap: instance, device, swapchain, render pass
- [ ] Glyph atlas: DejaVu Sans Mono rasterized at startup via fontdue
- [ ] Instanced rendering: one draw call for all visible cells
- [ ] Persistent mapped buffer for instance data
- [ ] Dirty cell tracking: only update changed cells in instance buffer
- [ ] Camera: smooth follow, zoom levels
- [ ] `--mode auto`: try Vulkan, fallback to terminal
- [ ] Single binary: font embedded via include_bytes!

**Graphics layers over ASCII (Phase 4b):**
- [ ] Lighting pass: compute shader calculates light grid from sources (lava, fire, torches)
  - Materials emit light with color/intensity
  - Walls cast shadows (ray-march in compute)
  - Light grid modulates cell brightness in render
- [ ] Particle system: GPU particles positioned relative to grid cells
  - Fire sparks, water splashes, smoke trails, blood
  - Particle lifetime + physics (gravity, wind)
- [ ] Procedural material textures: per-cell texture instead of flat color
  - Stone: noise pattern, cracks
  - Water: animated wave distortion
  - Lava: flowing magma texture, glow
  - Wood: grain pattern
- [ ] Post-processing: bloom (bright materials glow), vignette, optional CRT curvature
- [ ] Ambient effects: heat shimmer above lava, dust motles in air, screen shake on explosions

**Terminal mode stays pure ASCII. Vulkan mode = ASCII + graphics layers.**

**Tests needed:**
- Vulkan init doesn't crash on supported hardware
- Render output matches terminal render for same state (cell positions/colors)
- Frame time < 16ms with full viewport + lighting + particles
- Lighting grid updates when light sources change
- Particle count scales with active fire/lava cells

### Phase 5: Content & Polish

**Goal: playable vertical slice**

- [ ] Factions: goblins, skeletons, slimes, trolls — each with AI behavior
- [ ] Boss entity: large rigid body (10x10), multiple attack patterns
- [ ] Books/readable items: lore text displayed in terminal
- [ ] Crafting: combine materials to create new ones (water + dirt = mud)
- [ ] Sound: procedural audio via terminal bell or optional ALSA
- [ ] Save/load: full game state to file (grid + entities + player + inventory)
- [ ] Death screen: stats summary, cause of death
- [ ] Tutorial: first-time controls overlay
- [ ] Difficulty scaling: deeper levels = stronger enemies

### Phase 6: Advanced Physics

**Goal: deeper Noita-style material simulation**

- [ ] Multi-layer world: separate grid layers for material, temperature, pressure, gas/air, light
  - Air layer: gas flow, ventilation in caves, gas accumulates at ceiling, displaced by fire
  - Pressure layer: liquids have pressure, flow through pipes and U-bends
  - Temperature layer: proper heat diffusion, materials melt/freeze at thresholds
  - Light layer: ray-cast from sources (lava, fire, torch), affects rendering
  - Layers interact: fire heats temp layer → temp melts material → material releases gas
- [ ] Electricity: conductive materials carry current, shocks entities
- [ ] Explosions: rapid gas expansion, creates fire + destroys terrain
- [ ] Structural integrity: stone/wood can collapse under load
- [ ] GPU compute: cellular automaton on Vulkan compute shader for large worlds
- [ ] Fluid simulation: proper Navier-Stokes for water instead of CA approximation

**Architecture: `World { layers: Vec<GridLayer> }` — each layer is a separate grid updated by its own rules, with cross-layer interactions.**

**Tests needed:**
- Pressure equalizes in connected containers
- Heat propagates through conductive materials
- Gas flows upward, accumulates at ceiling
- Electricity follows conductive path
- Explosion destroys terrain in radius
- Collapse triggers when support removed
- Layer interaction: fire → temp rise → material melt

### Phase 7: AI Agent Integration

**Goal: local neural network plays Verbatim as an agent**

- [ ] LLM agent: local model (Ollama/Llama/Qwen) connects via pipe protocol
  - Reads JSON state (ASCII view + structured data)
  - Reasons in text, sends JSON actions
  - Good for testing mechanics, exploration, debug
- [ ] RL agent: trained policy network (PyTorch)
  - State as tensor (material grid + entity positions + HP)
  - Action as discrete output (move, attack, use ability)
  - Fast inference, real-time play
  - Requires training data (see Phase 8)
- [ ] Agent observation format: compact binary state tensor for RL (not JSON)
- [ ] Agent action batch mode: multiple actions per pipe message for throughput
- [ ] Agent recording: save (state, action, reward) tuples for offline training
- [ ] Agent vs agent: two pipe connections, competitive play

**Tests needed:**
- LLM agent can init, observe, act, quit via pipe
- RL state tensor matches grid state
- Recording produces valid training data format
- Agent vs agent game completes with winner

### Phase 8: Web Arena & Training Pipeline

**Goal: browser-based multiplayer arena for human + AI training data**

- [ ] Headless game server: Rust + tokio, authoritative simulation, WebSocket API
- [ ] WASM render port: game renders in browser via Canvas/WebGL, reads JSON state
- [ ] WebSocket bridge: server ↔ browser, state diffs + input commands
- [ ] Arena mode: single room, enemies, fast respawn, score timer
- [ ] Multiplayer: multiple clients connect to same server, shared world
- [ ] Recording pipeline: all player sessions recorded as (state, action, outcome) tuples
- [ ] Dataset export: recorded sessions → training data for RL agent (Phase 7)
- [ ] Leaderboard: human vs AI scores, competitive training incentive
- [ ] Spectator mode: watch AI agents fight, replay system in browser

**Architecture:**
```
Browser (WASM + Canvas)  ←WebSocket→  Rust Server (tokio + game engine)
     ↑                                    ↑
  Player input                       Pipe protocol
                                     (AI agents connect locally)
```

**Tests needed:**
- Server accepts WebSocket connections
- State sync: all clients see same world state
- WASM render matches terminal render for same state
- Recording captures all state changes
- Dataset export produces valid tensor format
- Multiple clients don't desync

---

## Architecture Decisions

### Locked

| Decision | Rationale |
|----------|-----------|
| Text grid as source of truth | AI-observable, dual renderer, single state |
| Rust + crossterm + ash | Zero-cost, memory safety, explicit GPU control |
| Fixed 60Hz timestep | Deterministic replay, consistent physics |
| AABB for rigid, Verlet for ragdoll | Simple, no tunneling for rigid; expressive for ragdoll |
| Seeded RNG for determinism | Replay system, reproducible tests |
| JSON pipe protocol | Any AI agent can connect, no vision needed |
| Single binary with embedded font | Portable, no external assets |

### Open Questions

| Question | Options | When to decide |
|----------|---------|----------------|
| Turn-based vs real-time | Currently real-time 60Hz. Qud is turn-based. Hybrid? | Phase 3 |
| World topology | Single deep shaft vs branching dungeon vs open world | Phase 2 |
| Save format | Binary (compact) vs JSON (debuggable) vs RON | Phase 5 |
| Multiplayer | Phase 8: web arena for AI training. Core game stays single-player | Phase 8 |
| Modding | Data-driven materials from JSON/TOML? | Phase 3 |
| Multi-layer architecture | Separate grids per layer vs interleaved in one Cell? | Phase 6 |
| RL model architecture | CNN over grid? Transformer? Hybrid? | Phase 7 |
| WASM render target | Canvas 2D vs WebGL vs WebGPU | Phase 8 |

---

## File Structure (current + planned)

```
src/
  main.rs              # CLI entry point
  lib.rs               # Library root
  game.rs              # Game loop, world gen, entity management
  input.rs             # Keyboard input → Action enum
  world/
    cell.rs            # Cell struct, MaterialId enum
    material.rs        # Material properties registry
    grid.rs            # Grid (250x250), cell access
    cellular.rs        # Cellular automaton rules
    chunk.rs           # [Phase 2] chunk system
    worldgen.rs        # [Phase 2] procedural generation
    layers.rs          # [Phase 6] multi-layer world (temp, pressure, gas, light)
  physics/
    verlet.rs          # Verlet integrator, constraints
    collision.rs       # AABB-vs-grid collision (used by ragdoll)
    projectile.rs      # [Phase 1] lightweight projectiles
  entity/
    entity.rs          # Entity struct, rigid/ragdoll, build_humanoid
    player.rs          # Player controller
    ai.rs              # [Phase 1] goblin AI
    inventory.rs       # [Phase 3] items and equipment
    stats.rs           # [Phase 3] character stats
    mutations.rs       # [Phase 3] mutation system
  render/
    mod.rs             # Renderer trait
    terminal.rs        # Terminal renderer (ANSI)
    vulkan.rs          # [Phase 4] Vulkan renderer
    lighting.rs        # [Phase 4b] compute shader lighting
    particles.rs       # [Phase 4b] GPU particle system
    textures.rs        # [Phase 4b] procedural material textures
  ai/
    session.rs         # GameSession wrapper for AI/testing
    state.rs           # JSON state export
    action.rs          # AiAction enum
    protocol.rs        # JSON pipe protocol
    replay.rs          # Record/playback
    scenario.rs        # JSON test scenarios
    rl_bridge.rs       # [Phase 7] tensor state export for RL agents
    recording.rs       # [Phase 7/8] (state, action, reward) recording
server/                # [Phase 8] web arena server
  server.rs            # tokio WebSocket server
  arena.rs             # arena game mode
  recording.rs         # training data collection
web/                   # [Phase 8] WASM browser client
  render.rs            # Canvas/WebGL render from JSON state
  input.rs             # browser keyboard → commands
tests/                 # 28 integration tests
scenarios/             # 8 JSON scenarios
assets/
  DejaVuSansMono.ttf   # Embedded font for Vulkan renderer
```

---

## Performance Targets

| Metric | Target | Current |
|--------|--------|---------|
| CA step (250x250) | < 1ms | ~0.5ms |
| Rigid entity update | < 0.5ms per entity | ~0.2ms |
| Terminal render frame | < 5ms | ~2ms (diff-based) |
| Vulkan render frame | < 16ms (60 FPS) | N/A |
| Pipe protocol latency | < 1ms per command | ~0.1ms |
| RL state export | < 0.5ms per frame | N/A |
| WebSocket state sync | < 50ms per frame | N/A |
| Binary size (release) | < 10MB | ~6MB (debug, no Vulkan) |

---

## Testing Strategy

| Layer | Method | Count |
|-------|--------|-------|
| Material physics | Rust integration tests | 15 |
| Entity physics | Rust integration tests | 8 |
| AI/replay | Rust integration tests | 4 |
| JSON scenarios | Declarative test files | 8 |
| Multi-layer physics | Rust integration tests | [Phase 6] |
| RL bridge | Rust integration tests | [Phase 7] |
| Web server | Rust integration tests | [Phase 8] |
| Manual playtest | Terminal mode | As needed |
| AI playtest | Pipe protocol + agent | [Phase 7] |

**Priority: every new feature gets tests before merge.**

---

## Release Milestones

| Milestone | Content | Target |
|-----------|---------|--------|
| 0.1 (done) | Core engine: CA, rigid, ragdoll, terminal, AI pipe | June 2026 |
| 0.2 | Combat, goblin AI, projectiles, corpse decomposition | July 2026 |
| 0.3 | Chunks, biomes, dungeon gen, camera zoom | August 2026 |
| 0.4 | RPG layer: stats, inventory, mutations, XP | October 2026 |
| 0.5 | Vulkan renderer + graphics layers (lighting, particles, textures) | December 2026 |
| 0.6 | Multi-layer world: air, pressure, temperature, light as separate grids | Feb 2027 |
| 0.7 | AI agent: LLM + RL bridge, agent recording | April 2027 |
| 0.8 | Web arena: WASM render, WebSocket server, multiplayer, training pipeline | June 2027 |
| 1.0 | Full vertical slice: content, balance, death screen, trained AI agents | Q3 2027 |