Uruk Engine Editor

Subsystem Maturity

Each subsystem is rated on a four-level scale:

Repository Structure

client/                        ← React 19 + TypeScript editor frontend
  src/
    pages/                     ← Page-level components (Home, Studio3D, CharacterDesigner, etc.)
    components/editor/         ← Editor panels (Viewport, SceneTree, Inspector, Timeline, etc.)
    engine/                    ← Client-side engine subsystems
      core/ecs.ts              ← Entity Component System
      world/streamingManager.ts ← Cell-based world streaming
      ai/navigationGraph.ts    ← A* pathfinding on waypoint graph
      ai/agentRuntime.ts       ← AI agent state machine + patrol/schedule
      physics/physics.ts       ← Collision detection + trigger volumes
      renderer/renderPipeline.ts ← Multi-pass render pipeline
      runtime/runtimeOrchestrator.ts ← Per-frame subsystem sequencer
      content/contentTypes.ts  ← Typed content schemas
      content/urukProjectData.ts ← Default Uruk world data
    contexts/EditorContext.tsx  ← Central editor state
server/                        ← Express + tRPC backend
  routers.ts                   ← tRPC procedures (AI chat, 3D generation, content gen)
  aiPrompt.ts                  ← AI Co-Pilot system prompt + action schema
drizzle/                       ← MySQL database schema & migrations

Getting Started

pnpm install
pnpm db:push
pnpm dev

The editor runs at the URL shown in the terminal output.

Tech Stack

Tests

pnpm test

189+ tests across 10 files covering: auth, AI co-pilot action parsing, 3D generation pipeline, character/animation management, blueprint logic, terrain operations, multiplayer session logic, streaming lifecycle, A* navigation, AI state machine, content validation, physics stats, mission zone triggers, runtime orchestration, renderer capabilities, render graph compilation, clustered lighting, post-processing stack, CSM cascade fitting, TAA jitter, streaming visibility, and renderer facade.

Known Limitations

The following are explicitly not implemented despite appearing in the UI or earlier documentation:

• WebGPU custom render shaders — The WebGPU backend uses THREE.WebGPURenderer which auto-converts materials through the Three.js TSL node material system. No hand-written WGSL render/fragment shaders.
• WebGPU indirect draw — The compute frustum culling pass reads results back to CPU and sets mesh.visible. No indirect draw buffer or GPU-driven draw call submission.
• Bindless textures / mesh shaders — Not implemented. The WebGPU backend does not use any WebGPU-exclusive rendering features beyond compute.
• SSR — No screen-space reflections. SSAO exists but uses a simplified kernel.
• Authoritative multiplayer — The multiplayer page is a UI mockup with simulated peers. No WebSocket server exists.
• VR / WebXR — The status bar shows "VR" but no WebXR integration exists.
• Audio system — No audio engine, no spatial audio, no music playback.
• Platform deployment — The editor runs in a browser. No native runtime for PC, console, or mobile.
• Terrain export — The terrain sculptor operates on a local array and does not connect to the viewport scene.
• Motion vectors — The TAA pass uses reprojection jitter but has no per-object motion vector generation.
• Contact shadows / Occlusion queries — These passes exist as skeleton implementations but do not produce visual output.

WebGPU Backend Architecture

The WebGPU backend is a real, minimal implementation that renders the same scene through the WebGPU API path.

What Is Real

• GPU device acquisition — navigator.gpu.requestAdapter() and adapter.requestDevice() are called through THREE.WebGPURenderer. A real GPUDevice is obtained.
• Render path — renderer.render(scene, camera) executes through the WebGPU command encoder pipeline, not WebGL2.
• Material auto-conversion — Three.js converts materials to its TSL node material system, which compiles to WGSL internally.
• Backend detection — probeBackends() does a real async probe: checks navigator.gpu, requests an adapter, and reports adapter info.
• Runtime selection — User can choose auto/webgl2/webgpu in Engine Settings. Preference persists in localStorage.
• Safe fallback — If WebGPU init fails, the system falls back to WebGL2 automatically.
• Status reporting — The Stats HUD and Status Bar show the actual active backend from the capability manifest.

WebGPU-Exclusive Features (Three.js Layer)

• GPU Compute Frustum Culling — Real WGSL compute shader that tests bounding spheres against 6 frustum planes on the GPU. Auto-enabled when WebGPU backend is active.
• Indirect Draw Buffer Compaction — 3-pass WGSL compute (reset / compact / finalize). Produces a GPUBuffer with INDIRECT usage flag.
• Backend-neutral render targets — All post-processing passes use THREE.RenderTarget (base class), compatible with both backends.
• RenderGraph as primary path — The Viewport uses RenderGraph with compute cull, shadow, opaque, SSAO, bloom, color grading, and debug overlay passes.

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

Custom WGSL Shaders

Advanced Render Features

Code Path Proof

Viewport.tsx useEffect
  → probeBackends()              — real async GPU probe
  → selectBackend(preference)    — preference + availability
  → if webgpu:
      new WebGPUBackend()
      gpuBackend.init(canvas)     → dynamic import('three/webgpu')
                                  → new WebGPURenderer({ canvas })
      await gpuBackend.waitForInit()  → await renderer.init()  [real GPU device]
      → auto-enable ComputeFrustumCullPass in render graph
  → else:
      new THREE.WebGLRenderer()   [standard Three.js]
  → renderGraph.execute(renderer, scene, camera, dt, frame)
      → ComputeFrustumCullPass.execute()  (if enabled)
          → dispatchWorkgroups()  [real WGSL compute]
          → dispatchCompaction()  [3-pass indirect draw buffer]
          → mapAsync()  [readback, 1-frame latency]
      → ShadowPass.execute()
      → OpaquePass.execute()
          → renderer.render(scene, camera)  [dispatches to active backend]

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 exists as typed TypeScript data. It is not loaded from asset files or a database.

License

Proprietary — All rights reserved.