From bcbf474df6551eb010463f5e5a18b7d4902347e3 Mon Sep 17 00:00:00 2001 From: Emil Date: Sat, 20 Jun 2026 22:10:33 +0300 Subject: [PATCH] docs: add 4 new phases to PLAN.md - Phase 4b: Graphics over ASCII (lighting, particles, textures, post-processing) - Phase 6: Multi-layer world (separate grids for air, pressure, temp, light) - Phase 7: AI agent integration (LLM via pipe + RL with tensor state) - Phase 8: Web arena (WASM render, WebSocket server, multiplayer, training pipeline) - Updated: milestones to 0.8 + 1.0 Q3 2027 - Updated: open questions, file structure, testing strategy, perf targets --- PLAN.md | 127 +++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 116 insertions(+), 11 deletions(-) diff --git a/PLAN.md b/PLAN.md index aae5664..4db2ba9 100644 --- a/PLAN.md +++ b/PLAN.md @@ -107,9 +107,9 @@ Game loop: fixed 60Hz timestep - XP accumulation triggers level up - Status effect ticks deal correct damage -### Phase 4: Vulkan Renderer +### Phase 4: Vulkan Renderer + Graphics Over ASCII -**Goal: 60+ FPS windowed rendering with GPU** +**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 @@ -117,14 +117,33 @@ Game loop: fixed 60Hz timestep - [ ] Persistent mapped buffer for instance data - [ ] Dirty cell tracking: only update changed cells in instance buffer - [ ] Camera: smooth follow, zoom levels -- [ ] Post-processing: subtle bloom for lava/fire, vignette - [ ] `--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 -- Frame time < 16ms with full viewport +- 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 @@ -144,20 +163,82 @@ Game loop: fixed 60Hz timestep **Goal: deeper Noita-style material simulation** -- [ ] Pressure: liquids have pressure, flow through pipes and U-bends -- [ ] Temperature gradient: heat radiates, materials melt/freeze at thresholds +- [ ] 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 }` — 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 --- @@ -182,8 +263,11 @@ Game loop: fixed 60Hz timestep | 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 | No. But pipe protocol could enable AI vs AI | Never (single-player) | +| 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 | --- @@ -202,6 +286,7 @@ src/ 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) @@ -217,6 +302,9 @@ src/ 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 @@ -224,6 +312,15 @@ src/ 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/ @@ -241,6 +338,8 @@ assets/ | 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) | --- @@ -253,8 +352,11 @@ assets/ | 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 | Future | +| AI playtest | Pipe protocol + agent | [Phase 7] | **Priority: every new feature gets tests before merge.** @@ -268,5 +370,8 @@ assets/ | 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, save/load, polish | December 2026 | -| 1.0 | Full vertical slice: content, balance, death screen | Q1 2027 | +| 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 |