AstraWeave — AI‑Native Game Engine

---

🚀 Quick Start

git clone https://github.com/lazyxeon/AstraWeave.git
cd AstraWeave

# Build core engine
cargo build --release -p astraweave-core

# Run the flagship AI companion demo (7 planning modes, feature-gated)
cargo run -p hello_companion --release

# Run the visual editor (fetch the asset packs first: cargo xtask fetch-assets)
cargo editor

Note: Editor (aw_editor) has 9,425 test annotations. See workflow tests in tools/aw_editor/tests.

Key Documentation:

• Architecture Map — Crate relationships, editor viewport pipeline, data flow diagrams (v0.7.2; the v0.7.0 pass reconciled it against the 13 subsystem traces, v0.7.1–0.7.2 are incremental campaign reconciliations)
• 🕸️ Interactive Workspace Map — Cytoscape.js-powered live visualization of 72 workspace nodes (50 production crates, 12 tools, 10 supporting members) and 190 dependency edges. Hover or click any node for crate detail (domain, status, LoC, trace link); click any edge for the load-bearing types flowing across the boundary. Toggle blast-radius highlighting to see what depends on a crate before you change it, or launch the 8-step guided tour for a 10-minute architectural walk-through. Domain filter, focus mode, dependency-path finder, and shareable URL-hash state make it the fastest way to orient in the 850 K+ LoC workspace.
• Editor Behavioral Audit — 37-fix correctness audit with visual, data pipeline, and state machine verification
• Unified Pipeline Plan — 7-phase architectural refactor eliminating the dual rendering pipeline

---

🔍 Engineering Methodology: The Architecture Trace Campaign

AstraWeave's architecture is documented through a forensic trace campaign covering 13 subsystems under docs/architecture/. Each trace is evidence-grounded, version-controlled, and explicitly separates load-bearing code from in-design surface. Trace docs are part of the production contract: when subsystem code changes, the trace updates in the same commit (see CLAUDE.md).

The campaign produced three artifacts that together form the engine's navigational surface:

• Architecture Map — the ~1,000-line consolidated synthesis. Crate dependency graph, structural axioms, dormant-code inventory (~200K LoC across six categories), integration seams with risk levels, data flow paths, 23 cross-cutting open questions (net-trio Q17 resolved 2026-06-10). v0.7.2 reconciled 2026-06-10.
• Interactive Workspace Map — Cytoscape.js visualization of the 130-member workspace. Surfaces production-wired core (ECS, AI pipeline, rendering, terrain, editor) alongside ~200K LoC of dormant-but-designed surface. Click any node for crate detail, any edge for load-bearing types, or run the 8-step guided tour.
• 13 subsystem traces — terrain materials, render pipeline, physics, persistence-ECS, net, net-ECS, input, fluids, ECS/math/core/SDK foundation, audio, animation, AI pipeline, aw_editor. Each trace is forensic: §5 file map, §6 conflict map, §7 decision log, §8 invariants, §11 open questions.

The methodology — applying forensic auditing as a counterweight to AI-generated documentation drift — is part of the Genesis Code Protocol (GCP) approach to AI-augmented development. Cross-cutting structural rules surfaced by the campaign (the §7.7 wrapped-component resource identity trap, the no-second-implementation Fix-27 lesson, the "wired beats tested" axiom, the silent-failure policy) are documented in ARCHITECTURE_MAP.md §4 and applied across the workspace.

---

🌌 Why AstraWeave?

Traditional game engines bolt AI onto simulation. AstraWeave weaves AI into the core.

In AstraWeave, the "Game Loop" is an Intelligence Loop:

1. Perception: Agents "see" the world through a snapshot system.
2. Reasoning: LLMs and Utility systems analyze the state.
3. Planning: GOAP and Behavior Trees formulate plans.
4. Action: Plans execute via deterministic ECS commands.

This architecture enables 12,700+ intelligent agents running at 60 FPS with complex reasoning on reference hardware (HP Pavilion Gaming Laptop — benchmarks), not just simple state machines.

---

🏗️ Architecture

The diagram below is the high-level Intelligence Loop abstraction; the actual ECS scheduler runs an 8-stage canonical pipeline described below the diagram. See ARCHITECTURE_MAP.md §3 for the full data flow.

flowchart TB
    A[Perception] --> B[Reasoning]
    B --> C[Planning]
    C --> D[Action]
    D --> E[Validation]
    E --> F[Simulation]
    F --> A
    
    style A fill:#4a90e2
    style B fill:#7b68ee
    style C fill:#50c878
    style D fill:#ffa500
    style E fill:#ff6b6b
    style F fill:#45b7d1

8-Stage Deterministic ECS Pipeline (executed in canonical order, single-threaded per tick):

1. PRE_SIMULATION → 2. PERCEPTION → 3. SIMULATION → 4. SYNC (ECS ↔ legacy core::World) → 5. AI_PLANNING → 6. PHYSICS → 7. POST_SIMULATION → 8. PRESENTATION

Systems within a stage execute in registration order; stages execute in the order above. ParallelSchedule was removed 2026-04-18 (see docs/audits/parallel_schedule_removal_2026-04-18.md); parallelism lives at the subsystem level (rayon for terrain meshing; tokio for I/O and LLM inference; GPU compute for rendering).

---

---

📊 Project Status

Overall Status: Active research-grade engine under solo development for the Veilweaver game project. Phase 8 (Game Engine Readiness). Active campaign: Editor Multi-Tool Architecture Sub-phase 5 (Phase 8.8 Physics Robustness paused — no physics commits since Feb 2026). Engine ships when Veilweaver ships (12–18 month horizon as of May 2026). Status icons below: ✅ production-wired · 🔧 active, mid-campaign · 🔬 research surface (in-design, not currently runtime-wired) · 🧪 experimental.

🏆 Quality Metrics

• Build Health: cargo check --workspace clean — 130/130 members, 0 errors (verified 2026-06-10)
• Test Coverage: 57.35% whole-workspace line via cargo llvm-cov --workspace (130 members; measured 2026-06-29, supersedes the prior 29-crate-subset 59.3%)
• Total Tests: ~39,000+ test annotations across 130 workspace members (live count 2026-06-10: 39,973 #[test]/#[tokio::test] markers; cargo metadata 130 members)
• Mutation Testing: 4 waves — Wave 1: 767 manual + Wave 2: 1,261 automated + Wave 3: 489 targeted + Wave 4: 411 fluids (100% kill rate on prompts, 792 mutants)
• Memory Safety: Miri-validated (1,059 tests, 0 undefined behavior across 4 crates)
• Formal Verification: Kani-verified (71+ proof harnesses across safety-critical crates)
• Performance: 60 FPS @ 12,700 agents on reference hardware (HP Pavilion Gaming Laptop — see benchmark hardware spec)
• Security: A- (92/100) — November 2025 network-security audit (aw-net-server scope); input signing since enforced end-to-end by Net-Trio-Remediation (June 2026)
• Architecture Traces: 13 subsystem traces under docs/architecture/ (forensic file map / conflict map / decision log / invariants / open questions per trace)

---

📦 Crate Ecosystem

AstraWeave is a modular workspace of ~51 production crates organized into 7 functional domains, plus 12 tools and 59 example crates (130 workspace members via cargo metadata --no-deps, verified 2026-06-10). Each crate is designed for composability, testability, and production deployment.

🏗️ Core Engine (9 crates)

• astraweave-core: Foundation framework with WorldSnapshot, PlanIntent schemas, and tool registry system
• astraweave-ecs: AI-native archetype-based ECS with deterministic scheduling and event systems
• astraweave-math: SIMD-accelerated math operations (1.7-2.5× speedup, SSE2/AVX2/NEON support)
• astraweave-profiling: Zero-cost Tracy integration with GPU/memory/lock tracing
• astraweave-input: Action-based input binding system with multi-device support
• astraweave-sdk: C ABI interface for embedding AstraWeave in external engines
• astraweave-observability: Production telemetry, logging, and crash reporting
• astraweave-optimization: LLM performance optimization (batching, caching, token compression)
• astraweave-alloc: Opt-in mimalloc global-allocator shim (fast-alloc feature; +43% FPS on the profiling-demo workload, default-on in profiling_demo, hello_companion, and the editor)

🧠 AI & Intelligence (14 crates)

• astraweave-ai: Core loop orchestration with GOAP planner and async LLM executor
• astraweave-llm: Production LLM integration (Qwen via Ollama, prompt caching, circuit breaker; Phi-3/Hermes clients retained only as legacy comparison modules)
• astraweave-llm-eval: Automated LLM evaluation with multi-metric scoring
• astraweave-behavior: Behavior trees, HTN planning, GOAP with LRU plan caching
• astraweave-context: Conversation history with token-aware sliding windows and summarization
• astraweave-embeddings: Vector embeddings with linear-scan similarity search (cosine default; Euclidean/Manhattan/dot-product configurable). HNSW is advertised in doc-comments but not implemented — VectorStore::search is a brute-force scan (see the Memory / Coordination / RAG research-surface row above)
• astraweave-rag: Retrieval-augmented generation pipeline with memory consolidation
• astraweave-prompts: Handlebars templating with persona integration and A/B testing
• astraweave-persona: NPC personality system with zip-based persona packs
• astraweave-memory: Hierarchical memory (sensory/working/episodic/semantic) with SQLite persistence
• astraweave-coordination: Multi-agent coordination framework (Experimental)
• astraweave-director: Boss director with LLM orchestration and dynamic difficulty
• astraweave-npc: NPC runtime with sensing, behavior execution, and profile management
• astraweave-dialogue: Branching dialogue graph system with validation

🎨 Rendering & Assets (5 crates)

• astraweave-render: AAA rendering pipeline (PBR, clustered lighting, VXGI, MegaLights, Nanite virtualized geometry)
• astraweave-camera: Canonical camera types (Projection, RenderView, CameraProducer trait, FreeFly controller) — sole upload contract for the renderer (Unified Camera campaign, 2026-06)
• astraweave-materials: Material graph system with PBR-E advanced shading (clearcoat, anisotropy, transmission)
• astraweave-asset: Asset management with Nanite preprocessing and World Partition cell loading
• astraweave-asset-pipeline: Texture and mesh optimization pipeline. BC7/ASTC cook path present but currently non-functional (placeholder encoder; runtime uploads uncompressed RGBA8 — Terrain Asset Quality outcome, 2026-06)

🍎 Physics & Simulation (5 crates)

• astraweave-physics: Rapier3D integration with spatial hash, projectiles, gravity zones, and ragdoll
• astraweave-nav: Navigation mesh with pathfinding and geometric utilities
• astraweave-terrain: Procedural terrain with erosion, biomes, LOD, and async streaming
• astraweave-fluids: Deprecated PBD/accent remnant — W.1 (2026-06-20) removed the SPH/voxel sim (−58.8K LoC); retains in-crate caustics/foam + the F.4 GPU-particle accent substrate. Live water is the view-side successor (astraweave-water + astraweave-render/src/water.rs)
• astraweave-scene: Scene management with world partitioning and GPU resource streaming

🎮 Gameplay Systems (5 crates)

• astraweave-gameplay: Core gameplay framework (biomes, combat, crafting, quests, cutscenes)
• astraweave-quests: Quest system with authorable steps and LLM-powered generation
• astraweave-weaving: Emergent behavior layer with anchor system and echo currency (VeilWeaver mechanics)
• astraweave-cinematics: Cinematic timeline system for cutscenes and scripted sequences
• astraweave-pcg: Procedural content generation with deterministic seed-based RNG

🌐 Networking & Persistence (4 crates)

• astraweave-net: Snapshot-based networking with delta compression and interest management
• astraweave-net-ecs: ECS networking plugin with client prediction and server reconciliation
• astraweave-persistence-ecs: ECS save/load integration with replay recording
• astraweave-ipc: Inter-process communication for AI orchestration via WebSocket

🛠️ Infrastructure & Tools (8 crates)

• astraweave-audio: Spatial audio engine with dialogue integration and TTS adapter
• astraweave-ui: UI framework with HUD (quest tracker, minimap), menus, and accessibility
• astraweave-scripting: Rhai-based scripting for game logic and AI behavior
• astraweave-author: Rhai authoring for map design and encounter configuration
• astraweave-security: Security framework with sandboxing and input validation
• astraweave-secrets: Secrets management with keyring backend
• astraweave-steam: Steamworks SDK integration (achievements, cloud saves, statistics)
• astraweave-stress-test: Comprehensive stress testing and benchmarking framework

🔧 Additional Components

• Tools: aw_editor (active mid-campaign, 9,425 test annotations), aw_asset_cli, aw_texture_gen, aw_save_cli, and ~8 other build/debugging utilities (12 tool crates total)
• Examples: 57 example crates including hello_companion (7 AI modes, feature-gated), biome_showcase, adaptive_boss, and physics/fluids demos

---

🤝 Contributing

AstraWeave is an experimental project being built solo through AI-augmented development under the Genesis Code Protocol (GCP) — a methodology that pairs AI code generation with forensic auditing (the architecture trace campaign) as a counterweight to AI-generated documentation drift. The project's mandate is zero human-written code; the audit campaign is how that mandate stays honest.

Current Development Status:

• ~51 production crates across 130 workspace members with 57.35% whole-workspace LLVM line coverage (~39,000+ test annotations)
• Editor: Active mid-campaign with 9,425 test annotations (Multi-Tool Architecture Sub-phase 5 in flight; Sub-phases 3/4 complete)
• Architecture: 13 subsystem traces under docs/architecture/ + the Architecture Map (v0.7.2) + the Interactive Workspace Map
• Research surface (in-design, not runtime-wired): Fluids, Memory pipeline, Coordination, RAG composite, advanced GOAP, LLM production-hardening — see §5.1 of the architecture map
• Active Phases: Editor Multi-Tool Architecture Sub-phase 5 (5.C closeout, Mediator Removal, Sub-phase 6 pending). Phase 8.8 Physics Robustness paused since Feb 2026. Recently closed: Net-Trio-Remediation (Jun 10), Terrain Asset Quality (Jun 2), Unified Camera (Jun 1), Render Parity (May 17)

See CONTRIBUTING.md, CLAUDE.md, and docs/masters/MASTER_ROADMAP.md for detailed roadmap and contribution guidelines.

---