Documentation
Uruk Engine v1.0.0
Browser-based AAA game development platform for Uruk — The First City
A web-based visual editor and game engine for an open-world action-adventure RPG set in ancient Mesopotamia (~3000 BCE). Built with React 19 + TypeScript + Three.js on the frontend, Express + tRPC on the backend. Features a complete editor with 12 modes, AI-powered world building (Uruk AI with 25+ actions and 60+ mode tools), a WebGPU/WebGL2 dual-backend render pipeline, 2D→3D character pipeline, cinematic sequencer, mission editor, blueprint system, dialogue system, and 2,047+ tests.
Current version: v10.32 — Sequence Conflict Resolution, Objective Progress in Countdown, Background Revalidation Loop. The subsystem maturity table below is the source of truth for what works, what is scaffolded, and what is placeholder.
Subsystem Maturity
Each subsystem is rated on a three-level scale:
| Level | Meaning |
|---|---|
| Implemented | Runs in the editor, produces visible/measurable results, has tests |
| Integrated | Wired into the runtime loop but limited in scope or fidelity |
| Architecture | Types, interfaces, and data structures exist; logic is stubbed or minimal |
| Subsystem | Maturity | What Exists |
|---|---|---|
| Visual Editor (v10.26+) | Implemented | Full IDE: TopBar, ToolShelf (12 modes), CommandPalette (30+ commands), Enhanced Inspector (search, reset-to-default, color picker), Viewport Context Menu, keyboard shortcuts (W/E/R/Q/F/P/G + Ctrl combos) |
| 3D Viewport | Implemented | Three.js scene with orbit controls, grid, sky, weather overlays, entity selection, gizmos, stats overlay. RenderGraph with compute cull, shadow, opaque, SSAO, bloom, color grading, debug overlay passes. WebGPU backend with runtime detection and fallback. |
| ECS | Implemented | World, Entity, Component, System with typed registration, per-phase step loop, stats collection. |
| Uruk AI (v10.27) | Implemented | 25+ cataloged actions across 10 categories. 60+ tools across 12 editor modes. 4 context collectors (selection, scene, viewport, project). Transaction log with draft→applied→reverted lifecycle. Cross-session memory. Enhanced 4-tab panel: Chat, Actions, History, Memory. AI commands in Command Palette and Viewport Context Menu. Playtest analysis with FPS/event tracking. |
| Render Pipeline | Implemented | 6-layer architecture with RenderGraph. TAA, CSM, PostProcessStack (Bloom/Vignette/SSAO/ColorGrade). Runtime backend selection (auto/webgl2/webgpu). GPU compute frustum culling. InstancedMesh batching (palm trees 51→2 draw calls). GPU timestamp queries. Render quality presets (low/medium/high/ultra). WebGPU compute post-processing (WGSL shaders). |
| Content Persistence (PCS) | Implemented | ProjectContentService with auto-save, conflict resolution (Smart Merge with field-level diff), save slots, JSON export/import. Stale/Live diagnostics. Per-asset authority tracking. File history with version timeline and diff preview. |
| Cinematic Sequencer | Implemented | PCS-first editing. Timeline with keyframe tracks (camera, lighting, crowd, weather, dialogue). Per-sequence authority status, binding validation, stale detection. Conflict resolution with optimistic locking. |
| Mission Editor | Implemented | Full CRUD editor. Time-based failures, prerequisite chains, multi-objective states. Mission countdown overlay with urgency-based HUD. Objective progress tracking (required/optional). Per-mission diagnostics and cell-aware activation. |
| Blueprint Editor | Implemented | Node-graph canvas with 12 node types, pin-type validation, drag-and-drop, zoom/pan. Connected to interpreter via PCS. Persists to DB. |
| Dialogue System | Implemented | Runtime interpreter with branching dialogue trees. PCS-AUTH CRUD. |
| Audio Runtime | Implemented | Spatial audio, ambience, and voice playback. |
| Particle System | Implemented | Particle system engine with runtime integration. |
| Code Editor | Implemented | Full-screen/split modes, file explorer, version timeline, diff preview, one-click restore (Ctrl+H). |
| 3D Studio (Forge 3D) | Implemented | Image-to-3D pipeline via Tripo API, PBR texture extraction, auto-rigging, text-to-animate, GLB export. Ultra/Standard mesh quality. |
| 2D Character Designer | Implemented | Text-to-2D generation with style controls, historical period presets (3500–1500 BCE), clothing styles, skin tone/hair/body type selectors, accessories, multiple AI models (Manus AI, Qwen VL, SDXL). Send to 3D pipeline. |
| World Streaming | Integrated | StreamingManager with real cell lifecycle, proximity activation, LOD, memory budget caps, live minimap. 12 cells defined for Uruk city. |
| AI Navigation | Integrated | NavigationGraph with A* pathfinding (42 nodes). AgentRuntime with 8-state FSM, patrol route following, schedule execution, perception/suspicion. Patrol validation cache with dirty-flagging. Background revalidation loop. |
| Physics | Integrated | PhysicsWorld with AABB/sphere/mesh colliders, trigger volumes, overlap detection, raycast, character controller, debug wireframe overlay. |
| Runtime Orchestrator | Integrated | Single update() sequences streaming→AI→physics→render per frame. Game time with configurable scale. |
| Profiling & Diagnostics | Integrated | Start/stop profiling sessions, frame-by-frame subsystem timing, per-pass CPU/GPU timing, renderer stats (draw calls, triangles, texture memory), health indicators. |
| WebGPU Compute Renderer | Architecture | Custom WebGPU-native renderer with own GPU device, resource management, pipeline caching, WGSL shaders. Not yet wired into Viewport render loop. |
| Terrain Sculptor | Architecture | Brush tools, texture splatting, 3D wireframe preview. Operates on local heightmap. |
| Desktop App (Electron) | Architecture | Electron shell with main process, preload script, splash screen, build scripts. |
| Multiplayer | Architecture | Session lobby UI, simulated peer cursors. No WebSocket server. |
Editor Features (v10.26+)
The editor underwent a major overhaul in v10.26, replacing the old MenuBar and Toolbar with a unified TopBar and ToolShelf system. Key additions:
| Feature | Version | Description |
|---|---|---|
| Top Bar | v10.26 | Unified bar: logo, scene name, save status, undo/redo, play controls, mode switcher (12 modes), command palette (Ctrl+P), BUILD, AI toggle |
| Tool Shelf | v10.26 | Vertical left sidebar with 12 mode icons and mode-specific tools (Select: W/E/R + snap; Place: mesh/light/camera/trigger; Terrain: sculpt/paint/flatten/smooth/erosion; Lighting: sun/sky/fog; Debug: collision/navmesh/physics) |
| Command Palette | v10.26 | Ctrl+P fuzzy search across 30+ commands in 8 categories with keyboard navigation and shortcut display |
| Enhanced Inspector | v10.26 | AAA-style collapsible sections, property search, per-property reset-to-default, copy values, color picker, modified highlighting |
| Viewport Context Menu | v10.26 | Right-click: Select All, Deselect, Focus, Duplicate, Delete, Group, Add Entity, Transform Tools, Toggle Grid/Wireframe |
| Keyboard Shortcuts | v10.26 | W/E/R (transform), Q (select), F (focus), P (play), G (game view), Ctrl+S, Ctrl+Z/Y, Ctrl+D, Ctrl+G, Ctrl+A, Delete, Ctrl+P, Esc |
Uruk AI System (v10.27)
The AI system was rebuilt in v10.27 with a modular architecture spanning context collection, action execution, transaction logging, and cross-session memory.
| Component | Version | Description |
|---|---|---|
| AI Context Collection | v10.27 | 4 context collectors (selection, scene, viewport, project). Unified collectAIContext() + scope-based serialization |
| AI Action Registry | v10.27 | 25+ cataloged actions across 10 categories. Filtering by mode, category, selection, search |
| AI Transaction Log | v10.27 | Full lifecycle: draft → applied → reverted/failed. Subscriber pattern. Stats. Revert support |
| AI Mode Tools | v10.27 | 60+ tools across 12 editor modes. Select, Place, Terrain, Lighting, Debug, etc. |
| AI Playtest Analysis | v10.27 | Session-based FPS/event/warning tracking. Auto-warning on sustained low FPS |
| AI Memory | v10.27 | Custom instructions, preferences, recent prompts, action usage, corrections. localStorage persistence |
| AI Assistant Panel | v10.27 | Enhanced 4-tab panel: Chat, Actions (searchable catalog), History (transaction log), Memory. Context summary bar |
| AI Command Palette | v10.27 | 10 AI commands: Generate Entity, Modify Selected, Explain Selected, Optimize Scene, etc. |
| AI Viewport Context Menu | v10.27 | AI section in right-click: Generate Here, Explain Selected, Modify Selected, Analyze Scene |
Render Pipeline
The rendering system has been significantly expanded through v10.29–v10.30 with post-processing, GPU timing, instanced batching, and WebGPU compute shaders.
| Feature | Version | Description |
|---|---|---|
| Render Graph Per-Pass Timing | v10.29 | Per-pass CPU timing (RenderPassTiming), FramePassTimings aggregation, 60-frame history |
| PostProcessStack | v10.29 | Unified Bloom/Vignette/SSAO/ColorGrade management, config-driven from RenderSettingsPersist |
| Render Quality Presets | v10.29 | Low/medium/high/ultra presets, applyRenderSettings() maps to Three.js renderer |
| Material/Instance Diagnostics | v10.29 | Material cache hit/miss stats, instance batch stats, instanced mesh counting |
| InstancedMesh Batching | v10.29.1 | Palm trees (51→2 draw calls), residential buildings (~239→7 draw calls) |
| GPU Timestamp Queries | v10.29.1 | EXT_disjoint_timer_query_webgl2, double-buffered queries, per-pass GPU timing in RenderGraph |
| PostProcessStack Reactive PCS | v10.30 | Reactive updates: bloom/SSAO/colorGrade/vignette subscribe to PCS renderSettings changes |
| WebGPU Compute Post-Processing | v10.30 | WGSL compute shaders: bloomPass (separable Gaussian), ssaoPass (hemisphere sampling), colorGradePass (exposure/LGG/contrast/saturation/ACES/vignette) |
Repository Structure
text
client/src/
pages/ ← Page-level components (Home, Studio3D, CharacterDesigner, etc.)
components/editor/ ← Editor panels (TopBar, ToolShelf, CommandPalette, Viewport, SceneTree, Inspector, etc.)
components/studio3d/ ← 3D Studio tool panels (16 components)
hooks/usePCSData.ts ← PCS subscription hooks (usePCSData, usePCSDraft)
hooks/useUndoRedo.ts ← Generic undo/redo command stack hook (v10.14)
engine/
core/ecs.ts ← Entity Component System (Implemented)
world/streamingManager.ts ← Cell-based world streaming (Implemented)
ai/agentRuntime.ts ← AI agent state machine (Implemented)
ai/navigationGraph.ts ← A* pathfinding (Implemented)
ai/aiContext/ ← AI context collectors (v10.27)
ai/aiActions/ ← AI action registry + executor (v10.27)
ai/aiTransactions/ ← AI transaction log (v10.27)
ai/aiModeTools/ ← Mode-specific AI tools (v10.27)
ai/aiAnalysis/ ← Playtest analysis tracker (v10.27)
ai/aiMemory/ ← Cross-session AI memory (v10.27)
physics/ ← Physics (Implemented — V8 canonical)
render-core/ ← RenderGraph + render features (Implemented)
render-backends/webgpu/ ← Custom WebGPU renderer (Architecture)
render-features/ ← Clustered lighting, GI, virtualized geometry (Architecture)
runtime/ ← Runtime orchestrator + rehydrate (Implemented)
sequencer/ ← Sequencer runtime (Implemented — PCS-AUTH)
mission/ ← Mission runtime (Implemented — PCS-AUTH)
blueprint/ ← Blueprint interpreter (Implemented — PCS-AUTH)
content/ ← Typed content schemas + ProjectContentService
dialogue/ ← Dialogue runtime interpreter (Implemented — v10.15)
audio/ ← Audio runtime (Implemented — v10.15)
gizmo/ ← Transform gizmo + world data gizmos (Implemented)
particles/ ← Particle system engine (Implemented — v10.16)
debug/ ← Debug overlay + diagnostics collector
multiplayer/ ← Multiplayer foundation (Architecture)
contexts/EditorContext.tsx ← Central editor state + undo/redo + multi-select
server/ ← Express + tRPC backend
drizzle/ ← MySQL database schema & migrationsGetting Started
bash
pnpm install
pnpm db:push
pnpm devThe editor runs at the URL shown in the terminal output.
Tech Stack
| Layer | Technology |
|---|---|
| Frontend | React 19, TypeScript, Tailwind CSS 4, Three.js r183 |
| Backend | Express 4, tRPC 11, Node.js 22 |
| Database | MySQL / TiDB, Drizzle ORM |
| 3D Rendering | Three.js r183 (WebGL2 + WebGPU dual backend), custom render graph + post stack |
| AI | Built-in LLM API, Tripo 3D API (external dependency for 3D generation) |
| Testing | Vitest (2,047+ tests, 47+ files) |
Tests
bash
pnpm test2,047+ tests across 47+ files covering: ECS, AI agent runtime, A* navigation, physics, render graph compilation, clustered lighting, post-processing stack, CSM cascade fitting, TAA jitter, streaming visibility, renderer facade, content validation, mission zone triggers, runtime orchestration, auth, AI action parsing, 3D generation pipeline, character/animation management, blueprint logic, terrain operations, multiplayer session logic, patrol validation cache, background revalidation, sequence conflict resolution, mission countdown, objective progress, and more.
Known Limitations
Explicitly not implemented despite appearing in the UI or earlier documentation:
- Multiplayer networking — The Multiplayer Preview page is a UI mockup with simulated peers. No WebSocket server exists.
- VR / WebXR — No WebXR integration exists.
- Rigid body dynamics — Physics handles collision detection and triggers but objects do not move, bounce, or respond to forces.
- Custom renderer integration — Custom WebGPU renderer modules exist as standalone architecture but are not wired into the Viewport render loop.
- 3D Studio mesh tools — Mesh Editor, Topology Tools, and UV Editor have UI but no actual mesh manipulation logic.
- Content hot-reload — No live-reload of individual asset types without full rehydration.
Previously Resolved
- Sequencer persistence — Resolved Resolved in v10.12 — sequences persist to DB via PCS
- Blueprint persistence — Resolved Resolved in v10.12 — blueprint graphs persist to DB via PCS
- Mission authoring — Resolved Resolved in v10.13 — MissionEditor is a full CRUD editor
- Blueprint execution — Resolved Resolved in v10.13 — BlueprintEditor connected to interpreter via PCS
- Audio system — Resolved Resolved in v10.15 — AudioRuntime with spatial audio, ambience, and voice
- Gizmo click-to-select — Resolved Resolved in v10.16 — Raycasting + GizmoSelectionBus + World Editor auto-select
Custom WebGPU Renderer (v6.0)
A fully custom WebGPU-native renderer exists alongside the Three.js integration layer. This renderer owns its own GPU device, resource management, pipeline caching, and WGSL shaders. It does NOT go through Three.js for rendering — it encodes GPU commands directly.
Foundation
| Module | Description |
|---|---|
| webgpuDeviceManager.ts | GPU device lifecycle, adapter selection, feature/limit detection, device lost recovery |
| webgpuResourceManager.ts | GPU buffer pool (camera, object, material, light UBOs/SSBOs), texture/sampler cache |
| webgpuPipelineCache.ts | Shader module cache, bind group layout registry, render/compute pipeline factory |
| webgpuFrameContext.ts | Per-frame command encoder, GPU timestamp queries, pass timing, draw call stats |
Custom WGSL Shaders
| Shader | Description |
|---|---|
| depthPrepass.wgsl | Depth-only vertex shader with object SSBO transforms |
| opaquePBR.wgsl | Full PBR fragment shader: GGX, Schlick fresnel, Smith geometry, Cook-Torrance specular, Lambert diffuse, multi-light evaluation, shadow atlas sampling |
| motionVectors.wgsl | Current/previous frame MVP for temporal reprojection |
| fullscreenPost.wgsl | Tonemapping (ACES/Reinhard/Uncharted2), exposure, vignette, gamma |
Advanced Render Features
| Feature | Description |
|---|---|
| GPU-Driven Clustered Lighting | 16x9x24 clusters with exponential depth slicing. Compute build + assign shaders with atomic counters. Debug heatmap overlay. |
| GPU Culling System | Instance-level frustum culling with visibility buffer and indirect draw compaction. HLOD proxy visibility and streaming cell residency checks. |
| Lumen-like Global Illumination | SSGI ray marching, DDGI probe grid (8x4x8 = 256 probes), temporal denoiser with variance-guided bilateral filter. |
| Virtualized Geometry | Meshlet builder (64 verts, 124 tris), cluster hierarchy LOD DAG, GPU LOD selection via screen-space error, cluster renderer. |
Honesty note: The custom renderer systems are implemented as standalone modules with real WGSL shaders, real GPU buffer management, and real compute dispatches. However, they are NOT yet wired into the main Viewport render loop. Integrating the custom renderer requires a scene extraction bridge which is not yet built.
Game World
Uruk — The First City is set in ancient Mesopotamia (~3000 BCE). The content data defines:
- 12 world streaming cells covering the Uruk city districts
- 42 navigation waypoints with A* pathfinding
- 6 patrol routes for NPC guard/merchant/priest behaviors
- 6 mission zones (circle and rect trigger volumes)
- 3 mission definitions across 2 chapters
- 2 branching dialogue trees
- 6 AI archetypes (temple guard, merchant, priest, commoner, laborer, noble)
This content is persisted to the database via ProjectContentService. Seed data in urukProjectData.ts is used only as a fallback when no saved content exists.
License
Proprietary — All rights reserved.
← Back to Home
Uruk Engine © 2026