# Immersive Open World SOTA Gap Closure Proposal ## Achieving Industry-Leading Lifelike Virtual Worlds in the Oshun Ecosystem **Date:** 2026-03-19 **Scope:** Maya Engine, Neith Engine Framework, Hathor Worldbuilding, Bellona Build Platform, Project Obsidian **Status:** Proposal --- ## Table of Contents 1. [Executive Summary](#1-executive-summary) 2. [Reference Analysis](#2-reference-analysis) 3. [Current Oshun Coverage Assessment](#3-current-oshun-coverage-assessment) 4. [Gap Analysis & Feature Proposals](#4-gap-analysis--feature-proposals) - [4.1 Euphoria-Class Active Ragdoll & Dynamic Motion Synthesis](#41-euphoria-class-active-ragdoll--dynamic-motion-synthesis) - [4.2 Motion Matching & ML-Driven Animation](#42-motion-matching--ml-driven-animation) - [4.3 Chemistry Engine & Systemic Interaction Framework](#43-chemistry-engine--systemic-interaction-framework) - [4.4 Deep Ecology & Wildlife Simulation](#44-deep-ecology--wildlife-simulation) - [4.5 Terrain Deformation & Surface Interaction](#45-terrain-deformation--surface-interaction) - [4.6 Nubis-Class Volumetric Cloud & Storm System](#46-nubis-class-volumetric-cloud--storm-system) - [4.7 FFT Ocean & Hydrological Simulation](#47-fft-ocean--hydrological-simulation) - [4.8 GPU Procedural Foliage & Vegetation Interaction](#48-gpu-procedural-foliage--vegetation-interaction) - [4.9 Wind Propagation & Vorticle System](#49-wind-propagation--vorticle-system) - [4.10 Vehicle Physics & Deformation](#410-vehicle-physics--deformation) - [4.11 Crowd Simulation at Scale](#411-crowd-simulation-at-scale) - [4.12 Digital Twin & Earth-Scale World Streaming](#412-digital-twin--earth-scale-world-streaming) - [4.13 SSD-Optimized Asset Streaming](#413-ssd-optimized-asset-streaming) - [4.14 Mesh Shaders, Work Graphs & DXR 1.2](#414-mesh-shaders-work-graphs--dxr-12) - [4.15 Advanced Skin, Eye & Hair Rendering](#415-advanced-skin-eye--hair-rendering) - [4.16 GPU Particle System (Niagara-Class)](#416-gpu-particle-system-niagara-class) - [4.17 Seasonal System & Procedural Weathering](#417-seasonal-system--procedural-weathering) - [4.18 Facial Performance Capture Pipeline](#418-facial-performance-capture-pipeline) - [4.19 Advanced Haptic Feedback System](#419-advanced-haptic-feedback-system) - [4.20 Photo Mode System](#420-photo-mode-system) - [4.21 Save System Architecture](#421-save-system-architecture) - [4.22 Footstep & Surface Audio System](#422-footstep--surface-audio-system) - [4.23 Dynamic Music Composition System](#423-dynamic-music-composition-system) - [4.24 Gameplay Framework Systems](#424-gameplay-framework-systems) - [4.25 NPC Life Simulation Engine](#425-npc-life-simulation-engine) - [4.26 NPC Social & Relationship System](#426-npc-social--relationship-system) - [4.27 NPC Occupation & Work System](#427-npc-occupation--work-system) - [4.28 City Infrastructure Simulation](#428-city-infrastructure-simulation) - [4.29 Dynamic Agent Economy](#429-dynamic-agent-economy) - [4.30 Law Enforcement & Justice System](#430-law-enforcement--justice-system) - [4.31 Social Events & Cultural Life](#431-social-events--cultural-life) - [4.32 NPC-to-NPC Interaction Framework](#432-npc-to-npc-interaction-framework) - [4.33 Simulation LOD & AI Budget Management](#433-simulation-lod--ai-budget-management) - [4.34 World History & Civilization Generation](#434-world-history--civilization-generation) - [4.35 Information Propagation Network](#435-information-propagation-network) - [4.36 Domestic & Working Animals](#436-domestic--working-animals) - [4.37 Political & Governance Simulation](#437-political--governance-simulation) 5. [Cross-Cutting Concerns](#5-cross-cutting-concerns) 6. [Architecture Recommendations](#6-architecture-recommendations) 7. [Implementation Priority Matrix](#7-implementation-priority-matrix) --- ## 1. Executive Summary The Oshun ecosystem — specifically the Maya engine (Rust), Neith sovereign stack, Hathor worldbuilding, and Bellona build platform — already contains an extraordinarily comprehensive plan across Phases 40, 41-43, 72, 73, 76, and 77 of TODOS.md, covering ~4,000+ tasks across engine systems, multiplayer infrastructure, and game production tooling. However, a deep study of techniques used by the most acclaimed open-world games (Red Dead Redemption 2, GTA V/6, The Witcher 3, Cyberpunk 2077, Zelda: Tears of the Kingdom, Horizon Forbidden West, Ghost of Tsushima, Spider-Man 2, Elden Ring, Starfield, Assassin's Creed, Star Citizen, No Man's Sky, Microsoft Flight Simulator) and cutting-edge rendering research — combined with a deep study of living world simulation techniques (NPC life simulation, city behavior, dynamic economies, social systems, wildlife ecosystems, law enforcement, political dynamics, gossip networks, and NPC-to-NPC interaction from games like Dwarf Fortress, The Sims, RimWorld, Oblivion/Skyrim, Watch Dogs Legion, Hitman, Mount & Blade, Crusader Kings 3, Shenmue, and the Stanford Generative Agents research) — reveals **37 critical gap categories** not covered by any existing phase. These gaps represent the difference between a technically capable engine and one that produces the **visceral, living, breathable worlds** that define the medium's finest achievements. RDR2's ecology where coyotes hunt rabbits and vultures circle carcasses. GTA V's Euphoria-driven characters who grab for handholds as they fall. Zelda TotK's chemistry engine where fire melts ice and electricity conducts through water. Ghost of Tsushima's individual GPU-rendered grass blades swaying in vorticle-driven wind. Cyberpunk 2077's path-traced neon reflections in rain puddles. This proposal provides a complete, actionable specification for every missing system, with architectural guidance, reference implementations from specific games, and a priority matrix for implementation sequencing. --- ## 2. Reference Analysis ### 2.1 Games Analyzed | Game | Engine | Key Techniques Studied | | --------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------- | | Red Dead Redemption 2 | RAGE | Ecology simulation, terrain deformation, Euphoria ragdoll, NPC routines, volumetric fog, wildlife AI | | GTA V / GTA 6 | RAGE 9 | Euphoria, vehicle physics & deformation, crowd simulation, dynamic weather, procedural generation | | Cyberpunk 2077 | REDengine 4 | Path tracing (Overdrive), RTXDI, crowd density, vehicle physics | | The Witcher 3 | REDengine 3 | Quest branching, ecology, wind simulation, HDR deferred rendering | | Zelda: Tears of the Kingdom | Custom | Chemistry engine, systemic physics, Ultrahand mechanics | | Horizon Forbidden West | Decima | Nubis clouds, deferred texturing, HTN AI, Jolt physics, machine ecology | | Ghost of Tsushima | Custom | Procedural grass (GPU Bezier), vorticle wind, foliage interaction | | Spider-Man 2 | Insomniac Engine | Automated LOD, SSD streaming, seamless city streaming | | Elden Ring | Custom | Procedural world placement, atmospheric zoning, open-world boss design | | Starfield | Creation Engine 2 | Procedural planet generation, Havok animation, modular worldbuilding | | Assassin's Creed Shadows | Anvil Next 2 | RTGI, virtualized geometry, 10K crowd simulation, physics destruction | | Star Citizen | StarEngine | Server meshing, 64-bit positioning, seamless planetary transitions | | No Man's Sky | Custom | 18 quintillion planet procedural generation, L-systems, noise layering | | Microsoft Flight Simulator | Custom (Asobo) | 2PB cloud streaming, Blackshark.ai terrain, digital twin Earth | | Fortnite (UE5) | Unreal Engine 5 | Lumen, Nanite, World Partition, Niagara VFX | ### 2.2 Technical References Studied - NVIDIA Neural Radiance Cache, Ray Reconstruction, Cooperative Vectors (GDC 2025) - DirectX Raytracing 1.2 — Opacity Micromaps, Shader Execution Reordering - DirectX Shader Model 6.8 — Work Graphs - Mesh Shaders (NVIDIA, AMD) - Guerrilla Nubis volumetric cloudscape system (SIGGRAPH 2017, GDC 2023) - Guerrilla deferred texturing with software VRS (Horizon Forbidden West) - Jerry Tessendorf FFT ocean simulation - NaturalMotion Euphoria Dynamic Motion Synthesis - Ubisoft Motion Matching & Learned Motion Matching (GDC 2016, 2022) - DeepMimic physics-based character skill learning - Ghost of Tsushima procedural grass (GDC 2021) - Ghost of Tsushima Vorticle wind simulation - AC Unity massive crowd AI recycling (GDC 2015) - id Software MegaTexture / Virtual Texturing - Teardown voxel destruction - NVIDIA DLSS 3.5, AMD FSR 3.1, Intel XeSS 1.3 - Epic MetaHuman Animator & Convai NeuroSync - 3D Gaussian Splatting for real-time rendering - Jolt Physics (Horizon Forbidden West, Death Stranding 2) --- ## 3. Current Oshun Coverage Assessment ### 3.1 What IS Already Planned The following systems are comprehensively covered across existing TODOS.md phases and require no additional proposal: | System | Phase | Status | | ---------------------------- | --------------------------- | ----------------------- | | ECS / Engine Kernel | 40.1 | Tasks exist (marked ✅) | | Render Graph / Multi-Backend | 40.2.1 | Tasks exist | | Lumen-Class GI | 40.2.2 | Tasks exist | | Nanite-Class Geometry | 40.2.3 | Tasks exist | | Shadows & Lighting | 40.2.4 | Tasks exist | | PBR Materials | 40.2.5 | Tasks exist | | Post-Processing | 40.2.6 | Tasks exist | | Rigid/Soft Body Physics | 40.3 | Tasks exist | | Spatial Audio / HRTF | 40.4 (maya-audio) | Tasks exist | | Procedural Terrain | 40.x (maya-genesis-terrain) | Tasks exist | | Procedural Urban | 40.x (maya-genesis-urban) | Tasks exist | | Avatar/Embodiment | 40.x (maya-embodiment) | Tasks exist | | LLM NPC AI (maya-souls) | 40.x | Tasks exist | | Multiplayer Nexus | 40.x + Phase 77 | Tasks exist | | Neural Rendering (NRC) | 72.1 | Tasks exist (unchecked) | | Dedicated Servers | 72.2 | Tasks exist (unchecked) | | Distributed Builds | 72.3 | Tasks exist (unchecked) | | Dialogue System | 72.7 | Tasks exist (unchecked) | | Quest System | 72.8 | Tasks exist (unchecked) | | Inventory System | 72.9 | Tasks exist (unchecked) | | Anti-Cheat | 72.10 | Tasks exist (unchecked) | | NPC Scheduling | 72.17 | Tasks exist (unchecked) | | Character Controller | 72.24 | Tasks exist (unchecked) | | HUD System | 72.25 | Tasks exist (unchecked) | | Replay System | 72.26 | Tasks exist (unchecked) | | Input System | 72.27 | Tasks exist (unchecked) | | Audio Middleware | 72.28 | Tasks exist (unchecked) | | VR Production Studio | Phase 73 | Tasks exist (unchecked) | | Modding/Forge | Phase 76 | Tasks exist (unchecked) | | Full Multiplayer SOTA | Phase 77 | Tasks exist (unchecked) | ### 3.2 What IS NOT Planned — The Gaps The following 24 categories represent **critical missing systems** that are not covered by any existing task, phase, or proposal in TODOS.md. Each gap represents a technique used by one or more of the reference games that creates the visceral sense of a living, breathing world. --- ## 4. Gap Analysis & Feature Proposals --- ### 4.1 Euphoria-Class Active Ragdoll & Dynamic Motion Synthesis **Reference Games:** GTA IV, GTA V, RDR2 (NaturalMotion Euphoria) **What It Is:** Euphoria is not ragdoll physics. It is a full-body motor nervous system simulation where characters dynamically synthesize animation on-the-fly based on simulated muscles, bones, and a nervous system. Characters don't play canned animations when hit — they actively try to maintain balance, protect their head during falls, reach for handholds when stumbling off ledges, grab injured limbs when shot, and brace for impact. Each reaction is unique and context-dependent. **Why It's Critical:** This is the single most impactful system for making characters feel alive. The uncanny valley exists not in rendering but in animation — perfectly rendered characters that ragdoll like sacks of potatoes break immersion instantly. Euphoria is what makes RDR2's characters feel like they have mass, intention, and self-preservation instincts. **Gap:** Maya's `maya-embodiment` crate covers animation state machines, IK, and blend trees, but lacks the fundamental active ragdoll architecture where physics and neural motor control coexist simultaneously. The current system switches between animation and ragdoll discretely; Euphoria operates both continuously. **Proposed Feature Set:** #### 4.1.1 Motor Nervous System Simulation - Musculoskeletal model with 200+ muscles mapped to the character skeleton - Active muscle forces computed from nervous system commands, not keyframes - Balance controller maintaining center-of-mass over support polygon - Proprioceptive feedback loop (character "feels" its own joint positions) - Vestibular simulation (sense of gravity/acceleration affecting balance) - Pain response system — muscle weakness proportional to damage location - Fatigue model — sustained exertion reduces motor control quality #### 4.1.2 Reactive Behaviors - **Fall Protection:** Characters tuck and roll, extend arms to break falls, protect head with crossed arms during uncontrolled falls - **Stumble Recovery:** When pushed or tripped, character actively fights to regain balance through compensatory steps, arm windmilling - **Grab Reflex:** Characters reach for and grab ledges, railings, other characters, or vehicles when falling or being pushed - **Impact Bracing:** Anticipate collisions and brace with arms extended toward impact point - **Wound Response:** Grab injured body part, limp on wounded leg, favor unwounded arm - **Environmental Awareness:** Characters avoid obstacles during stumbles, look for landing zones during falls - **Drowning Response:** Desperate surface-seeking behavior with decreasing coordination #### 4.1.3 Blended Animation-Physics Pipeline - Continuous blend between keyframe animation and physics simulation (not discrete state switch) - Animation drives desired pose, physics applies constraints and external forces - Motor controller PID loops that track animation targets while respecting physics - Smooth transition zone: running animation → stumble → active balance → ragdoll is a continuous spectrum - Override priorities: gameplay animation intent vs physics reality vs motor control response #### 4.1.4 Integration Points - **Physics Integration:** Bidirectional coupling with `maya-physics` — Euphoria drives joint torques, physics applies external forces and collision responses - **Animation Integration:** Euphoria consumes target poses from `maya-embodiment` animation system, applies motor control on top - **AI Integration:** `maya-souls` can influence motor behavior — an NPC who sees the fall coming braces better than one surprised - **Damage System:** Hit location and force magnitude determine motor response severity **Technology:** Rust crate `maya-euphoria` within `libs/maya/engine-core/crates/` **Complexity:** Very High — this is one of the most complex animation systems in the industry. NaturalMotion spent 10+ years developing Euphoria. The Maya implementation should start with a simplified motor model and iterate toward full fidelity. --- ### 4.2 Motion Matching & ML-Driven Animation **Reference Games:** Far Cry 6 (Choreograph), GTA 6, Horizon Forbidden West, The Last of Us Part II **What It Is:** Motion matching eliminates hand-authored animation state machines. Instead, a large database of motion capture data is searched in real-time to find the best-matching animation clip given the character's current pose, velocity, trajectory, and desired future trajectory. The system continuously selects the optimal continuation, producing fluid, natural animation without visible transitions. Learned Motion Matching (Ubisoft, 2022) extends this by training a neural network to replicate the motion matching search, reducing memory from gigabytes of animation data to megabytes of network weights while preserving quality. **Gap:** Phase 40 `maya-embodiment` mentions animation state machines and blend trees — the traditional approach. Motion matching is fundamentally different and superior for locomotion, traversal, and combat animation. **Proposed Feature Set:** #### 4.2.1 Motion Matching Core - Animation database compiler: process MoCap FBX/BVH into searchable pose database - Feature extraction: joint positions, velocities, trajectory (future path), foot phase, contact states - KD-tree spatial search for nearest-neighbor pose lookup in feature space - Cost function combining pose similarity, trajectory match, and transition smoothness - Inertia blending: crossfade to selected clip starting at matched frame - Tag system: annotate clips with metadata (surface type, mood, weapon held, speed class) - Query system: game code requests future trajectory → motion matching finds best animation - Foot locking IK: prevent foot sliding on matched animations via ground contact markers #### 4.2.2 Learned Motion Matching - Train lightweight neural network (2-3 hidden layers) to approximate motion database search - Network input: current pose features + desired trajectory features - Network output: predicted animation state (bone positions, velocities) - Decompressor network: compact latent space → full skeleton pose - Online training pipeline: capture new MoCap → retrain incrementally - Memory reduction target: 10-100x compression vs raw motion database - Quality target: indistinguishable from full motion matching in blind tests #### 4.2.3 Physics-Aware Motion Matching - Integration with `maya-euphoria` active ragdoll: motion matching drives target pose, Euphoria applies physical corrections - Terrain-adaptive locomotion: query ground slope/material → bias motion selection toward uphill/downhill/slippery variants - Obstacle awareness: predict collisions along trajectory → select avoidance animations - Object interaction: approach animation selected based on object height/type (pick up from ground vs shelf vs overhead) #### 4.2.4 ML Locomotion (DeepMimic-Class) - Reinforcement learning agent controlling character's muscles/joint torques - Training: physics-based character learns to mimic reference motion capture - Skills: walk, run, sprint, jump, climb, swim, fight — each trained separately or as multi-skill policy - Terrain adaptation: agent trained on varied terrains generalizes to unseen geometry - Recovery: agent learns to recover from perturbations (pushed, tripped) - Integration with motion matching: ML handles edge cases and physics transitions, motion matching handles normal locomotion **Technology:** Rust crate `maya-motion-matching` + `maya-ml-locomotion` with ONNX Runtime integration for ML inference. --- ### 4.3 Chemistry Engine & Systemic Interaction Framework **Reference Games:** Zelda: Breath of the Wild, Zelda: Tears of the Kingdom **What It Is:** Nintendo's "chemistry engine" assigns physical/chemical properties to every object in the world. Three fundamental rules govern all interactions: 1. Elements can change a material's state (fire burns wood, ice freezes water) 2. Elements can change other elements' states (wind spreads fire, water extinguishes fire) 3. Materials cannot change other materials' states (wood doesn't directly affect metal) This creates "multiplicative gameplay" where the interaction of simple systems produces emergent, complex, often surprising outcomes — dropping a metal weapon in a thunderstorm causes it to attract lightning; setting grass on fire creates an updraft that makes the player's paraglider rise. **Gap:** Phase 40 `maya-physics` covers rigid bodies, soft bodies, fluids, and destruction but treats these as independent systems. The chemistry engine is a cross-cutting interaction layer that connects all physical systems through property-based rules, enabling emergent systemic gameplay. **Proposed Feature Set:** #### 4.3.1 Material Property System - Every entity has a material property component defining: - **Element affinity:** fire, water, ice, electricity, wind, earth, light, dark - **Material class:** wood, metal, stone, cloth, organic, liquid, gas - **State:** solid, liquid, gas, plasma, frozen, burning, electrified, wet - **Conductivity:** how well it transmits each element (metal conducts electricity, cloth absorbs water) - **Flammability:** ignition temperature, burn rate, ash residue - **Buoyancy:** density relative to water/air - **Temperature:** current thermal state affecting behavior - Material state transitions defined as rules: - wood + fire → burning_wood (produces light, heat, smoke, eventually ash) - water + ice_element → ice (becomes solid, walkable surface) - metal + electricity → electrified_metal (damages contacts, conducts to adjacent metals) - cloth + water → wet_cloth (heavier, no longer flammable, cold damage) #### 4.3.2 Interaction Rule Engine - Rule database: `(source_element, target_material, condition) → effect` - Priority system for conflicting rules (water vs fire → steam, not "wet fire") - Propagation system: effects spread through connected/adjacent objects - Fire spreads to adjacent flammable objects within proximity - Electricity conducts through chains of conductive materials - Water flows downhill and pools in depressions - Cold/heat propagate through conductive materials - Chain reaction support: fire → wooden bridge → rope holding boulder → boulder falls → dam breaks → water flood → fire extinguished - Area-of-effect interactions: lightning strike electrifies puddle affecting all entities standing in it - Temporal effects: wood burns over time (fully consumed → ash), ice melts gradually in warm areas #### 4.3.3 Environmental Integration - Weather system feeds elements into the world: - Rain → all outdoor surfaces become wet, fire extinguished, puddles form - Lightning storms → metallic objects have chance of lightning strike - Cold weather → water surfaces freeze, characters take cold damage without insulation - Hot weather → ice melts faster, dehydration mechanic - Time-of-day effects: - Night → reduced temperature → ice persists longer - Dawn/dusk → dew forms on surfaces (minor wetness) - Biome-specific defaults: - Desert → high ambient heat, no natural water, fire spreads faster - Tundra → ambient cold, natural ice, fire is harder to start #### 4.3.4 Gameplay Implications - Player can exploit interactions for puzzle-solving, combat, and traversal - NPCs should react to systemic effects (flee from fire, seek shelter from rain) - Quest objectives can leverage chemistry (burn the barricade, freeze the river to cross, electrify the water to defeat aquatic enemies) - Crafting system can use material properties (combine flammable material + fire source = torch) **Technology:** Rust crate `maya-chemistry` with component-based property system integrated into ECS. --- ### 4.4 Deep Ecology & Wildlife Simulation **Reference Games:** RDR2 (200 species), Horizon Forbidden West (machine ecology), The Witcher 3 **What It Is:** RDR2's wildlife isn't decorative — it simulates a functioning ecosystem. Approximately 200 species exhibit species-specific behaviors: wolves hunt in packs, vultures circle carcasses, geese fly in V-formations, possums play dead, grizzly bears bluff-charge before attacking. A full food chain operates: predators hunt prey, carcasses decay and attract scavengers, over-hunting causes population decline with cascading effects. **Gap:** Phase 40 has maya-souls for LLM NPC dialogue and behavior, but no dedicated ecosystem simulation system. Phase 72.17 covers NPC scheduling for humanoid NPCs but not wildlife. No existing task addresses predator-prey dynamics, population management, migration, or species-specific behavioral programs. **Proposed Feature Set:** #### 4.4.1 Species Database & Behavioral Programs - Species definition schema: - Taxonomy: class, order, family, genus, species - Physical stats: size, weight, speed, stamina, strength, senses (sight range, hearing range, smell range) - Behavioral archetype: predator, prey, scavenger, herbivore, omnivore, apex predator - Diet: list of species/plants consumed, caloric needs - Social structure: solitary, pair, pack (size range), herd (size range), flock - Activity pattern: diurnal, nocturnal, crepuscular - Habitat preferences: biome affinity, altitude range, water proximity - Reproduction: season, gestation, litter size, maturation time - Per-species behavioral state machine: - Idle/rest → forage/hunt → eat → drink → sleep → reproduce → flee → fight → die → decay - Species-specific behaviors mapped to states: - Wolf: coordinated pack hunting with flanking, alpha leadership - Deer: herd flight response, sentinel alerting - Eagle: soaring thermals, dive attacks on small prey - Bear: territorial marking, fishing at rivers, hibernation in winter - Vulture: circle high above carcasses, wait for predators to leave - Snake: ambush predation, basking on warm rocks - Fish: schooling behavior, upstream spawning runs #### 4.4.2 Food Chain & Population Dynamics - Predator-prey relationships modeled with Lotka-Volterra dynamics - Population tracking per species per region (birth rate, death rate, carrying capacity) - Energy flow: prey consumed → predator energy → survival/reproduction capacity - Starvation mechanics: insufficient prey → predator population decline → prey population recovery → cycle - Player impact: - Over-hunting prey → predator starvation → predator population decline - Over-hunting predators → prey population explosion → habitat degradation - Introduction of new species (intentional or accidental) → ecosystem disruption - Seasonal effects: - Migration: birds fly south in winter, caribou follow seasonal routes - Hibernation: bears, some mammals in winter - Breeding seasons: increased territorial aggression, mating displays - Famine periods: increased predator aggression, expanded territory #### 4.4.3 Carcass & Decay System - Dead animals become carcass entities with decay state - Decay progression: fresh → bloated → decaying → skeletal → bones → gone - Each stage affects: - Visual appearance (mesh morphing, texture changes) - Scavenger attraction radius (increases then decreases) - Usability (player can skin fresh/bloated, not skeletal) - Disease risk (decaying carcasses near water contaminate drinking sources) - Scavenger behavior: vultures arrive first (aerial surveillance), then crows, then ground scavengers (coyotes, hyenas), then insects #### 4.4.4 Rendering Integration - Animal LOD system: full skeletal animation (near) → simplified animation (mid) → sprite impostor (far) → population count (distant) - Flock/herd formation rendering: GPU-instanced rendering for large groups - Migration visual effects: hundreds of birds darkening the sky, fish runs in rivers - Predator-prey chase sequences: coordinated multi-agent animation events **Technology:** Rust crate `maya-ecology` with TypeScript companion `libs/maya/ecology/` for species database management and population analytics. --- ### 4.5 Terrain Deformation & Surface Interaction **Reference Games:** RDR2 (mud, snow, footprints), Horizon Forbidden West (machine tracks), various snow-deformation games **What It Is:** In RDR2, characters leave persistent footprints in mud and snow. Wagon wheels carve ruts that persist. Snow deforms under weight, compacting rather than simply disappearing. Horse hooves throw up mud particles. Deep mud affects movement speed and animation. These effects use a combination of parallax occlusion mapping (POM), tessellation shaders, and displacement maps rendered per-frame into persistent deformation buffers. **Gap:** Phase 40 covers terrain generation and rendering but no task addresses runtime terrain deformation. Phase 72 mentions terrain-related tasks only in the context of the character controller (step detection, slope angle). **Proposed Feature Set:** #### 4.5.1 Deformation Buffer System - Per-region displacement map (heightmap) tracking accumulated deformation - Heightmap resolution: 1-2 cm per texel for footprint-level detail - Deformation sources: character feet, vehicle wheels, projectile impacts, animal hooves, physics objects - Deformation types: - **Depression:** Weight pushes surface down (footprints, tracks) - **Displacement:** Material pushed outward creating ridges (tire ruts, plow furrows) - **Compression:** Material compacts without displacement (snow compaction) - **Erosion:** Material removed entirely (water erosion, explosions) - Deformation persistence: - Permanent until region unloads (default for most surfaces) - Gradual recovery (elastic surfaces like grass return over time) - Fill-in from weather (rain fills tracks, snow covers footprints) - Bake to streaming chunk for long-term persistence #### 4.5.2 Surface Material Response - Per-surface-material deformation properties: - **Mud:** Deep deformation, slow recovery, particle splash, movement speed penalty, squelching audio - **Snow:** Medium deformation with compaction, crunch audio, cold temperature effect, fills gradually - **Sand:** Shallow deformation, wind erosion, particle kick-up, no recovery (wind redistributes) - **Grass:** Minimal deformation, fast elastic recovery, visual bending only (uses foliage interaction system §4.8) - **Gravel:** Slight displacement, crunch audio, particle scatter - **Wet soil:** Deep deformation, no recovery, darker visual where disturbed, transition to mud in rain #### 4.5.3 Rendering - Parallax Occlusion Mapping for deformation visual on non-tessellated terrain - Tessellation + displacement mapping for close-range deformation detail - Normal map update from deformation heightmap for correct lighting - Material darkening/lightening at deformation sites (compacted snow is icier, disturbed dirt is lighter) - Deformation buffer streaming aligned with world partition streaming chunks - Performance: deformation map rendered as screen-space overlay projected onto terrain, only updating tiles with active deformation sources #### 4.5.4 Physics & Gameplay Integration - Deformed terrain feeds back into physics: - Deep ruts affect vehicle handling (wheels follow grooves) - Deep mud increases drag on moving characters/vehicles - Compacted snow is more slippery than fresh powder - Tracking: NPCs can follow player's tracks (hunting/pursuit AI) - Stealth: avoiding soft surfaces reduces noise, hard surfaces leave fewer visual tracks **Technology:** Rust crate `maya-terrain-deformation` integrated with `maya-physics` and `maya-renderer`. --- ### 4.6 Nubis-Class Volumetric Cloud & Storm System **Reference Games:** Horizon Zero Dawn/Forbidden West (Guerrilla's Nubis), RDR2, GTA 6, Microsoft Flight Simulator **What It Is:** Guerrilla Games' Nubis system renders photorealistic volumetric clouds through ray-marching with a coverage/type map-based modeling method. In under 2ms on PS4, it produces clouds that evolve dynamically, cast volumetric shadows on the terrain, and participate in atmospheric scattering. For Horizon Forbidden West's Burning Shores DLC, they extended Nubis with voxel technology for dense tornadic superstorms with internal lightning, temporal upscaling for fast-moving clouds, and full volumetric storm systems — without expensive fluid simulations. RDR2 uses similar voxelization and ray-marching for clouds and fog, with volumetric fog reacting to time-of-day transitions. GTA 6 features real-time hurricanes building over time with accumulating puddles affecting driving physics. **Gap:** Phase 40.2.6 mentions post-processing including "volumetric light scattering" but this is a screen-space god-ray effect, not a full volumetric cloud system. No existing task covers cloud modeling, cloud ray-marching, storm systems, or cloud-terrain shadow interaction. **Proposed Feature Set:** #### 4.6.1 Cloud Modeling - Coverage map: 2D texture defining where clouds exist (0-1 coverage) - Type map: defines cloud type at each coverage point (cumulus, stratus, cirrus, cumulonimbus) - Cloud density volume: 3D noise-based volume using layered Worley and Perlin noise - Height-based density profiles per cloud type: - Cumulus: dense bottom, billowing top, flat base - Stratus: thin, flat, wide coverage - Cirrus: wispy, high-altitude, ice crystal appearance - Cumulonimbus: towering, dark base, anvil top, storm-producing - Temporal evolution: wind advects coverage map, clouds form/dissipate over time - Artist controls: weather preset system drives coverage/type maps, with blending between presets #### 4.6.2 Cloud Rendering - Ray-marching through cloud volume from camera: - Primary ray: march through volume accumulating density and scattering - Secondary ray (light ray): for each sample, march toward sun to compute self-shadowing - Multi-scattering approximation: 2-lobe Henyey-Greenstein phase function for silver-lining effect - Powder effect: darkening at cloud edges transitioning to bright interiors - Beer's Law attenuation for light absorption through cloud volume - Temporal reprojection: render clouds at quarter resolution, temporally upsample across 16 frames - Cloud shadow map: project cloud density onto terrain for cloud shadows that drift across the landscape - Performance target: <2ms GPU on current-gen consoles at quarter resolution with temporal upscaling #### 4.6.3 Storm Systems - Storm cell simulation: cumulonimbus growth cycle (developing → mature → dissipating) - Anvil formation: cloud top spreads as it hits atmospheric ceiling - Precipitation generation: rain/snow particle emission from cloud base - Lightning system: - Intra-cloud lightning (flashes illuminate cloud interior) - Cloud-to-ground lightning (visual bolt + illumination + thunder delay) - Lightning probability increases with storm intensity - Random Lichtenberg-pattern bolt generation - Tornado/funnel formation (extreme weather events): - Rotating mesocyclone visible in cloud structure - Funnel cloud descending from cloud base - Debris particle effects at ground contact - Physics influence on nearby objects - Hurricane/typhoon system: - Eye-wall structure visible from distance - Spiral rain bands with varying intensity - Storm surge effects on water bodies #### 4.6.4 Integration - Weather system drives cloud presets over time (clear → partly cloudy → overcast → storm → clearing) - Clouds participate in atmospheric scattering (sunrise/sunset colors) - Cloud shadows affect terrain lighting and NPC behavior (seek shelter during dark storms) - Rain precipitation generates puddles in deformation system (§4.5) - Wind system (§4.9) drives cloud movement direction and speed **Technology:** Rust crate `maya-clouds` with WGSL/GLSL compute shaders for ray-marching. --- ### 4.7 FFT Ocean & Hydrological Simulation **Reference Games:** Sea of Thieves, Assassin's Creed Black Flag/Odyssey, Uncharted 4, various naval games **What It Is:** Realistic ocean rendering uses Jerry Tessendorf's FFT-based approach: the ocean surface is represented as a sum of thousands of sinusoidal waves computed via Inverse Fast Fourier Transform. Each frame, the GPU computes displacement maps, normal maps, and foam maps from spectral data. The JONSWAP/Pierson-Moskowitz spectrum models realistic wave statistics based on wind speed and fetch distance. **Gap:** Phase 40.2.5.11 mentions "water and liquid materials" as a shading model but this is surface appearance only. No task covers ocean simulation geometry, wave spectra, foam generation, river flow, waterfall systems, buoyancy physics, or underwater rendering. **Proposed Feature Set:** #### 4.7.1 FFT Ocean Surface - Spectral wave model: - Pierson-Moskowitz spectrum for fully developed seas - JONSWAP spectrum for developing seas (adjustable peak enhancement) - Phillips spectrum as simplified alternative - FFT computation: - 512x512 or 1024x1024 FFT grid computed per frame on GPU (compute shader) - Output textures: height displacement, XZ displacement, normal map, foam (Jacobian) - Multiple cascade resolutions (ocean-scale swell + medium waves + fine ripples) - Wind-driven parameters: - Wind speed → wave height and wavelength - Wind direction → wave travel direction - Fetch distance → spectral shape - Tiling: seamless ocean surface tiling across arbitrarily large bodies of water - Shore interaction: wave height attenuates approaching shore, wave direction refracts around coastline geometry #### 4.7.2 Foam & Surface Detail - Jacobian-based foam generation: foam appears where wave crests fold (negative Jacobian = breaking wave) - Foam persistence: foam texture accumulates at breaking points, dissipates over time - Wake foam: boats and swimming characters leave foam trails - Shore foam: waves breaking on beaches create foam wash patterns - Bubbles: sub-surface bubbles at wave breaking points (particle + subsurface scattering contribution) #### 4.7.3 Water Rendering - Reflections: planar reflection for calm water, screen-space or ray-traced for rough water - Refractions: underwater scene visible through surface with chromatic dispersion - Caustics: light patterns projected onto underwater surfaces and objects (animated caustic texture or ray-traced) - Absorption/scattering: water color deepens with depth (Beer's Law), scatter contributes to underwater fog - Underwater rendering: full underwater camera mode with color absorption, volumetric light shafts, particle effects, depth fog - Surface-to-underwater transition: smooth camera transition with water line effect (split-screen above/below) #### 4.7.4 Rivers, Lakes & Waterfalls - Flow map system: 2D vector field defining water flow direction and speed - River spline: artists define river path, system generates flow maps and geometry automatically - River interaction with terrain: banks, rapids over rocky terrain, pools in flat areas - Waterfall rendering: particle-based spray + geometric sheet with flow animation - Lake system: still water with wind-driven ripples, distinct from ocean simulation - Puddle rendering: screen-space or deformation-buffer driven rain puddles with ripple animations #### 4.7.5 Buoyancy & Water Physics - Buoyancy simulation: Archimedes' principle with wave-height sampling - Multi-point buoyancy: boats sample wave height at multiple hull points for pitch/roll response - Drag forces: submerged objects experience water resistance - Floating debris: objects dropped in water float, drift with current, wash ashore - Character swimming physics: stamina-based swimming, current affects movement, underwater breath management **Technology:** Rust crate `maya-ocean` with GPU compute shaders for FFT. --- ### 4.8 GPU Procedural Foliage & Vegetation Interaction **Reference Games:** Ghost of Tsushima, Horizon Forbidden West, RDR2, Elden Ring **What It Is:** Ghost of Tsushima generates individual grass blades on the GPU using cubic Bezier curves for shape and animation. A damped wave is applied to displacement for natural bounce-back when characters walk through. Each blade is a procedurally generated geometry patch — not a billboard or pre-modeled mesh. This enables fields of millions of unique grass blades with physically- responsive animation at minimal CPU cost. Horizon Forbidden West uses a deferred texturing system for foliage with software VRS, enabling dense vegetation without GPU fill-rate bottleneck. **Gap:** Phase 40 mentions procedural flora generation (`maya-genesis-flora`) for L-system plant modeling, but this is offline asset generation. No task covers runtime GPU grass rendering, vegetation interaction (character pushes through foliage), or real-time vegetation response to wind and movement. **Proposed Feature Set:** #### 4.8.1 GPU Grass Rendering - Grass blade generation in compute shader: - Input: terrain heightmap + grass density map + wind data - Output: per-blade vertex data (cubic Bezier control points, width, color variation) - Blade shape: cubic Bezier curve with 3-4 control points for natural curvature - Blade variation: height, width, curvature, color (hue shift, tip bleaching) randomized per-blade using hash of world position - LOD system: - Near (0-10m): individual Bezier blades, full animation - Medium (10-50m): simplified blade batches, reduced animation - Far (50-200m): flat ground texture with normal-mapped grass appearance - Distant (200m+): terrain color only - Instancing: GPU indirect rendering with per-tile grass patches - Culling: frustum + occlusion culling per grass tile, hi-z occlusion buffer #### 4.8.2 Vegetation Interaction - Character-to-vegetation interaction: - Characters moving through grass push blades aside - Interaction sphere/capsule around character's lower body - Blades deflect away from movement direction, spring back with damped oscillation - Interaction force proportional to movement speed - Vehicle interaction: wider interaction zone, stronger deflection, possible destruction (crushed grass stays flat) - Wind interaction (linked to §4.9): - Global wind direction applied as base animation to all blades - Wind gusts create visible wave patterns across grass fields - Sheltered areas (behind buildings, in valleys) have reduced wind effect - Animal interaction: grazing animals visually shorten grass, herds create trampled paths #### 4.8.3 Tree & Bush Interaction - Branch deflection: character pushing through bushes bends branches, which spring back - Leaf particle emission on impact (leaves break off when hit) - Tree sway: per-vertex wind animation with trunk, branch, and leaf layers responding at different frequencies - SpeedTree integration path: import SpeedTree assets with wind animation data - Falling leaves: seasonal particle system for deciduous trees - Fruit/nut drop: interactable resources that fall from trees (physics objects) #### 4.8.4 Biome-Specific Vegetation - Grass type variation by biome: - Savanna: tall golden grass, slow wave - Temperate: short green grass, dense - Tundra: sparse, short, wind-flattened - Tropical: undergrowth ferns and broad leaves - Wetland: reeds and marsh grass (tall, thin, clustered near water) - Vegetation density driven by soil moisture, altitude, temperature (feeds from world generation) **Technology:** Rust crate `maya-vegetation` with WGSL compute shaders. --- ### 4.9 Wind Propagation & Vorticle System **Reference Games:** Ghost of Tsushima (Vorticles), RDR2, Horizon Forbidden West **What It Is:** Ghost of Tsushima's wind system uses "vorticles" — a simplified vortex particle system. Wind sources (global wind, player movement, explosions, fans) emit vorticles that propagate through the environment. All wind-responsive systems (grass, trees, cloth, particles, flags, hair) sample the vorticle field to determine local wind force, creating spatially coherent wind effects where a gust visibly travels across a field of grass. **Gap:** No task in any phase addresses wind simulation. Phase 40 mentions cloth simulation and foliage, but no unified wind system that drives all of these. **Proposed Feature Set:** #### 4.9.1 Wind Field - Global wind: direction, speed, gust frequency, gust intensity (set by weather system) - Wind map: 3D grid or 2D heightfield storing wind vectors at spatial resolution of ~1-2m - Wind sources: - **Global directional:** uniform wind across the world (base weather wind) - **Point sources:** explosions (radial outward), fans, vents, propellers - **Line sources:** vehicles (wake turbulence along path) - **Volume sources:** storms, tornadoes (rotational + uplift) - Wind occlusion: buildings and terrain block wind, creating sheltered areas (wind shadow computation via simplified raycast or distance field) - Wind channeling: valleys and streets funnel wind, increasing speed (Venturi effect approximation) #### 4.9.2 Vorticle Simulation - Vorticle: lightweight vortex particle with position, rotation axis, strength, radius, lifetime - Vorticle emission from wind sources (gusts emit clusters of vorticles) - Vorticle advection: vorticles move with global wind + their own velocity - Vorticle decay: strength decreases over lifetime - Vorticle interaction: nearby vorticles can merge or interfere - Sampling: any system needing wind force queries the vorticle field at a position → returns aggregate wind vector from all nearby vorticles + global wind - Performance: vorticle count budget (~1000 active), spatial hashing for efficient nearby queries #### 4.9.3 Wind Consumers - **Grass & vegetation** (§4.8): blades bend in wind direction, wave patterns from gusts - **Trees:** trunk sway, branch oscillation, leaf flutter — all driven by sampled wind - **Cloth:** `maya-physics` cloth simulation driven by wind forces - **Hair/fur:** character hair responds to wind (sampled at character position) - **Particles:** smoke, fire, dust, leaves carried by wind - **Flags/banners:** decorative objects animated by wind - **Water surface:** wind-driven ripples on lakes and puddles - **Sound:** wind audio volume and pitch respond to wind speed at listener position - **Gameplay:** strong wind affects projectile trajectory, character movement on exposed ridges **Technology:** Rust module within `maya-physics` or standalone `maya-wind` crate. --- ### 4.10 Vehicle Physics & Deformation **Reference Games:** GTA V/6, Forza Horizon 5, Cyberpunk 2077, BeamNG.drive **What It Is:** Realistic vehicle physics require suspension simulation providing weight transfer that feeds into tire models. GTA 6's RAGE 9 engine features physically-simulated vehicle deformation where crashes dent panels, shatter windows, and crumple chassis in real-time. Forza uses brush deflection tire models with heat and wear simulation. BeamNG.drive simulates entire vehicles as soft-body node-beam structures for extreme deformation fidelity. **Gap:** Phase 40.3 covers rigid body physics and destruction but no task addresses vehicle-specific physics (suspension, tires, drivetrain, aerodynamics) or real-time vehicle deformation. Phase 72.24 covers character controllers but not vehicle controllers. **Proposed Feature Set:** #### 4.10.1 Vehicle Dynamics - Suspension simulation: - Per-wheel spring-damper system with configurable travel, stiffness, damping - Anti-roll bars connecting left/right wheels - Weight transfer calculation (acceleration, braking, cornering) - Suspension geometry: double wishbone, MacPherson strut, live axle (simplified) - Tire model: - Pacejka "Magic Formula" for tire force calculation - Slip angle → lateral force curve - Slip ratio → longitudinal force curve - Combined slip handling (braking while turning) - Surface material affects grip (asphalt > gravel > mud > ice) - Tire temperature model (optional): cold → optimal → overheated grip curve - Drivetrain: - Engine torque curve, RPM, gear ratios, differential types (open/limited-slip/locked) - FWD, RWD, AWD configurations - Transmission modes: manual, automatic, semi-auto with sequential shifting - Turbo/supercharger boost model (optional) - Aerodynamics: - Drag coefficient × frontal area × velocity² = drag force - Downforce at speed (relevant for high-performance vehicles) - Lift effects (relevant for off-road jumps) #### 4.10.2 Vehicle Deformation - Node-beam deformation model (simplified from BeamNG): - Vehicle body represented as mesh of nodes connected by beams - On impact: force propagated through beam network, beams that exceed stress threshold deform permanently - Deformation affects visual mesh (dented panels, bent frame) - Deformation affects physics (bent axle pulls steering, damaged wheel reduces grip) - Component damage: - Windows: crack on moderate impact, shatter on severe impact (particle effect) - Doors: dent, jam (won't open), fall off on extreme damage - Hood/trunk: dent, pop open, fall off - Lights: break (affects nighttime visibility) - Engine: damage reduces performance, overheating, eventual failure - Wheels: puncture → flat tire → reduced speed + pull to affected side - Deformation LOD: full node-beam at close range, simplified deformation at distance, no deformation physics for off-screen vehicles #### 4.10.3 Vehicle Types - **Cars/trucks:** full suspension, tire, drivetrain simulation - **Motorcycles:** lean physics, counter-steering, low-speed balance, ragdoll dismount on crash - **Boats:** buoyancy (§4.7.5), water resistance, wave response, propeller thrust - **Aircraft:** lift, drag, thrust, control surfaces (elevator, ailerons, rudder), stall mechanics - **Horses/mounts:** biological locomotion (not wheeled), terrain-adaptive gait, bonding/trust system, autonomous movement AI #### 4.10.4 Vehicle Audio - Engine RPM-driven audio: pitch-shifted engine sample layers (idle, low RPM, mid, high RPM, redline) - Exhaust pops on deceleration - Tire audio: surface-dependent (asphalt screech, gravel crunch, mud squelch) - Wind noise at speed - Suspension audio: bump, creak, bottoming out - Collision audio: impact force-dependent (tap, crunch, crash) - Horn/siren (interactive) **Technology:** Rust crate `maya-vehicles` integrated with `maya-physics`. --- ### 4.11 Crowd Simulation at Scale **Reference Games:** Assassin's Creed Unity (10,000 NPCs), Hitman World of Assassination, GTA V **What It Is:** AC Unity's "Bulk System" renders 10,000 on-screen NPCs using three LOD tiers: LoRes Bulk (40m+, low-poly, simple animation), Autonomous Bulk (full animation system), and Puppet Bulk (full NPC with AI). Only ~40 NPCs have real AI at any time; the rest use deterministic closed-loop paths managed by "Wandering Crowd Shepherds." NPC pools swap LOD tiers dynamically without the player noticing the transition. **Gap:** Phase 72.17 covers NPC scheduling for individual named NPCs with daily routines. No task addresses mass crowd simulation where thousands of anonymous NPCs populate cities, markets, and events with coordinated emergent behavior. **Proposed Feature Set:** #### 4.11.1 Crowd LOD System - **Tier 1 — Full NPC (0-15m):** Complete character with full AI, animation, physics, dialogue capability, inventory, reactions - **Tier 2 — Autonomous (15-40m):** Animated character with simplified AI (follow path, react to loud events), reduced polygon count, shared animation instances - **Tier 3 — Bulk (40-100m):** Low-poly mesh with vertex-animated walk cycle, no individual AI, follows Shepherd path, LOD mesh is ~500 triangles - **Tier 4 — Impostor (100m+):** Billboard sprite or point-cloud representation, simple parallax animation - **Transition:** Seamless LOD swapping using distance hysteresis bands (promote at 14m, demote at 16m) to prevent flickering #### 4.11.2 Crowd Behavior - Shepherd paths: predefined closed-loop routes through the environment that Bulk NPCs follow - Path variation: NPCs on same Shepherd path are offset in time and have slight speed variation - Density control: crowd density maps per area (market = dense, residential = sparse) - Time-of-day variation: morning commute crowds, afternoon shopping, evening entertainment district, late-night sparse - Event response: crowds gather around street performers, flee from combat, clear path for vehicles - Emergent lane formation: opposing pedestrian flows self-organize into lanes (flocking-based) #### 4.11.3 Crowd Rendering - GPU instanced rendering for Bulk tier: single draw call for hundreds of NPCs sharing same mesh/animation - Animation texture: bone transforms baked into texture, sampled in vertex shader (no CPU skinning for Bulk tier) - Variety: multiple clothing/skin color combinations via material parameters, not unique meshes - Shadow LOD: Bulk NPCs cast simplified shadow (capsule proxy), Full NPCs cast proper skeletal shadow - Performance target: 10,000 visible NPCs at 60fps on current-gen hardware #### 4.11.4 Crowd Audio - Crowd noise: layered ambient audio with density-responsive volume - Individual barks: random one-liners from nearby NPCs (ambient chatter) - Crowd reactions: collective gasp, cheer, scream based on events - Footstep aggregate: blended footstep audio increasing with crowd density **Technology:** Rust crate `maya-crowds` with GPU instancing and animation texture rendering. --- ### 4.12 Digital Twin & Earth-Scale World Streaming **Reference Games:** Microsoft Flight Simulator, Google Earth VR **What It Is:** MSFS streams over 2 petabytes of world map data from Azure cloud, using Bing Maps for satellite imagery and Blackshark.ai's neural network to generate 3D buildings and terrain from 2D satellite photos. The result is a photorealistic digital twin of the entire Earth that updates every 28 days with fresh satellite imagery. **Gap:** Phase 40.1.2 covers world partitioning and streaming for artist- authored worlds. No task addresses cloud-streamed geospatial data, satellite imagery integration, or neural mesh reconstruction from 2D imagery for earth-scale worlds. **Proposed Feature Set:** #### 4.12.1 Geospatial Data Pipeline - Satellite imagery ingestion: - Support Bing Maps, Google Maps, Mapbox, OpenStreetMap tile APIs - Tile pyramid management (zoom levels 0-21) - Tile caching with LRU eviction and configurable disk cache size - Elevation data: - DEM (Digital Elevation Model) ingestion: SRTM, ASTER, Copernicus - Terrain mesh generation from heightmap tiles - Coastline detection and water body placement - Vector data: - Road network from OpenStreetMap - Building footprints with height estimation - Land use classification (residential, commercial, industrial, park, water) #### 4.12.2 Neural 3D Reconstruction - Building mesh generation from satellite imagery + footprints: - Roof type classification (flat, gabled, hipped) from aerial imagery - Height estimation from shadow length or LiDAR data - Texture projection from satellite imagery onto generated meshes - Vegetation placement from land cover classification - Road surface generation from vector data with proper width, markings, intersections - Integration with `maya-genesis-urban` for enhanced procedural detail #### 4.12.3 Streaming Architecture - Cloud tile server: CDN-backed tile serving with edge caching - Predictive prefetching: fetch tiles along flight/drive direction before they're needed - Multi-resolution blending: seamless transition between zoom levels - Offline mode: pre-download regions for offline use - Custom overlay: artists can override satellite data with hand-crafted terrain in specific areas (hybrid real+authored worlds) **Technology:** TypeScript service `libs/maya/geospatial/` + Rust streaming integration in `maya-world`. --- ### 4.13 SSD-Optimized Asset Streaming **Reference Games:** Spider-Man 2, Ratchet & Clank: Rift Apart (PS5), Forspoken (DirectStorage) **What It Is:** Modern NVMe SSDs can deliver 5-7 GB/s, but traditional I/O paths through the OS and CPU bottleneck throughput. DirectStorage (Windows) and the PS5's custom I/O complex bypass the CPU entirely — compressed assets are read from NVMe directly into GPU memory, decompressed on-GPU, and made available to shaders without touching main RAM. This enables Spider-Man 2's instant fast travel and Ratchet & Clank's portal-based world switching. **Gap:** Phase 40.1.2 covers world streaming and phase 40.2.3 covers mesh streaming, but no task addresses the I/O path itself — DirectStorage integration, GPU decompression, or the SSD-optimized data layouts required to exploit modern storage hardware. **Proposed Feature Set:** #### 4.13.1 DirectStorage Integration - Windows DirectStorage API integration: - Bypass CPU for storage→GPU transfers - GPU decompression of GDeflate-compressed assets - Submit read requests with GPU fence synchronization - Custom I/O on Linux: - io_uring for async I/O with minimal system call overhead - Custom GPU decompression via compute shaders - Memory mapping for large asset files with page-aligned access #### 4.13.2 Asset Data Layout - Asset files organized for sequential SSD reads: - Colocate assets used together (same world partition, same streaming chunk) - Avoid seek patterns: streaming chunks stored contiguously - Compression: LZ4 for CPU path (fast decompression), GDeflate for GPU path - Streaming priority system: - Priority 0: immediately visible geometry and textures - Priority 1: soon-to-be-visible (based on camera velocity prediction) - Priority 2: nearby but occluded - Priority 3: prefetch for likely future areas - Memory budget management: - GPU memory budget for streamed assets (textures, meshes) - System memory budget for metadata and decompression staging - Eviction policy: LRU with priority weighting #### 4.13.3 Instant Transition Support - Portal system: pre-stream destination world partition while transition animation plays - Fast travel: stream destination area during loading vignette, target <2s load time on NVMe - Level transition: old world evicted and new world streamed simultaneously **Technology:** Rust integration in `maya-resource` and `maya-world` crates. --- ### 4.14 Mesh Shaders, Work Graphs & DXR 1.2 **Reference Games:** Fortnite (UE5 Nanite uses mesh shaders on supported HW), Cyberpunk 2077 (RT Overdrive uses DXR 1.2 extensions) **What It Is:** Three cutting-edge GPU pipeline features: 1. **Mesh Shaders** replace the traditional vertex/geometry pipeline with task shaders (amplification) and mesh shaders (geometry generation) operating on meshlets — compact clusters of vertices. This enables fine-grained GPU-side LOD selection, culling, and procedural geometry generation. 2. **Work Graphs** (DirectX 12 SM 6.8) allow GPU shaders to schedule additional GPU work without CPU round-trips, enabling fully GPU-driven rendering pipelines where the GPU autonomously decides what to render. 3. **DXR 1.2** introduces Opacity Micromaps (up to 2.3x faster alpha-tested geometry like foliage in RT) and Shader Execution Reordering (up to 2x faster divergent ray tracing). **Gap:** Phase 40.2.1 mentions "GPU-driven rendering pipeline" and "indirect draw call batching" but doesn't specifically address mesh shaders, work graphs, or DXR 1.2 extensions. Phase 72.1 covers neural rendering but not these lower- level GPU pipeline advances. **Proposed Feature Set:** #### 4.14.1 Mesh Shader Pipeline - Meshlet generation: preprocess source meshes into meshlets (64-128 vertices, 124 triangles per meshlet — hardware optimal sizes) - Meshlet data structure: vertex indices, primitive indices, bounding sphere, normal cone for backface culling - Task shader: per-meshlet-group amplification stage — performs frustum culling, occlusion culling, LOD selection, then emits mesh shader workgroups - Mesh shader: generates per-meshlet vertices and primitives, outputs to rasterizer - Fallback: non-mesh-shader path using traditional vertex pipeline for hardware without support - Integration with Nanite-class virtualized geometry: mesh shaders process Nanite clusters natively #### 4.14.2 Work Graphs - Work graph definition: DAG of GPU nodes that can spawn child work items - Rendering use cases: - GPU-side LOD selection spawns appropriate render work - Decal rendering: GPU identifies surfaces needing decals, spawns decal rendering work - Light culling → shadow rendering → illumination as GPU-autonomous pipeline - Fallback: indirect dispatch chain for hardware without work graph support #### 4.14.3 DXR 1.2 Integration - Opacity Micromaps (OMM): - Pre-build OMM data for all alpha-tested geometry (foliage, fences, grates) - Integrate OMM into BLAS (Bottom-Level Acceleration Structure) build - Measure and verify 2x+ speedup for RT shadows through foliage - Shader Execution Reordering (SER): - Enable SER for all ray tracing shaders - Reorder hit/miss shader execution by material type for coherence - Measure divergent RT performance improvement - Cooperative Vectors (SM 6.9): integration with Phase 72.1 neural rendering **Technology:** Integrated into `maya-renderer` with feature-flag paths. --- ### 4.15 Advanced Skin, Eye & Hair Rendering **Reference Games:** The Last of Us Part II, Hellblade II, Cyberpunk 2077, UE5 MetaHuman **What It Is:** Photorealistic human rendering requires three specialized subsystems beyond standard PBR: 1. **Skin:** Dual-lobe subsurface scattering with separate profiles for epidermis and dermis layers. Micro-detail from pore normal maps. Blood flow simulation affecting skin color (blushing, pallor). Wrinkle maps activated by facial expression. 2. **Eyes:** Multi-layer rendering with sclera, iris, pupil, cornea, and tear film. Corneal refraction creates parallax on the iris. Caustic patterns from light entering the eye. Pupil dilation responding to light levels. 3. **Hair:** Strand-based rendering where individual hair strands (50,000- 100,000 per head) are simulated for physics and rendered with anisotropic specular models (Marschner model). TressFX (AMD) and HairWorks (NVIDIA) are industry references. **Gap:** Phase 40.2.5 mentions subsurface scattering (40.2.5.5), hair rendering (40.2.5.9), and eye rendering (40.2.5.10) as single line items within the materials section. These require dedicated subsystems with far more depth than a material shader — they involve geometry generation (hair strands), physics simulation (hair/fur dynamics), and specialized rendering pipelines. **Proposed Feature Set:** #### 4.15.1 Advanced Skin Rendering - Separable subsurface scattering (sSSS): - Screen-space blur in multiple passes with different kernel widths for epidermis and dermis - Configurable scattering profiles per skin type (light, medium, dark skin) - Transmittance through thin geometry (ears, nostrils, fingers against bright light) - Micro-detail: - Pore normal maps at high resolution (4K+) blended with base normals - Micro-wrinkle system: wrinkle maps activated/deactivated by FACS blend shapes - Sweat/oil layer: dynamic specular increase under stress/heat - Blood flow simulation: - Subsurface color shift based on emotional state (anger → redness, fear → pallor) - Exertion flush (cheeks, neck, chest during physical activity) - Bruising over time (impact → redness → purple → yellow → healed) - Peach fuzz: fine facial hair rendered as thin strand layer catching rim light #### 4.15.2 Advanced Eye Rendering - Multi-layer eye model: - Sclera: white of eye with vein detail texture, slight SSS - Iris: parallax-mapped iris with depth, fibers visible at close range - Pupil: dilates/contracts based on ambient light level (animated) - Cornea: refractive dome over iris creating parallax shift at viewing angles - Tear film: wet specular layer with occasional tear formation - Eye caustics: light entering cornea creates caustic highlight on iris - Ambient occlusion: upper eyelid casts shadow on eye surface - Eye movement: micro-saccades during fixation, smooth pursuit tracking, reflexive blink at 15-20 blinks/minute - Bloodshot/tired: overlay vein intensity based on character fatigue state #### 4.15.3 Strand-Based Hair & Fur - Hair strand generation: - Root placement from scalp density map (guide strands + interpolated strands) - Per-strand shape: Bezier or Catmull-Rom curve with curl, wave, length variation - Strand count: 30,000-100,000 for head hair, LOD reduces count with distance - Hair physics: - Mass-spring or position-based dynamics per strand - Strand-strand collision (prevent interpenetration) - Head collision (hair stays on head) - Wind response (§4.9) with per-strand force sampling - Inertia: hair continues moving when head stops (follow-through) - Hair rendering: - Marschner hair shading model (R, TT, TRT lobes for specular) - Deep opacity maps for self-shadowing - Per-strand ambient occlusion - Transparency sorting via per-pixel linked lists or OIT - Fur rendering: - Shell method for short fur at distance (layered alpha shells) - Strand method for close-up fur detail - Species-specific fur patterns (tabby stripes, dalmatian spots) **Technology:** Rust crate `maya-character-rendering` with specialized shaders. --- ### 4.16 GPU Particle System (Niagara-Class) **Reference Games:** All modern AAA titles — Unreal's Niagara, Unity's VFX Graph **What It Is:** Modern VFX systems run entirely on the GPU, simulating and rendering millions of particles per frame. Niagara (UE5) uses a data-driven graph where artists create custom particle behaviors through node connections rather than code. Particles can interact with physics, lighting, and each other. GPU simulation enables effects impossible on CPU: fluid-like fire, volumetric smoke, millions of sparks. **Gap:** No task in any phase addresses particle systems. Phase 40.2.6 mentions post-processing effects, and Phase 40.3 mentions fluid simulation, but there is no VFX/particle system for rendering fire, smoke, sparks, dust, blood, magic effects, weather particles, or any other game visual effect. **Proposed Feature Set:** #### 4.16.1 GPU Particle Simulation - Particle data stored in GPU buffers (position, velocity, age, size, color, custom attributes) - Compute shader simulation: update all particles in parallel per frame - Emitter types: - Point, sphere, box, cone, mesh surface, skeletal mesh socket, curve/spline - Burst (emit N particles once) and rate (emit N particles per second) - Particle modules (composable simulation behaviors): - **Forces:** gravity, wind (from §4.9), drag, turbulence noise, vortex, attraction/repulsion points - **Collision:** scene depth buffer collision, bounce, stick, slide, kill - **Sizing:** size over lifetime curve, random size variation - **Color:** color over lifetime gradient, random color variation - **Rotation:** spin rate, alignment to velocity - **Velocity:** initial velocity (random in cone), velocity over lifetime - **Noise:** curl noise for turbulent motion, simplex noise displacement - **Interaction:** particle-particle forces (flocking, repulsion), particle- character interaction - **Strips/trails:** connected particle trails for ribbon effects (sword swipe, bullet tracer, magic trail) - **Events:** particle death triggers (spawn child particles on death = sub- emitters) #### 4.16.2 Particle Rendering - Render modes: - Billboard (camera-facing quad) with sprite animation - Mesh particles (full 3D mesh per particle, GPU instanced) - Ribbon/trail (connected strips between sequential particles) - Volumetric (raymarched volume per particle for smoke/fog) - Light (each particle emits dynamic light) - Material integration: particles use standard material system with custom parameters - Sorting: distance-sorted for transparency, per-pixel linked lists for OIT - Lighting: particles receive scene lighting (lit particles for smoke/dust) or are unlit (fire, magic) - Shadows: large particles can cast and receive shadows - Distortion: heat haze distortion effect from particle screen-space refraction #### 4.16.3 VFX Graph Editor - Node-based visual editor for creating particle effects without code - Module library: drag-and-drop simulation modules - Preview: real-time preview in editor viewport - Template library: fire, smoke, explosion, rain, snow, magic, blood, sparks, dust, waterfall spray, fireflies, volumetric fog patch - LOD: particle count/quality scaling with distance and performance budget **Technology:** Rust crate `maya-vfx` with compute shaders and material system integration. --- ### 4.17 Seasonal System & Procedural Weathering **Reference Games:** Forza Horizon 5 (seasonal cycles), AC Shadows (dynamic seasons), RDR2 (weather aging) **What It Is:** AC Shadows introduces dynamic seasons — the same environment transitions through spring cherry blossoms, summer foliage, autumn colors, and winter snow, affecting gameplay, visibility, and aesthetics. Separately, procedural weathering simulates the aging of materials over time: rust accumulating on metal, paint peeling, moss growing on stone, dirt accumulating in crevices. **Gap:** Phase 40.1.3 mentions "seasonal time progression" as a single line item in the time system. No task addresses the rendering implications of seasons (vegetation color change, snow accumulation, frozen water), the gameplay implications (seasonal NPC behaviors, seasonal wildlife migration, seasonal crops), or procedural material weathering. **Proposed Feature Set:** #### 4.17.1 Seasonal Rendering - Vegetation season response: - Spring: new growth, bright green, flowers/blossoms (particle effects) - Summer: full green, dense foliage, maximum grass height - Autumn: color palette shift (green → yellow → orange → red → brown), leaf fall particle system - Winter: bare branches (deciduous), snow accumulation on branches (evergreen), reduced grass - Season transition: gradual blend over in-game days, not instant switch - Snow accumulation: - Snow depth map accumulating over winter based on precipitation - Snow coverage on upward-facing surfaces (rooftops, branches, rocks) - Melting in spring: gradual depth reduction, melt-water rivulets, exposed patches on sun-facing slopes first - Frozen water: lakes and rivers freeze in winter (walkable ice surface, fishing through ice holes) - Ground frost: morning frost texture overlay in cold weather #### 4.17.2 Seasonal Gameplay - Seasonal wildlife: migration, hibernation, breeding seasons (§4.4) - Seasonal NPC activities: farming seasons, festival events, clothing changes - Seasonal traversal: frozen lakes create new paths, snow slows movement, spring floods block paths - Seasonal crops: if farming/gardening exists, growth cycles tied to seasons - Day length variation: shorter days in winter, longer in summer (affects lighting, NPC schedules) #### 4.17.3 Procedural Weathering - Material aging system: - Time-based accumulation of weathering effects - Rust: spreads from edges/scratches on metal surfaces - Moss/lichen: grows on north-facing stone surfaces in humid biomes - Dirt/grime: accumulates in crevices, runoff streaks from rain - Paint peel: paint chips and peels from exposed surfaces - Wood rot: wooden structures darken and soften over time - Weathering maps: artists paint weathering susceptibility maps, system applies procedural effect over time - Dynamic weathering: player-caused damage creates weathering seed points (scratch on metal → rust starts there) - Maintenance: repaired/cleaned surfaces reset weathering progress **Technology:** Material system extensions in `maya-renderer`, world state tracking in `maya-world`. --- ### 4.18 Facial Performance Capture Pipeline **Reference Games:** The Last of Us Part II, Hellblade II, UE5 MetaHuman Animator, Cyberpunk 2077 **What It Is:** Epic's MetaHuman Animator captures actor performance via iPhone or stereo head-mounted camera and retargets it to MetaHuman characters with 250+ blend shapes. Convai's NeuroSync automatically drives these blend shapes for AI NPCs. This pipeline is essential for AAA narrative games where character emotion drives the story. **Gap:** Phase 40's maya-embodiment mentions "facial FACS" and "lip sync" but no task covers the capture-to-game pipeline: camera-based facial tracking, blend shape solving, retargeting to different character rigs, or integration with AI-driven lip sync for dynamically generated dialogue. **Proposed Feature Set:** #### 4.18.1 Facial Capture - iPhone ARKit face tracking integration: - 52 ARKit blend shape coefficients captured at 60fps - Network streaming from capture device to engine - Recording to animation clip for offline use - Stereo head-mounted camera (HMC) support: - Higher-fidelity capture for cinematic sequences - Per-vertex face tracking (not just blend shapes) - Solve to FACS blend shapes: - Map capture data to 68+ Action Unit (AU) blend shapes - Handle AU combinations (smile + brow raise = different from either alone) - Jaw, tongue, and eye tracking channels #### 4.18.2 Retargeting - Source-to-target retargeting: map captured performance to any character rig - Proportional correction: account for different facial proportions (wide face → narrow face) - Style transfer: exaggerate or dampen captured performance for stylized characters - Cross-species retargeting: human performance → creature face (stretch mapping) #### 4.18.3 AI-Driven Facial Animation - Viseme generation from phoneme stream (text-to-speech or speech recognition → visemes → blend shapes) - Emotion-driven expression: `maya-souls` emotion state → appropriate facial expression overlay - Procedural micro-expressions: blink rate, gaze shift, subtle emotional leakage - Integration with dialogue system (Phase 72.7): dialogue emotion tags trigger facial presets **Technology:** Rust crate `maya-facial-capture` + TypeScript pipeline `libs/maya/facial-pipeline/`. --- ### 4.19 Advanced Haptic Feedback System **Reference Games:** Astro Bot (DualSense showcase), Returnal, GT7 **What It Is:** The PS5 DualSense controller's adaptive triggers provide variable resistance (simulate bow draw, trigger pull, gear shift) and HD rumble provides precise localized vibration (feel individual raindrops, terrain surface texture through the controller). Xbox's impulse triggers provide similar capabilities. These haptic systems transform the controller from a button box into a sensory feedback device. **Gap:** Phase 72.27 covers input action mapping but mentions haptics only as a single line item (72.27.1.13). No task addresses the granularity required for compelling haptic design: per-surface feedback, adaptive trigger profiles, contextual rumble patterns, or the authoring tools needed. **Proposed Feature Set:** #### 4.19.1 Haptic Engine - Haptic effect definition system: - Waveform: sine, square, triangle, custom curve - Frequency, amplitude, duration, fade-in/fade-out - Spatial: left/right motor balance, trigger-specific - Layering: multiple simultaneous effects with priority - Platform abstraction: - DualSense: HD rumble (haptic motors), adaptive triggers (L2/R2 resistance profiles) - Xbox: impulse triggers (left/right trigger rumble), standard rumble motors - Nintendo Switch: HD rumble (linear resonant actuators) - Generic: standard dual-motor rumble fallback #### 4.19.2 Adaptive Trigger Profiles - Effect modes: - **Resistance:** constant resistance through trigger travel (e.g., brake pedal) - **Weapon trigger:** light pull then hard break at firing point - **Bow draw:** increasing resistance proportional to draw length - **Lock pick:** vibration at sweet spot, resistance at wrong angle - **Terrain feedback:** vibration pattern matching surface (rumble on gravel, smooth on asphalt) - **Gear shift:** resistance notch at each gear position - Dynamic adjustment: resistance changes in real-time based on game state (bow string tension decreases when fatigued, brake resistance increases as vehicle slows) #### 4.19.3 Contextual Haptic Events - Surface feedback: walking on wood vs stone vs metal vs grass produces distinct rumble patterns - Weather: rain creates subtle patter, wind creates directional pressure, thunder creates single sharp pulse - Combat: weapon impact recoil, getting hit (directional), blocking (resistance then release) - Vehicle: engine vibration (frequency matches RPM), road surface texture, collision impact - Environment: waterfall proximity rumble, machinery vibration, earthquake tremor **Technology:** Rust crate `maya-haptics` integrated with input system. --- ### 4.20 Photo Mode System **Reference Games:** Ghost of Tsushima, Spider-Man 2, Horizon Forbidden West, Cyberpunk 2077 **What It Is:** Photo mode has become a standard feature in AAA games. The world pauses, the camera is freed from the character, and the player is given tools to compose, light, filter, and capture stunning screenshots. Ghost of Tsushima's photo mode is considered best-in-class with wind direction control, particle density adjustment, and time-of-day scrubbing. **Gap:** No task in any phase addresses photo mode. **Proposed Feature Set:** #### 4.20.1 Camera Controls - Free camera: detach from character, fly freely within radius - Orbit camera: orbit around character/subject - Focal length: adjustable FOV (telephoto to wide-angle) - Focus distance: manual depth-of-field focus point with aperture control - Roll: camera tilt for Dutch angle compositions - Camera position save/load: store up to 10 camera positions #### 4.20.2 Scene Controls - Time of day: scrub time to change lighting (golden hour, blue hour, noon, night) - Weather override: select weather preset (clear, cloudy, rainy, foggy, stormy) - Wind direction and intensity (affects vegetation, particles) - Character pose: select from pose library, adjust expression - Character hide: toggle character visibility for landscape shots - NPC freeze: pause or resume NPC animation - Particle density: increase/decrease environmental particles #### 4.20.3 Post-Processing - Filters: film presets (cinematic, vintage, noir, high-contrast, desaturated) - Color grading: exposure, contrast, saturation, temperature, tint - Vignette: intensity and shape - Film grain: intensity and size - Borders: aspect ratio frames (2.39:1 cinematic, 1:1 square, 4:3 classic) - Stickers/stamps: logo placement, date stamp - Resolution: capture at higher resolution than display (supersampling) #### 4.20.4 Sharing - Screenshot capture to disk (PNG, JPEG with quality selection) - Metadata embed: location, time, character, camera settings - Social sharing integration (platform screenshot APIs) **Technology:** Rust module within `maya-renderer` or standalone `maya-photo- mode`. --- ### 4.21 Save System Architecture **Reference Games:** All open-world games — critical infrastructure **What It Is:** A comprehensive save system is fundamental to open-world games but rarely discussed as a feature. It encompasses quicksave, autosave, manual save slots, cloud save synchronization, save migration between game versions, and the serialization of massive world state including quest progress, inventory, NPC states, deformation data, ecology populations, and player progression. **Gap:** Phase 40.1.2 mentions "persistent world state serialization" as a single line item. Phase 72.8 and 72.9 mention save/load for quests and inventory respectively. No task addresses the unified save system architecture that ties all of these together. **Proposed Feature Set:** #### 4.21.1 Save Architecture - Save data schema: versioned, self-describing format with schema evolution support - Save components: - Player state: position, health, stats, abilities, progression - Inventory state: all items, equipment, crafting materials - Quest state: all quest stages, objective progress, choice history - World state: deformation data, moved/destroyed objects, placed items - NPC state: alive/dead, relationship values, last known positions - Ecology state: population counts, active migration events - Economy state: prices, shop inventories, player wealth - Time state: in-game date/time, weather state, season - Custom data: mod-added save data - Save compression: LZ4 for fast save/load, total target <50MB per save #### 4.21.2 Save Types - **Manual save:** player-initiated save to named slot (unlimited slots) - **Quicksave:** instant save to rotating quicksave slot (1 key press) - **Autosave:** triggered on milestone events (quest complete, area enter, before combat), rotating 3-5 autosave slots - **Checkpoint:** resume from last checkpoint on death (distinct from manual save) - **Profile save:** settings, key bindings, accessibility options (separate from game save) #### 4.21.3 Cloud Save - Platform cloud save integration (Steam Cloud, Xbox Cloud Save, PS Plus Cloud Storage) - Conflict resolution: when local and cloud saves diverge, offer choice (keep local, keep cloud, keep newer) - Cross-platform cloud save: unified save accessible from any platform (if cross-platform progression is enabled) - Bandwidth-efficient sync: delta upload (only changed bytes) #### 4.21.4 Save Migration - Version detection: save files carry schema version number - Migration chain: v1→v2→v3 migration functions applied in sequence - Forward compatibility: save system ignores unknown future fields gracefully - Backward compatibility: new game version always loads old saves **Technology:** Rust crate `maya-save-system` with platform-specific cloud backends. --- ### 4.22 Footstep & Surface Audio System **Reference Games:** RDR2, The Last of Us Part II, Horizon Forbidden West **What It Is:** Surface-aware audio means that footsteps on stone sound different from footsteps on wood, grass, gravel, mud, water, metal, and snow. RDR2 extends this to weight (heavy boots vs barefoot), speed (walk vs run vs sprint), and wetness (splashing in puddles). The system detects the surface material under each foot contact point and selects from material-specific audio banks with random variation to avoid repetition. **Gap:** Phase 72.28 covers audio middleware integration (Wwise/FMOD) and mentions "footstep surface detection" as a single example line. No task addresses the footstep system itself: surface detection raycasting, material audio banks, variation logic, or weight/speed modulation. **Proposed Feature Set:** #### 4.22.1 Surface Detection - Per-foot raycast: each foot IK contact point raycasts down to detect surface material - Material identification from: - Terrain material map (painted per-vertex or per-texture-layer) - Mesh material tag (wood floor, metal grate, stone tile) - Dynamic surface state (wet, frozen, muddy — from weather/deformation systems) - Water depth detection: shallow splash vs wade vs swim transition #### 4.22.2 Audio Selection - Per-material audio bank: 8-12 variations per material × per speed class - Speed classes: walk, jog, run, sprint, sneak - Modulation: - Volume: proportional to speed and weight - Pitch: slight random variation per step - Reverb: send to middleware reverb bus based on environment (indoor/outdoor/ cave) - Clothing audio layer: armor clink, cloth rustle, leather creak layered on footsteps - Equipment audio: backpack bounce, weapon jingle, coin purse - NPC footsteps: same system applied to NPCs, attenuated by distance #### 4.22.3 Environmental Surface Audio - Interaction sounds: grass rustle when walking through, leaf crunch in autumn, snow crunch in winter - Vehicle-surface sounds: tire-on-surface audio (screech on asphalt, crunch on gravel, squelch in mud) - Impact sounds: material-specific for dropped/thrown objects, body falls **Technology:** Integration layer between `maya-physics` (contact detection) and audio middleware (§72.28). --- ### 4.23 Dynamic Music Composition System **Reference Games:** RDR2 (interactive score), No Man's Sky (procedural), DOOM (intensity layers), Horizon Forbidden West (adaptive) **What It Is:** Beyond adaptive music (which Phase 72.22 covers), a dynamic composition system generates music in real-time from musical building blocks. No Man's Sky layers instruments and melodies procedurally based on planetary biome, time of day, and player action — no two listening sessions are identical. RDR2 uses interactive scoring where individual instrument stems are activated/deactivated and cross-faded based on game state. **Gap:** Phase 72.22 covers adaptive music with stinger triggers and cross- fading between stems. This proposal extends it to full procedural composition and generative music capabilities. **Proposed Feature Set:** #### 4.23.1 Procedural Music Generation - Musical element library: melodic phrases, chord progressions, rhythm patterns, bass lines tagged with mood/energy/genre - Rule-based composition: select and layer elements based on game state - Harmonic constraints: ensure generated combinations are musically coherent (key, tempo, consonance) - Phrase structure: 4/8/16 bar phrases with intro, development, climax, resolution - Variation generation: algorithmic variation of base phrases (transposition, rhythmic displacement, ornamentation) #### 4.23.2 Environmental Music - Biome themes: each biome has an instrument palette and harmonic language - Time-of-day adaptation: dawn = sparse/gentle, noon = open/bright, dusk = melancholic, night = sparse/mysterious - Weather influence: rain adds muted/minor elements, clear weather adds brightness - Interior/exterior: entering a building adds reverb and shifts to intimate instrumentation #### 4.23.3 Intensity System - Combat intensity: layers added as threat increases (percussion → brass → full orchestra) - Exploration wonder: crescendo when discovering new areas or vistas - Tension building: during stealth, subtle tension phrases with stingers on detection - Resolution: combat end → tension dissolve → return to exploration theme - Silence as tool: moments of deliberate musical absence for emotional impact **Technology:** Rust crate `maya-music-engine` with MIDI-like internal sequencing and sample playback through audio middleware. --- ### 4.24 Gameplay Framework Systems **Reference Games:** Various — these are standard AAA gameplay systems **What It Is:** Beyond the systems already covered in Phase 72 (dialogue, quests, inventory, economy), several core gameplay frameworks are needed for any AAA open-world game. These are game-design-level systems that sit between the engine and the game-specific logic. **Gap:** The following gameplay systems have no coverage in any existing phase: #### 4.24.1 Combat System Framework - Melee combat: light/heavy attack, combo chains, dodge, parry/block, riposte - Ranged combat: aim, fire, reload, weapon sway, recoil, bullet drop - Lock-on targeting: lock to nearest enemy, cycle targets, soft lock vs hard lock - Damage system: damage types (physical, fire, frost, poison, electric), resistance, vulnerability - Stamina/resource management: attacks consume stamina, block drains guard, recovery over time - Hit feedback: hit-stop (freeze frame on impact), screen shake, directional damage indicator, health flash - Execution/finisher system: contextual finishing moves based on enemy state #### 4.24.2 Stealth System - Light/shadow detection: character visibility based on lighting at position (shadow = hidden, light = exposed) - Sound propagation: actions produce noise at radius, NPCs within radius investigate - NPC awareness states: unaware → suspicious → alerted → searching → combat → return-to-patrol - Last known position: NPCs investigate where they last saw/heard the player - Stealth takedowns: context-sensitive silent elimination from behind/above - Distraction mechanics: thrown objects create noise at target location - Camouflage: hiding in vegetation, crowds, shadows, disguises - Detection meter: UI indicator showing how close to detection #### 4.24.3 Investigation/Scanner System - Detective vision / witcher senses / eagle vision mode: - Toggle visual filter highlighting interactable objects, tracks, clues - Object examination: zoom in on clues, rotate, inspect details - Track following: highlight footprints, blood trails, scent trails - Evidence collection: gather clues into case file - Deduction system: connect evidence to form conclusions - Environmental storytelling: arrangement of objects tells a story without dialogue #### 4.24.4 Companion AI System - Companion NPCs that follow the player and fight alongside - Autonomous combat: companions select targets, use abilities, take cover - Pathfinding: follow player through complex environments without getting stuck - Commands: player can issue simple orders (attack, defend, wait, follow, go-to) - Companion dialogue: contextual comments about environment, quests, combat - Relationship system: companion opinion of player changes based on decisions - Companion abilities: unique skills that complement player (healer, tank, ranged, stealth) - Companion inventory: shared or separate inventory management - Non-interference: companions should never block doorways, trigger traps, or alert enemies accidentally #### 4.24.5 Mount/Vehicle System - Mounting/dismounting: context-sensitive animation, running mount, emergency dismount - Mounted combat: melee and ranged combat while riding - Mount AI: horse/creature avoids obstacles, slows for terrain, can be called from distance (whistle) - Mount inventory: saddlebags with additional storage - Mount bonding: trust/loyalty system affecting mount responsiveness and behavior - Mount care: feeding, grooming, rest (if realistic survival elements present) - Mount damage: mount can be injured or killed, affecting gameplay #### 4.24.6 Swimming & Diving System - Swimming locomotion: surface swimming with stamina drain - Diving: underwater exploration with breath management (or oxygen equipment) - Underwater combat: limited combat capability while swimming - Underwater world: marine life, coral, shipwrecks, underwater caves - Water current: flow affects swimming speed and direction - Surfacing urgency: breath indicator, increasingly frantic animation as breath runs out - Waterlogged equipment: weapons may be less effective when wet #### 4.24.7 Settlement/Base Building - Structure placement: snap-to-grid or free placement of buildings and structures - Resource management: gather materials for construction - NPC assignment: assign NPCs to roles (guard, farmer, merchant, crafter) - Defense: build defenses against attacks (walls, turrets, traps) - Upgrades: improve buildings for better functionality - Settlement economy: production chains, trade routes, income generation - Cosmetic customization: decorations, furniture, landscaping #### 4.24.8 Survival Systems (Optional Module) - Hunger/thirst: food and water requirements with stat effects when neglected - Temperature: cold/hot environments affect health, require appropriate clothing - Sleep/fatigue: rest requirement, performance degradation when exhausted - Crafting integration: cook food, purify water, craft shelter - Hardcore mode toggle: enable/disable survival mechanics per player preference **Technology:** Rust crates within `libs/maya/engine-core/crates/` for performance-critical systems (combat, stealth detection), TypeScript libraries in `libs/maya/` for design-level systems (settlement, companion dialogue). --- ### 4.25 NPC Life Simulation Engine **Reference Games:** The Sims (needs-based AI), Dwarf Fortress (personality facets + values + goals), RDR2 (1200 actors, 80-page scripts), Oblivion/Skyrim (AI Packages), Watch Dogs Legion (play-as-anyone census), Shenmue (daily life), Stanford Generative Agents (LLM memory architecture) **What It Is:** A complete NPC autonomy system where every named NPC in the world has needs that decay, a personality that shapes decisions, emotions that fluctuate based on events, and memory that accumulates experiences. The Sims proved this architecture with its "object advertisement" pattern — objects broadcast utility, characters select based on weighted need scores. Dwarf Fortress extended it to 50+ personality facets, 17+ values, and long-term goals. The Stanford Generative Agents research (2023) showed that LLM-backed memory streams with retrieval scoring produce emergent social behavior (autonomously organizing a Valentine's Day party from a single seed). **Gap:** Phase 40 has `maya-souls` for LLM-powered NPC dialogue, and Phase 72.17 covers NPC scheduling as time-location tables. But no system addresses: - Need-based autonomous decision making (hunger, sleep, social, fun) - Multi-dimensional personality affecting behavior selection - Emotional state machines with mood buffers and mental break thresholds - Long-term memory with importance scoring and reflection synthesis - The "object advertisement" pattern for scalable world interaction **Proposed Feature Set:** #### 4.25.1 Needs System (Sims-Inspired) - **Core Needs** with continuous 0-100 values and per-need decay rates: - **Hunger:** decays ~12/hr, satisfied by eating (food quality affects satisfaction amount) - **Energy:** decays ~8/hr when active, restored by sleeping (bed quality matters) - **Hygiene:** decays ~6/hr, restored by bathing - **Bladder:** decays ~10/hr, restored by toilet use - **Social:** decays ~4/hr, restored by conversation and group activities - **Fun/Entertainment:** decays ~5/hr, restored by entertainment objects - **Comfort:** environmental — affected by furniture, shelter, temperature - **Safety:** affected by danger proximity, crime history, war state - **Extended Needs** (activated by personality traits or context): - Knowledge (scholars), Martial (warriors), Craft (artisans), Nature (rangers), Devotion (clergy), Wealth (merchants) - **Need-Driven Behavior Selection:** - Each world object/activity advertises need fulfillment values - NPC scores all available activities: `score = Σ(need_deficit × advertisement_value × personality_weight × proximity_factor)` - Selection: weighted random from top-3 scoring options (not always optimal — prevents robotic behavior, as The Sims deliberately designed) - Maslow-inspired priority curves: physical needs spike when deficient, higher-order needs only matter when physical needs are satisfied #### 4.25.2 Personality System (NEO PI-R / Dwarf Fortress Inspired) - **Personality Facets** (30+ dimensions, scored 0-100): - Openness: Imagination, Artistic Interest, Adventurousness, Intellect, Curiosity - Conscientiousness: Self-Discipline, Orderliness, Dutifulness, Achievement-Striving - Extraversion: Gregariousness, Assertiveness, Excitement-Seeking, Cheerfulness, Activity Level - Agreeableness: Trust, Altruism, Cooperation, Modesty, Sympathy - Neuroticism: Anxiety, Anger, Depression, Self-Consciousness, Vulnerability - Additional: Bravery, Greed, Humor, Patience, Stubbornness - **Values** (15+ beliefs, scored -100 to +100): - Tradition, Family, Knowledge, Craftsmanship, Martial Prowess, Commerce, Nature, Law, Freedom, Power, Art, Religion, Community, Wealth, Honor - **Goals** (1-3 long-term aspirations per NPC): - Master a Skill, Start a Family, Accumulate Wealth, Create a Great Work, Gain Political Power, Find True Love, See the World, Protect the Innocent, Achieve Revenge - **Trait Interactions:** - High Gregariousness + Low Self-Discipline = party-goer who neglects work - High Anxiety + Low Bravery = NPC who flees from any danger - High Greed + Low Altruism = NPC who steals and hoards - Personality generates unique behavioral signatures visible to observant players #### 4.25.3 Emotional State System - **Mood Bar** (0-100 with target and drift): - Current mood drifts toward mood target at configurable rate - Mood target is sum of all active thoughts (positive and negative) - Extreme moods trigger special behaviors (mental breaks, celebrations) - **Thought System:** - Thoughts are time-limited mood modifiers: `(source, strength, duration)` - Examples: "Friend died" (-25, 30 days), "Ate excellent food" (+8, 1 day), "Slept in the cold" (-10, 2 days), "Received compliment" (+5, 8 hours) - Thoughts stack but cap per category (max -50 from social, etc.) - **Mental Break Thresholds** (RimWorld-inspired): - Mood < 20%: minor break (insult random NPC, binge eat, wander aimlessly) - Mood < 10%: major break (start fight, flee settlement, refuse to work) - Mood < 5%: extreme break (psychotic rage, catatonia, arson) - Break type selected based on personality (high Anger → fight, high Anxiety → flee, high Depression → catatonia) - **Emotional Contagion:** - Nearby NPCs in good/bad moods influence each other - Group panic: one NPC fleeing can trigger others to flee - Group celebration: joy spreads in social settings #### 4.25.4 Memory System (Stanford Generative Agents Inspired) - **Memory Stream:** sequential log of NPC experiences stored as structured records: - `(timestamp, location, event_type, participants, description, importance)` - **Memory Retrieval Scoring:** - `score = α_recency × recency + α_importance × importance + α_relevance × relevance` - Recency: exponential decay (0.995 per game-hour since last access) - Importance: rated 1-10 (routine tasks = 1, life-changing events = 8-10) - Relevance: semantic similarity to current query context - **Memory Capacity:** NPCs retain last 200-500 memories; oldest/lowest- importance memories are pruned (not forgotten — compressed into reflections) - **Reflection System:** - Triggered when cumulative new importance exceeds threshold (~150 points) - NPC "reflects" on recent memories, extracting high-level insights - Reflections become new memories at higher abstraction level - Forms a reflection tree: observations → insights → beliefs - Example: multiple "player stole from me" memories → reflection "player is a thief, avoid them" → behavioral change - **Player-Specific Memory:** - NPCs remember player's past interactions: gifts, crimes, help, insults - Memory affects disposition, dialogue, willingness to trade/help - NPCs share memories through gossip (§4.35) **Technology:** Rust crate `maya-npc-life` for needs/personality/mood, with `maya-souls` integration for LLM-backed memory retrieval and reflection. TypeScript library `libs/maya/npc-database/` for species/personality template database. --- ### 4.26 NPC Social & Relationship System **Reference Games:** Dwarf Fortress (friendship → romance → marriage → children), RimWorld (compatibility scores, social fights), Stardew Valley (heart meters), Crusader Kings 3 (dynasty politics), Watch Dogs 2 (fuzzy logic social AI) **What It Is:** Every NPC has relationships with other NPCs — not just with the player. Dwarves in Dwarf Fortress form friendships through proximity, develop romantic interest based on personality compatibility, marry, have children, and suffer severe mood debuffs when loved ones die. This creates organic social networks where events cascade through relationship graphs. **Gap:** Phase 72.17 (NPC scheduling) doesn't address inter-NPC relationships. Maya-souls handles LLM dialogue but not the underlying relationship data model and social mechanics. **Proposed Feature Set:** #### 4.26.1 Relationship Graph - Every NPC pair has a relationship record: - **Opinion** (-100 to +100): overall feeling toward the other - **Familiarity** (0-100): how well they know each other - **Relationship type:** stranger, acquaintance, friend, close friend, best friend, rival, enemy, romantic interest, partner, spouse, parent, child, sibling - **Opinion Modifiers:** - Shared values alignment (§4.25.2): +1 to +20 per shared value - Conflicting values: -1 to -20 per opposing value - Gift giving: +5 to +30 per gift (diminishing returns) - Insult/slight: -10 to -30 - Witnessed crime: -30 to -80 - Saved life: +40 to +60 - Betrayal: -50 to -80 - Natural decay: opinion drifts toward 0 over time without reinforcement #### 4.26.2 Social Interactions - **Positive interactions** (probability weighted by personality): - Deep talk: +2-3 opinion each, cap at +10 per conversation - Compliment: +5 opinion - Share meal: +3 opinion - Work together: +1 opinion per hour - Give gift: +5 to +30 based on gift quality and recipient preferences - Help in need: +10 to +30 - **Negative interactions:** - Insult: -15 opinion, chance of escalation based on Anger facet - Slight (unintentional): -5 opinion - Argument: -10 to -20 opinion (triggered by opposing values in conversation) - Gossip about: -5 to -15 (if target learns of it) - Physical altercation: -30 to -50 opinion, potential injury - **Romantic interactions** (requires minimum friendship + personality compatibility + attraction): - Flirt: +3 romantic interest if compatible, -5 if not - Confess feelings: relationship upgrade or rejection (-20 embarrassment) - Date: +10 opinion, +5 romantic interest - Proposal: accepted if opinion > 70 and romantic interest > 80 - Marriage: permanent bond, shared household, strong mood effects - Breakup: severe negative mood for both parties #### 4.26.3 Family & Dynasty - Marriage produces children (probability based on age, health) - Children inherit personality facets from parents (±20 random variation) - Children acquire traits during growth (0-16 game-years), shaped by upbringing - Family death causes severe grief (spouse > child > parent > sibling > friend) - Inheritance: property and wealth transfer on death - Family feuds: harming one family member creates enemies of the entire family #### 4.26.4 Social Network Effects - Cliques form naturally from high-familiarity groups - Introduction system: NPCs introduce friends to each other - Social isolation causes mood penalties (unmet Social need) - Community leaders emerge (highest average opinion across settlement) - Social outcasts emerge (lowest average opinion) **Technology:** Rust crate `maya-social` integrated with `maya-npc-life`. --- ### 4.27 NPC Occupation & Work System **Reference Games:** Skyrim (guard, blacksmith, innkeeper, farmer schedules), Dwarf Fortress (labor assignments), The Sims 3 (career tracks), Watch Dogs Legion (profession-based daily routines), Shenmue (shop owner schedules) **What It Is:** Every NPC has a job that determines a large portion of their daily schedule, skills, income, social status, and available interactions. A blacksmith wakes early, opens the forge, hammers all day, closes shop, visits the tavern, and sleeps. A guard patrols routes, inspects travelers, and rotates shifts. A farmer plants in spring, tends in summer, harvests in autumn, and repairs in winter. Jobs aren't just labels — they produce visible, gameplay- relevant behavior. **Gap:** Phase 72.17 covers NPC scheduling (time-location tables) but treats occupation as a schedule input rather than a system. No task addresses job mechanics: what a blacksmith actually does at the forge, skill progression, production of goods, economic output, career changes, hiring/firing, or unemployment. **Proposed Feature Set:** #### 4.27.1 Occupation Database - **Occupation definition schema:** - Name, category (craft, trade, service, labor, military, clergy, crime) - Required skills and minimum skill levels - Schedule template (start time, end time, break times, days off) - Workplace type (shop, farm, guard post, temple, mine, workshop) - Production outputs (blacksmith → weapons/tools, farmer → crops, baker → bread) - Income level (determines housing quality, clothing, social status) - Social class mapping (nobility, merchant class, working class, peasant) - Available promotions / career progression - **Occupation categories:** - **Craftspeople:** blacksmith, carpenter, tailor, potter, tanner, jeweler, mason, armorer, bowyer, cobbler, glassblower, candlemaker - **Merchants:** shopkeeper, traveling merchant, market vendor, innkeeper, tavern keeper, money lender - **Agriculture:** farmer, rancher, fisherman, beekeeper, vintner, miller, shepherd - **Service:** barber, healer, cook, stable hand, gravedigger, courier, lamplighter, chimney sweep - **Military:** town guard, soldier, knight, mercenary, bounty hunter, caravan guard - **Clergy/Scholars:** priest, monk, scholar, librarian, teacher, scribe - **Entertainment:** bard, actor, dancer, juggler, street performer - **Criminal:** pickpocket, fence, smuggler, assassin, beggar (optional underworld) - **Governance:** mayor, tax collector, magistrate, town crier #### 4.27.2 Work Behavior - NPCs physically perform work actions at their workplace: - Blacksmith: operate anvil and forge, produce items on schedule - Farmer: plow fields (spring), plant seeds, water crops, harvest (autumn) - Guard: patrol route with stops, inspect travelers, respond to crimes - Merchant: unlock shop, arrange wares, serve customers, restock from supply - Baker: prepare dough, operate oven, sell bread from counter - Work produces visible economic output: - Goods appear in shop inventory over time - Crops grow in fields and are physically harvested - Ore is mined and transported to smelter - Work skill progression: NPCs improve at their craft over time, producing higher-quality goods - Work breaks: NPCs eat lunch, chat with coworkers, take rest breaks #### 4.27.3 Career Dynamics - **Hiring:** NPC employers seek workers based on skill match and reputation - **Firing:** Poor performance, crimes, or economic downturn causes job loss - **Career change:** Unemployed NPCs seek new work based on available skills - **Apprenticeship:** Young NPCs learn trades from masters - **Retirement:** Elderly NPCs reduce work hours, eventually stop working - **Unemployment:** Jobless NPCs exhibit different daily behavior (wander, seek work, beg, turn to crime based on personality) - **Shift work:** Some jobs have multiple shifts (day guard, night guard) #### 4.27.4 Player Interaction with NPC Jobs - Player can commission work (order weapons from blacksmith, request specific goods) - Player hiring: recruit NPCs for player-owned businesses (§4.24.7 settlement) - Player impact: destroying a workplace eliminates jobs, causing economic disruption - Reputation affects service: hostile NPCs refuse service, friendly NPCs offer discounts **Technology:** TypeScript library `libs/maya/npc-occupations/` with occupation database, integrated with `maya-npc-life` needs/schedule system. --- ### 4.28 City Infrastructure Simulation **Reference Games:** Cities: Skylines (traffic, transit, utilities), GTA V (traffic systems), Shenmue (bus schedules), Cyberpunk 2077 (city districts) **What It Is:** A living city requires more than NPCs walking around. It requires functional infrastructure: traffic that flows, public transit that runs on schedules, emergency services that respond to incidents, districts with distinct personalities that change behavior by time of day, and visible utility systems that make the city feel like a functioning organism. **Gap:** No existing phase addresses city infrastructure simulation. Phase 72.17 covers individual NPC schedules but not the emergent city-level systems that arise from thousands of NPCs interacting with infrastructure. **Proposed Feature Set:** #### 4.28.1 Traffic Simulation - **Road network graph:** intersections as nodes, road segments as edges with lane count, speed limit, and direction - **Vehicle pathfinding:** - NPC vehicles calculate routes considering distance, speed, and congestion - Route calculated once on trip start, re-route on road changes - Multiple vehicle types: car, truck, bus, motorcycle, bicycle, emergency - **Traffic flow:** - Vehicles maintain following distance based on speed - Lane selection based on upcoming turns (early lane commitment, as in Cities: Skylines) - Intersection logic: traffic lights with timing cycles, yield/stop signs, right-of-way rules - Rush hour patterns: residential → commercial in morning, reverse in evening - Congestion emergence: popular routes develop realistic backups - **Vehicle behavior:** - Speed governed by road limits, congestion, weather conditions - Anticipation of curves, intersections, pedestrian crossings - Horn honking in congestion (audio), aggressive drivers cut in line - Accident events: random vehicle collisions create temporary blockages, trigger emergency response - **Performance:** vehicles simulated ~4 times/second (Cities: Skylines approach), rendering interpolates between simulation frames #### 4.28.2 Public Transportation - **Bus system:** - Routes defined as ordered stop sequences with schedule - Bus NPCs drive routes, stop at each stop for passengers - NPC pedestrians wait at bus stops, board/alight based on destination - Schedule deviations from traffic congestion - **Rail/subway:** - Fixed routes with stations, timetabled departures - Underground stations as connected interior zones - Train capacity affects crowding (standing vs sitting NPCs) - **Taxi/rideshare:** - Hailable taxis cruise streets or wait at stands - Player and NPCs can hail for point-to-point transport - **Integration with NPC pathfinding:** - NPCs evaluate walk vs drive vs transit for each trip - Weighted by: time, cost (if economy simulated), comfort, weather #### 4.28.3 Emergency Services - **Police:** - Patrol routes through city districts - Respond to crime reports from witnesses (§4.30) - Chase and apprehend criminals (player or NPC) - Police density varies by district (high crime = more patrols) - **Fire department:** - Respond to fire events (from chemistry engine §4.3 or random) - Fire trucks navigate to fire location, firefighter NPCs extinguish - Building damage from uncontrolled fires - **Medical:** - Ambulances respond to injury events - Transport injured NPCs to hospital locations - Hospital as healable location for player and NPCs #### 4.28.4 District Personality - **District types** with distinct NPC populations, density, and behavior: - Financial district: business attire NPCs, busy 9-5, dead at night - Entertainment district: active evening/night, bars, clubs, street performers - Residential: families, children, quiet streets, active morning/evening - Market/bazaar: vendors, shoppers, noise, density peaks midday - Industrial: workers, trucks, noise, sparse pedestrians - Slums: poverty, crime, fewer services, distinct clothing/behavior - Government: guards, officials, restricted access areas - Academic: students, scholars, libraries, campus feel - **Time-of-day transitions:** smooth density/NPC-type changes between day and night per district - **Weather response by district:** rain empties outdoor areas, fills indoor spaces **Technology:** Rust crate `maya-city-sim` for traffic and pathfinding, TypeScript `libs/maya/city-infrastructure/` for route/schedule definitions. --- ### 4.29 Dynamic Agent Economy **Reference Games:** BazaarBot (open-source economics engine), Dwarf Fortress (trade caravans), Mount & Blade (regional trade), Kenshi (autonomous faction economies), Stardew Valley (seasonal market) **What It Is:** Instead of fixed shop prices, a dynamic economy uses agent- based simulation where every merchant and consumer has price beliefs that evolve based on trade outcomes. When a merchant sells bread at 5 gold and it sells instantly, they raise their price belief. When it doesn't sell, they lower it. Supply chains connect producers to merchants — a disrupted grain supply raises bread prices across the region. Trade caravans physically transport goods between settlements, vulnerable to bandits. **Gap:** Phase 72.18 covers a "Game Economy & Virtual Economy System" with 15 tasks but focuses on currency, stores, and player-facing economy. No task addresses the agent-based simulation where NPC merchants autonomously set prices, producers supply goods, supply chains function between settlements, or economic disruption cascades from player actions. **Proposed Feature Set:** #### 4.29.1 Price Belief System (BazaarBot-Inspired) - Every merchant agent maintains a price belief as a **numerical range** (low, high) for each commodity they trade - When creating buy/sell orders, agents randomly select from their belief range - **After successful trade:** range tightens (confidence increases) - **After failed trade:** range expands (confidence decreases) - **Market observation:** beliefs shift toward observed clearing prices - Result: prices emerge organically from agent interactions, not designer fiat #### 4.29.2 Supply Chains - **Production chain modeling:** - Farmer → grain → miller → flour → baker → bread - Miner → ore → smelter → ingots → blacksmith → weapons - Shepherd → wool → spinner → yarn → weaver → cloth → tailor → clothing - **Physical transport:** - Goods must be physically moved between production stages - NPC workers or caravans transport goods along trade routes - Transport time creates natural supply delay - Route disruption (bandit attack, road destroyed) breaks supply chain - **Cascading effects:** - Farm destroyed → grain shortage → flour price rises → bread becomes expensive → NPC hunger increases → social unrest - Mine depleted → ore shortage → weapon prices rise → military weakness - Player completing trade quest → new route opens → prices stabilize #### 4.29.3 Inter-Settlement Trade - **Trade caravans:** - NPC merchants travel between settlements carrying trade goods - Caravan composition: merchant + guards + pack animals - Route determined by profit opportunity (buy low, sell high between regions) - Caravan visible in the world, interactable, attackable - **Regional price variation:** - Coastal towns: cheap fish, expensive metal - Mountain settlements: cheap ore, expensive food - Agricultural villages: cheap grain, expensive manufactured goods - Trade routes naturally equalize prices between regions - **Trade agreements:** faction-level trade treaties affect tariffs and available goods #### 4.29.4 Economic Indicators - **Per-settlement tracking:** - Average commodity prices - Employment rate - Wealth distribution (Gini coefficient) - Production output - Trade balance (imports vs exports) - **Economic events:** - Boom: high production, low unemployment, rising prices - Recession: overproduction, rising unemployment, falling prices - Famine: food shortage, skyrocketing food prices, starvation risk - Gold rush: discovery of valuable resource triggers migration **Technology:** Rust crate `maya-economy` for agent simulation, TypeScript `libs/maya/economy-tools/` for balance analytics. --- ### 4.30 Law Enforcement & Justice System **Reference Games:** RDR2 (bounty system, witness reports), Skyrim (hold bounties), Star Citizen (prison, bounty hunters), Elder Scrolls (theft detection) **What It Is:** When the player (or an NPC) commits a crime, the world responds through a realistic chain: witnesses observe → witnesses report to authorities → authorities investigate → pursuit → arrest or escape → trial/ punishment → bounty persistence. RDR2's system is the gold standard: crimes are only reported if witnessed, witnesses can be silenced, bounties persist per-region, and bounty hunters actively pursue wanted players. **Gap:** Phase 72.10 covers anti-cheat for multiplayer (server-side validation). No task addresses the in-game justice system — how the game world reacts to player and NPC crimes. **Proposed Feature Set:** #### 4.30.1 Crime Detection - **Crime types:** murder, assault, theft, trespassing, property destruction, fraud, disturbing the peace, smuggling, kidnapping - **Witness system:** - NPCs within sight/hearing range of crime become witnesses - Witness detection checks: line of sight + distance + lighting (dark = harder to see) + disguise - Witnesses marked (UI indicator) — player can intimidate or silence them - Witness decision: report to authorities (most NPCs), ignore (low Responsibility personality), join in (criminal NPCs) - **Evidence system:** - Physical evidence: weapon left at scene, footprints, blood trail - Circumstantial: player seen near crime location, matching description - Direct: witnessed committing the act #### 4.30.2 Law Enforcement Response - **Alert levels** (per-region): - None: no active pursuit - Investigating: guards search crime area - Searching: guards patrol expanded area looking for suspect - Pursuing: guards chase identified suspect - Lockdown: all exits blocked, intensive search (major crimes) - **Response scaling:** - Minor crime (theft, trespass): single guard investigates - Moderate crime (assault): patrol dispatched - Major crime (murder): full pursuit, reinforcements called - Repeated crimes: escalated response, specialized units - **Guard behavior during pursuit:** - Call for backup (nearby guards converge) - Cut off escape routes - Issue verbal warnings before escalating to force - Non-lethal vs lethal force based on crime severity - Search hiding spots in last-known-position area #### 4.30.3 Consequences - **Bounty system:** - Per-region bounty accumulates from crimes - Bounty amount proportional to crime severity - Bounty hunters dispatched at high bounty levels - Bounty can be paid off at specific locations (post office, court) - Bounty decay over time without new crimes (optional) - **Arrest & imprisonment:** - Arrested player: confiscate stolen goods, pay fine or serve time - Prison as playable area (Star Citizen approach): escape or serve sentence - NPC arrest: criminal NPCs are removed from population, return after sentence - **Reputation impact:** - Crimes affect faction reputation - High crime record: NPCs refuse service, guards watch closely, prices increase - Criminal reputation persists even after bounty paid - **Pardons & amnesty:** - Quest-based reputation recovery - Faction-wide amnesty events during political changes #### 4.30.4 NPC Crime - NPCs with low Responsibility / high Greed commit crimes autonomously - NPC theft: NPCs steal from shops, other NPCs, or unattended player property - NPC assault: drunken fights, grudge-based violence - Organized crime: criminal factions operate smuggling, protection rackets - Crime rates vary by district, time of day, economic conditions (recession increases crime) **Technology:** Rust crate `maya-justice` integrated with `maya-npc-life` and `maya-city-sim`. --- ### 4.31 Social Events & Cultural Life **Reference Games:** Stardew Valley (seasonal festivals), Skyrim (holidays), Dwarf Fortress (temple worship, tavern performances), AC series (historical events) **What It Is:** Cities and villages aren't just collections of NPCs going to work — they have cultural life. Markets assemble on specific days. Festivals celebrate seasonal milestones with unique activities. Religious ceremonies draw congregations. Street performers attract crowds. Funerals mourn the dead. The rhythms of cultural life make settlements feel like communities rather than NPC dispensers. **Gap:** No existing task addresses cultural events, festivals, performances, or community gatherings. **Proposed Feature Set:** #### 4.31.1 Event System - **Scheduled events:** - Weekly market days (merchants set up stalls, NPC shoppers increase) - Seasonal festivals (harvest festival, winter solstice, spring equinox, midsummer) - Religious holy days (congregation at temple, ceremonies) - Annual commemorations (founding day, victory celebrations) - **Dynamic events:** - Funerals when notable NPCs die (attended by friends/family) - Weddings when NPCs marry (ceremony + feast) - Births celebrated in community - Election/coronation when political leadership changes - Protest/riot when NPC dissatisfaction is high (see §4.37) - Victory celebration after military success - **Event structure:** - Preparation phase: NPCs set up decorations, prepare food, arrange venue - Active phase: event activities, unique interactions, mini-games - Cleanup phase: NPCs disassemble setup, return to normal schedules #### 4.31.2 Street Life & Performance - **Street performers:** musicians, jugglers, storytellers attract NPC crowds - Crowd gathers around performer in semicircle - NPCs toss coins (if economy simulated) - Performance quality varies by NPC skill - **Market vendors:** set up temporary stalls on market days - Vendors call out wares (audio barks) - NPCs browse and purchase from stalls - Haggling interactions between vendor and customer NPCs - **Tavern/inn social life:** - NPCs gather in the evening for drinks, food, socializing - Bard performances with NPC audience reactions - Drunk NPCs with altered behavior (stumbling, loud, confrontational) - Gambling games between NPCs - Rumors and quest hooks overheard in tavern conversation #### 4.31.3 Religious & Spiritual Life - Temple/church services at scheduled times - Priest NPCs conduct ceremonies - Congregation NPCs attend, pray, sing - Shrine and altar interactions: NPCs visit for individual prayer - Religious holidays with special rituals and community meals - Pilgrimage: NPCs travel to holy sites periodically **Technology:** TypeScript library `libs/maya/social-events/` with event templates, integrated with `maya-npc-life` scheduling. --- ### 4.32 NPC-to-NPC Interaction Framework **Reference Games:** RDR2 (NPCs interact with each other), Skyrim (NPC conversations), Watch Dogs 2 (ambient NPC exchanges), Dwarf Fortress (social interactions), The Sims (autonomous socialization) **What It Is:** In a living world, NPCs don't just interact with the player — they interact with each other. Two NPCs meet on the street and chat. A merchant argues with a customer over price. Coworkers share gossip during lunch. A guard reprimands a drunk. Parents call children home for dinner. These ambient NPC-to-NPC interactions create the perception of a living world even when the player is merely observing. **Gap:** Phase 72.7 covers player-NPC dialogue. Maya-souls handles LLM dialogue generation. No task addresses autonomous NPC-to-NPC conversation initiation, topic selection, or multi-party interaction choreography. **Proposed Feature Set:** #### 4.32.1 Interaction Initiation - **Proximity trigger:** NPCs within conversation range (2-3m) with shared idle time and positive opinion may initiate interaction - **Probability factors:** - Gregariousness (personality): higher = more likely to initiate - Familiarity: friends chat more than strangers - Social need: high social deficit increases initiation - Context: workplace → work talk, tavern → social talk, market → commerce - Time pressure: NPCs on schedule skip conversations - **Interaction types:** - Greeting (brief nod/wave, 2 seconds) - Small talk (weather, neighborhood, 10-30 seconds) - Deep conversation (personal topics, 1-5 minutes) - Argument (opposing views, escalates based on personality) - Transaction (commerce, service request) - Physical interaction (handshake, hug, push, fight) #### 4.32.2 Conversation Topics - Topic selection based on context and NPC state: - **Recent events:** "Did you hear about [event]?" (from memory system) - **Weather:** universal small talk (modulated by actual weather) - **Work:** complaints, accomplishments, gossip about colleagues - **Gossip about others:** share opinions about third-party NPCs or player - **Current affairs:** political situation, faction events, economic state - **Personal:** health, family, aspirations (close friends only) - **Player-related:** "That stranger who [did X]" (player actions become gossip topics) - **Topic outcome:** conversation may change opinion (positive/negative), transfer information (gossip §4.35), fulfill social need, or escalate to argument #### 4.32.3 Group Interactions - **Dynamic group formation:** - NPCs at the same location with shared activity merge into groups - Group size: 2-8 NPCs typically - Groups have emergent behavior: laughter, collective reactions, shared movement - **Multi-party conversation:** - Turn-taking: NPCs alternate speaking/listening - Side conversations can split from main group - Dominant personalities speak more (high Assertiveness) - **Work groups:** - Construction crews work together on building projects - Guard patrols walk in pairs/groups - Farmers help each other during harvest - **Social events** (§4.31): Large-scale group interactions with coordinated behavior #### 4.32.4 Ambient Conversation Audio/Visual - Overhead speech bubbles or dialogue audio for nearby NPC conversations - Body language during conversation: gestures, head nods, shoulder shrugs - Appropriate facing and eye contact between conversation participants - Conversation interruption when external event occurs (explosion, combat) **Technology:** Rust module within `maya-npc-life` for interaction scheduling, with `maya-souls` LLM generating conversation content when player is within earshot. --- ### 4.33 Simulation LOD & AI Budget Management **Reference Games:** Bethesda (4-tier AI processing), Watch Dogs Legion (simulation hierarchy), Hitman (1000+ NPCs with LOD), AC Unity (crowd AI recycling) **What It Is:** Simulating a full city of 10,000+ NPCs at full fidelity is computationally impossible. The solution is Simulation LOD — a tiered processing system where only nearby NPCs receive full AI, distant NPCs use simplified behavior, and far-away NPCs are essentially statistical entries. The critical innovation from Game AI Pro is the "LOD Trader" — a system that treats the space of detail levels as an optimization problem, maximizing perceived realism within a fixed CPU budget. When NPCs transition from low to high LOD, "alibi generation" retroactively fills in plausible behavior for the time they were off-screen. **Gap:** No existing task addresses AI performance budgeting. Phase 40 mentions rendering LOD but not simulation LOD. Without this system, every NPC system proposed in this document will exceed its CPU budget. **Proposed Feature Set:** #### 4.33.1 Simulation Tiers - **Tier 0 — Full Simulation (0-30m from player):** - Complete needs evaluation, emotional updates, memory recording - Full pathfinding with obstacle avoidance - Full animation with IK, facial expressions, gestures - Active perception (see, hear, smell nearby events) - Can initiate and participate in conversations - Inventory tracked, production simulated - CPU budget: ~0.1ms per NPC, ~50 NPCs = 5ms total - **Tier 1 — Simplified Simulation (30-100m):** - Needs decay tracked but not actively driving decisions - Pre-calculated path following (waypoint to waypoint, no obstacle avoidance) - Simplified animation (walk/idle only, no IK) - Perception limited to major events (combat, explosions) - No conversation capability - CPU budget: ~0.01ms per NPC, ~200 NPCs = 2ms total - **Tier 2 — Abstract Simulation (100m-1km):** - Position tracked as abstract cell/zone, not world coordinates - Schedule table drives zone transitions (at 9:00 → work zone) - No pathfinding, no animation, no perception - State updated on tick (~once per game-minute) - CPU budget: ~0.001ms per NPC, ~2000 NPCs = 2ms total - **Tier 3 — Statistical (1km+):** - Not individually simulated - Population counts per zone maintained - Birth/death/migration statistics applied periodically - CPU budget: negligible - Total across all tiers: ~9ms = well within budget #### 4.33.2 Tier Transition & Alibi Generation - **Promotion (Tier 2→1→0):** - When player approaches, NPC must appear to have been doing something plausible - **Alibi generation:** Given NPC's schedule, current time, and last known state, determine: - Current location (based on schedule) - Current activity (based on occupation and time) - Current attire, inventory, health - Recent social interactions (fabricated from relationship graph) - NPC spawns at correct location with correct state — player never sees the transition - **Demotion (Tier 0→1→2):** - When player moves away, record NPC's exact state - Continue schedule-based abstract simulation - If NPC has active state (in combat, in conversation), delay demotion until activity completes - **Hysteresis:** promotion distance < demotion distance (prevents flickering) #### 4.33.3 AI Budget Manager - **Per-frame CPU budget:** configurable (default 8ms for all AI systems) - **Priority scoring:** each NPC gets a priority score based on: - Distance to player (closer = higher priority) - Player attention (NPCs the player is looking at = higher priority) - Activity importance (NPC in combat or conversation = higher priority) - Narrative importance (quest NPCs = higher priority always) - **Budget allocation:** sort NPCs by priority, allocate CPU time from budget until exhausted - **Temporal distribution:** not all NPCs need updating every frame: - Tier 0: every frame - Tier 1: every 4th frame (staggered) - Tier 2: every 60th frame (1/second) - **Profiling integration:** Tracy markers for per-NPC and per-system timing **Technology:** Rust crate `maya-sim-lod` as the scheduling/budgeting layer sitting above all NPC systems. --- ### 4.34 World History & Civilization Generation **Reference Games:** Dwarf Fortress (200+ years of simulated history), Crusader Kings 3 (generational dynasties), Caves of Qud (procedural history with myth) **What It Is:** Dwarf Fortress generates entire world histories before the player starts — civilizations rise and fall, wars are fought, artifacts are created and lost, megabeasts terrorize regions, historical figures live full lives. This history is viewable in Legends Mode and provides the foundation for every NPC, ruin, and quest in the world. The world doesn't begin when the player starts — it has 200+ years of context. **Gap:** Hathor domain (worldbuilding) handles narrative content creation but is designed for authored storytelling, not procedural history generation. Phase 40's `maya-genesis-terrain` generates terrain but no history. No system generates the deep history that makes a world feel lived-in — the ruins, the legends, the old grudges between factions, the lost artifacts. **Proposed Feature Set:** #### 4.34.1 History Simulation - **World creation phase** (runs during world generation, before player starts): - Generate civilizations: location, culture, values, technology level - Simulate N years of history in accelerated time - Each year: population growth, expansion, diplomacy, wars, discoveries - Track notable historical figures: rulers, heroes, villains, scholars - Generate artifacts: named weapons, relics, tomes — each with creation story - Generate ruins: former settlements destroyed by war, disaster, or abandonment - Generate legends: distorted accounts of historical events that NPCs tell - **Historical events generated:** - City founding and naming - Wars between factions (with battles, victories, defeats, truces) - Natural disasters (earthquakes, plagues, floods) - Cultural achievements (great works of art, architectural wonders) - Religious schisms and reformations - Technological discoveries - Royal marriages, assassinations, coups - Migration of peoples #### 4.34.2 History Integration with Gameplay - **Ruins reflect history:** destroyed cities are placed as explorable ruins with loot, enemies, and lore - **Artifacts are findable:** historically generated items exist in the world as legendary equipment - **NPC knowledge:** NPCs know their civilization's history, can tell stories about historical events - **Faction grudges:** historical wars create present-day tensions between factions - **Lineage:** NPC noble families trace ancestry to historical figures - **Legends mode:** player-accessible encyclopedia of world history (as in Dwarf Fortress) #### 4.34.3 Ongoing History - History doesn't stop when the player starts — events continue to accumulate - Player actions become part of history: defeating a dragon is recorded, NPCs retell the story, it becomes legend - Non-player events continue: off-screen wars, political changes, natural events (reported via news/gossip system §4.35) **Technology:** TypeScript library `libs/maya/world-history/` for generation and storage, integrated with Hathor worldbuilding. --- ### 4.35 Information Propagation Network **Reference Games:** RDR2 (witness reports travel to authorities), Assassin's Creed (eagle vision information), academic gossip protocol research **What It Is:** Information in the real world doesn't teleport — it travels at the speed of communication. A crime committed in a remote village shouldn't instantly be known in the capital. News propagates through NPC gossip networks at a rate determined by population density, travel routes, and information importance. This creates realistic information asymmetry: frontier settlements are weeks behind on news; capital cities know everything quickly. **Gap:** No existing task addresses how information travels between NPCs or between settlements. Phase 72.17 (NPC scheduling) and maya-souls (NPC dialogue) don't model information propagation. **Proposed Feature Set:** #### 4.35.1 Gossip Protocol - **Information as entity:** each piece of news has: - Content: what happened (crime, death, discovery, political change) - Origin: where and when it happened - Importance: 1-10 (routine gossip vs world-shaking news) - Accuracy: degrades through retelling (telephone effect) - Spread count: how many NPCs have heard it - **NPC-to-NPC transmission:** - When two NPCs converse (§4.32), they may share information - Probability of sharing = importance × sharer's gregariousness × relationship closeness - Receiver stores information in memory (§4.25.4) - Information can only travel as fast as NPCs travel and meet - **Propagation patterns:** - Hub NPCs (tavern keepers, merchants, guards) spread information faster (many contacts) - Isolated NPCs (hermits, frontier settlers) receive information late - Trade caravans carry news between settlements (speed of travel) - Town criers accelerate official information within settlements - **Information decay:** - Accuracy degrades with each retelling (original fact → exaggeration → rumor → legend) - Stale information eventually stops propagating (NPCs assume everyone knows) #### 4.35.2 Rumor System - Some information becomes distorted into rumors: - Player killed a bandit → "a stranger slew ten bandits" → "a legendary warrior passed through" - Treasure found → "the caves hold untold riches" (NPC treasure hunters investigate) - Monster sighting → "a dragon terrorizes the east" (may be exaggerated from a large lizard) - Rumors create gameplay: - NPCs acting on false information (evacuating due to false threat, seeking nonexistent treasure) - Player can spread false information deliberately (disinformation as gameplay mechanic) - Investigating rumors reveals truth, creating quests #### 4.35.3 Player Reputation Propagation - Player's reputation spreads via gossip network: - Deeds witnessed by NPCs become gossip topics - Positive deeds spread: "the hero saved our village" travels along trade routes - Negative deeds spread: "a murderer roams the roads" reaches distant towns - **Regional reputation:** reputation arrives at different speeds per-region - Nearby settlements know quickly, distant ones slowly - Eventually, reputation precedes the player everywhere - **Disguise counterplay:** changing appearance can reset recognition (not reputation) until re-identified **Technology:** Rust module within `maya-social` for gossip simulation. --- ### 4.36 Domestic & Working Animals **Reference Games:** RDR2 (horse bonding, dog companions), Stardew Valley (farm animals), Skyrim (dogs, horses), Dwarf Fortress (livestock, war animals) **What It Is:** Beyond wild ecology (§4.4), domestic and working animals are integral to settlement life. Farm animals produce resources, guard dogs protect property, horses serve as transportation, cats catch mice, carrier pigeons deliver messages, and stray animals scavenge in city streets. These animals have needs, routines, and relationships with their owners. **Gap:** §4.4 (Deep Ecology) covers wild animals and food chains. §4.24.5 (Mount System) covers player riding. No system addresses the broader presence of domestic and working animals in the world — animals owned by NPCs, farm animals with production cycles, stray animals in cities, or pet bonding systems. **Proposed Feature Set:** #### 4.36.1 Farm Animals - **Species:** cow, chicken, pig, sheep, goat, horse, duck, bee (hive) - **Production cycles:** - Cows: milked daily (visible NPC farmer milking animation) - Chickens: lay eggs daily (collectible from coops) - Sheep: sheared seasonally (wool for textile production) - Bees: honey harvested seasonally - **Care requirements:** - Feeding (farmer NPC fills troughs on schedule) - Shelter (barn at night, pasture during day — driven by NPC farmer schedule) - Health: sick animals produce less, may die (veterinary NPC treats them) - **Breeding:** populations grow/shrink based on care quality - **Visual integration:** animals graze in pastures, wander in pens, sleep in barns — creating pastoral atmosphere #### 4.36.2 Working Animals - **Guard dogs:** assigned to NPC properties, bark at intruders, attack trespassers - **Herding dogs:** assist shepherd NPCs in managing flocks - **Pack animals:** mules and horses carry goods for trade caravans (§4.29.3) - **Hunting dogs:** accompany hunter NPCs, flush out game, retrieve kills - **Message carriers:** pigeons carry messages between settlements (visible flight) - **Pest control:** cats in granaries/warehouses reduce vermin (passive bonus to food storage) #### 4.36.3 Pets & Bonding - NPCs own pets (dogs, cats) that follow them through daily routines - Pet bonding: pets exhibit loyalty behaviors (waiting at door, greeting owner, sleeping near owner) - Pet needs: food, water, attention (owner NPC cares for pet on schedule) - Stray animals: unowned animals wander cities, scavenge food, can be adopted - Player pets: player can adopt strays or purchase animals, gaining a companion with autonomous behavior #### 4.36.4 Urban Wildlife - Rats in alleys, sewers, grain stores (attracted by food, avoided by NPCs) - Pigeons in plazas (scatter when approached, return when clear) - Stray cats/dogs in neighborhoods - Insects near food sources and waste areas - Seasonal: nesting birds in spring, mosquitoes near water in summer **Technology:** Extension of `maya-ecology` crate for domestic animals, TypeScript `libs/maya/animal-database/` for species templates. --- ### 4.37 Political & Governance Simulation **Reference Games:** Crusader Kings 3 (intrigue, schemes, elections), Mount & Blade Bannerlord (lord politics), Stellaris (faction demands), Dwarf Fortress (noble mandates) **What It Is:** Settlements and nations are governed, and that governance produces visible effects. A benevolent lord invests in infrastructure and keeps taxes low — NPCs are prosperous and content. A tyrant raises taxes for personal wealth — NPCs are impoverished and resentful, eventually leading to protest or revolution. Power changes hands through elections, inheritance, or coups. The player can influence or participate in political dynamics. **Gap:** Phase 72.18 covers game economy but not political systems. Hathor handles authored faction narratives but not simulated politics with emergent outcomes. No task addresses governance mechanics, political NPCs with ambitions, election systems, or civil unrest. **Proposed Feature Set:** #### 4.37.1 Governance Structure - **Government types per settlement/faction:** - Monarchy: hereditary succession, single ruler - Democracy: periodic elections, council governance - Theocracy: religious leader, temple-based governance - Oligarchy: merchant council, wealth-based influence - Tribal: elder council, tradition-based - Military: commander-based, strength determines leadership - **Governance effects:** - Tax rate: affects NPC wealth and satisfaction - Law enforcement budget: affects guard quantity and crime rate - Infrastructure investment: affects road quality, building maintenance - Military spending: affects defense capability - Social services: affects healthcare, education access - **Leader personality** (§4.25.2) affects governance: - Greedy ruler: high taxes, personal wealth accumulation - Benevolent ruler: balanced taxes, infrastructure investment - Paranoid ruler: heavy surveillance, political imprisonment - Militarist ruler: military spending, aggressive expansion #### 4.37.2 Political Dynamics - **Faction satisfaction:** - Each political faction has demands (lower taxes, more military, religious freedom) - Unmet demands reduce faction loyalty - Faction power based on population count, wealth, military strength - **Civil unrest:** - Low satisfaction → grumbling NPCs → protests → riots → rebellion - Protests: NPCs gather in public squares with demands - Riots: property damage, guard response, escalation risk - Rebellion: armed uprising, potential regime change - **Schemes & intrigue:** - Political NPCs with ambition plot to gain power - Assassination plots, bribery, blackmail, alliance-building - Player can participate in or thwart political schemes - **Succession:** - On leader death: succession crisis based on government type - Hereditary: heir assumes power (contested if multiple heirs) - Elected: emergency election - Military: strongest commander claims power (potential civil war) #### 4.37.3 Player Political Participation - Player can: - Run for office in democratic settlements - Support or oppose political candidates - Bribe officials for favorable treatment - Incite or suppress rebellion - Assassinate or protect leaders - Negotiate treaties between factions - Establish own governance in player-controlled settlements (§4.24.7) - Political reputation: player's political actions affect how factions perceive them #### 4.37.4 Inter-Faction Politics - **Diplomacy:** trade agreements, alliances, non-aggression pacts, tribute - **War declaration:** factions declare war based on accumulated grievances, territorial ambitions, or leader personality - **Peace negotiations:** war exhaustion eventually drives factions to negotiate - **Refugee displacement:** war creates civilian refugees who flee to neutral settlements, straining resources - **Occupation:** victorious faction installs puppet government, extracts tribute **Technology:** TypeScript library `libs/maya/politics/` integrated with Hathor faction system and `maya-npc-life`. ## 5. Cross-Cutting Concerns ### 5.1 Integration Architecture Every system in this proposal must integrate with existing Maya engine subsystems. Key integration points: | New System | Integrates With | | --------------------------- | ---------------------------------------------------- | | Euphoria (§4.1) | maya-physics, maya-embodiment, maya-souls | | Motion Matching (§4.2) | maya-embodiment, maya-euphoria | | Chemistry (§4.3) | maya-physics, maya-world, maya-souls (NPC reactions) | | Ecology (§4.4) | maya-world, maya-souls, maya-genesis-terrain | | Terrain Deformation (§4.5) | maya-physics, maya-renderer, maya-audio | | Clouds (§4.6) | maya-renderer, maya-world (weather), maya-wind | | Ocean (§4.7) | maya-renderer, maya-physics, maya-audio | | Vegetation (§4.8) | maya-renderer, maya-wind, maya-physics | | Wind (§4.9) | maya-physics, maya-vegetation, maya-clouds, maya-vfx | | Vehicles (§4.10) | maya-physics, maya-audio, maya-haptics | | Crowds (§4.11) | maya-renderer, maya-world, maya-souls | | Geospatial (§4.12) | maya-world, maya-renderer | | SSD Streaming (§4.13) | maya-resource, maya-world | | Mesh Shaders (§4.14) | maya-renderer | | Character Rendering (§4.15) | maya-renderer, maya-embodiment | | VFX (§4.16) | maya-renderer, maya-physics, maya-wind | | Seasons (§4.17) | maya-world, maya-vegetation, maya-ecology | | Facial Capture (§4.18) | maya-embodiment, maya-souls | | Haptics (§4.19) | Input system (Phase 72.27) | | Photo Mode (§4.20) | maya-renderer, Post-processing | | Save System (§4.21) | All gameplay systems | | Footstep Audio (§4.22) | maya-audio, maya-physics | | Dynamic Music (§4.23) | Audio middleware (Phase 72.28) | | Gameplay Systems (§4.24) | maya-physics, maya-souls, maya-embodiment | | NPC Life Sim (§4.25) | maya-souls, maya-social, maya-npc-occupations | | NPC Social (§4.26) | maya-npc-life, maya-souls, maya-sim-lod | | NPC Occupations (§4.27) | maya-npc-life, maya-economy, maya-world | | City Infrastructure (§4.28) | maya-world, maya-npc-life, maya-justice | | Dynamic Economy (§4.29) | maya-npc-occupations, maya-world, maya-city-sim | | Law & Justice (§4.30) | maya-npc-life, maya-city-sim, maya-social | | Social Events (§4.31) | maya-npc-life, maya-social, maya-world | | NPC-NPC Interaction (§4.32) | maya-npc-life, maya-souls, maya-social | | Simulation LOD (§4.33) | ALL NPC systems — this is the budget manager | | World History (§4.34) | Hathor, maya-world, maya-genesis | | Info Propagation (§4.35) | maya-social, maya-npc-life | | Domestic Animals (§4.36) | maya-ecology, maya-npc-life, maya-economy | | Political Sim (§4.37) | Hathor factions, maya-npc-life, maya-social | ### 5.2 Performance Budgets For 60fps at 4K on current-gen hardware (PS5, RTX 4070+): | System | GPU Budget | CPU Budget | | -------------------------- | ---------- | ---------- | | Rendering (total) | 12ms | 4ms | | Clouds (§4.6) | 1.5ms | 0.1ms | | Ocean (§4.7) | 1.0ms | 0.2ms | | Vegetation (§4.8) | 1.5ms | 0.3ms | | VFX/Particles (§4.16) | 1.0ms | 0.5ms | | Hair/Skin/Eyes (§4.15) | 0.5ms | 0.1ms | | Terrain Deformation (§4.5) | 0.3ms | 0.1ms | | Crowds (§4.11) | 1.0ms | 1.0ms | | Physics (total) | 0.5ms GPU | 4ms | | Euphoria (§4.1) | — | 1.0ms | | Motion Matching (§4.2) | — | 0.5ms | | Vehicles (§4.10) | — | 0.5ms | | Wind (§4.9) | — | 0.2ms | | Ecology (§4.4) | — | 0.5ms | | Chemistry (§4.3) | — | 0.3ms | | AI/NPC (all) | — | 3ms | **Total budget:** ~16.6ms (= 60fps) with headroom for game-specific logic. ### 5.3 Scalability All systems must scale from low-end (integrated GPU, HDD) to high-end (RTX 5090, NVMe): | System | Low Setting | Ultra Setting | | ----------- | ---------------------------------- | -------------------------------------- | | Clouds | 2D skybox with animated texture | Full volumetric ray-marching | | Ocean | Normal-mapped plane with scrolling | FFT simulation with full foam/caustics | | Vegetation | Billboard grass, no interaction | GPU Bezier blades, full interaction | | Crowds | 50 visible NPCs | 10,000 visible NPCs | | Hair | Shell-based approximation | Full strand simulation | | Deformation | No terrain deformation | Full POM + tessellation deformation | | Euphoria | Traditional ragdoll | Full motor system simulation | | Particles | Reduced count, no volumetrics | Full count, volumetric rendering | --- ## 6. Architecture Recommendations ### 6.1 Crate Organization All new Rust crates should be added to `libs/maya/engine-core/crates/` following the existing naming convention: ``` libs/maya/engine-core/crates/ ├── maya-euphoria/ # §4.1 Active ragdoll ├── maya-motion-matching/ # §4.2 Motion matching ├── maya-ml-locomotion/ # §4.2.4 ML locomotion ├── maya-chemistry/ # §4.3 Chemistry engine ├── maya-ecology/ # §4.4 Ecosystem simulation ├── maya-terrain-deform/ # §4.5 Terrain deformation ├── maya-clouds/ # §4.6 Volumetric clouds ├── maya-ocean/ # §4.7 FFT ocean ├── maya-vegetation/ # §4.8 GPU vegetation ├── maya-wind/ # §4.9 Wind system ├── maya-vehicles/ # §4.10 Vehicle physics ├── maya-crowds/ # §4.11 Crowd simulation ├── maya-geospatial/ # §4.12 Earth-scale streaming ├── maya-character-render/ # §4.15 Skin/eye/hair ├── maya-vfx/ # §4.16 Particle system ├── maya-facial-capture/ # §4.18 Facial capture ├── maya-haptics/ # §4.19 Haptic feedback ├── maya-photo-mode/ # §4.20 Photo mode ├── maya-save-system/ # §4.21 Save system ├── maya-music-engine/ # §4.23 Dynamic music ├── maya-combat/ # §4.24.1 Combat framework ├── maya-stealth/ # §4.24.2 Stealth system ├── maya-investigation/ # §4.24.3 Scanner/detective ├── maya-companion-ai/ # §4.24.4 Companion AI ├── maya-mounts/ # §4.24.5 Mount system ├── maya-swimming/ # §4.24.6 Swimming/diving ├── maya-settlement/ # §4.24.7 Base building ├── maya-survival/ # §4.24.8 Survival systems ├── maya-npc-life/ # §4.25 NPC needs, personality, emotions, memory ├── maya-social/ # §4.26 Relationships, gossip, reputation ├── maya-city-sim/ # §4.28 Traffic, transit, emergency services ├── maya-economy/ # §4.29 Agent-based dynamic economy ├── maya-justice/ # §4.30 Crime, law enforcement, bounties ├── maya-sim-lod/ # §4.33 AI budget management, tier scheduling └── maya-world-history/ # §4.34 Procedural civilization history ``` TypeScript companion libraries where applicable: ``` libs/maya/ ├── ecology/ # Species database, population analytics ├── geospatial/ # Tile server, satellite data pipeline ├── facial-pipeline/ # Capture processing, retarget tools ├── settlement-tools/ # Building template editor, NPC assignment UI ├── npc-database/ # §4.25 Personality templates, species data ├── npc-occupations/ # §4.27 Job database, schedule templates ├── city-infrastructure/ # §4.28 Route/schedule definitions ├── economy-tools/ # §4.29 Balance analytics, trade visualization ├── social-events/ # §4.31 Event templates, festival definitions ├── world-history/ # §4.34 History generation, legends mode ├── animal-database/ # §4.36 Domestic animal templates └── politics/ # §4.37 Governance, faction politics ``` ### 6.2 Dependency Graph ``` maya-wind ← maya-vegetation, maya-clouds, maya-vfx, maya-physics(cloth) maya-chemistry ← maya-physics, maya-world maya-sim-lod ← maya-npc-life, maya-social, maya-city-sim (budget manager for all) maya-npc-life ← maya-souls, maya-social maya-social ← maya-npc-life maya-city-sim ← maya-world, maya-npc-life, maya-economy maya-economy ← maya-npc-life, maya-world maya-justice ← maya-npc-life, maya-city-sim, maya-social maya-world-history ← maya-world, hathor maya-ecology ← maya-world, maya-souls, maya-chemistry maya-euphoria ← maya-physics, maya-embodiment maya-motion-matching ← maya-embodiment maya-vehicles ← maya-physics, maya-audio, maya-haptics maya-terrain-deform ← maya-physics, maya-renderer maya-crowds ← maya-renderer, maya-world, maya-souls maya-ocean ← maya-renderer, maya-physics maya-clouds ← maya-renderer, maya-wind maya-vfx ← maya-renderer, maya-physics, maya-wind maya-save-system ← all gameplay crates (consumer) ``` ### 6.3 Testing Strategy - Unit tests: each crate tests its algorithms in isolation (e.g., FFT wave computation, Lotka-Volterra population dynamics, Pacejka tire forces) - Integration tests: cross-crate tests (e.g., wind → vegetation response, chemistry interaction chains, Euphoria + motion matching handoff) - Visual regression tests: render standardized scenes, compare against baseline screenshots (clouds, ocean, vegetation, hair) - Performance regression tests: Tracy-instrumented benchmarks, CI fails on > 10% regression - Gameplay tests: automated bot runs through scenarios exercising gameplay systems (combat, stealth, companions, mounts) --- ## 7. Implementation Priority Matrix ### Tier 1 — Critical for Any Open-World Game (Implement First) These systems are non-negotiable for a AAA open-world experience: | # | System | Rationale | | ------ | ------------------- | -------------------------------------------------------------------------------- | | 4.16 | GPU Particle System | No game can ship without VFX — fire, smoke, sparks, weather | | 4.21 | Save System | Players must be able to save/load — foundational | | 4.24.1 | Combat Framework | Core gameplay loop for action games | | 4.6 | Volumetric Clouds | Sky is visible 100% of the time — most impactful visual system | | 4.9 | Wind System | Drives vegetation, clouds, particles, cloth — everything looks dead without wind | | 4.8 | GPU Vegetation | Ground cover is visible nearly always — critical for natural environments | | 4.5 | Terrain Deformation | Footprints and tracks ground the character in the world | | 4.22 | Footstep Audio | Audio grounds every step the player takes | ### Tier 2 — Essential for Lifelike Immersion (Implement Second) These systems elevate a good game to a great one: | # | System | Rationale | | ---- | ------------------ | ---------------------------------------------------------------------- | | 4.1 | Euphoria Ragdoll | Transforms character reactions from robotic to human | | 4.2 | Motion Matching | Eliminates animation jank — the #1 cause of uncanny valley in movement | | 4.7 | FFT Ocean | Any game with water bodies needs realistic water | | 4.10 | Vehicle Physics | Vehicles are central to open-world traversal | | 4.15 | Skin/Eye/Hair | Close-up character scenes require photorealistic faces | | 4.4 | Ecology Simulation | Wildlife makes the world feel alive beyond NPCs | | 4.17 | Seasonal System | Temporal change prevents the world from feeling static | | 4.19 | Haptic Feedback | Controller feedback is expected on modern platforms | ### Tier 3 — Differentiating Features (Implement Third) These systems create competitive advantage and industry leadership: | # | System | Rationale | | ---- | -------------------- | ------------------------------------------------------------ | | 4.3 | Chemistry Engine | Multiplicative gameplay — unique selling point | | 4.11 | Crowd Simulation | Dense cities feel alive — distinguishes AAA from indie | | 4.14 | Mesh Shaders/DXR 1.2 | Cutting-edge GPU utilization for maximum performance | | 4.13 | SSD Streaming | Eliminates loading screens — modern player expectation | | 4.18 | Facial Capture | Enables cinematic storytelling at AAA level | | 4.23 | Dynamic Music | Unique audio identity — most games use static adaptive music | | 4.20 | Photo Mode | Community engagement driver — free marketing | ### Tier 4 — Living World Systems (Critical for Believable Worlds) These systems make the world feel alive, populated, and self-sustaining: | # | System | Rationale | | ---- | ----------------------- | ---------------------------------------------------------------------- | | 4.33 | Simulation LOD | MUST implement first — without this, all NPC systems exceed CPU budget | | 4.25 | NPC Life Simulation | Foundation for all other NPC behavior — needs, personality, memory | | 4.26 | NPC Social System | NPCs interacting with each other creates living world perception | | 4.27 | NPC Occupations | NPCs visibly working gives purpose to every character | | 4.28 | City Infrastructure | Traffic, transit, districts make cities feel functional | | 4.30 | Law & Justice | Crime consequences are expected in any open-world game | | 4.32 | NPC-NPC Interaction | Ambient NPC conversations are the #1 living world indicator | | 4.35 | Information Propagation | Gossip networks make the world feel socially connected | ### Tier 5 — Deep World Simulation (Implement for Maximum Depth) These systems create unprecedented world depth — differentiating features: | # | System | Rationale | | ---- | -------------------- | ------------------------------------------------------------------ | | 4.29 | Dynamic Economy | Supply/demand creates organic economic storytelling | | 4.34 | World History | Deep history makes every ruin, faction, and artifact meaningful | | 4.31 | Social Events | Festivals and cultural life make settlements feel like communities | | 4.36 | Domestic Animals | Farm animals and pets complete the lived-in world | | 4.37 | Political Simulation | Governance dynamics create grand-scale emergent narrative | ### Tier 6 — Gameplay Depth Systems (Implement as Needed by Game Design) These are game-design-dependent — implement based on Project Obsidian's needs: | # | System | Rationale | | ------ | -------------------- | --------------------------------------------------------- | | 4.24.2 | Stealth System | If game includes stealth gameplay | | 4.24.3 | Investigation System | Specifically needed for Project Obsidian (detective noir) | | 4.24.4 | Companion AI | If game includes companion characters | | 4.24.5 | Mount System | If game includes rideable animals/vehicles | | 4.24.6 | Swimming/Diving | If game includes water exploration | | 4.24.7 | Settlement Building | If game includes base-building mechanics | | 4.24.8 | Survival Systems | If game includes survival elements | | 4.12 | Digital Twin | For MSFS-class earth-scale applications | --- ## Appendix A: Task Count Estimate | Section | Estimated Tasks (at 15 tasks per subsection) | | ---------------------------- | -------------------------------------------- | | 4.1 Euphoria | 60 | | 4.2 Motion Matching | 60 | | 4.3 Chemistry Engine | 60 | | 4.4 Deep Ecology | 60 | | 4.5 Terrain Deformation | 60 | | 4.6 Volumetric Clouds | 60 | | 4.7 FFT Ocean | 75 | | 4.8 GPU Vegetation | 60 | | 4.9 Wind System | 45 | | 4.10 Vehicle Physics | 60 | | 4.11 Crowd Simulation | 60 | | 4.12 Digital Twin | 45 | | 4.13 SSD Streaming | 45 | | 4.14 Mesh Shaders/DXR | 45 | | 4.15 Skin/Eye/Hair | 45 | | 4.16 GPU Particles | 45 | | 4.17 Seasonal System | 45 | | 4.18 Facial Capture | 45 | | 4.19 Haptics | 45 | | 4.20 Photo Mode | 60 | | 4.21 Save System | 60 | | 4.22 Footstep Audio | 45 | | 4.23 Dynamic Music | 45 | | 4.24 Gameplay Systems | 120 | | 4.25 NPC Life Simulation | 60 | | 4.26 NPC Social System | 60 | | 4.27 NPC Occupations | 60 | | 4.28 City Infrastructure | 60 | | 4.29 Dynamic Economy | 60 | | 4.30 Law & Justice | 60 | | 4.31 Social Events | 45 | | 4.32 NPC-NPC Interaction | 60 | | 4.33 Simulation LOD | 45 | | 4.34 World History | 45 | | 4.35 Information Propagation | 45 | | 4.36 Domestic Animals | 60 | | 4.37 Political Simulation | 60 | | **Total** | **~2,130 new tasks** | Combined with existing Phases 72 + 77 (~2,800 unchecked tasks), the complete SOTA gap closure represents approximately **4,930 tasks** across engine systems, rendering, simulation, living world, and gameplay frameworks. --- ## Appendix B: Reference Game Technique Matrix | Technique | RDR2 | GTA6 | CP2077 | HFW | GoT | ZeldaTotK | Spider2 | MSFS | AC Unity | StarCitizen | | ------------------------- | ---- | ---- | ------ | --- | --- | --------- | ------- | ---- | -------- | ----------- | | Active Ragdoll (Euphoria) | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | Motion Matching | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | Chemistry Engine | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | | Deep Ecology | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | Terrain Deformation | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | Volumetric Clouds | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | | FFT Ocean | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | | GPU Grass | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | Wind (Vorticles) | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | Vehicle Deformation | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | 10K Crowd | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | | Earth-Scale Streaming | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | | Path Tracing | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | Server Meshing | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | | SSD Streaming | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | | Photo Mode | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ### Living World Technique Matrix | Technique | RDR2 | Sims | DwarfFortress | Skyrim | WatchDogsLegion | Hitman | CK3 | Shenmue | | ---------------------- | ---- | ---- | ------------- | ------ | --------------- | ------ | --- | ------- | | Needs-Based AI | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | 50+ Personality Facets | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | | NPC Memory Stream | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | NPC Relationships | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | | NPC Daily Schedules | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | | NPC Occupations | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | | Traffic Simulation | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | | Public Transit | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | | Dynamic Economy | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | Crime & Justice | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | | Gossip Networks | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | World History Gen | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | | Political Sim | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | | NPC-NPC Conversation | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | Simulation LOD | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ | | Domestic Animals | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | Social Events | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | | Play-As-Anyone Census | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | **Maya's target: ✅ in every column.** No single game has all techniques. Maya aims to be the first engine where all of them coexist in a unified, integrated system — combining RDR2's ecological depth, The Sims' needs-based autonomy, Dwarf Fortress's civilizational simulation, Skyrim's schedule-driven world, Watch Dogs Legion's procedural census, and Crusader Kings 3's political intrigue into one coherent living world engine. --- _This proposal should be converted into granular TODOS.md tasks (Phase 78 or appended to Phase 72) once approved. Each section maps to approximately 3-5 task groups of 15 tasks each, following the existing TODOS.md format._