Historical task source. The Eve task board holds current task state.
Phase 79: Immersive Open World SOTA — Industry-Leading Lifelike Virtual Worlds#
Purpose: Close every remaining gap between the Maya engine ecosystem and the state-of-the-art techniques used by the most acclaimed open-world games (RDR2, GTA V/6, Zelda: TotK, Horizon Forbidden West, Ghost of Tsushima, Spider-Man 2, Cyberpunk 2077, AC Unity/Shadows, Star Citizen, MSFS, Dwarf Fortress, The Sims, Crusader Kings 3) to achieve industry-leading lifelike virtual worlds. Covers 37 identified gaps across rendering, physics, animation, world simulation, NPC life systems, city infrastructure, ecology, economy, politics, and gameplay frameworks.
Reference Proposal: docs/proposals/IMMERSIVE_OPEN_WORLD_SOTA_PROPOSAL.md
Scope: Maya engine (Rust crates in libs/maya/engine-core/crates/),
TypeScript companion libraries (in libs/maya/), and Hathor worldbuilding
integration.
79.0 Cross-cutting prerequisites (added 2026-09-18)#
The open residue of this phase is systematic: the simulation crates are finished
on the CPU, and what is left is their GPU halves, their sounds and their tools.
Three facts explain why those halves stayed open, and the three items below
remove them. (1) No crate in libs/maya/engine-core depends on a GPU API:
maya-renderer models a renderer on the CPU and ships seven WGSL files that
nothing executes, while the crate docs of maya-clouds, maya-ocean,
maya-vegetation, maya-crowds, maya-character-render, maya-vfx and
maya-terrain-deform all defer their shaders to it. (2) The sound items name
sounds but no source for them. (3) The tool and debug-UI items have no host
application. Every rendering item below says "GPU convention", every sound item
"audio convention" and every tool item "viewer convention"; they mean these
three items.
- 79.0.1 Build the headless GPU harness and name the reference devices.
Add a
maya-gpu-harnesscrate underlibs/maya/engine-core/crates/onwgpu(pin the version in the workspaceCargo.toml): create a device with no window, compile a WGSL module, run a compute or render pass into an offscreen texture, read it back, and compare it with a golden PNG under a per-channel tolerance or with a CPU reference buffer under a stated error bound. First install what it needs and record the exact commands and versions here: the toolchain fromrust-toolchain.toml, and on the Linux server Mesa's software Vulkan driver (lavapipe:apt-get install mesa-vulkan-drivers vulkan-tools, thenvulkaninfo --summarymust listllvmpipe). Park only with a named failed install attempt. Reference devices: lavapipe on the Linux server decides correctness (every golden image and every CPU-reference comparison); the Mac's Apple-silicon GPU through Metal decides every millisecond budget in this phase, measured with wgpu timestamp queries, and its chip name is written into this item the first time it is measured. A budget that was written without naming a GPU is kept as the goal, but a benchmark fails only on a regression of more than 20 % against the baseline recorded on the Mac. Verify:cargo test -p maya-gpu-harnessrenderslibs/maya/engine-core/crates/maya-renderer/shaders/maya/post_process/tonemap.wgslfor 8 frames on lavapipe and matches its golden image, and the same test passes on the Mac. - 79.0.2 Record the audio source for this phase and add the offline
check the sound items verify against. Decision (2026-09-18, the
open-source route; the owner can override it): sounds are synthesised
procedurally by the modules that already exist in
libs/maya/engine-core/crates/maya-audio/src/(creature_vocalization_sounds.rs,ambient_soundscape.rs,wind_air_sounds.rs,water_liquid_sounds.rs,vehicle_engine_sounds.rs,rolling_sliding_sounds.rs,impact_sounds.rs,granular_synthesis.rs), and speech-like material comes from the open Kokoro TTS model on the CPU. Recorded samples may enter only through a manifest that names each file's source and licence (CC0 or bought by the owner); a licensed library or Isis audio generation needs the owner's approval per asset class. Write this aslibs/maya/engine-core/crates/maya-audio/AUDIO_SOURCES.md, and addmaya_audio::testing::render_offline(source, seconds, sample_rate)with assertions for peak below 0 dBFS, RMS above a floor, spectral centroid inside a stated band, and bit-identical output for a fixed seed. Verify:cargo test -p maya-audio offline_renderpasses for one wind preset and one creature preset. - 79.0.3 Set the convention for the tool and debug-UI items, which have
no host application. Each one is (a) a serialisable snapshot or document
type in the owning crate, following the precedent of
maya-chemistry/src/feedback.rsfor 79.3.1.14, and (b) a pure viewer or editor module underlibs/maya/tooling/src/debug-viewers/<name>/that turns the JSON into SVG, or applies an edit and returns a validated document, so it runs under vitest with no browser. Build the shared scaffold there (axes, legend, heat-map, node-link layout, schema validation errors with a JSON pointer) and one worked viewer for the chemistry snapshot that already exists. Verify:npx vitest run src/debug-viewersinlibs/maya/toolingasserts that the SVG holds one node per entity of the fixture snapshot, and that a malformed snapshot is rejected with the pointer to the bad field.
79.1 Euphoria-Class Active Ragdoll & Dynamic Motion Synthesis (Rust)#
Active motor nervous system simulation where characters dynamically synthesize animation on-the-fly based on simulated muscles, bones, and a nervous system — producing unique, context-dependent reactions to every physical event.
79.1.1 Motor Nervous System Core#
- 79.1.1.1 Create
maya-euphoriaRust crate with Cargo.toml, module structure, and integration tests directory - 79.1.1.2 Implement musculoskeletal model with 200+ muscle groups mapped to character skeleton bones
- 79.1.1.3 Create active muscle force computation from nervous system commands (PID controllers per joint targeting desired angles)
- 79.1.1.4 Implement balance controller maintaining center-of-mass over support polygon (feet contact points)
- 79.1.1.5 Create proprioceptive feedback loop — character senses own joint positions, velocities, and accelerations
- 79.1.1.6 Implement vestibular simulation — sense of gravity and acceleration affecting balance decisions
- 79.1.1.7 Create pain response system — muscle weakness proportional to damage location and severity
- 79.1.1.8 Implement fatigue model — sustained exertion reduces motor control quality over time
- 79.1.1.9 Create nervous system signal delay simulation — reaction time varies by alertness, injury, inebriation
- 79.1.1.10 Implement configurable motor skill level per character — trained fighters recover balance faster than civilians
- 79.1.1.11 Create character mass and body proportion configuration affecting balance and inertia
- 79.1.1.12 Implement gravity-aware center-of-mass tracking updated every physics substep
- 79.1.1.13 Create unit tests for balance controller with known force inputs and expected recovery behaviors
- 79.1.1.14 Implement performance profiling with Tracy zones for all Euphoria subsystems
- 79.1.1.15 Create Euphoria motor system documentation and tuning guide
79.1.2 Reactive Behaviors#
- 79.1.2.1 Implement fall protection — characters tuck, roll, extend arms to break falls, protect head with crossed arms
- 79.1.2.2 Create stumble recovery — compensatory stepping, arm windmilling, torso rotation to regain balance after push/trip
- 79.1.2.3 Implement grab reflex — characters reach for and grab ledges, railings, other characters, or vehicles when falling
- 79.1.2.4 Create impact bracing — anticipate collisions and extend arms toward impact point before contact
- 79.1.2.5 Implement wound response — grab injured body part, limp on wounded leg, favor unwounded arm for actions
- 79.1.2.6 Create environmental awareness during falls — avoid obstacles, look for landing zones, orient toward softest surface
- 79.1.2.7 Implement drowning response — desperate surface-seeking behavior with decreasing coordination as breath runs out
- 79.1.2.8 Create electrocution response — involuntary muscle contractions, spasms, collapse based on shock severity
- 79.1.2.9 Implement explosion response — characters blown back with orientation based on blast direction, cover face/head
- 79.1.2.10 Create vehicle impact response — characters hit by vehicles attempt to jump/roll, crumple on impact based on speed
- 79.1.2.11 Implement stagger from projectile impact — body part hit determines stagger direction and severity
- 79.1.2.12 Create climbing slip response — hands scrabble for grip, feet seek toeholds, body swings realistically
- 79.1.2.13 Implement recovery from prone — characters roll to side, push up, stand — animation varies by injury state
- 79.1.2.14 Create integration tests for each reactive behavior with standardized force/scenario inputs
- 79.1.2.15 Implement reactive behavior blending — multiple simultaneous reactions combine naturally (stumble + grab + wound)
79.1.3 Animation-Physics Blending Pipeline#
- 79.1.3.1 Implement continuous blend between keyframe animation and physics simulation (not discrete state switch)
- 79.1.3.2 Create motor controller PID loops that track animation target poses while respecting physics constraints
- 79.1.3.3 Implement smooth transition spectrum: running animation → stumble → active balance → ragdoll as continuous blend
- 79.1.3.4 Create override priority system: gameplay animation intent vs physics reality vs motor control response
- 79.1.3.5 Implement animation-to-Euphoria handoff — detect when external forces exceed animation's ability to maintain pose
- 79.1.3.6 Create Euphoria-to-animation recovery — detect when character regains stability, blend back to animation
- 79.1.3.7 Implement partial Euphoria — upper body reacts to hit while lower body maintains locomotion animation
- 79.1.3.8 Create Euphoria intensity scaling — minor bump = subtle correction, major impact = full ragdoll with motor control
- 79.1.3.9 Implement integration with
maya-physics— bidirectional coupling: Euphoria drives joint torques, physics applies external forces - 79.1.3.10 Create integration with
maya-embodiment— Euphoria consumes target poses from animation system - 79.1.3.11 Implement integration with
maya-soulsAI — NPC alertness affects brace timing (alert NPC braces faster) - 79.1.3.12 Create LOD system for Euphoria — full motor sim near camera, simplified ragdoll at distance, no Euphoria off-screen
- 79.1.3.13 Implement deterministic Euphoria for multiplayer replay consistency
- 79.1.3.14 Create Euphoria quality presets (low: traditional ragdoll, medium: simplified motor, high: full motor system)
- 79.1.3.15 Implement comprehensive benchmark suite comparing Euphoria vs traditional ragdoll quality and performance
79.2 Motion Matching & ML-Driven Animation (Rust)#
Database-driven animation selection eliminating hand-authored state machines, plus neural network acceleration for memory reduction.
79.2.1 Motion Matching Core#
- 79.2.1.1 Create
maya-motion-matchingRust crate with module structure - 79.2.1.2 Implement animation database compiler — process MoCap FBX/BVH files into searchable pose database with metadata
- 79.2.1.3 Create feature extraction pipeline — joint positions, velocities, future trajectory, foot phase, ground contact states per frame
- 79.2.1.4 Implement KD-tree spatial index for nearest-neighbor pose lookup in feature space
- 79.2.1.5 Create cost function combining pose similarity, trajectory match, transition smoothness, and tag compatibility
- 79.2.1.6 Implement inertia blending — crossfade to selected clip starting at matched frame with configurable blend duration
- 79.2.1.7 Create tag system — annotate clips with metadata (surface type, mood, weapon held, speed class, terrain slope)
- 79.2.1.8 Implement query system — game code specifies desired future trajectory → motion matching finds best animation
- 79.2.1.9 Create foot locking IK — prevent foot sliding by locking foot position at ground contact markers
- 79.2.1.10 Implement trajectory prediction — extrapolate player input into future trajectory for motion matching query
- 79.2.1.11 Create motion database LOD — near characters use full database, distant characters use subset
- 79.2.1.12 Implement multi-character motion matching — synchronized pair animations (combat exchanges, handshakes, conversations)
- 79.2.1.13 Create motion matching debugging visualization (show current pose features, query trajectory, selected match, cost breakdown)
- 79.2.1.14 Implement motion matching profiling and memory budget tracking
- 79.2.1.15 Create motion matching documentation with MoCap pipeline guide
79.2.2 Learned Motion Matching#
- 79.2.2.1 Implement lightweight neural network (2-3 hidden layers) to approximate motion database search
- 79.2.2.2 Create training pipeline — generate training data from full motion matching queries, train network to predict matching results
- 79.2.2.3 Implement decompressor network — compact latent space representation to full skeleton pose
- 79.2.2.4 Create ONNX export for trained networks and ONNX Runtime integration for cross-platform inference
- 79.2.2.5 Implement memory reduction measurement — target 10-100x compression vs raw motion database
- 79.2.2.6 Create quality comparison tool — side-by-side full vs learned motion matching output
- 79.2.2.7 Implement online retraining — capture new MoCap and retrain network incrementally
- 79.2.2.8 Create fallback system — use full motion matching if network quality degrades for specific queries
- 79.2.2.9 Implement learned motion matching profiling (inference latency vs database search latency comparison)
- 79.2.2.10 Create learned motion matching unit tests verifying output quality against full motion matching baseline
79.2.3 Physics-Aware & ML Locomotion#
- 79.2.3.1 Implement terrain-adaptive locomotion — query ground slope and material to bias motion selection toward appropriate variants
- 79.2.3.2 Create obstacle-aware trajectory prediction — predict collisions and select avoidance animations
- 79.2.3.3 Implement object interaction approach — select animation based on target object height/type (pick up from ground vs shelf vs overhead)
- 79.2.3.4 Create
maya-ml-locomotioncrate for reinforcement learning based character control - 79.2.3.5 Implement physics-based character controller with joint torque actuation (DeepMimic-inspired)
- 79.2.3.6 Create reward function for locomotion mimicry — match reference motion capture while maintaining physical plausibility
- 79.2.3.7 Implement terrain generalization — agent trained on varied terrains adapts to unseen geometry
- 79.2.3.8 Create perturbation recovery — ML agent learns to recover from pushes, trips, and unexpected forces
- 79.2.3.9 Implement multi-skill policy — single network handles walk,
run, jump, climb, swim with smooth transitions. State on 2026-09-18 (moved
out of an HTML comment): the mechanism exists in
maya-ml-locomotionas a skill-conditioned single policy whose environment models all six skills, and it was demonstrated for a three-skill subset (stand, walk, run). Training one network on all five named skills showed skill interference within a local test budget. The residual task is that training run: train on the Linux server's CPU with a fixed seed and a per-skill curriculum (one skill added per stage, earlier skills replayed), log the per-skill return for every stage, and keep the run resumable from checkpoints. Verify: a spec loads the final checkpoint and asserts each of the five skills reaches at least 80 % of its single-skill baseline return, and that a walk → run → jump command sequence produces no joint-velocity discontinuity above the threshold the three-skill demo already uses. Tag this item as GPU-blocked only after that CPU run has been attempted and its wall-clock time and final returns are recorded here. - 79.2.3.10 Create ML locomotion + motion matching integration — ML handles edge cases and physics transitions, motion matching handles normal movement
79.3 Chemistry Engine & Systemic Interaction Framework (Rust)#
Property-based object interactions creating emergent, multiplicative gameplay inspired by Zelda: Tears of the Kingdom.
79.3.1 Material Property System#
- 79.3.1.1 Create
maya-chemistryRust crate with ECS component definitions - 79.3.1.2 Implement material property component — element affinity, material class, conductivity, flammability, buoyancy, temperature per entity
- 79.3.1.3 Create material state enumeration — solid, liquid, gas, plasma, frozen, burning, electrified, wet, rusted, corroded
- 79.3.1.4 Implement state transition rules —
(source_element, target_material, condition) → new_state + effects - 79.3.1.5 Create fire propagation system — fire spreads to adjacent flammable objects based on proximity, material, and wind
- 79.3.1.6 Implement electricity conduction — electrical charge propagates through chains of conductive materials
- 79.3.1.7 Create water flow system — water flows downhill, pools in depressions, extinguishes fire, conducts electricity
- 79.3.1.8 Implement temperature propagation — heat and cold transfer through conductive materials with thermal diffusion
- 79.3.1.9 Create ice/freeze mechanics — water surfaces freeze in cold, become walkable, melt in warmth
- 79.3.1.10 Implement chain reaction support — fire → rope → boulder falls → dam breaks → flood → fire extinguished
- 79.3.1.11 Create area-of-effect interactions — lightning electrifies puddle affecting all entities standing in it
- 79.3.1.12 Implement temporal material effects — wood burns over time (fire → charred → ash → gone), ice melts gradually
- 79.3.1.13 Create priority system for conflicting interactions (water vs fire → steam, not "wet fire")
- 79.3.1.14 Implement chemistry debugging visualization — show material states, active interactions, propagation paths
- 79.3.1.15 Create chemistry interaction unit tests for all standard element-material combinations
79.3.2 Environmental Integration#
- 79.3.2.1 Implement weather → chemistry integration — rain wets outdoor surfaces, extinguishes fires, creates puddles
- 79.3.2.2 Create lightning strike mechanics — metallic objects attract lightning during storms, electrical chain through conductors
- 79.3.2.3 Implement cold weather effects — water freezes, characters take cold damage without insulation, breath visible
- 79.3.2.4 Create hot weather effects — ice melts faster, dehydration risk, fire spreads more easily in dry conditions
- 79.3.2.5 Implement biome-specific chemistry defaults — desert (high heat, no water), tundra (ambient cold, natural ice)
- 79.3.2.6 Create time-of-day chemistry effects — night cold, dawn dew, midday heat
- 79.3.2.7 Implement NPC reactions to chemistry events — flee from fire, seek shelter from electrical storms, avoid deep water
- 79.3.2.8 Create quest integration — objectives leveraging chemistry (burn barricade, freeze river to cross, electrify water)
- 79.3.2.9 Implement crafting integration — combine materials using chemistry rules (flammable + fire source = torch)
- 79.3.2.10 Create player feedback — visual indicators for active chemistry states (fire particles, electricity arcs, ice crystals, steam)
79.4 Deep Ecology & Wildlife Simulation (Rust + TypeScript)#
Full predator-prey ecosystem with species-specific behaviors, population dynamics, food chains, and carcass decay — inspired by RDR2's ~200 species.
79.4.1 Species Database & Behavioral Programs#
- 79.4.1.1 Create
maya-ecologyRust crate andlibs/maya/ecology/TypeScript library for species data management - 79.4.1.2 Implement species definition schema — taxonomy, physical stats, behavioral archetype, diet, social structure, habitat, reproduction
- 79.4.1.3 Create predator behavioral program — hunting (solo ambush, pack flanking, aerial dive), territory marking, prey selection
- 79.4.1.4 Implement prey behavioral program — grazing/foraging, sentinel alerting, herd flight response, evasion tactics
- 79.4.1.5 Create scavenger behavioral program — carcass detection, wait for predators to leave, competitive feeding hierarchy
- 79.4.1.6 Implement pack behavior — alpha leadership, coordinated hunting with role assignment (driver, ambusher, blocker)
- 79.4.1.7 Create herd behavior — cohesion, sentinel rotation, stampede trigger, following migration routes
- 79.4.1.8 Implement flock behavior — V-formation flight, murmuration patterns, roost selection, seasonal migration
- 79.4.1.9 Create species-specific unique behaviors — bear fishing at rivers, snake basking on rocks, eagle soaring thermals, possum playing dead
- 79.4.1.10 Implement activity patterns — diurnal, nocturnal, crepuscular species active at appropriate times
- 79.4.1.11 Create habitat preference system — species spawn and remain in biomes matching their habitat requirements
- 79.4.1.12 Implement animal perception system — species-specific sight, hearing, and smell ranges affecting detection
- 79.4.1.13 Create animal-to-player interaction — animals flee, investigate, or attack player based on species temperament and player behavior
- 79.4.1.14 Implement 50+ species templates covering mammals, birds, reptiles, amphibians, fish, and insects
- 79.4.1.15 Create species database editor tool for adding new species
without code changes (viewer convention, 79.0.3): a JSON species document
validated against the schema in
libs/maya/ecology/src/species.ts, an editor module underlibs/maya/tooling/src/debug-viewers/species-editor/that adds, edits and removes a species and refuses a document that breaks the food web (a predator whose prey list names no existing species, a habitat that does not exist), and a loader inmaya-ecologythat reads the same file at start-up. Verify: a vitest spec adds a new herbivore and gets a valid document back, a broken prey reference is rejected with its JSON pointer, and amaya-ecologytest spawns the added species from the file without recompiling species code.
79.4.2 Population Dynamics & Food Chain#
- 79.4.2.1 Implement Lotka-Volterra population dynamics — predator-prey population oscillation per region
- 79.4.2.2 Create per-region population tracking — birth rate, death rate, carrying capacity per species per world region
- 79.4.2.3 Implement energy flow model — prey consumed → predator energy → survival and reproduction capacity
- 79.4.2.4 Create starvation mechanics — insufficient prey → predator aggression increases → expanded territory → population decline
- 79.4.2.5 Implement player impact on ecosystem — over-hunting reduces populations, causing cascading ecological effects
- 79.4.2.6 Create seasonal effects — migration routes, hibernation entry/ exit, breeding seasons with increased territorial aggression
- 79.4.2.7 Implement food web modeling — multiple predator-prey relationships forming interconnected web, not just chains
- 79.4.2.8 Create ecosystem equilibrium detection — alert when player actions push ecosystem toward collapse
- 79.4.2.9 Implement population recovery — depleted species gradually return if habitat is suitable and predation pressure reduces
- 79.4.2.10 Create population analytics dashboard — per-region species counts, trends, food chain health indicators
79.4.3 Carcass & Decay System#
- 79.4.3.1 Implement carcass entity creation on animal death with decay state machine (fresh → bloated → decaying → skeletal → bones → gone)
- 79.4.3.2 Create per-stage visual changes — mesh morphing, texture
darkening, bloating, skeletal exposure (GPU convention, 79.0.1): a
per-decay-stage parameter set in
maya-ecology(bloat morph weight, albedo darkening, skeleton-reveal mask threshold) andlibs/maya/engine-core/crates/maya-renderer/shaders/maya/ecology/carcass_decay.wgslthat applies it to a test mesh. Verify: the harness renders the five decay stages of one fixture carcass and matches five golden images, and a unit test asserts the parameters change monotonically with decay progress. - 79.4.3.3 Implement scavenger attraction — carcass emits scavenger attraction radius that increases then decreases through stages
- 79.4.3.4 Create scavenger arrival order — vultures first (aerial surveillance), then crows, then ground scavengers (coyotes)
- 79.4.3.5 Implement player interaction with carcasses — skinning, looting, study (only valid in fresh/bloated stages)
- 79.4.3.6 Create disease risk from decaying carcasses near water sources
- 79.4.3.7 Implement insect swarm particles around decaying carcasses:
an
insect_swarmeffect inlibs/maya/engine-core/crates/maya-vfx/src/templates.rswhose emission rate follows the carcass decay stage and the temperature frommaya-ecology, with a curl-noise orbit around the carcass bounds. Verify: amaya-vfxtest asserts zero particles on a fresh carcass, a peak at the active-decay stage, and that 95 % of particles stay within twice the carcass radius over 10 simulated seconds. - 79.4.3.8 Create carcass audio — buzzing flies, scavenger vocalizations
(audio convention, 79.0.2): a fly-buzz source (band-limited sawtooth swarm
with random detune) driven by the swarm density of 79.4.3.7, and scavenger
calls from
creature_vocalization_sounds.rstriggered by the arrival events of 79.4.3.4. Verify: an offline render of 5 seconds at peak decay passes the convention's assertions with a spectral centroid between 150 and 400 Hz for the buzz, and renders silence for a fresh carcass. - 79.4.3.9 Implement decay rate variation by temperature and humidity (faster in heat, slower in cold)
- 79.4.3.10 Create carcass persistence management — LOD and cleanup for distant/old carcasses
79.4.4 Wildlife Rendering & Audio#
- 79.4.4.1 Implement animal LOD system — full skeletal animation (near) → simplified animation (mid) → sprite impostor (far)
- 79.4.4.2 Create GPU-instanced rendering for large groups (flocks,
herds, fish schools) (GPU convention, 79.0.1): an instance buffer filled
from the
maya-ecologygroup state andlibs/maya/engine-core/crates/maya-renderer/shaders/maya/ecology/instanced_animals.wgsldrawing one mesh per species with per-instance transform and animation phase. Verify: the harness draws a 5,000-bird flock in one indirect draw call and matches a golden image, a readback of the instance buffer equals the CPU group state, and the Mac frame time is recorded as the baseline. - 79.4.4.3 Implement flock/herd formation rendering with coordinated
group movement: feed the instance buffer of 79.4.4.2 from the flock and
herd steering that
maya-ecologyalready simulates (79.4.1.7, 79.4.1.8), with each animal's heading and wing or gait phase derived from its velocity. Verify: over 120 simulated frames of a V-formation fixture, a test asserts that every instance's rendered heading stays within 5° of its velocity direction and that no two instances overlap. - 79.4.4.4 Create migration visual effects — hundreds of birds darkening sky, fish runs in rivers: drive 79.4.4.2 from the seasonal migration routes of 79.4.2.6, with a distance tier that turns far flocks into a single alpha-blended density sprite. Verify: a test runs a migration day and asserts the flock follows its route within a stated tolerance, and the harness matches golden images for the near (instanced) and far (density sprite) tiers.
- 79.4.4.5 Implement species-specific audio — vocalizations, movement
sounds, feeding sounds, alarm calls (audio convention, 79.0.2): one
parameter preset per species template of 79.4.1.14 for
creature_vocalization_sounds.rs(body size sets pitch and formants), with call types idle, alarm, feeding and movement. Verify: an offline render per call type for three species of very different size (for example wolf, deer, songbird) passes the convention's assertions, and the fundamental frequency orders inversely with body mass. - 79.4.4.6 Create ambient wildlife soundscape — layered bird calls,
insect chirps, frog croaks varying by biome and time (audio convention,
79.0.2): a biome-and-hour table that sets the layer gains and call rates
of
ambient_soundscape.rs, fed by the species thatmaya-ecologyreports as present. Verify: offline renders of forest at dawn, forest at night and desert at noon differ in layer energy the way the table says (a dawn-chorus bird layer above the night one, a frog layer only at night near water), asserted per band. - 79.4.4.7 Implement predator-prey chase audio events — alert calls,
pursuit sounds, kill sounds (audio convention, 79.0.2): map the hunt state
machine's transitions in
maya-ecology(detect, flee, pursue, kill, escape) to audio events with the species presets of 79.4.4.5. Verify: a test runs one scripted hunt and asserts the ordered event list with the right emitter positions, and an offline render of that timeline passes the convention's assertions. - 79.4.4.8 Create wildlife audio LOD — full audio near, ambient blend far
- 79.4.4.9 Implement ecology integration tests — simulate ecosystem for 1000 game-days, verify population stability
- 79.4.4.10 Create ecology performance benchmarks — target <0.5ms CPU for full ecosystem tick
79.5 Terrain Deformation & Surface Interaction (Rust)#
Persistent footprints, wagon tracks, and surface deformation with parallax occlusion mapping and tessellation — inspired by RDR2.
79.5.1 Deformation Buffer System#
- 79.5.1.1 Create
maya-terrain-deformRust crate integrated with maya-renderer and maya-physics - 79.5.1.2 Implement per-region displacement heightmap at 1-2cm per texel resolution for footprint-level detail
- 79.5.1.3 Create deformation source registration — character feet, vehicle wheels, projectile impacts, animal hooves, physics objects
- 79.5.1.4 Implement depression deformation type — weight pushes surface down creating footprints and tracks
- 79.5.1.5 Create displacement deformation type — material pushed outward creating ridges alongside tire ruts and plow furrows
- 79.5.1.6 Implement compression deformation type — snow compacts without displacement, creating hard-packed paths
- 79.5.1.7 Create erosion deformation type — material removed entirely by water flow or explosions
- 79.5.1.8 Implement deformation persistence — permanent until region unloads with optional gradual recovery for elastic surfaces
- 79.5.1.9 Create weather-driven deformation fill — rain fills tracks with water, snow covers footprints over time
- 79.5.1.10 Implement deformation buffer streaming aligned with world partition streaming chunks
79.5.2 Surface Material Response#
- 79.5.2.1 Implement per-surface-material deformation properties — mud (deep, slow recovery, squelch audio), snow (medium, crunch audio), sand (shallow, wind erosion), grass (minimal, fast recovery)
- 79.5.2.2 Create mud deformation — deep impressions, particle splash on step, movement speed penalty, darkened color at disturbed sites
- 79.5.2.3 Implement snow deformation — variable depth based on snow accumulation, compaction with icier visual, crunch audio
- 79.5.2.4 Create sand deformation — shallow impressions, wind-driven erosion over time, particle kick-up on step
- 79.5.2.5 Implement wet soil deformation — rain transforms dirt to mud gradually, deeper deformation, no recovery
79.5.3 Deformation Rendering#
- 79.5.3.1 Implement Parallax Occlusion Mapping (POM) for deformation
visual on non-tessellated terrain (GPU convention, 79.0.1):
libs/maya/engine-core/crates/maya-renderer/shaders/maya/terrain/deform_pom.wgslray-marches the displacement heightmap thatmaya-terrain-deformproduces. Verify: the harness renders a footprint-and-rut fixture at a grazing angle and matches a golden image, and a test compares the shader's per-pixel intersection depth with a CPU ray-march of the same heightmap within one height-field texel. - 79.5.3.2 Create tessellation + displacement mapping for close-range
deformation geometric detail (GPU convention, 79.0.1). WGSL has no
tessellation stage, so generate the dense patch in a compute pass
(
libs/maya/engine-core/crates/maya-renderer/shaders/maya/terrain/deform_displace.wgsl) that subdivides tiles near the camera and displaces vertices by the deformation heightmap. Verify: the displaced vertex positions read back from the GPU equal a CPU displacement of the same patch within 1 mm, and the harness matches a golden image of the rut fixture. - 79.5.3.3 Implement normal map recalculation from deformation heightmap for correct lighting on deformed surfaces
- 79.5.3.4 Create material appearance change at deformation sites —
compacted snow icier, disturbed dirt lighter (GPU convention, 79.0.1): a
per-material response in
maya-terrain-deform/src/material.rs(roughness and albedo shift as a function of compression and displacement) sampled by the terrain shader. Verify: a unit test asserts the response curves per material, and the harness matches golden images of a compacted-snow and a disturbed-dirt fixture. - 79.5.3.5 Implement deformation rendering performance optimization —
only update tiles with active deformation sources: a dirty-tile set in
maya-terrain-deformthat limits heightmap uploads and normal recomputation to tiles touched this frame. Verify: a test with one walker on a 64-tile region asserts at most four tile uploads per frame and zero uploads on an idle frame, with a rendered result identical to a full update.
79.5.4 Physics & Gameplay Integration#
- 79.5.4.1 Implement deformed terrain feeding back into physics — deep ruts affect vehicle handling, deep mud increases drag
- 79.5.4.2 Create tracking system — NPC AI can follow player's footprint trail for hunting/pursuit gameplay
- 79.5.4.3 Implement stealth integration — soft surfaces reduce noise, hard surfaces leave fewer visual tracks
- 79.5.4.4 Create deformation-aware pathfinding — NPCs and animals prefer existing tracks over unbroken snow/mud
- 79.5.4.5 Implement deformation system integration tests and performance benchmarks (target <0.3ms GPU)
79.6 Nubis-Class Volumetric Cloud & Storm System (Rust)#
Photorealistic volumetric clouds through ray-marching with coverage maps, storm cells, lightning, and tornado formation — inspired by Guerrilla's Nubis system.
79.6.1 Cloud Modeling#
- 79.6.1.1 Create
maya-cloudsRust crate with WGSL/GLSL compute shaders. Split 2026-09-18 because the two halves are in different states.- 79.6.1.1.a Crate scaffold. It exists at
libs/maya/engine-core/crates/maya-clouds(cloud.rs,noise.rs,render.rs,storm.rs) and the eight modelling items of §79.6.1 that depend on it are checked. Verify it under the checkbox rule (read the public API, run the adversarial scan,cargo test -p maya-clouds) and close this child. - 79.6.1.1.b GPU plumbing (GPU convention, 79.0.1): a
gpufeature inmaya-cloudsthat uploads the coverage map, the type map and the 3D Worley noise volume fromnoise.rsas textures, with the noise volume generated bylibs/maya/engine-core/crates/maya-renderer/shaders/maya/clouds/noise_volume.wgsl. Verify: the harness generates the volume for 8 frames on lavapipe and a readback matches the CPUnoise.rsvolume within 1/255 per voxel.
- 79.6.1.1.a Crate scaffold. It exists at
- 79.6.1.2 Implement coverage map — 2D texture defining cloud density distribution (0-1) across the sky
- 79.6.1.3 Create type map — define cloud type per coverage point (cumulus, stratus, cirrus, cumulonimbus)
- 79.6.1.4 Implement height-based density profiles per cloud type — cumulus (dense bottom, billowing top), stratus (thin, flat), cirrus (wispy high)
- 79.6.1.5 Create 3D noise volume for cloud detail using layered Worley and Perlin noise at multiple frequencies
- 79.6.1.6 Implement temporal cloud evolution — wind advects coverage map, clouds form and dissipate over time
- 79.6.1.7 Create artist weather preset system — presets drive coverage/type maps with smooth blending between presets
- 79.6.1.8 Implement cloud layer altitude configuration (low cumulus at 2-4km, mid alto at 4-7km, high cirrus at 8-12km)
- 79.6.1.9 Create cloud anvil formation for cumulonimbus — top spreads horizontally at tropopause height
- 79.6.1.10 Implement cloud modding API — expose cloud parameters to
content creators: a versioned, serialisable
CloudPresetdocument inmaya-clouds(coverage, type mix, density profile, wind, lighting) with range validation, registered throughmaya-plugin-apiso a mod can add or override presets without touching engine code. Verify: a test loads a mod-supplied preset file, rejects an out-of-range density with the field name, and shows that the override changes the CPU reference render ofrender.rs.
79.6.2 Cloud Rendering#
- 79.6.2.1 Implement ray-marching compute shader — march through cloud
volume accumulating density and scattering (GPU convention, 79.0.1): port
the CPU reference ray-marcher in
libs/maya/engine-core/crates/maya-clouds/src/render.rstolibs/maya/engine-core/crates/maya-renderer/shaders/maya/clouds/raymarch.wgsl. Verify: for three camera fixtures the harness output matches the CPU reference within a stated mean absolute error per channel, and a golden image is stored for each. - 79.6.2.2 Create secondary light ray marching — for each sample, march
toward sun computing self-shadowing: add the sun march of
render.rsto the shader of 79.6.2.1. Verify: a fixture with the sun behind a thick cell renders a darker base than the same fixture with the secondary march off, and both match the CPU reference within the 79.6.2.1 bound. - 79.6.2.3 Implement multi-scattering approximation — 2-lobe Henyey- Greenstein phase function for silver-lining effect
- 79.6.2.4 Create powder effect — darkening at cloud edges transitioning to bright interiors
- 79.6.2.5 Implement Beer's Law attenuation for light absorption through cloud volume
- 79.6.2.6 Create temporal reprojection — render at quarter resolution,
temporally upsample across 16 frames for performance (GPU convention,
79.0.1): a 4×4 interleaved update with motion-vector reprojection and
neighbourhood clamping in
libs/maya/engine-core/crates/maya-renderer/shaders/maya/clouds/temporal_upsample.wgsl. Verify: with a static camera, the 16-frame accumulated image matches the full-resolution render of 79.6.2.1 above a stated PSNR; with a panning camera, a ghosting metric stays under a stated bound. - 79.6.2.7 Implement cloud shadow map — project cloud density onto terrain for drifting cloud shadows (GPU convention, 79.0.1): a top-down transmittance texture from the coverage and density fields. Verify: the shadow texture read back from the GPU matches a CPU projection of the same fields, and a test shows the shadow centroid moving with the wind vector at the expected ground speed.
- 79.6.2.8 Create atmospheric scattering integration — clouds
participate in sunrise/sunset coloring: sample the sky radiance and sun
transmittance of
maya-atmosphereinside the cloud lighting of 79.6.2.1. Verify: the mean cloud colour at sun elevations of 60°, 5° and −2° moves from neutral toward warm as the atmosphere model predicts, asserted as a red-to-blue ratio per elevation against the CPU reference. - 79.6.2.9 Implement cloud rendering quality presets — ultra (full ray- march), medium (reduced samples), low (2D skybox fallback)
- 79.6.2.10 Create cloud rendering performance benchmark (target <2ms GPU at quarter resolution with temporal upscaling). The target named no GPU, so it is restated under the GPU convention (79.0.1): measure the pass of 79.6.2.6 at 1920×1080 with timestamp queries on the Mac's GPU, record the chip and the milliseconds here as the baseline, keep 2 ms as the goal, and fail the benchmark only on a regression of more than 20 % against the baseline. Verify: a harness benchmark target prints the timing, and the baseline file is committed beside it.
79.6.3 Storm Systems#
- 79.6.3.1 Implement storm cell lifecycle — developing → mature → dissipating cumulonimbus growth cycle
- 79.6.3.2 Create precipitation generation — rain/snow particle emission from cloud base proportional to cloud density
- 79.6.3.3 Implement intra-cloud lightning — flashes illuminating cloud
interior volumetrically: a transient point light inside the volume, driven
by the lightning events of
libs/maya/engine-core/crates/maya-clouds/src/storm.rsand added to the scattering integral of 79.6.2.1. Verify: a CPU-reference test shows radiance falling off with optical depth from the flash position, and the harness matches golden images for the frame before and during the flash. - 79.6.3.4 Create cloud-to-ground lightning — visual bolt with Lichtenberg pattern generation + flash illumination + delayed thunder audio
- 79.6.3.5 Implement lightning probability scaling with storm intensity and metallic object proximity
- 79.6.3.6 Create tornado/funnel formation — rotating mesocyclone
visible in cloud structure, funnel descending from base: a funnel density
field in
storm.rs(a Rankine-vortex radius profile, a descent driven by storm-cell intensity) composited into the cloud density. Verify: a test asserts that the funnel tip height falls monotonically while the intensity is above threshold and retracts when it drops, that tangential speed peaks at the core radius, and the CPU reference render shows the funnel in a golden image. - 79.6.3.7 Implement tornado physics influence — nearby objects affected by rotational wind forces
- 79.6.3.8 Create hurricane system — eye-wall structure, spiral rain
bands, storm surge on water bodies: a hurricane coverage generator in
storm.rs(a clear eye, an eye-wall ring, logarithmic-spiral bands) plus a surge height offset handed tomaya-ocean. Verify: a test asserts coverage near zero inside the eye radius and maximal at the eye wall, that the band centrelines fit the configured spiral pitch, and that the surge offset scales with the pressure deficit. - 79.6.3.9 Implement storm audio — rolling thunder, heavy rain, wind
intensity, hail impacts (audio convention, 79.0.2): thunder as a filtered
noise burst whose delay and low-pass depend on the distance of the
lightning event in
storm.rs, rain and hail fromwater_liquid_sounds.rsandimpact_sounds.rsscaled by precipitation rate, wind fromwind_air_sounds.rs. Verify: offline renders show the thunder arriving distance ÷ 343 m/s after the flash, a lower spectral centroid for the distant strike than for the near one, and rain RMS rising with the rate. - 79.6.3.10 Create weather system integration — weather state drives
cloud presets over time (clear → cloudy → storm → clearing): a weather
state machine that cross-fades the
CloudPresetvalues of 79.6.1.10 and spawns storm cells instorm.rs. Verify: a test runs a scripted clear → storm → clear day and asserts that coverage changes continuously with no step above a stated delta per simulated minute, that a storm cell exists only in the storm state, and that the run is deterministic for a seed.
79.7 FFT Ocean & Hydrological Simulation (Rust)#
Tessendorf FFT-based ocean with JONSWAP spectra, foam, caustics, rivers, waterfalls, buoyancy, and underwater rendering.
79.7.1 FFT Ocean Surface#
- 79.7.1.1 Create
maya-oceanRust crate with GPU compute shaders. Split 2026-09-18 because the two halves are in different states.- 79.7.1.1.a Crate scaffold. It exists at
libs/maya/engine-core/crates/maya-ocean(spectrum.rs,fft.rs,ocean.rs,foam.rs,hydro.rs) and thirteen items of §79.7.1 that depend on it are checked. Verify it under the checkbox rule (read the public API, run the adversarial scan,cargo test -p maya-ocean) and close this child. - 79.7.1.1.b GPU FFT pipeline (GPU convention, 79.0.1):
libs/maya/engine-core/crates/maya-renderer/shaders/maya/ocean/spectrum_update.wgslandlibs/maya/engine-core/crates/maya-renderer/shaders/maya/ocean/fft.wgslcompute the 512×512 height, displacement and normal fields on a wgpu device behind agpufeature. Note that 79.7.1.4 ("GPU FFT computation") is checked while only the CPU reference infft.rsexists; this child is the shader that box still owes. Verify: the harness runs 8 frames on lavapipe and the read-back height field matches the CPUocean.rsfield within a stated RMS error.
- 79.7.1.1.a Crate scaffold. It exists at
- 79.7.1.2 Implement Pierson-Moskowitz spectrum for fully developed seas
- 79.7.1.3 Create JONSWAP spectrum with adjustable peak enhancement for developing seas
- 79.7.1.4 Implement GPU FFT computation — 512x512 grid per frame producing height, XZ displacement, and normal maps
- 79.7.1.5 Create multiple cascade resolutions — ocean-scale swell + medium waves + fine ripples combined
- 79.7.1.6 Implement wind-driven parameters — wind speed → wave height, wind direction → travel direction
- 79.7.1.7 Create seamless ocean tiling across arbitrarily large water bodies
- 79.7.1.8 Implement shore wave attenuation — waves reduce height approaching coastline, refract around headlands
- 79.7.1.9 Create Jacobian-based foam generation — foam at breaking wave crests where Jacobian goes negative
- 79.7.1.10 Implement foam persistence — foam accumulates at breaking points, dissipates over time
- 79.7.1.11 Create wake foam — boats and swimming characters leave foam trails
- 79.7.1.12 Implement shore foam — waves breaking on beaches create wash patterns
- 79.7.1.13 Create ocean LOD — full FFT near camera, simplified wave at distance, flat horizon
- 79.7.1.14 Implement ocean rendering performance benchmark (target <1ms GPU)
- 79.7.1.15 Create ocean parameter tuning interface for artists (viewer
convention, 79.0.3): a serialisable
OceanTuningdocument inmaya-ocean(wind speed and direction, fetch, choppiness, foam threshold, cascade sizes) with range validation and named presets, and an editor module underlibs/maya/tooling/src/debug-viewers/ocean-tuning/that edits it and draws the resulting wave spectrum and a height-field slice as SVG. Verify: a vitest spec changes the wind speed and sees the spectrum peak move to the frequency the JONSWAP formula predicts, and an out-of-range value is refused with its field.
79.7.2 Water Rendering#
- 79.7.2.1 Implement planar reflections for calm water, screen-space or
ray-traced reflections for rough water (GPU convention, 79.0.1): a planar
reflection pass for water bodies below a roughness threshold and a
screen-space reflection march above it, in
libs/maya/engine-core/crates/maya-renderer/shaders/maya/water/reflections.wgsl. Hardware ray-traced reflections are out of this item. Verify: the harness renders a fixture with a red pole on the far bank and finds its mirrored pixels in the calm case, a stretched and blurred reflection in the rough case, and matches two golden images. - 79.7.2.2 Create refraction rendering — underwater scene visible through surface with chromatic dispersion (GPU convention, 79.0.1): refract the scene colour through the water normal with per-channel offsets. Verify: for a flat-water fixture the rendered shift of a submerged marker matches Snell's law at three view angles within one pixel, and the red and blue channels separate by the configured dispersion.
- 79.7.2.3 Implement caustics — animated light patterns projected onto
underwater surfaces using caustic texture or ray-tracing (GPU convention,
79.0.1): use the open route, a caustic intensity computed from the ocean
normal field by projecting a light grid and measuring its area change, in
libs/maya/engine-core/crates/maya-renderer/shaders/maya/water/caustics.wgsl. Verify: the caustic texture's mean intensity is conserved within 2 % (energy is only redistributed), it varies between frames, and the harness matches a golden image of a sand-floor fixture. - 79.7.2.4 Create depth-based absorption — water color deepens with depth using Beer's Law scattering model
- 79.7.2.5 Implement underwater rendering mode — full underwater camera
with color absorption, volumetric light shafts, particle effects (GPU
convention, 79.0.1): a post-process chain that applies the per-channel
depth absorption of
maya-ocean/src/hydro.rs, light shafts from the caustics of 79.7.2.3, and a suspended-particlemaya-vfxtemplate. Verify: the rendered colour of a white target at depths of 1, 5 and 20 m matches thehydro.rsabsorption within a stated error, and the harness matches a golden image. - 79.7.2.6 Create surface-to-underwater transition — smooth camera transition with waterline split-screen effect (GPU convention, 79.0.1): evaluate the ocean height at the near plane per pixel column so that the above-water and underwater pipelines meet at a waterline with a meniscus band. Verify: for a camera half submerged, a test asserts that the pixels above the projected waterline use the above-water path and the ones below use the underwater path, and that a 60-frame descent shows no full-frame pop (frame-to-frame mean difference under a stated bound).
- 79.7.2.7 Implement underwater depth fog with configurable color and
density per water body: a per-water-body fog colour and density in
maya-ocean, applied exponentially by view distance in the underwater pass of 79.7.2.5. Verify: a unit test for the transmittance curve, and harness renders of a clear-lake and a murky-river preset that differ as configured at a fixed target distance. - 79.7.2.8 Create water surface distortion from raindrops (ripple
animation during rain) (GPU convention, 79.0.1): a ripple normal layer in
libs/maya/engine-core/crates/maya-renderer/shaders/maya/water/rain_ripples.wgslwith ring count and amplitude driven by the precipitation rate of the weather state. Verify: zero perturbation at a zero rate, ring radius growing at the configured speed across frames, and the harness matches a golden image at a moderate rate. - 79.7.2.9 Implement puddle rendering — screen-space or
deformation-buffer driven rain puddles with reflections: take the
deformation-buffer route. Accumulate water depth in the depressions of the
maya-terrain-deformheightmap from the rain rate minus per-material drainage, and render the wet areas with the reflection path of 79.7.2.1. Verify: a test asserts water gathers in the rut fixture's low points and nowhere else and drains after the rain stops, and the harness matches a golden image. - 79.7.2.10 Create water rendering integration tests (visual
regression): one harness suite,
cargo test -p maya-gpu-harness water_, that renders the fixtures of 79.7.2.1–.9 on lavapipe and compares each with its golden PNG under the tolerance of 79.0.1, with a documented command to regenerate the goldens. Verify: the suite is green on the Linux server, and a deliberate change to one shader constant makes exactly its fixture fail (run that once and record it).
79.7.3 Rivers, Lakes & Buoyancy#
- 79.7.3.1 Implement flow map system — 2D vector field defining water flow direction and speed for rivers
- 79.7.3.2 Create river spline tool — artists define path, system
generates flow maps, banks, and geometry (viewer convention, 79.0.3): a
RiverSplinedocument (control points with width and depth) inmaya-ocean, a generator that emits the flow map consumed byhydro.rs, the bank height offsets and the surface mesh, and an editor module underlibs/maya/tooling/src/debug-viewers/river-spline/. Verify: a test asserts that flow vectors are tangent to the spline within 5° and speed up where the river narrows (continuity), that a self-intersecting spline is rejected, and the viewer draws the banks of a fixture river. - 79.7.3.3 Implement waterfall rendering — particle-based spray +
geometric sheet with flow animation (GPU convention, 79.0.1): a sheet mesh
generated where a river spline of 79.7.3.2 drops beyond a slope threshold,
with scrolling flow coordinates, plus a spray
maya-vfxtemplate at the impact point scaled by the flow rate. Verify: a test detects the waterfall segment on a fixture river, the spray rate scales with the flow, and the harness matches a golden image. - 79.7.3.4 Create lake system — still water with wind-driven ripples, distinct from ocean simulation
- 79.7.3.5 Implement buoyancy simulation — Archimedes' principle with wave-height sampling for floating objects
- 79.7.3.6 Create multi-point buoyancy for boats — sample wave height at multiple hull points for pitch/roll
- 79.7.3.7 Implement water drag forces — submerged objects experience velocity-dependent resistance
- 79.7.3.8 Create floating debris system — dropped objects float, drift with current, wash ashore
- 79.7.3.9 Implement character swimming physics — stamina-based swimming, current affects movement, underwater breath
- 79.7.3.10 Create water physics integration tests (buoyancy accuracy, current effects, swimming mechanics)
79.8 GPU Procedural Foliage & Vegetation Interaction (Rust)#
GPU-generated grass blades with Bezier curves, vegetation interaction, and biome-specific ground cover — inspired by Ghost of Tsushima.
79.8.1 GPU Grass Rendering#
- 79.8.1.1 Create
maya-vegetationRust crate with compute shaders. Split 2026-09-18 because the two halves are in different states.- 79.8.1.1.a Crate scaffold. It exists at
libs/maya/engine-core/crates/maya-vegetation(blade.rs,distribution.rs,interaction.rs,wind.rs). Verify it under the checkbox rule (read the public API, run the adversarial scan,cargo test -p maya-vegetation) and close this child. - 79.8.1.1.b GPU blade generation (GPU convention, 79.0.1):
libs/maya/engine-core/crates/maya-renderer/shaders/maya/vegetation/grass_generate.wgslrebuilds each cubic-Bezier blade from the hash of its world position exactly asblade.rsdoes. Verify: the harness generates one 16×16 m tile for 8 frames on lavapipe and the read-back control points equal the CPUblade.rsoutput within 1 mm for every blade.
- 79.8.1.1.a Crate scaffold. It exists at
- 79.8.1.2 Implement grass blade compute shader — generate blades as cubic Bezier curves from terrain density map
- 79.8.1.3 Create per-blade variation — height, width, curvature, color randomized via hash of world position
- 79.8.1.4 Implement grass LOD — individual blades (0-10m), batch blades (10-50m), ground texture (50-200m), terrain color (200m+)
- 79.8.1.5 Create GPU indirect rendering with per-tile grass patches and frustum/occlusion culling (GPU convention, 79.0.1): a culling compute pass that writes the indirect draw arguments per tile from the camera frustum and a hierarchical depth buffer. Verify: for a fixture camera the read-back visible-tile list equals a CPU frustum test, tiles behind an occluder wall are dropped, and the harness matches a golden image.
- 79.8.1.6 Implement grass density map authoring — painted per-biome or per-terrain-layer
- 79.8.1.7 Create grass color variation by biome — savanna golden, temperate green, tundra sparse, wetland reeds
- 79.8.1.8 Implement grass rendering performance optimization (target <1.5ms GPU for visible grass tiles). The target named no GPU, so it is restated under the GPU convention (79.0.1): measure the generate, cull and draw passes for a 200 m view distance at 1920×1080 on the Mac's GPU, record the chip and the milliseconds as the baseline, keep 1.5 ms as the goal, and fail only on a regression of more than 20 %. Verify: a harness benchmark target prints the timing, the baseline is committed, and the blade-count-per-LOD table that produced it is written here.
- 79.8.1.9 Create grass visual quality presets (ultra → individual blades, low → billboard patches)
- 79.8.1.10 Implement grass rendering integration with terrain system:
place blades on the terrain height and normal, mask them by terrain
material and the density map of
distribution.rs, and flatten them wheremaya-terrain-deformreports compression. Verify: a test asserts that no blade root is more than 1 cm off the terrain height, that no blades grow on rock or road material, and that a trampled path shows a lower blade height.
79.8.2 Vegetation Interaction#
- 79.8.2.1 Implement character-to-grass interaction — blades deflect away from character movement capsule
- 79.8.2.2 Create damped wave spring-back — deflected blades oscillate back to rest with natural bounce
- 79.8.2.3 Implement interaction force proportional to movement speed — walking gently parts grass, sprinting flattens it
- 79.8.2.4 Create vehicle interaction — wider zone, stronger deflection, destruction for crushed grass
- 79.8.2.5 Implement wind-driven grass animation — global wind direction as base sway with gust wave patterns (linked to §79.9)
- 79.8.2.6 Create sheltered area detection — grass behind buildings/walls has reduced wind effect
- 79.8.2.7 Implement animal grazing interaction — grazing animals visually shorten grass, herds create trampled paths
- 79.8.2.8 Create tree branch deflection — characters pushing through bushes bends branches with spring-back
- 79.8.2.9 Implement leaf particle emission on vegetation impact: a
leaf_bursttemplate inlibs/maya/engine-core/crates/maya-vfx/src/templates.rsspawned by the impact events ofmaya-vegetation/src/interaction.rs, with a count scaled by impulse and a colour taken from the plant's biome palette. Verify: a test asserts no burst below the impulse threshold, a count proportional to the impulse above it, and that the leaves drift with themaya-windsample at the impact point. - 79.8.2.10 Create tree sway system — trunk, branch, and leaf layers respond to wind at different frequencies
79.8.3 SpeedTree & Biome Integration#
- 79.8.3.1 Implement SpeedTree asset import pipeline — load SpeedTree
models with wind animation data. The SpeedTree SDK and its
.spm/.stformats are licensed commercially with no free tier for an engine integration, and the owner holds no licence (stated 2026-09-18). The three-layer tree sway inmaya-vegetation/src/wind.rsalready covers wind on imported glTF trees.blocked:external - 79.8.3.2 Create falling leaves seasonal particle system for deciduous
trees in autumn: a
falling_leavestemplate inmaya-vfxwhose emission rate follows the autumn leaf-drop curve ofmaya-seasonsand the wind gusts ofmaya-wind, with a tumbling flutter motion and ground accumulation up to a cap. Verify: a test asserts zero emission outside autumn, a rate that peaks mid-autumn and rises with gust strength, and that settled leaves never exceed the cap. - 79.8.3.3 Implement fruit/nut drop from trees as interactable physics objects
- 79.8.3.4 Create vegetation density driven by soil moisture, altitude, and temperature from world generation
- 79.8.3.5 Implement vegetation LOD transitions — seamless crossfade between full tree mesh and impostor billboard
79.9 Wind Propagation & Vorticle System (Rust)#
Unified wind simulation driving grass, trees, cloth, particles, hair, and audio — inspired by Ghost of Tsushima's vorticle system.
79.9.1 Wind Field & Vorticles#
- 79.9.1.1 Create
maya-windRust crate integrated with maya-physics - 79.9.1.2 Implement global directional wind — direction, speed, gust frequency and intensity set by weather system
- 79.9.1.3 Create wind field grid — 2D heightfield or 3D grid storing wind vectors at ~1-2m spatial resolution
- 79.9.1.4 Implement point wind sources — explosions (radial outward), fans, vents, propellers
- 79.9.1.5 Create line wind sources — vehicle wakes with turbulence along movement path
- 79.9.1.6 Implement volume wind sources — storms and tornadoes with rotational + uplift components
- 79.9.1.7 Create wind occlusion — buildings and terrain block wind using simplified raycast or distance field
- 79.9.1.8 Implement wind channeling — valleys and streets funnel wind (Venturi effect approximation)
- 79.9.1.9 Create vorticle simulation — lightweight vortex particles with position, axis, strength, radius, lifetime
- 79.9.1.10 Implement vorticle advection, decay, and spatial hashing for efficient nearby queries
- 79.9.1.11 Create wind sampling API — any system queries wind force at a position → returns aggregate from vorticles + global wind
- 79.9.1.12 Implement wind consumer integration — grass, trees, cloth, hair, particles, flags, water surface, sound all sample wind field
- 79.9.1.13 Create gameplay wind effects — strong wind affects projectile trajectory and character movement on exposed ridges
- 79.9.1.14 Implement wind debugging visualization — vector field
overlay, vorticle particles, wind strength heatmap (viewer convention,
79.0.3): a
WindDebugSnapshotinmaya-wind(a sampled vector grid, the vorticle positions and radii, the strength field) and a viewer underlibs/maya/tooling/src/debug-viewers/wind/that draws arrows, vorticle circles and a heat-map. Verify: a crate test asserts the snapshot equals the field sampled at the same points, and a vitest spec asserts one arrow per grid sample and one circle per vorticle. - 79.9.1.15 Create wind system performance benchmark (target <0.2ms CPU with ~1000 active vorticles)
79.10 Vehicle Physics & Deformation (Rust)#
Advanced suspension, tire models, drivetrain, and real-time physically-simulated vehicle deformation — inspired by GTA V/6 and Forza.
79.10.1 Vehicle Dynamics#
- 79.10.1.1 Create
maya-vehiclesRust crate integrated with maya-physics - 79.10.1.2 Implement per-wheel spring-damper suspension with configurable travel, stiffness, damping, and anti-roll bars
- 79.10.1.3 Create weight transfer calculation for acceleration, braking, and cornering
- 79.10.1.4 Implement Pacejka "Magic Formula" tire model — slip angle → lateral force, slip ratio → longitudinal force
- 79.10.1.5 Create surface material grip variation — asphalt > gravel > mud > ice affecting tire force curves
- 79.10.1.6 Implement combined slip handling — simultaneous braking and cornering with force circle limiting
- 79.10.1.7 Create engine torque curve, RPM, gear ratios, differential types (open, limited-slip, locked)
- 79.10.1.8 Implement FWD, RWD, AWD drivetrain configurations
- 79.10.1.9 Create aerodynamics — drag (Cd × area × v²), downforce at speed, lift for off-road jumps
- 79.10.1.10 Implement transmission modes — manual, automatic, sequential shifting
79.10.2 Vehicle Deformation#
- 79.10.2.1 Implement simplified node-beam deformation model — vehicle body as mesh of nodes connected by beams with stress thresholds
- 79.10.2.2 Create force propagation through beam network — impact force spreads, beams exceeding threshold deform permanently
- 79.10.2.3 Implement deformation affecting visual mesh — dented panels,
bent frame visible in real-time (GPU convention, 79.0.1): upload the
per-vertex deformation offsets that
maya-vehiclescomputes to a storage buffer, apply them in the vertex stage, and recompute normals for the touched vertices. Verify: after a fixture side impact, the read-back vertex positions equal the CPU deformation within 1 mm, the recomputed normals stay unit length, and the harness matches a golden image of the dented door. - 79.10.2.4 Create deformation affecting physics — bent axle pulls steering, damaged wheel reduces grip
- 79.10.2.5 Implement component damage — windows (crack/shatter), doors (dent/jam/fall off), hood/trunk, lights, engine
- 79.10.2.6 Create wheel puncture system — flat tire reduces speed and pulls to affected side
- 79.10.2.7 Implement deformation LOD — full node-beam close, simplified at distance, no physics for off-screen vehicles
- 79.10.2.8 Create motorcycle physics — lean, counter-steering, low-speed balance, ragdoll dismount on crash
- 79.10.2.9 Implement boat physics — buoyancy, water resistance, wave response, propeller thrust (linked to §79.7)
- 79.10.2.10 Create aircraft physics — lift, drag, thrust, control surfaces, stall mechanics
79.10.3 Vehicle Audio & Integration#
- 79.10.3.1 Implement engine RPM-driven audio — layered samples (idle,
low, mid, high RPM, redline) with pitch shifting (audio convention,
79.0.2). Use the synthesis route, which needs no recordings: drive
maya-audio/src/vehicle_engine_sounds.rsfrom the RPM, load and gear state ofmaya-vehicles, cross-fading its combustion, intake and transmission layers across the five RPM bands. Verify: an offline render of a 0 → redline sweep shows the fundamental tracking RPM × cylinders ÷ 120 within 2 %, no click at band boundaries (no sample-to-sample jump above a stated bound), and a louder intake layer at full throttle than on overrun. - 79.10.3.2 Create tire-surface audio — asphalt screech, gravel crunch,
mud squelch, snow crunch (audio convention, 79.0.2): drive
rolling_sliding_sounds.rsfrom each wheel's slip ratio, slip angle and the surface material under it, with one preset per surface. Verify: offline renders show no screech below the slip threshold on asphalt, a granular (impulsive) envelope on gravel and a tonal one on asphalt, asserted by crest factor, and level scaling with slip. - 79.10.3.3 Implement collision audio — force-dependent from tap to
crash (audio convention, 79.0.2): map the collision impulse and the
deformed volume from
maya-vehiclestoimpact_sounds.rsparameters (a metal panel resonance bank, plus glass and debris layers above a threshold). Verify: offline renders at three impulses order by RMS and by spectral bandwidth, and the glass layer is present only above its threshold. - 79.10.3.4 Create wind noise scaling with vehicle speed (audio
convention, 79.0.2): feed the vehicle's air speed (its velocity minus the
maya-windsample) and the open or closed cabin state towind_air_sounds.rs. Verify: offline renders at 30, 90 and 150 km/h show the level rising by roughly 18 dB per doubling of speed within a stated tolerance, and a closed cabin attenuates the high band. - 79.10.3.5 Implement vehicle haptic feedback — engine vibration, road
surface texture, collision impact (linked to §79.18): produce
maya-hapticseffects from the vehicle state, with engine vibration frequency from RPM, road texture from the surface material and speed, and a collision transient from the impulse, mixed through the priority layers ofmaya-haptics/src/effect.rs. Verify: a test asserts the waveform frequency tracks RPM, that a collision pre-empts the road texture by priority, and that the accessibility scale ofplatform.rsattenuates all three. How it feels on a controller is a manual residual that needs the device.
79.11 Crowd Simulation at Scale (Rust)#
10,000+ on-screen NPCs with LOD-tiered AI, GPU-instanced rendering, and emergent crowd behaviors — inspired by AC Unity.
79.11.1 Crowd LOD & Rendering#
- 79.11.1.1 Create
maya-crowdsRust crate with GPU instancing. Split 2026-09-18 because the two halves are in different states.- 79.11.1.1.a Crate scaffold. It exists at
libs/maya/engine-core/crates/maya-crowds(lod.rs,path.rs,behavior.rs). Verify it under the checkbox rule (read the public API, run the adversarial scan,cargo test -p maya-crowds) and close this child. - 79.11.1.1.b GPU instancing (GPU convention, 79.0.1): fill one
instance buffer per LOD tier from
CrowdSimand draw the Bulk and Impostor tiers withlibs/maya/engine-core/crates/maya-renderer/shaders/maya/crowds/instanced_crowd.wgsl. Verify: the harness draws 10,000 agents for 8 frames on lavapipe with one indirect draw per tier, the read-back instance transforms equal the CPU state, and a golden image matches.
- 79.11.1.1.a Crate scaffold. It exists at
- 79.11.1.2 Implement Tier 1 Full NPC (0-15m) — complete AI, animation, physics, dialogue, inventory
- 79.11.1.3 Create Tier 2 Autonomous (15-40m) — simplified AI, path- following, reduced polygon count, shared animation instances
- 79.11.1.4 Implement Tier 3 Bulk (40-100m) — low-poly mesh (~500 tris), vertex-animated walk cycle, no AI, Shepherd path following
- 79.11.1.5 Create Tier 4 Impostor (100m+) — billboard sprite or point- cloud with parallax animation
- 79.11.1.6 Implement seamless LOD transition with distance hysteresis bands (promote at 14m, demote at 16m)
- 79.11.1.7 Create animation texture baking — bone transforms stored in texture for GPU vertex shader sampling (no CPU skinning for Bulk tier) (GPU convention, 79.0.1): a baker that writes each clip's per-frame bone matrices into an RGBA32F texture, and vertex-stage skinning that samples it by the instance's clip and phase. Verify: the GPU-skinned vertex positions of a fixture walk clip equal CPU skinning within 1 mm at ten sampled frames, and the baked texture round-trips through the asset format byte for byte.
- 79.11.1.8 Implement variety system — multiple clothing/skin combinations via material parameters on shared meshes
- 79.11.1.9 Create shadow LOD — Bulk NPCs cast capsule proxy shadows,
Full NPCs cast skeletal shadows (GPU convention, 79.0.1): an analytic
capsule occlusion term for the Bulk tier and the regular shadow pass for
the Full tier, chosen by the tier from
lod.rs. Verify: a test asserts that the shadow path switches exactly at the tier boundary with the same hysteresis as the LOD, and the harness matches a golden image holding one Full and one Bulk agent under the same light. - 79.11.1.10 Implement crowd rendering benchmark (target 10,000 visible NPCs at 60fps)
79.11.2 Crowd Behavior#
- 79.11.2.1 Implement Shepherd paths — predefined closed-loop routes with offset and speed variation per NPC
- 79.11.2.2 Create crowd density maps per area — market=dense, residential=sparse, adjustable by time of day
- 79.11.2.3 Implement time-of-day density variation — morning commute, afternoon shopping, evening entertainment, night sparse
- 79.11.2.4 Create event response — crowds gather around performers, flee from combat, clear path for vehicles
- 79.11.2.5 Implement emergent lane formation — opposing pedestrian flows self-organize using flocking steering behaviors
- 79.11.2.6 Create crowd noise audio — layered ambient with
density-responsive volume and random individual barks (audio convention,
79.0.2): a walla bed built by
granular_synthesis.rsover Kokoro-generated speech grains (unintelligible by construction), with gain and grain density driven by the local crowd density frommaya-crowds, plus sparse intelligible barks from a short Kokoro phrase list. First install the Kokoro ONNX model on the Linux server and record the command and version; park only with a named failed install attempt. Verify: offline renders at three densities order by RMS, barks occur at the configured mean rate within a tolerance, and the output is deterministic for a seed. - 79.11.2.7 Implement crowd reaction audio — collective gasp, cheer,
scream on events (audio convention, 79.0.2): reaction one-shots built the
same way as 79.11.2.6 (many detuned, time-jittered voices), triggered by
the event responses and the panic contagion of
maya-crowds/src/behavior.rs, with onset spread following the contagion wave. Verify: a test asserts the reaction type per event, that onset times follow the contagion front across the crowd, and an offline render passes the convention's assertions. - 79.11.2.8 Create crowd weather response — seek shelter in rain, open umbrellas, change clothing in cold
- 79.11.2.9 Implement crowd panic propagation — one NPC fleeing triggers nearby NPCs to flee (emotional contagion)
- 79.11.2.10 Create crowd integration tests simulating various density and event scenarios
79.12 SSD-Optimized Asset Streaming (Rust)#
DirectStorage and io_uring integration for bypassing CPU in storage→GPU transfers — inspired by Spider-Man 2.
79.12.1 Direct Storage Integration#
- 79.12.1.1 Implement Windows DirectStorage API integration — bypass CPU
for NVMe→GPU transfers: a
directstoragebackend behind awindowsfeature oflibs/maya/engine-core/crates/maya-streaming, using the redistributable DirectStorage runtime through thewindowscrate, that satisfies the same request interface as the portable path. Neither fleet machine runs Windows. Attempt it on a GitHub-hostedwindows-latestrunner, which offers Direct3D 12 through the WARP software adapter and the Agility SDK: add a workflow that builds the crate'swindowsfeature and runs its tests there, and record the run URL. Park only with a named failed attempt (the runner, the SDK version and the error). Verify: on the runner, a test enqueues 100 file reads into GPU buffers through DirectStorage and the read-back bytes equal the files. The throughput claim needs real NVMe and GPU hardware and belongs to 79.12.1.10. - 79.12.1.2 Create GPU decompression of GDeflate-compressed assets via
compute shader, on the DirectStorage path: compress the fixture assets
with the open-source GDeflate reference codec from Microsoft's
DirectStorage repository (MIT licence; record the commit) and let the
DirectStorage queue of 79.12.1.1 decompress them on the GPU. Neither fleet
machine runs Windows. Attempt it on a GitHub-hosted
windows-latestrunner, which offers Direct3D 12 through the WARP software adapter and the Agility SDK: add a workflow that builds the crate'swindowsfeature and runs its tests there, and record the run URL. Park only with a named failed attempt (the runner, the SDK version and the error). Verify: on the runner, the decompressed GPU buffers equal the source bytes for every fixture asset, including one larger than a single 64 KiB GDeflate tile. - 79.12.1.3 Implement io_uring async I/O on Linux for minimal system
call overhead: an
io_uringbackend inlibs/maya/engine-core/crates/maya-streamingon theio-uringcrate (add it to the workspaceCargo.tomland record the version) with registered buffers and batched submission, which falls back to the thread-pool reader whenio_uring_setupis refused (containers often deny it under seccomp). Verify: on the Linux server (kernel 6.8) a test reads 1,000 fixture files through the ring and gets bytes equal tostd::fs::read, the fallback engages when the ring cannot be created, and a benchmark records system calls per read (fromstrace -c) for both paths. - 79.12.1.4 Create custom GPU decompression compute shader for
non-Windows platforms (GPU convention, 79.0.1): port the GDeflate tile
decoder to
libs/maya/engine-core/crates/maya-renderer/shaders/maya/streaming/gdeflate_decode.wgsl, with the open-source reference codec as the CPU ground truth, so Linux and macOS decompress on the GPU without DirectStorage. Verify: the harness decompresses the fixture corpus on lavapipe and on the Mac byte-identically to the CPU codec, and a corrupted tile is reported as an error rather than returned as data. - 79.12.1.5 Implement asset colocated data layout — group assets by world partition for sequential SSD reads
- 79.12.1.6 Create streaming priority system — P0 visible, P1 predicted, P2 nearby occluded, P3 prefetch
- 79.12.1.7 Implement GPU/system memory budget management with LRU eviction and priority weighting
- 79.12.1.8 Create portal-based pre-streaming — stream destination world partition during transition animation
- 79.12.1.9 Implement fast travel optimization — target <2s load time on NVMe with background streaming during vignette
- 79.12.1.10 Create streaming performance benchmarks comparing
DirectStorage vs traditional I/O path. The portable half is actionable
now: a benchmark target in
libs/maya/engine-core/crates/maya-streamingthat loads a fixed 2 GiB fixture set through the thread-pool reader, the io_uring path of 79.12.1.3 and the GPU decoder of 79.12.1.4, reporting MiB/s and CPU time, run on the Linux server and the Mac with the results committed. The DirectStorage column needs a Windows host with an NVMe drive and a discrete GPU, because a CI runner's virtual disk and WARP adapter measure nothing meaningful; the fleet has no such machine (stated 2026-09-18).blocked:hardware
79.13 Mesh Shaders, Work Graphs & DXR 1.2 (Rust)#
Cutting-edge GPU pipeline features for maximum rendering performance.
79.13.1 Mesh Shader Pipeline#
- 79.13.1.1 Implement meshlet generation preprocessor — divide source meshes into 64-128 vertex meshlets with bounding sphere and normal cone
- 79.13.1.2 Create task shader — per-meshlet frustum/occlusion/backface
culling and LOD selection (GPU convention, 79.0.1). First establish
support and record it here:
vulkaninfoon the Linux server's lavapipe must listVK_EXT_mesh_shader, and the pinnedwgpumust expose mesh-shader pipelines; if wgpu does not, drive this one path throughashinside the harness. Park only with a named failed attempt. Then write the task stage, which culls the meshlets oflibs/maya/engine-core/crates/maya-meshletby frustum, by normal cone and by the hierarchical depth buffer, and emits mesh-shader work for the survivors. Verify: the surviving meshlet set read back from the GPU equals a CPU cull of the same fixture scene. - 79.13.1.3 Implement mesh shader — generate per-meshlet vertices and primitives for rasterizer (GPU convention, 79.0.1), on the device and API chosen in 79.13.1.2: the mesh stage expands each surviving meshlet's vertex and index ranges into primitives. Verify: the harness render of the fixture scene through the mesh-shader path is pixel-identical, within the 79.0.1 tolerance, to the vertex-pipeline render of 79.13.1.4.
- 79.13.1.4 Create fallback vertex pipeline for hardware without mesh shader support (GPU convention, 79.0.1): a compute pass that culls meshlets as in 79.13.1.2, compacts an index buffer and draws it indirectly, chosen at start-up when the device lacks mesh shaders (Metal through wgpu today). Verify: the harness renders the fixture scene through this path on lavapipe and on the Mac and matches the golden image, and a test asserts the path selection from the reported device features.
- 79.13.1.5 Implement mesh shader integration with Nanite-class
virtualized geometry clusters: feed the task stage of 79.13.1.2 from the
cluster hierarchy that
maya-renderer/src/cluster_cull.rsandcluster_mesh.rsmodel, choosing the cluster LOD by screen-space error. Verify: a test asserts that the clusters selected on the GPU equal the CPUcluster_cullselection for three camera distances, with no cracks (no unshared boundary edges) between neighbouring LODs in the rendered index set.
79.13.2 Work Graphs & DXR 1.2#
- 79.13.2.1 Implement DirectX 12 Work Graph definition for
GPU-autonomous rendering pipeline: a
d3d12module behind awindowsfeature ofmaya-rendererthat declares a work graph (cull node → LOD node → draw-record node) with the Agility SDK. Neither fleet machine runs Windows. Attempt it on a GitHub-hostedwindows-latestrunner, which offers Direct3D 12 through the WARP software adapter and the Agility SDK: add a workflow that builds the crate'swindowsfeature and runs its tests there, and record the run URL. Park only with a named failed attempt (the runner, the SDK version and the error). Verify: on the runner, the graph compiles, dispatches on the fixture scene, and the records written by its final node equal the CPU reference list. - 79.13.2.2 Create GPU-side LOD selection spawning appropriate render work items: the LOD node of the work graph of 79.13.2.1 picks a cluster LOD per instance from screen-space error and spawns one draw record per selected cluster, with a compute-shader equivalent on wgpu for every other platform. Verify: the record set equals the CPU selection for three camera distances, on the wgpu path under the GPU convention and on the work-graph path on the Windows runner.
- 79.13.2.3 Implement Opacity Micromaps (OMM) for all alpha-tested
geometry — foliage, fences, grates. The baker is portable and actionable:
bake 2-state and 4-state micromaps from alpha textures in
maya-renderer, and verify that a test classifies the micro-triangles of a fence fixture against a CPU alpha lookup with no misclassified opaque or transparent cell. Attaching them to a BLAS needs a driver that exposes OMM: run the capability probe of 79.13.2.6 first, and if WARP does not report it, that probe is the named failed attempt and the attach step waits on hardware. Depends on 79.13.2.6 (stated 2026-09-18).blocked:upstream - 79.13.2.4 Create OMM integration into BLAS build with measured 2x+
speedup verification. A traversal speed-up can only be measured on a GPU
with hardware ray tracing and OMM support. Needs a Windows host with a DXR
1.2-class discrete GPU; the fleet is a Mac and a GPU-less Linux server,
and the WARP software adapter on a CI runner can neither expose this
feature nor measure it (stated 2026-09-18).
blocked:hardware - 79.13.2.5 Implement Shader Execution Reordering (SER) — reorder
hit/miss shader execution by material for coherence. SER is a hardware
scheduling feature; on a device without it the calls are accepted and do
nothing, so neither its effect nor its correctness can be observed. Needs
a Windows host with a DXR 1.2-class discrete GPU; the fleet is a Mac and a
GPU-less Linux server, and the WARP software adapter on a CI runner can
neither expose this feature nor measure it (stated 2026-09-18).
blocked:hardware - 79.13.2.6 Create DXR 1.2 feature detection and graceful fallback for
non-supporting hardware: a capability probe in the
d3d12module that reports work graphs, the ray tracing tier, OMM, SER and cooperative vectors fromCheckFeatureSupport, and a renderer policy that maps each missing feature to its fallback (the compute LOD path, no OMM, the plain closest-hit order, CPU or compute inference). Neither fleet machine runs Windows. Attempt it on a GitHub-hostedwindows-latestrunner, which offers Direct3D 12 through the WARP software adapter and the Agility SDK: add a workflow that builds the crate'swindowsfeature and runs its tests there, and record the run URL. Park only with a named failed attempt (the runner, the SDK version and the error). Verify: on the runner the probe's report is committed as a fixture, a unit test asserts the fallback chosen for that report and for three synthetic reports, and the report is linked from 79.13.2.3 and 79.13.2.7. - 79.13.2.7 Implement Cooperative Vectors (SM 6.9) integration with
Phase 72.1 neural rendering (that phase is complete: 45 of 45 items
checked). Run the capability probe of 79.13.2.6 first. If the preview
Agility SDK on the Windows runner reports cooperative-vector support under
WARP, evaluate the small MLP of
maya-renderer/src/neural_radiance_cache.rsthrough it and verify that the outputs equal the CPU evaluation within 1e-4. If it does not, that probe is the named failed attempt and the item waits on a GPU that implements SM 6.9. Depends on 79.13.2.6 (stated 2026-09-18).blocked:upstream - 79.13.2.8 Create mesh shader + DXR 1.2 combined performance
benchmarks. Needs a Windows host with a DXR 1.2-class discrete GPU; the
fleet is a Mac and a GPU-less Linux server, and the WARP software adapter
on a CI runner can neither expose this feature nor measure it (stated
2026-09-18).
blocked:hardware - 79.13.2.9 Implement Vulkan equivalent paths (VK_EXT_mesh_shader,
VK_KHR_cooperative_matrix) (GPU convention, 79.0.1).
VK_EXT_mesh_shaderis the path of 79.13.1.2 and 79.13.1.3 on lavapipe, so what is left here is the cooperative-matrix route: checkvulkaninfoforVK_KHR_cooperative_matrixon lavapipe and record the result; where it is present, run the MLP of 79.13.2.7 through it, and otherwise fall back to a plain compute matrix multiply. Verify: the outputs equal the CPU evaluation within 1e-4 on whichever path the device offers, and the path taken is logged. - 79.13.2.10 Create GPU pipeline feature documentation and hardware
compatibility matrix:
libs/maya/engine-core/crates/maya-renderer/docs/gpu-feature-matrix.mdwith one row per feature of §79.13 (mesh shaders, work graphs, OMM, SER, cooperative vectors, the compute fallbacks) and one column per device actually probed (lavapipe on the Linux server, the Mac's GPU through Metal, WARP on the Windows runner), each cell citing the probe output that fills it. Verify: every cell links to a committed probe fixture or test, and no cell holds a claim about hardware nobody ran.
79.14 Advanced Skin, Eye & Hair Rendering (Rust)#
Photorealistic human rendering with dual-lobe SSS, multi-layer eyes, and strand-based hair — MetaHuman-class quality.
79.14.1 Advanced Skin#
- 79.14.1.1 Create
maya-character-renderRust crate with specialized shaders. Split 2026-09-18 because the two halves are in different states.- 79.14.1.1.a Crate scaffold. It exists at
libs/maya/engine-core/crates/maya-character-render(skin.rs,eye.rs,hair.rs). Verify it under the checkbox rule (read the public API, run the adversarial scan,cargo test -p maya-character-render) and close this child. - 79.14.1.1.b Shader plumbing (GPU convention, 79.0.1): a
libs/maya/engine-core/crates/maya-renderer/shaders/maya/character/directory with the shared skin, eye and hair parameter structs laid out exactly as the crate's Rust types (checked by a layout test), and one smoke shader that shades a sphere with theskin.rsscattering profile. Verify: the harness renders the sphere for 8 frames on lavapipe and matches a golden image, and the layout test fails when a Rust field is reordered.
- 79.14.1.1.a Crate scaffold. It exists at
- 79.14.1.2 Implement separable subsurface scattering (sSSS) —
multi-pass screen-space blur with configurable epidermis/dermis profiles
(GPU convention, 79.0.1): horizontal and vertical passes in
libs/maya/engine-core/crates/maya-renderer/shaders/maya/character/sss_blur.wgslwhose kernels come from the diffusion profiles inskin.rs, with depth-aware weights. Verify: the blurred response to a one-pixel white line matches the CPU profile's radial falloff per channel within a stated error (red scattering widest), and energy is conserved within 2 %. - 79.14.1.3 Create per-skin-type scattering profiles (light, medium, dark)
- 79.14.1.4 Implement transmittance through thin geometry — ears,
nostrils, fingers backlit by bright light (GPU convention, 79.0.1):
estimate thickness from the shadow-map depth difference and apply the
skin.rstransmittance profile to back lighting. Verify: a test asserts that transmitted radiance falls with thickness according to the profile for a slab fixture at 1, 3 and 10 mm, and the harness matches a golden image of a backlit ear fixture. - 79.14.1.5 Create pore-level normal maps (4K+) blended with base normals: blend a tiling micro-normal (pore) map with the base normal by reoriented normal mapping, masked per face region, in the skin shader. Use a procedurally generated pore map (cellular noise) as the fixture; an artist-made 4K pore map is content and not part of this item. Verify: the blended normals stay unit length, the blend equals the base normal where the mask is zero, and the harness matches a golden image of a close-up.
- 79.14.1.6 Implement micro-wrinkle system — wrinkle maps activated by FACS blend shapes
- 79.14.1.7 Create blood flow simulation — subsurface color shift for anger (redness), fear (pallor), exertion (flush)
- 79.14.1.8 Implement peach fuzz — fine facial hair strand layer
catching rim light (GPU convention, 79.0.1): a short-strand layer
generated by
hair.rsover a face-region density mask, shaded with its Marschner model at low opacity. Verify: a test asserts the strand length and density ranges per region, and harness renders with a rim light show a brighter silhouette band than the same fixture with the layer off. - 79.14.1.9 Create sweat/oil specular dynamic layer under stress/heat
- 79.14.1.10 Implement bruising progression — impact → redness → purple → yellow → healed over game time
79.14.2 Advanced Eyes#
- 79.14.2.1 Implement multi-layer eye model — sclera (SSS + vein
texture), iris (parallax-mapped with fiber detail), cornea (refractive
dome) (GPU convention, 79.0.1):
libs/maya/engine-core/crates/maya-renderer/shaders/maya/character/eye.wgslwith the three layers, driven by the pupil and gaze state ofeye.rs, using procedural vein and iris-fibre patterns as fixtures. Verify: the harness matches golden images at pupil diameters of 2 mm and 7 mm, and a test asserts that the rendered pupil radius tracks theeye.rsdilation value. - 79.14.2.2 Create pupil dilation/contraction responding to ambient light level
- 79.14.2.3 Implement corneal refraction creating parallax shift on iris at viewing angles: refract the view ray through the corneal dome (index of refraction 1.376) before sampling the iris plane in the shader of 79.14.2.1. Verify: the rendered iris-centre shift at view angles of 0°, 30° and 60° matches a CPU Snell's-law computation within one pixel.
- 79.14.2.4 Create tear film wet specular layer with occasional tear formation: a thin, smooth specular layer over the cornea and sclera, with a tear-line meniscus on the lower lid whose fill level is driven by the emotion state and wells over into a tear above a threshold. Verify: a test asserts that the meniscus level follows the driver and spills only above the threshold, and harness renders show a sharper highlight than the dry-eye fixture.
- 79.14.2.5 Implement eye caustics — light entering cornea creates highlight pattern on iris: an analytic caustic term that brightens the side of the iris opposite the light, from the light direction and the corneal refraction of 79.14.2.3. Verify: a test asserts that the caustic centroid lies opposite the light azimuth and moves with it, and that its energy stays under a stated fraction of the incident light.
- 79.14.2.6 Create eye micro-saccades, smooth pursuit tracking, reflexive blinking at 15-20/minute
- 79.14.2.7 Implement bloodshot/tired eye overlay based on character fatigue state
- 79.14.2.8 Create eyelid ambient occlusion shadow on eye surface: an
analytic occlusion band on the eyeball from the lid positions of
eye.rs(the blink state), darkening the sclera under the upper lid. Verify: a test asserts that the band follows the lid during a blink and vanishes on the fully exposed area, and the harness matches golden images at three lid positions.
79.14.3 Strand-Based Hair & Fur#
- 79.14.3.1 Implement hair strand generation — root placement from scalp density map, guide + interpolated strands
- 79.14.3.2 Create per-strand shape — Bezier curves with curl, wave, length variation (30K-100K strands per head)
- 79.14.3.3 Implement hair physics — mass-spring or position-based dynamics, head collision, strand-strand collision
- 79.14.3.4 Create wind-responsive hair — per-strand force sampling from wind system (§79.9)
- 79.14.3.5 Implement Marschner hair shading model — R, TT, TRT specular lobes for realistic highlights
- 79.14.3.6 Create deep opacity maps for hair self-shadowing (GPU
convention, 79.0.1): render the strands of
hair.rsfrom the light into a depth-start map plus three opacity layers, and look the shadow up when shading a strand. Verify: for a slab of uniform strand density, the shadow read at three depths matches the analytic exponential transmittance within a stated error. - 79.14.3.7 Implement hair transparency sorting via per-pixel linked lists or order-independent transparency (GPU convention, 79.0.1): take weighted-blended order-independent transparency, because it needs no unbounded per-pixel storage and runs on every wgpu backend; per-pixel linked lists are the rejected alternative. Verify: a render of overlapping strand layers is identical for two different submission orders, and it stays within a stated error of a CPU back-to-front composite of the same fixture.
- 79.14.3.8 Create fur rendering — shell method at distance, strand
method close-up, species-specific patterns: shell layers beyond a distance
threshold and
hair.rsstrands inside it, with a cross-fade, and a per-species pattern (length, density and colour map) keyed by the species templates ofmaya-ecology. Verify: a test asserts that the method switches at the threshold with hysteresis, and the harness matches golden images of one fixture at near and far distance whose mean colour differs by less than a stated delta across the switch. - 79.14.3.9 Implement hair LOD — full strand count near, reduced at distance, shell approximation far
- 79.14.3.10 Create hair rendering performance benchmark (target <0.5ms GPU for single character hair)
79.15 GPU Particle System — Niagara-Class (Rust)#
Data-driven GPU particle system for all VFX — fire, smoke, sparks, weather, magic, blood, dust, volumetric fog patches.
79.15.1 GPU Particle Simulation#
- 79.15.1.1 Create
maya-vfxRust crate with compute shader particle simulation pipeline. Split 2026-09-18 because the two halves are in different states.- 79.15.1.1.a Crate scaffold. It exists at
libs/maya/engine-core/crates/maya-vfx(emitter.rs,forces.rs,sim.rs,templates.rs). Verify it under the checkbox rule (read the public API, run the adversarial scan,cargo test -p maya-vfx) and close this child. - 79.15.1.1.b GPU simulation (GPU convention, 79.0.1):
libs/maya/engine-core/crates/maya-renderer/shaders/maya/vfx/particle_update.wgslruns spawn, forces (including the curl noise offorces.rs), integration and death on storage buffers with a dead-list allocator. Verify: the harness steps one fixed-seed fire template for 8 frames on lavapipe, and the read-back positions and ages equal the CPUsim.rsrun within 1e-4, with equal live counts every frame.
- 79.15.1.1.a Crate scaffold. It exists at
- 79.15.1.2 Implement particle data GPU buffer — position, velocity, age, size, color, rotation, custom attributes
- 79.15.1.3 Create emitter types — point, sphere, box, cone, mesh surface, skeletal socket, spline, ring
- 79.15.1.4 Implement burst and rate emission modes with configurable particle count limits
- 79.15.1.5 Create force modules — gravity, wind (from §79.9), drag, turbulence noise, vortex, attraction/repulsion points
- 79.15.1.6 Implement collision module — scene depth buffer collision with bounce, stick, slide, kill behaviors
- 79.15.1.7 Create size-over-lifetime and color-over-lifetime curve modules
- 79.15.1.8 Implement rotation, velocity-alignment, and noise displacement modules
- 79.15.1.9 Create particle trails/ribbons — connected strips for sword swipes, bullet tracers, magic trails
- 79.15.1.10 Implement sub-emitter system — particle death spawns child particles (spark → smoke on impact)
- 79.15.1.11 Create curl noise module for turbulent smoke/fire motion
- 79.15.1.12 Implement particle-particle interaction forces (flocking, repulsion)
79.15.2 Particle Rendering & Templates#
- 79.15.2.1 Implement billboard rendering (camera-facing quad) with sprite sheet animation (GPU convention, 79.0.1): expand each live particle into a camera-facing quad in the vertex stage, with sprite-sheet frame selection and interpolation from its age. Verify: the quads' read-back normals face the camera within 0.1°, the sheet frame index follows age ÷ lifetime, and the harness matches a golden image.
- 79.15.2.2 Create mesh particle rendering — GPU-instanced 3D meshes per particle (debris, sparks, leaves): draw one mesh instance per live particle straight from the simulation buffer of 79.15.1.1.b with an indirect draw, taking orientation from its angular velocity. Verify: the instance count equals the live count with no CPU readback in the draw path, and the harness matches a golden image of a debris burst.
- 79.15.2.3 Implement ribbon/trail rendering — connected geometry
between sequential particles: build a camera-facing strip per trail from
the trail history that
sim.rskeeps, with width and opacity over age and a break where the trail ends. Verify: a test asserts that the strip's vertex count equals twice the trail points, that no segment bridges two separate trails, and the harness matches a golden image. - 79.15.2.4 Create volumetric particle rendering — raymarched volume per particle for dense smoke/fog (GPU convention, 79.0.1): splat the particle densities into a low-resolution froxel grid and ray-march the grid with single scattering, which is cheaper than marching per particle. Verify: the grid's total density equals the sum over the particles within 1 %, transmittance through a uniform slab fixture matches Beer's law, and the harness matches a golden image.
- 79.15.2.5 Implement light-emitting particles — each particle
contributes a dynamic point light: feed the brightest N emissive particles
per cluster into the clustered-light list of
maya-renderer/src/light_clustering.rs, merging the rest into one light per cluster so the cost stays bounded. Verify: a test asserts that the light count never exceeds the cap, that the merged light conserves total intensity within 5 %, and the harness shows a ground plane lit by a spark burst. - 79.15.2.6 Create distortion/heat haze effect from particle screen-space refraction (GPU convention, 79.0.1): particles write offset vectors into a distortion buffer that a post-process pass uses to resample the scene colour. Verify: there is zero distortion where no particle covers the pixel, the offset magnitude follows the particle's strength curve, and the harness matches a golden image of a checkerboard behind a heat source.
- 79.15.2.7 Implement particle LOD — count and quality scaling with distance and performance budget
- 79.15.2.8 Create VFX template library — fire, smoke, explosion, rain, snow, magic bolt, blood splatter, sparks, dust cloud, waterfall spray, fireflies, embers, steam, bubble, lightning arc
- 79.15.2.9 Implement VFX graph node editor for visual effect authoring
without code (viewer convention, 79.0.3): a serialisable node-graph
document (emitter, force, curve, renderer and sub-emitter nodes with typed
ports) that compiles into the
maya-vfxeffect description, and an editor module underlibs/maya/tooling/src/debug-viewers/vfx-graph/that adds, connects and removes nodes and draws the graph as SVG. Verify: a vitest spec builds the shipped fire template as a graph and compiles it to a description equal to the one intemplates.rs, a connection between mismatched port types and a cycle are both refused, and the graph round-trips through JSON. - 79.15.2.10 Create VFX performance benchmark (target <1ms GPU for typical scene particle load)
79.16 Seasonal System & Procedural Weathering (Rust)#
Dynamic seasons affecting vegetation, weather, gameplay, and NPC behavior, plus time-based material aging — inspired by AC Shadows and Forza Horizon.
79.16.1 Seasonal Rendering & Gameplay#
- 79.16.1.1 Implement vegetation season response — spring (new growth, flowers), summer (full green), autumn (color shift, leaf fall), winter (bare branches, snow)
- 79.16.1.2 Create gradual season transition blending over in-game days
- 79.16.1.3 Implement snow accumulation depth map building over winter from precipitation
- 79.16.1.4 Create snow coverage on upward-facing surfaces — rooftops, branches, rocks
- 79.16.1.5 Implement spring melting — gradual depth reduction, melt-water rivulets, sun-facing slopes clear first
- 79.16.1.6 Create frozen water bodies — lakes and rivers freeze in winter with walkable ice surface
- 79.16.1.7 Implement morning frost texture overlay in cold weather
- 79.16.1.8 Create seasonal wildlife behavior — migration, hibernation, breeding seasons (integrated with §79.4)
- 79.16.1.9 Implement seasonal NPC activities — farming seasons, clothing changes, festival events
- 79.16.1.10 Create day length variation — shorter days in winter, longer in summer, affecting lighting and NPC schedules
- 79.16.1.11 Implement seasonal traversal changes — frozen lakes create new paths, spring floods block paths
- 79.16.1.12 Create seasonal crop cycles (if farming exists) — planting, growing, harvesting tied to seasons
79.16.2 Procedural Weathering#
- 79.16.2.1 Implement material aging system — time-based accumulation of weathering effects on world surfaces
- 79.16.2.2 Create rust propagation — spreads from edges/scratches on metal surfaces over time
- 79.16.2.3 Implement moss/lichen growth on north-facing stone in humid biomes
- 79.16.2.4 Create dirt/grime accumulation in crevices with rain runoff streaks
- 79.16.2.5 Implement paint peel — paint chips and peels from exposed surfaces based on weather exposure
- 79.16.2.6 Create wood rot — wooden structures darken and soften over time in wet conditions
- 79.16.2.7 Implement weathering susceptibility maps — artists paint where weathering appears, system applies procedural effect
- 79.16.2.8 Create dynamic weathering from player damage — scratch on metal → rust starts at scratch point
79.17 Facial Performance Capture Pipeline (Rust + TypeScript)#
Camera-based facial tracking to game animation pipeline with AI-driven lip sync for dynamic dialogue.
79.17.1 Facial Capture & Retargeting#
- 79.17.1.1 Create
maya-facial-captureRust crate andlibs/maya/facial-pipeline/TypeScript library. Split 2026-09-18 because the two halves are in different states.- 79.17.1.1.a Crate scaffold. It exists at
libs/maya/engine-core/crates/maya-facial-capture(facs.rs,expression.rs,viseme.rs). Verify it under the checkbox rule (read the public API, run the adversarial scan,cargo test -p maya-facial-capture) and close this child. - 79.17.1.1.b Create the TypeScript library
libs/maya/facial-pipeline/, which does not exist:project.json,package.json(@maya/facial-pipeline),tsconfig.json, thetsconfig.base.jsonpath mapping, and a first module that parses a recorded capture take (a frame-stamped array of the 52 ARKit blend-shape coefficients) and retargets it to the crate's FACS action units with the same mapping table asfacs.rs. Verify:npx vitest runin the library passes a spec that retargets a fixture take and gets the same action-unit curves as the Rust crate's test vector within 1e-5;npx tsc --noEmit -p libs/maya/facial-pipelineis clean.
- 79.17.1.1.a Crate scaffold. It exists at
- 79.17.1.2 Implement iPhone ARKit face tracking integration — 52 blend
shape coefficients at 60fps via network streaming. The receiver is
actionable without a phone: a UDP/OSC listener in
libs/maya/facial-pipeline/that accepts the 52-coefficient frame format of the free Live Link Face app, time-stamps the frames, and drops late or out-of-order ones, verified by a spec that replays a recorded 60 fps packet capture and asserts frame count, ordering and jitter handling. Capturing a real take needs an iPhone with a TrueDepth camera, and the fleet has none (stated 2026-09-18).blocked:hardware - 79.17.1.3 Create recording pipeline — capture facial data to animation clip format for offline use
- 79.17.1.4 Implement FACS Action Unit mapping — 68+ AU blend shapes from capture data
- 79.17.1.5 Create source-to-target retargeting — map performance to any character rig with proportion correction
- 79.17.1.6 Implement style transfer — exaggerate or dampen for stylized characters
- 79.17.1.7 Create viseme generation from phoneme stream — text-to-speech or speech recognition → visemes → blend shapes
- 79.17.1.8 Implement emotion-driven facial expression — maya-souls emotion state → appropriate expression overlay
- 79.17.1.9 Create procedural micro-expressions — blink rate, gaze shift, subtle emotional leakage
- 79.17.1.10 Implement facial capture integration with dialogue system
(Phase 72.7, which is complete and lives in the V2 Unreal project under
V2/ue/Source/V2Gameplay). Define the hand-off as data: a dialogue line id from thev2.dialogue.tree.v1format keys a facial track (a captured take fromlibs/maya/facial-pipeline/, or the viseme track thatmaya-facial-capture/src/viseme.rsgenerates from the line's text and audio timing), exported as a curve asset the dialogue runtime can play. Verify: a spec exports the tracks for the three lines ofV2/balance/dialogue/trees/asha-storm-market-intro.v2dialogue.json, each track's duration equals its audio duration within one frame, and an unknown line id is reported instead of skipped.
79.18 Advanced Haptic Feedback System (Rust)#
DualSense adaptive triggers, HD rumble, and per-surface contextual haptics.
79.18.1 Haptic Engine & Profiles#
- 79.18.1.1 Create
maya-hapticsRust crate integrated with input system. Split 2026-09-18 because the two halves are in different states.- 79.18.1.1.a Crate scaffold. It exists at
libs/maya/engine-core/crates/maya-haptics(effect.rs,triggers.rs,context.rs,platform.rs). Verify it under the checkbox rule (read the public API, run the adversarial scan,cargo test -p maya-haptics) and close this child. - 79.18.1.1.b Input-system integration. The crate's own doc says
device output "is the input backend's job", and the workspace has no
input crate (no
maya-inputunderlibs/maya/engine-core/crates/). Add the output port the crate promises: aHapticOutputtrait inmaya-haptics/src/platform.rswith a recording implementation for tests and agilrs-based implementation (open source; rumble on any connected gamepad) behind agamepadfeature. Verify: a test plays a layered effect through the recording output and asserts the motor command stream (amplitude, frequency, duration, priority pre-emption);cargo check -p maya-haptics --features gamepadis clean. Adaptive-trigger output on a DualSense stays a manual residual that needs the controller.
- 79.18.1.1.a Crate scaffold. It exists at
- 79.18.1.2 Implement haptic effect definition — waveform, frequency, amplitude, duration, spatial balance, layering priority
- 79.18.1.3 Create platform abstraction — DualSense HD rumble + adaptive triggers, Xbox impulse triggers, Switch HD rumble, generic fallback
- 79.18.1.4 Implement adaptive trigger profiles — weapon trigger break, bow draw resistance, brake pedal, lock pick vibration
- 79.18.1.5 Create dynamic trigger adjustment — resistance changes in real-time based on game state
- 79.18.1.6 Implement surface-based haptics — walking on wood vs stone vs metal produces distinct rumble patterns
- 79.18.1.7 Create weather haptics — rain patter, wind pressure, thunder pulse
- 79.18.1.8 Implement combat haptics — weapon recoil, hit feedback, blocking resistance
- 79.18.1.9 Create vehicle haptics — engine vibration at RPM frequency, road surface texture, collision impact
- 79.18.1.10 Implement haptic accessibility — intensity scaling, disable option, alternative feedback modes
79.19 Photo Mode System (Rust)#
World-pausing free camera with lighting, filter, and composition controls.
79.19.1 Photo Mode Controls#
- 79.19.1.1 Implement photo mode activation — pause world simulation, detach camera from character
- 79.19.1.2 Create free camera — fly within configurable radius of character with orbit mode
- 79.19.1.3 Implement focal length adjustment — telephoto to wide-angle FOV
- 79.19.1.4 Create depth of field control — manual focus point, aperture (bokeh intensity), focus peaking
- 79.19.1.5 Implement time-of-day scrubbing — change lighting in real-time
- 79.19.1.6 Create weather override — select preset for photo conditions
- 79.19.1.7 Implement character pose library and expression selection
- 79.19.1.8 Create filter system — cinematic, vintage, noir, high-contrast, desaturated presets
- 79.19.1.9 Implement color grading — exposure, contrast, saturation, temperature, tint sliders
- 79.19.1.10 Create border/aspect ratio frames — 2.39:1, 1:1, 4:3
- 79.19.1.11 Implement screenshot capture at higher-than-display
resolution (supersampling) (GPU convention, 79.0.1): render the photo-mode
frame as N×N tiles with a jittered off-centre projection per tile, stitch
them, and write a PNG; the
maya-photo-modecamera, depth of field and grade apply per tile. Verify: a 4× capture of a fixture scene has four times the display dimensions, shows no seam (the pixel difference across every tile border stays within the image's own local gradient), and its box-downsample matches the display-resolution render above a stated PSNR. - 79.19.1.12 Create screenshot metadata embedding and social sharing
integration.
- 79.19.1.12.a Embed the metadata: write the camera settings, the
world position, the time of day, the game build and an optional player
caption into PNG
iTXtchunks and XMP frommaya-photo-mode, with an opt-out that strips position and player identifiers. Verify: a test reads the chunks back with an independent PNG parser, and the opt-out file holds none of the private fields. - 79.19.1.12.b Share to social platforms. Posting needs a registered
developer application and API credentials on each network, which are the
owner's accounts (stated 2026-09-18). The portable part, handing the
file to the operating system's share sheet or the clipboard, belongs to
whichever client embeds the engine.
blocked:external
- 79.19.1.12.a Embed the metadata: write the camera settings, the
world position, the time of day, the game build and an optional player
caption into PNG
79.20 Save System Architecture (Rust)#
Unified versioned save system with quicksave, autosave, cloud sync, and migration.
79.20.1 Save Framework#
- 79.20.1.1 Create
maya-save-systemRust crate - 79.20.1.2 Implement versioned save schema — self-describing format with schema evolution support
- 79.20.1.3 Create save data aggregation — player state, inventory, quests, world state, NPC state, ecology, economy, time, custom mod data
- 79.20.1.4 Implement save compression with LZ4 (target <50MB per save)
- 79.20.1.5 Create manual save to named slot (unlimited slots), quicksave (single key), and autosave (milestone-triggered, 3-5 rotating slots)
- 79.20.1.6 Implement checkpoint system for death/respawn (distinct from manual save)
- 79.20.1.7 Create cloud save platform integration — Steam Cloud, Xbox
Cloud, PS Plus with conflict resolution UI.
- 79.20.1.7.a Build the provider-neutral half in
libs/maya/engine-core/crates/maya-save-system: aCloudSaveProvidertrait (list, download, upload with an expected-version precondition), a conflict detector over the save header (device id, play time, logical clock), a resolution model (keep local, keep cloud, keep both), and a reference provider backed by an S3-compatible bucket, tested against the MinIO ofdocker/docker-compose.dev.yml. Verify: tests cover the three-way conflict matrix, an upload refused on a stale version, and an interrupted upload that leaves the previous cloud save intact. - 79.20.1.7.b Implement the Steam, Xbox and PlayStation providers.
Steamworks needs a Steam partner account and app id; the Xbox GDK and
the PlayStation SDK are under NDA and need approved developer accounts
and devkits; the owner holds none of them (stated 2026-09-18).
blocked:external
- 79.20.1.7.a Build the provider-neutral half in
- 79.20.1.8 Implement cross-platform cloud save for unified progression across platforms: a platform-independent save schema version and a progression merge (the union of unlocks, the maximum of counters, the latest-by-logical-clock for positional state) on top of the reference provider of 79.20.1.7.a, keyed by the player's account and not by a platform id. Verify: a test merges saves made by two simulated platforms with divergent progress and asserts that nothing unlocked on either side is lost, that the merge is commutative and idempotent, and that a save from a newer schema version is refused with a clear error rather than truncated.
- 79.20.1.9 Create save migration chain — v1→v2→v3 applied in sequence, forward/backward compatibility
- 79.20.1.10 Implement save system integration tests verifying round-trip save/load for all game state
79.21 Footstep & Surface Audio System (Rust)#
Surface-aware footstep audio with material detection, speed modulation, and environmental reverb.
79.21.1 Surface Audio#
- 79.21.1.1 Implement per-foot raycast surface material detection at IK
contact points: on each foot-plant event from the foot-locking IK of
79.2.1.9, cast a short ray through
maya-physicsfrom the contact point, read the hit's surface material id, and hand it tomaya-surface-audio/src/material.rs; fall back to the last known material when the ray misses. Verify: a test walks a character across a fixture floor split between wood and gravel and asserts the material sequence per foot, including the step that straddles the boundary (each foot reports its own side). - 79.21.1.2 Create material identification from terrain material map, mesh material tags, and dynamic surface state (wet, frozen, muddy)
- 79.21.1.3 Implement per-material audio bank — 8-12 variations × speed class (walk, jog, run, sprint, sneak)
- 79.21.1.4 Create volume and pitch modulation proportional to speed and character weight
- 79.21.1.5 Implement reverb bus routing based on environment (indoor, outdoor, cave, tunnel)
- 79.21.1.6 Create clothing audio layer — armor clink, cloth rustle, leather creak layered on footsteps
- 79.21.1.7 Implement equipment audio — backpack bounce, weapon jingle during movement
- 79.21.1.8 Create water depth transition audio — shallow splash → wade → swim
- 79.21.1.9 Implement NPC footstep audio with distance attenuation
- 79.21.1.10 Create vehicle-surface audio — tire sounds per material (screech, crunch, squelch)
79.22 Dynamic Music Composition System (Rust)#
Procedural music generation and real-time composition from musical building blocks — beyond adaptive stems.
79.22.1 Procedural & Environmental Music#
- 79.22.1.1 Create
maya-music-engineRust crate with MIDI-like internal sequencing - 79.22.1.2 Implement musical element library — tagged melodic phrases, chord progressions, rhythm patterns, bass lines
- 79.22.1.3 Create rule-based composition — select and layer elements based on game state with harmonic constraints
- 79.22.1.4 Implement phrase structure — 4/8/16 bar phrases with intro, development, climax, resolution
- 79.22.1.5 Create biome-specific instrument palette and harmonic language
- 79.22.1.6 Implement time-of-day adaptation — dawn (sparse/gentle), noon (open/bright), dusk (melancholic), night (sparse/mysterious)
- 79.22.1.7 Create weather music influence — rain adds muted/minor elements, clear adds brightness
- 79.22.1.8 Implement combat intensity layers — percussion → brass → full orchestra escalation
- 79.22.1.9 Create exploration crescendo on discovering new areas or vistas
- 79.22.1.10 Implement deliberate musical silence as emotional tool
79.23 Gameplay Framework Systems (Rust + TypeScript)#
Core gameplay systems: combat, stealth, investigation, companions, mounts, swimming, settlement building, and survival.
79.23.1 Combat System#
- 79.23.1.1 Create
maya-combatRust crate - 79.23.1.2 Implement melee combat — light/heavy attacks, combo chains, dodge, parry/block, riposte
- 79.23.1.3 Create ranged combat — aim, fire, reload, weapon sway, recoil, bullet drop
- 79.23.1.4 Implement lock-on targeting — nearest enemy, cycle targets, soft lock vs hard lock modes
- 79.23.1.5 Create damage type system — physical, fire, frost, poison, electric with resistance/vulnerability
- 79.23.1.6 Implement stamina/resource management — attacks consume stamina, block drains guard, recovery over time
- 79.23.1.7 Create hit feedback — hit-stop freeze, screen shake, directional damage indicator
- 79.23.1.8 Implement execution/finisher system — contextual finishing moves based on enemy state
- 79.23.1.9 Create weapon class definitions with distinct movesets, ranges, speeds
- 79.23.1.10 Implement combat AI for enemies — attack patterns, openings, group tactics
79.23.2 Stealth System#
- 79.23.2.1 Create
maya-stealthRust crate - 79.23.2.2 Implement light/shadow visibility — character visibility based on lighting at position
- 79.23.2.3 Create sound propagation — actions produce noise at radius, NPCs investigate sounds
- 79.23.2.4 Implement NPC awareness states — unaware → suspicious → alerted → searching → combat → return-to-patrol
- 79.23.2.5 Create last known position tracking — NPCs investigate where they last detected the player
- 79.23.2.6 Implement stealth takedowns — context-sensitive from behind/ above with animation
- 79.23.2.7 Create distraction mechanics — thrown objects create noise at target location
- 79.23.2.8 Implement camouflage — hiding in vegetation, crowds, shadows, disguises
- 79.23.2.9 Create detection meter UI — indicator showing proximity to detection
- 79.23.2.10 Implement stealth integration tests with AI perception verification
79.23.3 Investigation System#
- 79.23.3.1 Create
maya-investigationRust crate (critical for Project Obsidian detective noir) - 79.23.3.2 Implement detective vision toggle — visual filter highlighting interactable objects, tracks, clues
- 79.23.3.3 Create object examination — zoom in, rotate, inspect details with discovery annotations
- 79.23.3.4 Implement track following — highlight footprints, blood trails, scent trails
- 79.23.3.5 Create evidence collection into case file with categorization
- 79.23.3.6 Implement deduction system — connect evidence to form conclusions with branching deductions
- 79.23.3.7 Create environmental storytelling support — object arrangements telling stories without dialogue
- 79.23.3.8 Implement investigation integration with quest system (Phase
72.8, which is complete and lives in the V2 Unreal project as
FV2QuestDefinitioninV2/ue/Source/V2Gameplay). Define the bridge as data:libs/maya/engine-core/crates/maya-investigationemits case events (case opened, clue found, deduction made, case solved or failed) as JSON, and a mapping table turns each into quest objective progress for a quest definition that declares an investigation objective. Verify: a spec drives the fixture case incasefile.rsto a solved state and asserts the ordered objective-progress messages against the quest definition format, including a wrong deduction that must not complete the objective. - 79.23.3.9 Create investigation UI — case board, evidence viewer,
deduction screen (viewer convention, 79.0.3): a serialisable
CaseBoardSnapshotinmaya-investigation(clues with their discovered state, the links the player has made, the deductions available) and viewer modules underlibs/maya/tooling/src/debug-viewers/investigation/that draw the board as a node-link diagram, list the evidence with provenance, and present the deduction choices. Verify: a vitest spec asserts that undiscovered clues never appear in the rendered board, that each link drawn exists in the snapshot, and that choosing a deduction returns the command the crate expects. - 79.23.3.10 Implement investigation tutorial and hint system
79.23.4 Companion, Mount, Swimming & Settlement Systems#
- 79.23.4.1 Implement companion AI — follow player, autonomous combat, commands (attack, defend, wait, follow)
- 79.23.4.2 Create companion dialogue — contextual comments about environment, quests, combat situations
- 79.23.4.3 Implement companion relationship system — opinion changes based on player decisions
- 79.23.4.4 Create mount system — context-sensitive mounting, mounted combat, mount AI obstacle avoidance
- 79.23.4.5 Implement mount bonding — trust/loyalty affecting responsiveness and behavior under stress
- 79.23.4.6 Create swimming locomotion — surface swimming with stamina drain, diving with breath management
- 79.23.4.7 Implement underwater exploration — marine life, coral,
shipwrecks, underwater caves: the systems half only, which is a
points-of-interest generator in
maya-gameplay-systemsthat places wrecks, coral fields and cave entrances by depth band and sea-floor slope, marine species spawned through themaya-ecologyhabitat preferences, and breath and pressure rules tied to the swimming state ofmaya-ocean/src/hydro.rs. Verify: a test generates a fixture sea floor deterministically from a seed, asserts that every placement respects its depth band and that no two wrecks overlap, and that breath runs out at the configured time. The meshes and textures for wrecks and coral are art content and are not part of this item. - 79.23.4.8 Create settlement building — structure placement with snap grid, resource requirements, NPC assignment
- 79.23.4.9 Implement settlement defense — walls, turrets, traps against attacks
- 79.23.4.10 Create settlement economy — production chains, trade routes, income generation
79.23.5 Survival Systems (Optional Module)#
- 79.23.5.1 Implement hunger/thirst system with food/water requirements and stat effects when neglected
- 79.23.5.2 Create temperature system — cold/hot environments affect health, require appropriate clothing
- 79.23.5.3 Implement sleep/fatigue — rest requirement, performance degradation when exhausted
- 79.23.5.4 Create survival crafting — cook food, purify water, craft shelter from gathered materials
- 79.23.5.5 Implement hardcore mode toggle — enable/disable survival per player preference
79.24 NPC Life Simulation Engine (Rust)#
Needs-based autonomous AI with personality facets, emotional state machines, and memory streams — combining The Sims, Dwarf Fortress, and Stanford Generative Agents.
79.24.1 Needs System#
- 79.24.1.1 Create
maya-npc-lifeRust crate with ECS component definitions - 79.24.1.2 Implement 8 core needs with continuous 0-100 values and per- need decay rates — hunger, energy, hygiene, bladder, social, fun, comfort, safety
- 79.24.1.3 Create extended needs activated by personality traits — knowledge, martial, craft, nature, devotion, wealth
- 79.24.1.4 Implement object advertisement system — world objects broadcast need fulfillment values to nearby NPCs
- 79.24.1.5 Create need-driven behavior scoring —
score = Σ(need_deficit × advertisement × personality_weight × proximity) - 79.24.1.6 Implement weighted random selection from top-3 scoring options (not always optimal — prevents robotic behavior)
- 79.24.1.7 Create Maslow-inspired priority curves — physical needs spike when deficient, higher-order needs only matter when physical are satisfied
- 79.24.1.8 Implement need satisfaction animations — NPC visibly eats,
sleeps, bathes, socializes when fulfilling needs: map each need-fulfilling
activity of
libs/maya/engine-core/crates/maya-npc-life/src/needs.rsto an animation request (a clip tag, a prop and a location anchor) that the motion-matching tag system of 79.2.1.7 resolves. Verify: a test runs one NPC through a simulated day and asserts that every activity start emits exactly one request with the right tag and prop, that it ends when the need is satisfied or interrupted, and that an activity with no matching clip tag is reported rather than skipped silently. The motion-capture clips themselves are content. - 79.24.1.9 Create need-driven schedule modification — starving NPC abandons work to seek food
- 79.24.1.10 Implement need system debugging overlay — show active
needs, scores, selected activities per NPC (viewer convention, 79.0.3): a
NeedsDebugSnapshotinmaya-npc-life(per NPC: the need levels, the utility scores of the candidate activities, the chosen one and why) and a viewer underlibs/maya/tooling/src/debug-viewers/npc-needs/. Verify: a crate test asserts that the chosen activity in the snapshot is the arg-max of the listed scores, and a vitest spec asserts one bar per need and a highlight on the chosen activity.
79.24.2 Personality System#
- 79.24.2.1 Implement 30+ personality facets scored 0-100 across Openness, Conscientiousness, Extraversion, Agreeableness, Neuroticism (NEO PI-R model) plus Bravery, Greed, Humor, Patience, Stubbornness
- 79.24.2.2 Create 15+ values scored -100 to +100 — tradition, family, knowledge, craftsmanship, martial prowess, commerce, nature, law, freedom, power, art, religion, community, wealth, honor
- 79.24.2.3 Implement 1-3 long-term goals per NPC — master skill, start family, accumulate wealth, create great work, gain power
- 79.24.2.4 Create personality-driven behavior weighting — high gregariousness increases social interaction frequency
- 79.24.2.5 Implement personality compatibility calculation between NPC pairs for relationship formation (§79.25)
- 79.24.2.6 Create personality template library — 50+ pre-built personality archetypes (warrior, scholar, merchant, healer, trickster, noble)
- 79.24.2.7 Implement procedural personality generation — randomized within cultural norms for faction/region
- 79.24.2.8 Create personality influence on dialogue — personality
modulates maya-souls LLM prompts for NPC speech style: a deterministic
function in
maya-npc-life/src/personality.rsthat turns the facet vector into style directives (verbosity, formality, warmth, hedging, typical interjections), and their insertion into themaya-soulsprompt template. Verify: a unit test asserts the directives for four contrasting personalities and that the prompt carries them. An end-to-end check generates one line per personality through OpenRouter withdeepseek/deepseek-v4-flash-0731(the repo's test binding) and asserts a measurable difference, mean sentence length ordered by the verbosity facet. - 79.24.2.9 Implement personality-driven crime tendency — low responsibility + high greed = theft risk
- 79.24.2.10 Create personality inspection UI for debugging (show all
facets, values, goals per NPC) (viewer convention, 79.0.3): a
PersonalitySnapshotinmaya-npc-lifeand a viewer underlibs/maya/tooling/src/debug-viewers/npc-personality/that draws the facets as a radar chart and lists values and goals. Verify: a vitest spec asserts one axis per facet with the snapshot's values, and that two NPCs can be overlaid for comparison.
79.24.3 Emotional State System#
- 79.24.3.1 Implement mood bar (0-100) with target drift — current mood approaches mood target at configurable rate
- 79.24.3.2 Create thought system — time-limited mood modifiers with source, strength, duration (e.g., "friend died" -25 for 30 days)
- 79.24.3.3 Implement thought stacking with per-category caps to prevent mood extremes from single sources
- 79.24.3.4 Create mental break thresholds — mood <20%: minor break (insult, binge), <10%: major (fight, flee), <5%: extreme (rage, catatonia)
- 79.24.3.5 Implement break type selection based on personality — high anger → fight, high anxiety → flee, high depression → catatonia
- 79.24.3.6 Create emotional contagion — nearby NPCs' moods influence each other, enabling group panic and group celebration
- 79.24.3.7 Implement mood effects on NPC appearance — happy NPCs smile
and stand tall, sad NPCs slouch and avoid eye contact: derive posture
parameters (spine curvature, head pitch, shoulder height, gaze-contact
probability, a baseline facial action-unit set) from the emotion state of
maya-npc-life/src/emotion.rs, exposed as additive pose offsets for the animation layer. Verify: a test asserts a monotonic mapping from valence to spine extension and gaze contact, that the offsets stay inside joint limits for extreme moods, and that mood changes are smoothed over the configured time constant. - 79.24.3.8 Create mood effects on work quality — happy NPCs produce better goods, sad NPCs produce less
- 79.24.3.9 Implement mood recovery events — positive thoughts from social interaction, entertainment, good food
- 79.24.3.10 Create emotional state integration with facial animation
(§79.17) for visible emotional expression: map the emotion state of
emotion.rsto FACS action-unit targets throughlibs/maya/engine-core/crates/maya-facial-capture/src/expression.rs, blended under speech visemes so the mouth stays readable. Verify: a test asserts the action-unit set for each basic emotion at full intensity, a linear scale with intensity, and that viseme-critical units (jaw, lips) keep at least the configured share of their viseme target while an emotion is active.
79.24.4 Memory System#
- 79.24.4.1 Implement memory stream — sequential log of NPC experiences as structured records (timestamp, location, event_type, participants, importance)
- 79.24.4.2 Create memory retrieval scoring —
score = α_recency × recency + α_importance × importance + α_relevance × relevance - 79.24.4.3 Implement recency decay — exponential decay (0.995 per game- hour) since memory last accessed
- 79.24.4.4 Create importance rating (1-10) for events — routine=1, life- changing=8-10
- 79.24.4.5 Implement memory capacity — retain last 200-500 memories, prune oldest/lowest-importance
- 79.24.4.6 Create reflection system — triggered when cumulative new importance >150, extract high-level insights from recent memories
- 79.24.4.7 Implement reflection tree — observations → insights → beliefs, forming hierarchical memory abstraction
- 79.24.4.8 Create player-specific memory — NPCs remember player's gifts, crimes, help, insults affecting disposition
- 79.24.4.9 Implement memory sharing through gossip system (§79.34)
- 79.24.4.10 Create memory integration with maya-souls LLM — memory
context injected into dialogue prompts for contextual NPC conversation:
retrieve the top-k memories from the memory stream of
maya-npc-life/src/memory.rsby recency, importance and relevance to the interlocutor and the topic, under a token budget, and place them in themaya-soulsprompt. Verify: a unit test asserts the retrieval order for a fixture stream and that the budget is never exceeded. An end-to-end check through OpenRouter withdeepseek/deepseek-v4-flash-0731asserts that an NPC holding the memory "the player returned my lost ring" mentions the ring, and that one without the memory does not.
79.25 NPC Social & Relationship System (Rust)#
Inter-NPC relationship graph with opinion, familiarity, romance, marriage, family, and social network effects — inspired by Dwarf Fortress and RimWorld.
79.25.1 Relationship Graph#
- 79.25.1.1 Create
maya-socialRust crate with relationship graph data structure - 79.25.1.2 Implement per-pair relationship record — opinion (-100 to +100), familiarity (0-100), relationship type (stranger through spouse)
- 79.25.1.3 Create opinion modifiers — shared values (+), conflicting values (-), gifts (+5 to +30), insults (-10 to -30), saved life (+50), betrayal (-70)
- 79.25.1.4 Implement natural opinion decay toward 0 without reinforcement
- 79.25.1.5 Create positive social interactions — deep talk, compliment, share meal, work together, give gift, help in need
- 79.25.1.6 Implement negative social interactions — insult, slight, argument (opposing values), gossip about, physical altercation
- 79.25.1.7 Create romantic interaction chain — flirt, confess, date, proposal, marriage (requires friendship + compatibility + attraction)
- 79.25.1.8 Implement marriage mechanics — permanent bond, shared household, strong mood effects, potential children
- 79.25.1.9 Create family system — children inherit personality from parents, grow over time, family death causes severe grief
- 79.25.1.10 Implement social network effects — clique formation, community leaders, social outcasts
79.25.2 Social Dynamics#
- 79.25.2.1 Implement introduction system — NPCs introduce friends to each other, expanding social networks
- 79.25.2.2 Create social isolation mood penalty — unmet social need for NPCs with few connections
- 79.25.2.3 Implement family feuds — harming one family member creates enemies of entire family
- 79.25.2.4 Create inheritance system — property and wealth transfer on NPC death
- 79.25.2.5 Implement relationship visualization tool for debugging
(social graph viewer) (viewer convention, 79.0.3): a
SocialGraphSnapshotfromlibs/maya/engine-core/crates/maya-social/src/graph.rs(nodes with family and faction, edges with opinion, familiarity and type) and a node-link viewer underlibs/maya/tooling/src/debug-viewers/social-graph/with edge colour by opinion and a filter by relationship type. Verify: a vitest spec asserts one node per NPC and one edge per relationship of a 30-NPC fixture, that the family filter hides non-family edges, and that the layout is deterministic for a seed.
79.26 NPC Occupation & Work System (TypeScript + Rust)#
40+ occupation types with visible work behavior, production, career progression, and economic output.
79.26.1 Occupation Database & Work Behavior#
- 79.26.1.1 Create
libs/maya/npc-occupations/TypeScript library with occupation templates - 79.26.1.2 Implement occupation definition schema — name, category, required skills, schedule, workplace type, production outputs, income, class
- 79.26.1.3 Create 40+ occupation templates — craftspeople (blacksmith, carpenter, tailor), merchants (shopkeeper, vendor), agriculture (farmer, rancher), service (barber, healer), military (guard, soldier), clergy (priest, scholar), entertainment (bard, performer), criminal (pickpocket, fence), governance (mayor, magistrate)
- 79.26.1.4 Implement NPC work actions — blacksmith operates anvil, farmer plows/plants/harvests, guard patrols, merchant serves customers
- 79.26.1.5 Create visible economic output — goods appear in shop inventory over time, crops grow and are harvested
- 79.26.1.6 Implement work skill progression — NPCs improve at their craft, producing higher-quality goods
- 79.26.1.7 Create work breaks — NPCs eat lunch, chat with coworkers on schedule
- 79.26.1.8 Implement shift work — day guard / night guard rotation
- 79.26.1.9 Create career dynamics — hiring, firing, career change, apprenticeship, retirement
- 79.26.1.10 Implement unemployment behavior — jobless NPCs wander, seek work, potentially turn to crime based on personality
- 79.26.1.11 Create player interaction with NPC jobs — commission work, hire for player businesses, impact from destroying workplaces
- 79.26.1.12 Implement occupation integration with economy system
(§79.28): connect
libs/maya/npc-occupations(work.ts,career.ts) tolibs/maya/engine-core/crates/maya-economy, so that work output entersproduction.rsas goods, wages are paid from the employer's funds at themarket.rswage level, and unemployment feeds the indicators ofindicators.rs. Verify: an integration test runs a 30-day village fixture and asserts that goods produced equal the sum of worker output, that money is conserved across wages and sales, and that removing the blacksmith raises the tool price. - 79.26.1.13 Create occupation integration tests verifying daily work cycles produce expected economic output
- 79.26.1.14 Implement occupation assignment during world generation — settlement needs determine initial job distribution
- 79.26.1.15 Create occupation documentation and template authoring guide
79.27 City Infrastructure Simulation (Rust + TypeScript)#
Traffic, public transit, emergency services, and district personality creating functional cities — inspired by Cities: Skylines.
79.27.1 Traffic Simulation#
- 79.27.1.1 Create
maya-city-simRust crate with road network graph - 79.27.1.2 Implement road network — intersections as nodes, segments as edges with lane count, speed limit, direction
- 79.27.1.3 Create NPC vehicle pathfinding — route calculation considering distance, speed, and congestion with early lane commitment
- 79.27.1.4 Implement traffic flow — following distance, intersection logic (traffic lights, yield/stop signs, right-of-way)
- 79.27.1.5 Create rush hour patterns — residential → commercial morning, reverse evening
- 79.27.1.6 Implement congestion emergence — popular routes develop realistic backups
- 79.27.1.7 Create accident events — random vehicle collisions creating temporary blockages triggering emergency response
- 79.27.1.8 Implement traffic simulation at ~4 updates/second with render interpolation
- 79.27.1.9 Create traffic LOD — full physics near player, simplified pathfinding at distance, statistical at far
- 79.27.1.10 Implement traffic performance benchmark (target 500+ vehicles simulated at 60fps)
79.27.2 Public Transportation & Emergency Services#
- 79.27.2.1 Implement bus system — routes as ordered stop sequences with schedule, bus NPCs drive routes
- 79.27.2.2 Create NPC transit usage — pedestrians evaluate walk vs drive vs transit for trips, wait at stops, board/alight
- 79.27.2.3 Implement rail/subway — fixed routes with timetabled departures and station interiors
- 79.27.2.4 Create taxi/rideshare — hailable vehicles for point-to-point transport
- 79.27.2.5 Implement police patrol routes — district-based with crime-rate- responsive density
- 79.27.2.6 Create fire department — respond to fire events, navigate to location, extinguish
- 79.27.2.7 Implement ambulance response — respond to injury events, transport to hospital
- 79.27.2.8 Create emergency vehicle priority — other traffic yields to sirens
- 79.27.2.9 Implement emergency response time affected by traffic congestion
- 79.27.2.10 Create emergency services integration with law system (§79.29)
79.27.3 District Personality#
- 79.27.3.1 Implement district type definitions — financial, entertainment, residential, market, industrial, slums, government, academic
- 79.27.3.2 Create per-district NPC population configuration — clothing, density, behavior patterns, ambient audio
- 79.27.3.3 Implement time-of-day transitions — smooth density and NPC-type changes between day and night per district
- 79.27.3.4 Create weather response per district — rain empties outdoor areas, fills indoor spaces
- 79.27.3.5 Implement district ambient soundscape — unique audio per district type (market chatter, factory noise, quiet residential)
79.28 Dynamic Agent Economy (Rust + TypeScript)#
BazaarBot-inspired price belief system with physical supply chains, trade caravans, and economic indicators.
79.28.1 Agent-Based Economy#
- 79.28.1.1 Create
maya-economyRust crate andlibs/maya/economy-tools/TypeScript library - 79.28.1.2 Implement merchant price belief system — per-commodity belief range (low, high), tightening on successful trades, widening on failures
- 79.28.1.3 Create market clearing algorithm — sort bids descending, asks ascending, match highest bid with lowest ask, clearing price = average
- 79.28.1.4 Implement agent replacement for bankrupt merchants — new agents prioritize most profitable commodity
- 79.28.1.5 Create production chain modeling — farmer→grain→miller→flour→ baker→bread with physical transport between stages
- 79.28.1.6 Implement NPC caravan system — merchants travel between settlements carrying trade goods along routes
- 79.28.1.7 Create caravan vulnerability — caravans visible in world, attackable by bandits or player
- 79.28.1.8 Implement regional price variation — coastal (cheap fish), mountain (cheap ore), agricultural (cheap grain)
- 79.28.1.9 Create cascading economic effects — farm destroyed → grain shortage → flour price rise → bread expensive → NPC hunger → unrest
- 79.28.1.10 Implement economic indicators per settlement — average prices, employment rate, wealth distribution, trade balance
- 79.28.1.11 Create economic events — boom, recession, famine, gold rush with visible effects on NPC behavior
- 79.28.1.12 Implement trade agreements between factions affecting tariffs
- 79.28.1.13 Create black market — illegal goods traded through underground channels
- 79.28.1.14 Implement economy balance testing tools — simulate 1000 trade cycles, verify price stability and convergence
- 79.28.1.15 Create economy debugging dashboard — real-time price
charts, supply/demand visualization, trade flow maps (viewer convention,
79.0.3): an
EconomyDebugSnapshottime series frommaya-economy(per good and market: price, supply, demand and price beliefs; per caravan: route and cargo) and viewers underlibs/maya/tooling/src/debug-viewers/economy/for a price chart, a supply-and-demand chart and a trade-flow map. Verify: a vitest spec asserts that the chart series equal the snapshot values, that flow-arrow width is proportional to the cargo value, and a crate test asserts that the snapshot matches the market state at the same tick.
79.29 Law Enforcement & Justice System (Rust)#
Crime detection, witness reporting, pursuit, arrest, bounty, and prison — inspired by RDR2.
79.29.1 Crime & Witnesses#
- 79.29.1.1 Create
maya-justiceRust crate integrated with maya-npc-life - 79.29.1.2 Implement crime type definitions — murder, assault, theft, trespassing, property destruction, disturbing peace, smuggling
- 79.29.1.3 Create witness system — NPCs within sight/hearing range become witnesses based on line-of-sight + distance + lighting + disguise checks
- 79.29.1.4 Implement witness decision making — high Responsibility NPCs report to authorities, low Responsibility ignore or join in
- 79.29.1.5 Create witness UI indicator — player sees which NPCs
witnessed crime and can attempt to intimidate or silence: expose from
libs/maya/engine-core/crates/maya-justice/src/crime.rsthe list of witnesses of the player's latest crime, each with what they saw, their report progress and the interactions open to the player (intimidate, bribe, silence) with success odds from the witness's personality, plus a marker-state record a HUD can draw. Verify: a test commits a fixture crime in view of two NPCs and out of view of a third, asserts the marker list and that it clears on report or on timeout, and asserts that a successful intimidation stops the report while a failed one speeds it up. - 79.29.1.6 Implement evidence system — weapon at scene, footprints, blood trail as circumstantial evidence
- 79.29.1.7 Create alert levels per region — none → investigating → searching → pursuing → lockdown
- 79.29.1.8 Implement response scaling — minor crime: single guard, moderate: patrol, major: full pursuit
- 79.29.1.9 Create guard pursuit behavior — call backup, cut off escape routes, verbal warnings before force
- 79.29.1.10 Implement last-known-position search — guards investigate area where suspect was last seen
79.29.2 Bounties & Consequences#
- 79.29.2.1 Implement per-region bounty accumulation proportional to crime severity
- 79.29.2.2 Create bounty hunter dispatch at high bounty levels — NPC hunters actively seek wanted player
- 79.29.2.3 Implement bounty payment at designated locations (post office, court)
- 79.29.2.4 Create arrest mechanics — confiscate stolen goods, pay fine or serve time
- 79.29.2.5 Implement prison as playable area — serve sentence or attempt escape
- 79.29.2.6 Create reputation impact from crime — NPCs refuse service, guards watch closely, prices increase
- 79.29.2.7 Implement NPC crime — NPCs with low responsibility commit theft, assault, organized crime
- 79.29.2.8 Create crime rate variation by district, time of day, and economic conditions (recession increases crime)
- 79.29.2.9 Implement pardons and amnesty — quest-based reputation recovery
- 79.29.2.10 Create justice system integration tests — crime → witness → report → pursuit → arrest/escape chain verification
79.30 Social Events & Cultural Life (TypeScript)#
Festivals, markets, performances, religious ceremonies, and community gatherings.
79.30.1 Events & Street Life#
- 79.30.1.1 Create
libs/maya/social-events/TypeScript library with event templates - 79.30.1.2 Implement scheduled events — weekly market days, seasonal festivals (harvest, solstice, equinox, midsummer), religious holy days
- 79.30.1.3 Create dynamic events — funerals (notable NPC death), weddings (NPC marriage), births, elections, protests, victory celebrations
- 79.30.1.4 Implement event lifecycle — preparation phase (setup, decorate) → active phase (activities, interactions) → cleanup phase (disassemble)
- 79.30.1.5 Create street performers — musicians, jugglers, storytellers attracting NPC crowds with coin-tossing
- 79.30.1.6 Implement market vendor system — temporary stalls on market days with vendor barks and NPC shopping
- 79.30.1.7 Create tavern social life — evening gathering, bard performance, drunk NPCs with altered behavior, gambling
- 79.30.1.8 Implement religious services — temple ceremonies at scheduled times with congregation, prayer, hymns
- 79.30.1.9 Create festival mini-games — competitions, contests, unique activities during seasonal events
- 79.30.1.10 Implement event NPC schedule overrides — NPCs attend events instead of normal daily activities
79.31 NPC-to-NPC Interaction Framework (Rust)#
Autonomous NPC conversations, arguments, cooperation, and ambient social behavior.
79.31.1 Interaction System#
- 79.31.1.1 Implement interaction initiation — proximity trigger with probability weighted by personality, familiarity, social need, and context
- 79.31.1.2 Create interaction types — greeting (2s), small talk (10-30s), deep conversation (1-5min), argument, transaction, physical interaction
- 79.31.1.3 Implement topic selection — recent events, weather, work, gossip about others, current affairs, personal topics (friends only)
- 79.31.1.4 Create conversation outcomes — opinion changes, information transfer (gossip §79.34), social need fulfillment, argument escalation
- 79.31.1.5 Implement dynamic group formation — NPCs at same location with shared activity merge into groups (2-8)
- 79.31.1.6 Create multi-party conversation — turn-taking, side conversations, dominant personalities speak more
- 79.31.1.7 Implement work groups — construction crews, guard patrols, harvest teams working cooperatively
- 79.31.1.8 Create ambient conversation audio — overhead speech bubbles
or dialogue audio for nearby NPC conversations (audio convention, 79.0.2):
take both routes by distance. Conversations of
maya-npc-interactinside a near radius get their lines spoken by Kokoro TTS with a per-NPC voice and spatialised; farther ones contribute only to the walla bed of 79.11.2.6, and a speech-bubble record with the text is emitted for a HUD. First install the Kokoro ONNX model on the Linux server and record the command and version; park only with a named failed install attempt. Verify: a test asserts the route chosen per distance and the bubble records, and an offline render of a two-NPC exchange passes the convention's assertions with the two voices panned to their positions. - 79.31.1.9 Implement conversation body language — gestures, head nods,
shoulder shrugs, appropriate facing: from the conversation state of
maya-npc-interact/src/interaction.rs, emit facing targets (participants turn toward the speaker), listener back-channel events (nods at phrase boundaries) and speaker gesture requests tagged by dialogue act (emphasis, question, denial), for the animation layer to resolve. Verify: a test runs a three-NPC fixture conversation and asserts that every participant's facing converges on the current speaker within the configured time, that nods come only from listeners, and that gesture tags follow the dialogue acts. - 79.31.1.10 Create conversation interruption — external events (explosion, combat) immediately break conversations
- 79.31.1.11 Implement NPC conversation LOD — full LLM-generated content near player, pre-scripted barks at distance
- 79.31.1.12 Create NPC argument mechanics — opposing values trigger debate, escalation based on personality (high anger → fight)
- 79.31.1.13 Implement NPC helping behavior — giving directions, helping carry items, assisting fallen NPCs
- 79.31.1.14 Create NPC reaction to player — conversations pause/change topic when player approaches, NPCs react to player appearance/reputation
- 79.31.1.15 Implement NPC-NPC interaction performance budget (target <1ms CPU for all active interactions)
79.32 Simulation LOD & AI Budget Management (Rust)#
4-tier NPC simulation with alibi generation ensuring all NPC systems fit within CPU budget.
79.32.1 Simulation Tiers & Budget Manager#
- 79.32.1.1 Create
maya-sim-lodRust crate as scheduling layer above all NPC systems - 79.32.1.2 Implement Tier 0 Full Simulation (0-30m) — complete needs, emotions, memory, pathfinding, animation, perception (~0.1ms per NPC)
- 79.32.1.3 Create Tier 1 Simplified (30-100m) — needs decay tracked, waypoint path following, simplified animation, major event perception (~0.01ms per NPC)
- 79.32.1.4 Implement Tier 2 Abstract (100m-1km) — schedule-driven zone transitions, no pathfinding, no animation, periodic tick (~0.001ms per NPC)
- 79.32.1.5 Create Tier 3 Statistical (1km+) — population counts per zone, birth/death/migration statistics (negligible CPU)
- 79.32.1.6 Implement tier promotion with alibi generation — when player approaches, generate plausible NPC state from schedule, occupation, and relationships
- 79.32.1.7 Create tier demotion with state recording — save exact NPC state when player moves away, continue abstract simulation
- 79.32.1.8 Implement hysteresis bands — promotion distance < demotion distance to prevent flickering
- 79.32.1.9 Create AI budget manager — configurable per-frame CPU budget (default 8ms), priority scoring per NPC (distance, attention, importance)
- 79.32.1.10 Implement temporal distribution — Tier 0 every frame, Tier 1 every 4th frame, Tier 2 every 60th frame
- 79.32.1.11 Create quest NPC priority boost — narrative-critical NPCs always receive Tier 0 processing regardless of distance
- 79.32.1.12 Implement Tracy profiling integration — per-NPC and
per-system timing markers:
libs/maya/engine-core/crates/maya-sim-loddeclares atracyfeature but its source holds no zones. Addmaya-profilerzones around each simulation tier's update, each NPC system (needs, social, economy, gossip) and the promotion and demotion pass, with the NPC id as zone text on the Full tier only. Verify:cargo check -p maya-sim-lod --features tracyis clean, a default build contains no Tracy symbols (the shipping guard still compiles), and a test asserts throughmaya-profiler's test sink that one zone per system is recorded per tick. - 79.32.1.13 Create simulation LOD visualization — color-coded NPCs by
current tier, budget utilization overlay (viewer convention, 79.0.3): a
SimLodSnapshotfrommaya-sim-lod(per NPC: position and tier; per tier: count, the CPU milliseconds spent and the budget ofbudget.rs) and a viewer underlibs/maya/tooling/src/debug-viewers/sim-lod/that draws a top-down map coloured by tier with budget bars. Verify: a vitest spec asserts one dot per NPC in its tier's colour and that a tier over its budget is flagged; a crate test asserts that the tier counts sum to the population. - 79.32.1.14 Implement simulation LOD stress test — 10,000 NPCs with full lifecycle, verify budget compliance
- 79.32.1.15 Create simulation LOD documentation and tuning guide
79.33 World History & Civilization Generation (TypeScript + Rust)#
Procedural 200+ year world history with civilizations, wars, artifacts, ruins, and legends — inspired by Dwarf Fortress Legends Mode.
79.33.1 History Simulation#
- 79.33.1.1 Create
libs/maya/world-history/TypeScript library andmaya-world-historyRust crate for generation - 79.33.1.2 Implement civilization generation — location, culture, values, technology level, government type, naming conventions
- 79.33.1.3 Create accelerated history simulation — N configurable years running before player starts
- 79.33.1.4 Implement population dynamics per settlement — growth, decline, migration, carrying capacity
- 79.33.1.5 Create war simulation — declaration based on grievances, battles with outcomes, territory changes, truces, peace treaties
- 79.33.1.6 Implement historical figure generation — rulers, heroes, villains, scholars with life events and legacy
- 79.33.1.7 Create artifact generation — named weapons, relics, tomes with creation story, creator, and history of ownership
- 79.33.1.8 Implement ruin generation — former settlements destroyed by war, disaster, or abandonment placed as explorable ruins
- 79.33.1.9 Create legend generation — distorted accounts of events that NPCs tell, varying by cultural perspective
- 79.33.1.10 Implement natural disaster events — earthquakes, plagues, floods, volcanic eruptions affecting civilization history
- 79.33.1.11 Create cultural achievement events — great works of art, architectural wonders, technological discoveries
- 79.33.1.12 Implement political events — royal marriages, assassinations, coups, religious schisms, reformations
- 79.33.1.13 Create history integration with gameplay — ruins contain loot, artifacts are findable, NPCs know history, faction grudges persist
- 79.33.1.14 Implement Legends Mode — player-accessible encyclopedia of generated world history with timeline visualization
- 79.33.1.15 Create ongoing history — player actions recorded as history, off-screen events continue (wars, political changes)
79.34 Information Propagation Network (Rust)#
Gossip protocol for news travel, rumor distortion, and reputation spreading.
79.34.1 Gossip & Rumors#
- 79.34.1.1 Implement information entity — content, origin (where/when), importance (1-10), accuracy (degrades through retelling), spread count
- 79.34.1.2 Create NPC-to-NPC information transmission — during conversations (§79.31), probability weighted by importance × gregariousness × relationship
- 79.34.1.3 Implement hub NPC acceleration — tavern keepers, merchants, guards spread information faster due to many contacts
- 79.34.1.4 Create trade caravan news transport — caravans carry information between settlements at travel speed
- 79.34.1.5 Implement town crier system — accelerate official information within settlements
- 79.34.1.6 Create information accuracy degradation — facts become exaggerated through retelling (telephone effect)
- 79.34.1.7 Implement rumor generation — distorted information becomes gameplay-relevant rumors (treasure, threats, opportunities)
- 79.34.1.8 Create player reputation propagation — deeds spread via gossip network, arriving at different times per region
- 79.34.1.9 Implement disinformation mechanic — player can deliberately spread false information
- 79.34.1.10 Create information propagation debugging — visualize news
spread wave across world map over time (viewer convention, 79.0.3): a
time-stamped
GossipSpreadSnapshotfromlibs/maya/engine-core/crates/maya-gossip/src/spread.rs(per settlement: when the item arrived, through whom, and its distortion level) and a viewer underlibs/maya/tooling/src/debug-viewers/gossip/that draws the spread front on the world map for a chosen tick. Verify: a crate test asserts that arrival times are consistent with travel times along the carrier routes, and a vitest spec asserts that the set of informed settlements at three ticks equals the snapshot's.
79.35 Domestic & Working Animals (Rust + TypeScript)#
Farm animals with production cycles, working animals, pets, and urban wildlife.
79.35.1 Domestic Animals#
- 79.35.1.1 Create domestic animal extension in
maya-ecologycrate andlibs/maya/animal-database/TypeScript library - 79.35.1.2 Implement farm animal species — cow (milking), chicken (eggs), pig, sheep (shearing), goat, horse, duck, bee (honey)
- 79.35.1.3 Create production cycles — daily milking, daily egg laying, seasonal shearing, seasonal honey harvest
- 79.35.1.4 Implement farmer NPC care routines — feeding (fill troughs), sheltering (barn at night), health checks
- 79.35.1.5 Create animal health and breeding — sick animals produce less, healthy populations grow
- 79.35.1.6 Implement working animals — guard dogs (bark at intruders), herding dogs, pack mules, hunting dogs, messenger pigeons
- 79.35.1.7 Create pet system — NPCs own dogs/cats that follow daily routines, show loyalty behaviors
- 79.35.1.8 Implement stray animals — unowned animals scavenging in cities, adoptable by player
- 79.35.1.9 Create urban wildlife — rats in alleys, pigeons in plazas, insects near food, nesting birds in spring
- 79.35.1.10 Implement animal-NPC bonding — owner NPCs care for animals, grief on animal death
- 79.35.1.11 Create player pet adoption and companionship with autonomous behavior
- 79.35.1.12 Implement farm animal visual integration — animals graze in pastures, wander in pens, sleep in barns: place each farm animal each tick from its production-cycle state and the time of day (pasture by day, pen or barn at night or in bad weather) with a wander target inside the enclosure polygon, and feed the instanced renderer of 79.4.4.2. Verify: a test runs a farm fixture for a simulated day and asserts that no animal leaves its enclosure, that the day and night locations follow the schedule, and that the instance buffer holds one entry per live animal.
- 79.35.1.13 Create animal audio — species-specific vocalizations,
feeding sounds, movement sounds (audio convention, 79.0.2): presets for
the farm, working and pet species of §79.35 for
creature_vocalization_sounds.rs, triggered by their state (hungry, feeding, alarmed, content), plus hoof and paw movement sounds throughmaya-surface-audio. Verify: offline renders for cow, chicken and dog presets pass the convention's assertions with fundamentals ordered by body size, and a test asserts that the hungry call rate rises as feeding time nears. - 79.35.1.14 Implement domestic animal integration with economy (§79.28) — production feeds into supply chains
- 79.35.1.15 Create domestic animal integration tests — verify care cycles, production output, bonding mechanics
79.36 Political & Governance Simulation (TypeScript)#
Government types, faction politics, civil unrest, and inter-faction diplomacy — inspired by Crusader Kings 3 and Dwarf Fortress.
79.36.1 Governance & Politics#
- 79.36.1.1 Create
libs/maya/politics/TypeScript library integrated with Hathor faction system - 79.36.1.2 Implement government type definitions — monarchy (hereditary), democracy (elections), theocracy, oligarchy, tribal, military
- 79.36.1.3 Create governance effects — tax rate affects NPC wealth, military spending affects defense, infrastructure investment affects quality
- 79.36.1.4 Implement leader personality influence on governance — greedy ruler = high taxes, benevolent = infrastructure investment
- 79.36.1.5 Create faction satisfaction tracking — each faction has demands, unmet demands reduce loyalty, faction power based on population and wealth
- 79.36.1.6 Implement civil unrest escalation — low satisfaction → grumbling → protests → riots → rebellion
- 79.36.1.7 Create protest mechanics — NPCs gather in public squares with demands, visible protest signs
- 79.36.1.8 Implement rebellion mechanics — armed uprising, potential regime change, civil war
- 79.36.1.9 Create political schemes — assassination plots, bribery, blackmail, alliance-building by ambitious NPCs
- 79.36.1.10 Implement succession system — heir assumption (hereditary), emergency election (democratic), military coup (military)
- 79.36.1.11 Create player political participation — run for office, support candidates, bribe officials, incite/suppress rebellion
- 79.36.1.12 Implement inter-faction diplomacy — trade agreements, alliances, non-aggression pacts, war declarations, peace negotiations
- 79.36.1.13 Create refugee displacement — war produces civilian refugees fleeing to neutral settlements
- 79.36.1.14 Implement political event integration with gossip system (§79.34) — political news travels through world
- 79.36.1.15 Create political simulation integration tests — verify governance effects, unrest escalation, succession mechanics
79.37 Digital Twin & Earth-Scale World Streaming (TypeScript + Rust)#
Cloud-streamed planet-scale terrain from satellite data — inspired by Microsoft Flight Simulator.
79.37.1 Geospatial Pipeline#
- 79.37.1.1 Create
libs/maya/geospatial/TypeScript service and Rust streaming integration in maya-world - 79.37.1.2 Implement satellite imagery tile ingestion — Bing Maps,
Mapbox, OpenStreetMap tile APIs with zoom levels 0-21.
- 79.37.1.2.a Take the open route first. In
libs/maya/geospatial/src/tiles.ts, add providers for openly licensed imagery that may be downloaded in bulk: Sentinel-2 cloudless mosaics and NASA GIBS over WMTS, and USGS NAIP for the United States, addressed by the slippy-map z/x/y scheme up to each source's real maximum zoom (about 14 for Sentinel-2; zoom 21 does not exist in open data), with the attribution string carried per tile and the cache ofcache.tshonoured. The OpenStreetMap standard tile servers are rendered maps, not imagery, and their usage policy forbids bulk download, so they are not a source here. Verify: a spec with the HTTP boundary mocked asserts the URL built per provider, the z/x/y-to-bounds maths against known tiles, cache hits on the second request, and attribution on every tile; one recorded live fetch of a single tile per provider is kept as a fixture. - 79.37.1.2.b Add the Bing Maps and Mapbox providers. Both need a paid
account and an API key under terms that restrict caching and offline
use, which are the owner's to accept (stated 2026-09-18).
blocked:external
- 79.37.1.2.a Take the open route first. In
- 79.37.1.3 Create tile pyramid caching with LRU eviction and configurable disk cache size
- 79.37.1.4 Implement DEM elevation data ingestion — SRTM, ASTER,
Copernicus heightmaps for terrain mesh generation: in
libs/maya/geospatial, read Copernicus GLO-30 and SRTM tiles (both openly licensed; record the download URLs and the licence text), resample them to the engine's terrain tile grid with void filling, and emit heightmaps in the formatmaya-genesis-terrainconsumes. ASTER GDEM needs a NASA Earthdata login, which is a free account only the owner can create, so it is left out unless a token is supplied. Verify: a spec ingests one real 1°×1° tile kept as a fixture, asserts a known summit elevation within the dataset's stated vertical error, that no void values remain, and that the edges match the neighbouring tile. - 79.37.1.5 Create vector data ingestion — road networks, building
footprints, land use classification from OpenStreetMap: parse an
OpenStreetMap
.osm.pbfregional extract (Geofabrik publishes them under the ODbL, and downloading an extract is the sanctioned bulk route) inlibs/maya/geospatialinto typed road, building and land-use features clipped per terrain tile, with the ODbL attribution carried. Verify: a spec ingests a small fixture extract and asserts the feature counts by class, that road geometry is continuous across a tile boundary, and that a building with aheightorbuilding:levelstag carries its height. - 79.37.1.6 Implement neural building reconstruction — roof type
classification from aerial imagery, height estimation, texture projection.
Make it granular: (1) height from the OpenStreetMap tags of 79.37.1.5,
falling back to a documented per-land-use default; (2) roof type (flat,
gabled, hipped) from a small ONNX classifier run on the CPU over the
footprint-cropped imagery of 79.37.1.2.a, trained on the openly licensed
roof labels carried by OpenStreetMap
roof:shapetags paired with that imagery; (3) facade and roof texture projection from the same imagery. First installonnxruntimeon the Linux server and record the version; park only with a named failed attempt. Verify: on a held-out set of at least 300 tagged buildings the classifier's accuracy is reported and beats the majority-class baseline, and a spec reconstructs a fixture block into meshes whose footprint area equals the source polygons within 1 %. - 79.37.1.7 Create vegetation placement from land cover classification:
map the ESA WorldCover 10 m classes (openly licensed; record the source
URL) and the OpenStreetMap land-use polygons of 79.37.1.5 to biome and
density inputs for
libs/maya/genesis-flora, so forests, grassland, cropland and built-up areas are planted accordingly. Verify: a spec places vegetation on a fixture tile and asserts tree density per class inside the configured ranges, no trees on water, roads or building footprints, and determinism for a seed. - 79.37.1.8 Implement road surface generation from vector data with
proper width, markings, and intersections: build road meshes from the road
features of 79.37.1.5 in
libs/maya/geospatial, with width from thelanesandwidthtags or a per-highway-class default, draped on the terrain of 79.37.1.4 with a cut-and-fill limit, lane markings as UV-mapped strips, and intersection polygons where ways share a node. Verify: a spec on a fixture junction asserts a watertight intersection polygon with no overlapping road quads, widths per class, a maximum grade under the limit, and markings that stop at the intersection. - 79.37.1.9 Create predictive tile prefetching — fetch along flight/drive direction before needed
- 79.37.1.10 Implement hybrid real+authored mode — artists override satellite data with hand-crafted terrain in specific areas
79.38 Procedural Environmental Sound Propagation (Rust + TypeScript)#
Sound that matches procedurally generated geometry — reverb from cave walls, occlusion from buildings, diffraction around corners. Currently sounds are generated procedurally but not propagated through the generated environments.
79.38.1 Geometry-Aware Audio#
- 79.38.1.1 Create acoustic probe auto-placement in procedural environments — after terrain/urban/cave generation, place probes at navigation-reachable positions with density proportional to geometry complexity
- 79.38.1.2 Implement cave acoustic profiling — analyze cave network geometry (chamber volume, tunnel width, surface material) → compute per- chamber reverb parameters (RT60, early reflection density, modal frequencies)
- 79.38.1.3 Create urban canyon sound propagation — model sound reflection and diffraction in procedurally generated street canyons: building height, street width, and surface materials determine reverberation character
- 79.38.1.4 Implement forest acoustic scattering — model sound attenuation through procedurally generated vegetation: tree density, canopy height, and undergrowth density determine high-frequency absorption and scattering
- 79.38.1.5 Create underwater acoustic propagation — model sound speed profile (temperature/depth dependent), absorption (frequency dependent), and reflection from procedural seafloor/surface for underwater environments
- 79.38.1.6 Implement dynamic acoustic update on world change — when procedural destruction removes a wall, cave collapses, or forest burns, incrementally update affected acoustic probes within 1 frame
- 79.38.1.7 Create ambient soundscape generation from environment — analyze procedural environment type (cave, forest, city, ocean, desert) → generate appropriate ambient sound bed with spatialized sources (dripping water in caves, birdsong in forests, traffic in cities)
- 79.38.1.8 Implement weather-driven acoustic changes — rain increases high-frequency absorption, snow dampens reflections, wind adds directional noise — tied to procedural weather system (§79.atmosphere)
- 79.38.1.9 Create acoustic occlusion for procedural interiors — in generated buildings (§79.urban), model door/window state affecting sound transmission between rooms, with portal-based propagation
- 79.38.1.10 Implement echo generation from terrain geometry — detect large flat surfaces (cliff faces, building walls) in procedural terrain → compute discrete echo timing and attenuation for mountain/canyon echo effects
79.39 Procedural Decorative Arts & Ornament Generation (Rust + TypeScript)#
Procedural knot patterns, Celtic interlace, braids, filigree, and ornamental motifs for architecture, furniture, jewelry, clothing, and tattoos — driven by mathematical knot theory and curve grammar systems.
79.39.1 Knot & Interlace Generation#
- 79.39.1.1 Create
libs/maya/ornament/TypeScript library with mathematical knot generator — define knots as sequences of crossings on a grid, generate smooth 3D curves from crossing diagrams with configurable strand radius and material - 79.39.1.2 Implement Celtic interlace pattern generator — plait/knot notation system with configurable grid size, break patterns, corner treatments, and terminations following Bain's "Celtic Art" methodology
- 79.39.1.3 Create braid pattern generator — mathematical braid group representation (σ_i generators) → 3D braid geometry with strand count, twist rate, and strand diameter parameters
- 79.39.1.4 Implement guilloche pattern generator — engine-turned engraving patterns from two rotating eccentric circles with phase, ratio, and amplitude parameters for banknote/watch/jewelry decoration
- 79.39.1.5 Create Moorish/Islamic geometric pattern generator — compass- and-straightedge construction of star-and-rosette patterns with configurable fold symmetry (6, 8, 10, 12-fold), interlacing rules, and color assignment
- 79.39.1.6 Implement filigree/scrollwork generator — recursive spiral and leaf motifs with branching rules, taper, and terminal decorations for wrought iron, jewelry, and architectural ornament
- 79.39.1.7 Create meander/fret pattern generator — Greek key and related angular meander patterns with configurable step size, nesting depth, and corner treatments
- 79.39.1.8 Implement tattoo placement system — map 2D ornamental
patterns onto character body mesh following UV flow, muscle topology, and
anatomical landmarks with proper distortion compensation: in
libs/maya/ornament, project a pattern frominterlace.tsonto a body-mesh region chosen by named landmarks, as a decal in UV space with a local conformal (least-squares) unwrap that compensates the stretch. Verify: a spec places a circular pattern on the upper-arm region of a fixture mesh and asserts that its 3D image stays circular within 5 % (the ratio of the principal axes), that it stays inside the region mask, and that it does not cross a UV seam. - 79.39.1.9 Create architectural ornament placement — apply generated
ornamental patterns to building facades at appropriate locations
(cornices, capitals, friezes, spandrels) based on architectural style
rules (§40.7 is complete; no
genesis-architecturepackage exists, and the facade generator islibs/maya/engine-core/crates/maya-genesis-urban/src/facade_grammar_system.rs): a rule table per architectural style that names which facade slots take which ornament family and at what scale, applied to the slot anchors that facade grammar exposes, with the pattern geometry fromlibs/maya/ornament. Verify: a spec decorates a fixture facade for two styles and asserts that ornaments appear only on the slots the style allows, that friezes tile without a partial repeat at the ends, and that nothing overlaps a window opening. - 79.39.1.10 Implement ornament-to-mesh conversion — extrude 2D
ornamental patterns into 3D relief geometry with configurable depth,
bevel, and material assignment for game-ready mesh generation: in
libs/maya/ornament, triangulate the closed curves ofcurves.tsandinterlace.ts(respecting the over-and-under crossings as height steps), extrude with a bevel profile, and emit an indexed mesh with normals, UVs and material slots. Verify: a spec converts a fixture knot and asserts a watertight manifold mesh (every edge shared by exactly two triangles), the configured depth and bevel in its bounds, the crossings at alternating heights, and a triangle count under the stated budget.
79.40 Procedural Food & Organic Material Generation (Rust)#
Procedural generation of food items, organic materials, and biological structures for game/film VFX — fruit cross-sections, bread crumb structures, meat grain, crystal formations, geological samples.
79.40.1 Organic Material Systems#
- 79.40.1.1 Create
libs/maya/organic-materials/crates/maya-organic/Rust crate with cellular structure generator — Voronoi-based cell packing with cell wall thickness, cell size variation, and anisotropy for bread, sponge, foam, and biological tissue - 79.40.1.2 Implement fruit cross-section generator — parametric fruit anatomy: skin thickness, flesh texture (fibrous/granular/smooth), seed arrangement (radial/scattered/central), color gradients from skin to core
- 79.40.1.3 Create bread/baked goods generator — crumb structure via Voronoi cell packing with gas expansion simulation, crust formation via surface hardening, scoring patterns via surface displacement
- 79.40.1.4 Implement meat/muscle fiber generator — anisotropic fiber bundle structure with grain direction, marbling (fat distribution via Perlin noise), and cooking state (raw→seared→well-done color/shrinkage)
- 79.40.1.5 Create crystal growth generator — seed-point crystal nucleation → dendritic growth along crystallographic axes → faceted termination, applicable to geodes, ice crystals, mineral specimens, and magical effects
- 79.40.1.6 Implement cheese/dairy generator — eye formation (CO2 bubble voids via Poisson placement), rind development, mold growth patterns (blue cheese veining via reaction-diffusion)
- 79.40.1.7 Create wood grain generator — annual ring growth simulation with variable ring width (climate), knot formation (branch junctions), ray figure (medullary rays), and species-specific characteristics
- 79.40.1.8 Implement geological sample generator — layered sedimentary structures, igneous crystal textures, metamorphic foliation patterns, fossil inclusion placement
- 79.40.1.9 Create coral/shell growth generator — accretionary growth simulation producing spiral shells (logarithmic spiral + aperture shape), coral branching (reaction-diffusion + space colonization), and barnacle clustering
- 79.40.1.10 Implement organic material aging — model decay processes: fruit bruising/rotting, bread staling/molding, meat decomposition, wood weathering/spalting, all as time-parameterized material transformations
79.41 Procedural Jewelry & Precious Object Generation (Rust + TypeScript)#
Parametric generation of jewelry, gemstones, and precious objects with physically accurate optical properties — gem cutting geometry, metalwork, settings, and decorative techniques.
79.41.1 Gem & Metalwork Generation#
- 79.41.1.1 Create
libs/maya/jewelry/TypeScript library with parametric gem cutting generator — define cut as sequence of facet planes (table, crown, pavilion, girdle) with angles derived from refractive index for optimal brilliance (Tolkowsky proportions for diamond, custom for colored stones) - 79.41.1.2 Implement standard gem cut library — round brilliant, princess, emerald, oval, marquise, pear, cushion, radiant, asscher, heart cuts with correct facet counts and angles per cut type
- 79.41.1.3 Create gem optical simulation — ray-trace through cut gem geometry using material refractive index (diamond=2.42, sapphire=1.77, emerald=1.58) to compute fire (spectral dispersion), brilliance (return light), and scintillation (sparkle pattern)
- 79.41.1.4 Implement prong/bezel/channel setting generator — parametric metal settings sized to gem dimensions with configurable prong count, metal type (gold, silver, platinum), and setting style
- 79.41.1.5 Create ring band generator — parametric ring cross-sections (comfort fit, flat, knife-edge, half-round) with finger size scaling, engraving channels, and stone mounting positions
- 79.41.1.6 Implement chain/link generator — parametric chain patterns (cable, curb, figaro, rope, box, wheat) with link dimensions, twist, and metal type for necklaces and bracelets
- 79.41.1.7 Create jewelry ensemble generator — compose complete jewelry sets (ring + earrings + necklace + bracelet) with consistent style, material, and gem coordination
- 79.41.1.8 Implement jewelry LOD chain — high-poly gem facets →
medium-poly simplified → low-poly billboard with baked sparkle texture for
distance rendering: in
libs/maya/jewelry, generate three LODs from the parametric gem and setting ofgems.tsandmetalwork.ts: full facets, a quadric-error simplification that preserves the girdle silhouette, and a billboard whose sparkle texture is baked from the facet normals. Verify: a spec asserts triangle counts under each LOD's budget, a silhouette difference between LOD0 and LOD1 under a stated fraction at the switch distance, and that the baked sparkle texture is deterministic. - 79.41.1.9 Create jewelry damage/wear states — scratched metal, chipped gems, tarnished silver, worn gold plating as time-parameterized material transformations
- 79.41.1.10 Implement jewelry try-on system — place generated jewelry
on character model at anatomically correct positions (ring finger joints,
earlobes, wrist, neck) with proper scale and physics (chain drape, earring
swing): in
libs/maya/jewelry, define attachment sockets on a skeleton (finger segment, earlobe, wrist, neck loop), size each piece from the socket's measured girth, and simulate chains and drop earrings as position-based-dynamics strands with collision against body capsules. Verify: a spec fits a ring to three finger sizes with no interpenetration and no gap above tolerance, a necklace fixture settles to a catenary-like drape with every link outside the neck and chest capsules, and an earring's swing decays after a head turn.
79.42 Procedural Environmental Storytelling (TypeScript + Rust)#
Automated placement of environmental narrative elements — scene dressing that tells stories without dialogue. Blood trails, scattered belongings, barricades, graffiti, posters, discarded items — placed by procedural rules driven by world simulation state.
79.42.1 Narrative Scene Dressing#
- 79.42.1.1 Create
libs/maya/env-storytelling/TypeScript library with event-to-decoration mapper — when world simulation produces events (battle, fire, abandonment, celebration, crime), generate corresponding environmental decoration rules - 79.42.1.2 Implement battle aftermath generator — based on combat simulation output: place weapon marks on walls, broken furniture, scattered equipment, blood spatters (direction from attack vectors), temporary barricades, and damaged terrain
- 79.42.1.3 Create abandonment/decay generator — based on time since last NPC occupation: accumulate dust, cobwebs, pest signs (droppings, nests), vegetation intrusion, structural deterioration, scattered personal items
- 79.42.1.4 Implement lived-in space generator — NPC personality and occupation drive decoration: scholarly NPC → books, scrolls, ink stains; blacksmith → tools, metal scraps, scorch marks; artist → paint splatters, canvases, pigment jars
- 79.42.1.5 Create graffiti/poster/sign generator — procedurally generate and place contextual graffiti, propaganda posters, shop signs, and notices on building surfaces based on district culture, political state, and economic conditions
- 79.42.1.6 Implement trail/track generator — NPCs and creatures leave traces: footprints in soft ground (species-specific), disturbed vegetation, scent trails (visible in tracking mode), broken branches, dropped items along travel paths
- 79.42.1.7 Create economic indicator decoration — wealthy district → maintained facades, decorative elements, clean streets; poor district → patched repairs, makeshift structures, accumulated refuse, informal market stalls
- 79.42.1.8 Implement seasonal decoration generator — festivals, holidays, and seasons drive decoration: harvest festival → crop displays, lanterns; winter → snow preparations, firewood stacks; mourning → black banners, closed shutters
- 79.42.1.9 Create crime scene generator — from crime simulation output: place evidence items, disturbed scene elements, investigation markers, witness reaction decorations (locked doors, curtained windows)
- 79.42.1.10 Implement environmental storytelling integration tests — verify decoration rules fire correctly from world events, placement avoids collision with existing geometry, decoration density scales with world simulation detail level