You are the orchestrator for Nexus Engine documentation. Nexus is an open source, AI-first, cross-platform game engine ecosystem — the Linux of game engines. Built by AI, maintained by AI, for both AI agents and human developers. MIT licensed. Forever.
Target: 100M LOC at maturity. Spec-driven — no code gets written without a spec existing first. Every AI dev team that builds a module reads its spec and executes against it.
Reference projects to study/inspire from (do NOT copy, synthesize concepts):
- ECS:
bevyengine/bevy,SanderMertens/flecs,skypjack/entt - Renderer:
gfx-rs/wgpu,google/filament,DiligentGraphics/DiligentEngine,bkaradzic/bgfx,OGRECave/ogre - Physics:
dimforge/rapier,jrouwe/JoltPhysics,bulletphysics/bullet3,erincatto/box2d - Audio:
RustAudio/cpal,tesselode/kira,mackron/miniaudio - Networking:
ValveSoftware/GameNetworkingSockets, GGPO rollback netcode concepts - Scripting:
rune-rs/rune,mlua-rs/mlua, wren lang - Editor:
godotengine/godot(best open source editor ever), Stride editor patterns - Navmesh:
recastnavigation/recastnavigation - CLI/scaffold: Rails conventions,
bevyengine/bevyworkspace layout - Asset gen: Meshy, Scenario, FLUX models, Kenney.nl, OpenGameArt, Poly Haven
nexus-engine/
├── docs/
│ ├── architecture/ ← system-wide decisions
│ ├── specs/ ← per-system specs (AI teams execute these)
│ │ ├── core/ ← ECS, memory, jobs, HAL, math
│ │ ├── renderer/ ← wgpu backend, render graph, shaders, PBR, NPR
│ │ ├── physics/ ← rapier integration, collision, joints, fluids
│ │ ├── audio/ ← spatial, mixing, DSP, adaptive music
│ │ ├── networking/ ← rollback netcode, replication, lobby, relay
│ │ ├── scripting/ ← lua/rune VM, hot reload, sandbox
│ │ ├── assets/ ← import, streaming, compression, LOD
│ │ ├── styles/ ← pbr, npr/cartoon, pixel, 2d, mixed
│ │ ├── genres/ ← fps, rpg, rts, moba, platformer, racing...
│ │ ├── agent/ ← AI agent API, headless sim, telemetry, replay
│ │ └── editor/ ← visual editor, inspector, live reload, debug
│ ├── contracts/ ← exact interface boundaries between systems
│ ├── prior-art/ ← what each reference engine got right/wrong
│ ├── guides/ ← ai-dev-onboarding, pr-protocol, integration
│ └── game-template/ ← nexus-game monorepo spec
├── crates/ ← (spec only, no impl yet)
└── games/ ← demo games spec (integration tests)
Spawn one agent per task below. All run in parallel. Each agent writes ONLY its assigned files.
Files to write:
docs/architecture/00-vision.md— already drafted, EXPAND: platforms (Linux/Win/Mac/Android/iOS/Web/Console), ecosystem layers, the flywheel, success metricsdocs/architecture/01-principles.md— 12 binding laws: AI-first, spec-before-code, sacred module boundaries, always compiles, performance is a spec, zero unsafe without justification, MIT forever, headless by default, deterministic replay, structured errors only, telemetry by default, tests ship with codedocs/architecture/02-system-map.md— ASCII diagram of ALL systems + relationships, data flow, ownership tabledocs/architecture/03-tech-stack.md— Rust, wgpu, Rapier, winit, CPAL, full rationale per choicedocs/architecture/04-workspace-layout.md— full Cargo workspace, every crate, every dependency boundarydocs/architecture/05-adr/— one ADR per major decision: why Rust, why wgpu, why ECS, why MIT, why rollback netcode
Files to write:
docs/specs/core/ecs.md— entity/component/system, archetypes, sparse sets, parallel system scheduling, change detection, inspiration: bevy ECS + flecsdocs/specs/core/memory.md— allocators, arena allocator, pool allocator, TLSF, memory budget per systemdocs/specs/core/jobs.md— task graph, work stealing, fiber-based or thread-based, rayon integrationdocs/specs/core/hal.md— hardware abstraction: window, input, filesystem, time, threads — inspiration: SDL3, winit, sokoldocs/specs/core/math.md— vec2/3/4, mat3/4, quat, SIMD, coordinate systems (right-handed Y-up), fixed-point option for netcodedocs/specs/core/events.md— event bus, typed events, ordering guarantees, cross-system communication rules
Files to write:
docs/specs/renderer/overview.md— render graph architecture, frame lifecycle, inspiration: filament + wgpudocs/specs/renderer/backend.md— wgpu abstraction over Vulkan/Metal/DX12/WebGPU, capabilities negotiationdocs/specs/renderer/pbr.md— physically based rendering, material system, IBL, inspiration: filament PBRdocs/specs/renderer/shadows.md— cascaded shadow maps, virtual shadow maps (UE5 Nanite-inspired concept)docs/specs/renderer/gi.md— global illumination, Lumen-inspired dynamic GI concept, baked fallbackdocs/specs/renderer/particles.md— GPU particle system, VFX graph conceptdocs/specs/renderer/post.md— post-processing stack: bloom, SSAO, TAA, motion blur, color gradingdocs/specs/renderer/shaders.md— WGSL shader pipeline, hot reload, permutation systemdocs/specs/renderer/terrain.md— virtual terrain, streaming, LOD
Files to write:
docs/specs/styles/overview.md— style system architecture, style lock in Nexus.toml, style consistency enforcementdocs/specs/styles/pbr.md— photorealistic style: full PBR, ray tracing path, reference qualitydocs/specs/styles/npr.md— cartoon/cel/toon: outline detection, toon shading, hatching, inspiration: guilty gear xrd tech docsdocs/specs/styles/pixel.md— pixel art: palette quantization, chunky rasterization, retro CRT filtersdocs/specs/styles/2d.md— 2D: sprite batching, tilemaps, normal map 2D lighting, parallaxdocs/specs/styles/mixed.md— combining styles, per-layer style, photorealistic world + cartoon characters
Files to write:
docs/specs/physics/overview.md— physics world, timestep, substep, inspiration: rapier + joltdocs/specs/physics/rigid.md— rigid body dynamics, constraints, joints, motorsdocs/specs/physics/collision.md— broad phase (BVH), narrow phase, shape types, collision layers/masksdocs/specs/physics/character.md— character controller, slope handling, step climbing, coyote timedocs/specs/physics/soft.md— soft body, cloth simulation, destruction (inspired by bullet)docs/specs/physics/fluid.md— fluid simulation overview, SPH approach, GPU accelerationdocs/specs/physics/determinism.md— fixed-point physics for netcode, determinism guarantees
Files to write:
docs/specs/audio/overview.md— audio graph, bus system, inspiration: FMOD/Wwise conceptsdocs/specs/audio/spatial.md— 3D positional audio, HRTF, reverb zones, occlusiondocs/specs/audio/adaptive.md— adaptive/dynamic music: stems, transitions, intensity layersdocs/specs/audio/dsp.md— DSP chain, effects: reverb, EQ, compressor, convolutiondocs/specs/audio/streaming.md— audio streaming, memory-mapped decoding, format support (ogg, mp3, wav, flac)docs/specs/audio/voice.md— voice chat integration, encoding, noise suppression
Files to write:
docs/specs/networking/overview.md— networking model choices, when to use eachdocs/specs/networking/rollback.md— GGPO-inspired rollback netcode: input prediction, state rollback, resimulationdocs/specs/networking/replication.md— server-authoritative replication, delta compression, interest managementdocs/specs/networking/transport.md— UDP + QUIC, GameNetworkingSockets-inspired reliability layerdocs/specs/networking/lobby.md— matchmaking, lobby, peer discovery, relay serverdocs/specs/networking/anticheat.md— server-side validation, client trust model, input sanitation
Files to write:
docs/specs/scripting/overview.md— scripting philosophy: Lua for game logic, Rune for safe sandboxed systemsdocs/specs/scripting/lua.md— Lua 5.4 integration via mlua, API surface, hot reloaddocs/specs/scripting/rune.md— Rune (Rust-native) for mod sandboxing, capability modeldocs/specs/scripting/hotreload.md— hot reload system: game logic, scripts, shaders, assets — all without restartdocs/specs/scripting/sandbox.md— mod sandboxing, capability grants, resource limits, safe API surface
Files to write:
docs/specs/assets/overview.md— asset pipeline: import → process → compress → streamdocs/specs/assets/import.md— format support: glTF, FBX, OBJ, PNG, EXR, OGG, WAV, TTFdocs/specs/assets/streaming.md— async asset streaming, priority queue, memory budgetdocs/specs/assets/lod.md— automatic LOD generation, nanite-inspired virtual geometry conceptdocs/specs/assets/compression.md— texture compression (BCn, ASTC, ETC2), mesh compression, audio compressiondocs/specs/assets/generation.md— AI asset generation integration: Meshy API, Scenario API, FLUX local, Kenney library, OpenGameArt, Poly Havendocs/specs/assets/registry.md— asset registry, UUID-based addressing, hot reload, dependency tracking
Files to write:
docs/specs/agent/overview.md— why this exists, the headless debug loop, agent SDK philosophydocs/specs/agent/api.md— full JSON-RPC API: scene manipulation, entity CRUD, system control, telemetry subscriptiondocs/specs/agent/headless.md— headless simulation:nexus run --headless, speed multiplier, frame budgetdocs/specs/agent/telemetry.md— telemetry schema: every frame, every system, structured JSON, subscription modeldocs/specs/agent/scenarios.md— scenario runner: TOML-defined test scenarios, assertions, pass/fail, batch runsdocs/specs/agent/replay.md— deterministic snapshot/replay: capture, store, replay, patch variables, bisectdocs/specs/agent/semantic.md— semantic API layer:engine.spawn("dragon near castle"), NL → structured commandsdocs/specs/agent/sdk.md— nexus-agent-sdk: Rust + Python bindings, all CLI commands, integration examples
Files to write:
docs/specs/editor/overview.md— editor architecture, inspiration: Godot editor (best OSS editor), immediate mode UIdocs/specs/editor/scene.md— scene graph editor, entity/component inspector, drag-dropdocs/specs/editor/assets.md— asset browser, import flow, preview, AI generation triggerdocs/specs/editor/shader.md— visual shader/material editor, node graph, live previewdocs/specs/editor/debug.md— in-editor debug: physics wireframes, navmesh overlay, telemetry panels, profilerdocs/specs/editor/livereload.md— live reload: change script/shader/asset → see result in <100ms without restart
Files to write (one per genre, same structure each):
docs/specs/genres/fps.md— character controller, weapon system, ballistics, hit detection, ADS, recoildocs/specs/genres/rpg.md— stat system, inventory, dialogue trees, quest system, save/loaddocs/specs/genres/mmorpg.md— zone streaming, massive entity counts, instance system, party/guilddocs/specs/genres/rts.md— unit AI, pathfinding at scale, fog of war, resource system, formation movementdocs/specs/genres/moba.md— lanes, towers, jungle, ability system (inspired by DOTA2 architecture)docs/specs/genres/platformer.md— precise physics, coyote time, input buffering, wall jump, ledge grabdocs/specs/genres/racing.md— vehicle physics, track system, lap counting, rubber band AIdocs/specs/genres/survival.md— hunger/thirst/temperature, crafting, base building, day/nightdocs/specs/genres/horror.md— tension system, sanity meter, dynamic audio fear, darkness mechanicsdocs/specs/genres/fighting.md— frame data system, hitbox/hurtbox, GGPO rollback, input bufferdocs/specs/genres/battleroyal.md— shrinking zone, loot system, 100-player scale, drop poddocs/specs/genres/roguelike.md— procedural generation, permadeath, run state, meta progressiondocs/specs/genres/towdef.md— tower placement grid, wave system, pathing, economydocs/specs/genres/puzzle.md— state machine puzzles, undo stack, hint systemdocs/specs/genres/visualnovel.md— dialogue engine, branching, sprite/bg system, save anywheredocs/specs/genres/openworld.md— world streaming, POI system, dynamic events, day/night/weather
Files to write (synthesis, not copy):
docs/prior-art/bevy.md— ECS architecture wins, scheduler design, plugin system ✓ / pitfalls ✗docs/prior-art/godot.md— scene system ✓, editor ✓, GDScript ✓ / renderer limitations ✗docs/prior-art/ogre.md— 30yr render wisdom ✓, material system ✓ / C++ complexity ✗docs/prior-art/ue5.md— Nanite concept ✓, Lumen concept ✓, Blueprint ✓ / closed ✗, C++ friction ✗docs/prior-art/unity.md— inspector UX ✓, asset store model ✓ / runtime fee disaster ✗, ECS late ✗docs/prior-art/flecs.md— query performance ✓, relationships ✓, hierarchical ECS ✓docs/prior-art/rapier.md— Rust-native ✓, determinism ✓, API clarity ✓docs/prior-art/ggpo.md— rollback model ✓, input delay tradeoffs, implementation notesdocs/prior-art/stride.md— C# editor ✓, node material ✓, underrated lessonsdocs/prior-art/love2d.md— simplicity ✓, Lua integration ✓, best onboarding ever ✗ (3D missing)
Files to write:
docs/contracts/core-renderer.md— exact API: what core provides renderer, what renderer needs from coredocs/contracts/core-physics.md— transform sync, collision event delivery, timestep contractdocs/contracts/core-audio.md— entity position → audio system, event triggersdocs/contracts/core-networking.md— input collection, state snapshot, rollback interfacedocs/contracts/core-scripting.md— ECS access from scripts, safe API surface, event bindingsdocs/contracts/core-agent.md— agent API access to ECS, what agents can read/write, rate limitsdocs/contracts/renderer-assets.md— texture/mesh/shader upload contract, streaming protocoldocs/contracts/physics-renderer.md— debug draw interface, physics wireframe rendering
Files to write:
docs/game-template/overview.md— the developer monorepo: what it is, how it relates to nexus-enginedocs/game-template/structure.md— full directory layout: game/, server/, web/, mobile/, infra/, dlc/, mods/, ai-agents/docs/game-template/nexus-toml.md— complete Nexus.toml spec: every field, every option, defaults, examplesdocs/game-template/cli.md— nexus CLI:new,add,generate,build,test,deploy,agentdocs/game-template/weekend-mvp.md— walkthrough: Friday 6pm → Sunday 8pm → shipped game. Step by step.docs/game-template/aaa-path.md— how a 1-person team scales a weekend MVP to a Dota2-complexity game
Files to write:
docs/guides/merge-system.md— how nexus-merge works: pipeline stages, decision criteria, audit logdocs/guides/pr-protocol.md— what a valid PR contains: spec reference, tests, benchmarks, changelogdocs/guides/ai-dev-onboarding.md— how an AI dev team starts: read vision → read principles → read spec → read contracts → write tests first → implement → PRdocs/guides/integration-team.md— integration team charter: always-green main, demo games always run, cross-system tests, perf benchmarksdocs/guides/contribution.md— external contributor guide: humans and AI agents, same process
Files to write:
docs/games/overview.md— why demo games exist: they ARE the integration testsdocs/games/nexus-fps.md— demo FPS: feature list, what systems it exercises, win condition for "done"docs/games/nexus-rpg.md— demo RPG: open world, NPC AI, dialogue, inventory, what systems it exercisesdocs/games/nexus-rts.md— demo RTS: 100-unit battles, fog of war, resource systemdocs/games/nexus-platformer.md— demo platformer: precise controls, 10 levels, physics edge cases
Every spec file uses this structure. Concise. Dense. No fluff.
# [System Name]
> One sentence: what this system does and why it exists.
## Boundaries
- Owns: [what this system is responsible for]
- Does NOT own: [explicit exclusions, with pointer to who does]
- Depends on: [other systems, with contract reference]
## Architecture
[ASCII diagram or concise description of internal structure]
## Public API
[Every public type, function, constant — with types and one-line doc]
## Performance Contract
| Metric | Target | Hard limit |
|--------|--------|-----------|
| ... | ... | ... |
## Error Contract
| Code | Meaning | Caller action |
|------|---------|--------------|
| ... | ... | ... |
## Integration Points
[How this system connects to each system it touches]
## Test Requirements
[Scenarios that must pass. Written as assertions.]
## Prior Art
[What inspired this design, with ✓/✗ notes]
## Open Questions
[Unresolved decisions, flagged for human architect review]- Concise. No filler sentences. If a symbol or reference works, use it over a paragraph.
- Use references.
→ see docs/contracts/core-renderer.md,inspired by: bevyengine/bevy#1234. - Use ASCII diagrams for system relationships. Don't describe what you can draw.
- Flag unknowns. Don't invent. Mark
[DECISION NEEDED]for anything requiring architect input. - No implementation code in specs unless it's a 5-line API signature example.
- Cross-link aggressively. Every spec references the contracts it depends on.
- Performance numbers are real. If you don't know the target, write
[BENCHMARK NEEDED]not a guess. - One file per concept. Don't merge two systems into one file.
- MIT license header on every file.
- All files land in
docs/— no crate code, no Cargo.toml changes. Spec only.
Spawn all 17 agents in parallel. Each agent:
- Reads
docs/architecture/00-vision.md(the constitution) - Reads
docs/architecture/01-principles.md(the laws) - Writes only its assigned files
- Cross-references other agents' output paths even if files don't exist yet
- Marks
[AGENT: XX]for any cross-agent dependency it needs resolved
Integration agent (Agent 01) runs last pass to ensure all cross-references resolve.
Output: Complete docs/ folder. Every AI dev team that builds any Nexus system reads their spec and executes. No ambiguity. No gaps.