Maya Domain — Technical Specifications

Technical specification of the Maya virtual-universe domain as implemented in code today. Maya is an early-stage domain: the libraries below all exist on disk with real source, but they sit at different depths. This document describes the domain objects, enums, evaluation logic, schemas, services, build targets, and integration points that the source actually defines. Sections that describe a roadmap rather than shipped code are explicitly labelled (planned).

This document is a precise inventory of Maya's implemented surface: the Rust types, TypeScript schemas, enumerations, and evaluation functions that exist in source today. It is the authoritative reference for engineers integrating with or extending Maya. Content is organized by library, starting with the Rust engine workspace, then the seven TypeScript readiness facades, and finally the TypeScript service libraries.

Library Inventory#

Maya has 17 libraries under libs/maya/. There is no apps/maya/ or services/maya/. The libraries fall into three implementation shapes:

"Readiness facade" is a precise description, not a euphemism. Each of the seven single-module libraries exports a domain-specific TypeScript evaluation function (evaluateMaya*) plus the input/output/issue types it operates on. Their own package.json description fields say so verbatim — e.g. @maya/physics is "TypeScript facade for Maya physics simulation readiness across cloth, fluid, destruction, and particles". They contain real scoring formulas, not stubs, but they evaluate readiness rather than run the simulation. The runtime engines they describe live as Rust crates inside engine-core (maya-physics, maya-renderer, maya-world, etc.).

Technology Stack#

The table below records the precise dependency versions and Cargo configuration used by the engine workspace. This is the ground truth for any engineer setting up the Rust toolchain.

The engine-core Cargo workspace pins edition = "2021", version = "0.1.0", license = "Apache-2.0", resolver 2, and a release profile with lto = true, codegen-units = 1, opt-level = "s".

The earlier draft of this document listed wgpu, Rapier, Havok, PhysX, Jolt, cpal, symphonia, wasm-bindgen, and a custom UDP protocol as stack entries. None of those crates appear in the engine-core workspace Cargo.toml. The renderer, physics, and audio crates are currently backend-agnostic Rust modules; they do not yet bind a concrete GPU, physics, or audio vendor SDK. They are documented below as what they are.

Engine Core — Rust Workspace (@maya/engine-core)#

libs/maya/engine-core/ is a Cargo workspace of 28 member crates plus a thin TypeScript facade (src/index.ts). The Nx build/check/test/lint targets currently compile a subset of ten crates (maya-kernel, maya-renderer, maya-scene, maya-world, maya-resource, maya-ecs, maya-math, maya-plugin-api, maya-jobs, maya-time); the remaining crates build via pnpm cargo:build / cargo build --workspace.

Workspace Members#

The table below lists every crate, its Rust file count, and its responsibility. Crates with more files carry more domain logic; maya-embodiment at 153 files is the single deepest crate.

Phase 40 §40.22–40.28 packages present as TypeScript libraries under libs/maya/ (not engine-core crates): genesis-nca (Neural Cellular Automata growth), genesis-tiling (Wang/aperiodic-monotile tiling), genesis-physarum (slime-mold transport networks), genesis-sketch (sketch-to-terrain), genesis-neural-flora (neural L-systems), genesis-scene-agent (LLM-agent scene orchestration), plus future-input (BCI/EMG emerging-input abstraction, §40.28).

maya-kernel — Engine Kernel#

The kernel is the engine's boot-and-plugin manager. It orchestrates three subsystems that handle the plugin lifecycle from installation through frame dispatch:

• PluginRegistry / PluginSlot — loaded-plugin set, lifecycle states, capability-to-plugin mapping, registration and removal.
• HotReloadWatcher (HotReloadConfig, HotReloadEvent) — monitors plugin library files on disk via the notify crate and triggers reload.
• DependencyResolver — topological sort of plugins by declared dependencies, with circular-dependency detection.
• NativePluginLoader — dynamic native plugin loading.
• KernelError — error enum wrapping PluginError from maya-plugin-api.

The kernel exposes APIs for registering Rust-native and dynamic plugins, running a frame loop with phased plugin dispatch, hot-reloading at safe points, and delivering inter-plugin messages over crossbeam-channel.

maya-ecs — Entity-Component-System#

An archetype-based ECS inspired by bevy_ecs / hecs / legion. The archetype model stores entities with identical component signatures together in the same table, so iterating a component type is a tight linear memory scan:

• Entity — generational index { index, generation }; EntityAllocator with free-list for O(1) spawn/despawn and stale-reference detection; EntityLocation tracks archetype placement.
• Archetype / ArchetypeId / ArchetypeKey — components stored in archetype tables with Structure-of-Arrays layout.
• BlobVec — type-erased per-component column.
• ComponentId / ComponentInfo / ComponentRegistry — component registration metadata.
• World — spawn / spawn2 / spawn3, despawn, add_component, remove_component, get_component(_mut), has_component, and query / query_mut / query2 / query2_mut / query3 iteration over matching archetypes.

maya-jobs — Work-Stealing Job System#

The job system distributes CPU-bound work across all available cores using a Chase-Lev work-stealing algorithm. Each worker thread owns a local LIFO deque and steals FIFO from peers when idle, maximising cache locality for short-lived work while preventing starvation.

Multi-threaded job pool on Chase-Lev work-stealing deques (crossbeam-deque). N worker threads each own a local LIFO deque; a global injector accepts work from any thread; idle workers steal FIFO from peers. Public surface: JobPool / JobPoolConfig / Scope, JobHandle / JobGroup / JobPriority, JobCounter. Supports fire-and-forget spawn, DAG dependencies via atomic counters, job groups, scoped stack-borrowing execution, parallel-for, and active waiting that participates in work-stealing.

maya-fibers — Cooperative Coroutines#

Fibers provide a cooperative scheduling layer for long-running async work (such as network calls and asset loading) that must coexist with the synchronous real-time tick loop. Suspension happens only at .await, so no preemption is needed.

Tick-driven executor over Rust async/await (stackless coroutines). Public surface: FiberExecutor / ExecutorConfig / TickStats, FiberId / FiberPriority / FiberState, Signal / CountedSignal, and fiber::{ yield_now, wait_ticks }.

maya-alloc — Memory Allocators#

General-purpose allocators for the engine's different allocation lifetimes. Each strategy eliminates a class of heap fragmentation or GC pressure:

• BumpAllocator (+ BumpSavedState) — fast bump allocation that resets at a frame boundary.
• ScratchArena — nested save/restore scopes for temporary scratch memory.
• FrameArena — double-buffered ping-pong for per-frame data that outlives a single scope.
• Pool — paged pool with generational handles and a hierarchical free-slot bitmask for O(1) alloc/free of fixed-size objects.
• StackAllocator — marker-based LIFO.
• DoubleEndedStack — bottom-up + top-down in one buffer.

maya-math — Math Library#

Re-exports the full glam crate as the math backend and adds Transform (position + rotation + scale for scene-graph nodes), Rect, Aabb, Ray / Ray2d, and Color (linear RGBA with conversion helpers). A prelude module re-exports the common glam types.

maya-spatial — Spatial Acceleration#

Three complementary spatial data structures serve different query patterns: the octree handles dynamic objects that move each frame, the BVH optimises static geometry ray tests, and the k-d tree answers point-set proximity queries.

• octree::Octree — loose octree for dynamic scenes; insert/remove/update plus AABB / sphere / ray queries.
• bvh::Bvh — bounding volume hierarchy with binned SAH construction for static geometry and efficient ray intersection.
• kdtree::KdTree — balanced k-d tree for nearest-neighbour, k-NN, and range queries over point sets.

maya-world — Chunk World Partitioning#

The world crate is the spatial backbone for large and infinite worlds. It manages a chunk grid where each chunk progresses through a lifecycle FSM, and provides streaming, LOD, culling, origin rebasing, instancing, and migration tooling.

Modules: async_ops, bounds, chunk, config, coord, culling, error, grid, instancing, level, lod, lod_manager, merge_diff, migration, pipeline, provider, query, rebase, serialization, streaming, state, template, validation, version.

Key types: ChunkCoord (integer 3D address), WorldConfig / WorldConfigBuilder / WorldBounds, Chunk<T>, WorldGrid<T> / GridStats, ChunkRegion / RegionIter, StreamingManager / FocusPoint / StreamingUpdate, StreamingPipeline / PipelineConfig / StreamingStats / TickResult, LodCalculator / LodAssignment, OriginRebase / RebaseConfig / RebaseEvent / WorldPosition, InstanceManager / WorldInstance / InstanceSnapshot, ChunkProvider / CallbackProvider / ChunkRequest / ChunkResponse.

ChunkState Lifecycle FSM (maya-world/src/state.rs)#

Every chunk moves through a defined sequence of states. The FSM ensures that chunks are never accessed before their data is ready, and that unloading is cleanly sequenced:

Unloaded ──► Loading ──► Active ⇄ Frozen ──► Unloading ──► Unloaded

ChunkState provides a transition-validity check that prevents illegal state changes at runtime.

maya-time — Time and Simulation#

Time management covers the fixed-timestep accumulator loop, calendar and in-world seasons, determinism, time dilation, rollback, and debug time travel. The list of modules gives a complete picture of what is implemented:

Fixed-timestep accumulator loop (the Fix Your Timestep! pattern). Modules: accumulator, calendar, clock, day_night, debug_step, deterministic, dilation, event_scheduler, fixed_timestep, historical, interpolation, rollback, seasons, speed_control, stats, temporal_debug, time_travel, time_zones. Key types: FixedTimestep (from_hz, with_max_accumulation), SimulationClock, FrameTick, FrameStats, StepAccumulator.

maya-renderer — Render Pipeline#

The renderer organises all visual features as nodes in a directed acyclic render graph. The graph compiler infers resource lifetimes and pass ordering from each pass's declared reads and writes, eliminating manual barrier management.

Frame-graph render pipeline. render_graph provides automatic resource management over a DAG of render passes: RenderGraph, TextureDesc, TextureFormat, ResourceUsage flags, add_pass builder, compile. The crate has ~94 feature modules including adaptive_resolution, anti_aliasing, area_light_shadows, async_compute, auto_lod, auto_quality, backend, bindless, bloom_energy_conservation, cascaded_shadow_maps, chromatic_aberration, clear_coat_materials, cloth_shading, anisotropic_materials. These are backend-agnostic Rust modules; no concrete GPU API binding (Vulkan/Metal/DX12/WebGPU) is present in the crate's dependencies.

maya-physics — Physics#

The physics crate uses a backend registry rather than committing to a single solver, so the simulation API is stable while the underlying implementation can be swapped. The public surface covers the full range of phenomena a game world needs:

Backend-agnostic physics layer. Public surface includes PhysicsBackendRegistry (capability-based backend selection), PhysicsSceneConfig (gravity, timestep, CCD, GPU simulation, large-world), CollisionLayerSet (object layers, broadphase layers, pairwise matrix), PhysicsMaterialSet (reusable surface materials, friction/restitution), ConstraintSet (hinge / slider / ball / fixed / spring joints), RagdollArticulation (skeleton-to-body mapping, pose round-trip), VehicleConfig (wheeled / tracked / hover drivetrains), BuoyancySimulator, PhysicsInterpolator (fixed-step snapshot interpolation), PhysicsDebugVisualizer, CollisionEventDispatcher (begin/persist/end events), PhysicsAnimationBlender, and cloth solvers MassSpringCloth, PbdCloth, GpuClothSolver. Crate source covers cloth (PBD, wind, tearing, self-collision, LOD), fluid (FLIP, GPU, bubbles, rigid interaction, cache), destruction (Voronoi, prefractured, cleanup, audio), and secondary motion (hair/fur, rope/cable, jiggle, inflatable).

maya-audio — Spatial Audio#

The audio crate implements spatial sound processing through successive layers: source spatialization (HRTF or ambisonics), occlusion (direct-path blocking, grazing obstruction, frequency-dependent transmission), and room propagation (portal routing, opening propagation through apertures).

Layered spatial-audio engine: binaural HRTF rendering for mono point sources (analytic dataset), personalized HRTF estimation from ear/head scan descriptors, ambisonics encoding (ACN ordering, SN3D/N3D normalization, first/second/third order), VR binaural rendering with headset profiles and head-pose transforms, distance-rolloff spatial-gain models, Doppler pitch shift, occlusion analysis (direct-path blocking, grazing obstruction, frequency-dependent transmission), portal room-to-room routing, opening propagation through apertures, VR head-tracking with predicted display time.

maya-atmosphere — Sky, Weather, Water#

The atmosphere crate's top-level entry point computes sky radiance from first principles. The ~75 crate modules cover every atmospheric phenomenon from aurora rendering to ocean caustics.

PhysicallyBasedAtmosphereScatteringSystem samples sky radiance from an observer position, view direction, and sun direction. Crate modules include accurate_celestial_positioning, alien_sky_configurations, artificial_lighting_at_night, aurora_rendering, blizzard_visibility_effects, boat_wake_and_trails, caustics_rendering, cloud_coverage_control, cloud_god_rays, cloud_lighting_shadows, cloud_lod_performance, cloud_movement_evolution, cloud_noise_generation, cloud_preset_library, and more (~75 files spanning clouds, weather, and water surfaces).

maya-embodiment — Avatars (153 files)#

The avatar system is built around a parametric body morphing system that drives rig bindings and clothing-fit metrics from a set of shape descriptors. The animation stack layers on top, providing IK, motion matching, retargeting, compression, and secondary motion.

ParametricBodyMorphingSystem combines descriptor-driven sliders, rig bindings, body measurements, clothing-fit metrics, and corrective passes (ParametricBodyMorphRequest, BodyMorphShape). Crate modules cover accessory_attachment_points, accessory_wearables, aging_weathering, and a deep animation stack: animation_additive, animation_blending, animation_compression, animation_foot_ik, animation_full_body_ik, animation_hand_ik, animation_look_aim_ik, animation_montage, animation_motion_matching, animation_pose_search, animation_procedural, animation_retargeting, plus accessibility testing tools.

maya-souls — AI NPCs (76 files)#

The NPC AI stack is built on a provider-neutral chat-completion layer so that the same personality and behaviour logic works with any LLM backend. The llm_integration module defines all request/response types; behaviour, memory, and social modules build on top of it.

llm_integration module is a provider-neutral chat-completion layer:

• MayaLlmProviderKind — provider enum (normalizes Claude / GPT / local Llama-style APIs).
• MayaLlmMessageRole, MayaLlmFinishReason, MayaLlmToolChoice, MayaLlmMessagePart — message-shape enums.
• MayaLlmMessage, MayaLlmToolDefinition, MayaLlmRequest, MayaLlmResponse, MayaLlmChoice, MayaLlmUsage — request/response model.
• MayaLlmProviderCapabilities, MayaLlmProviderConfig, MayaLlmIntegrationConfig, MayaLlmTransportRequest / MayaLlmTransportResponse — provider configuration and transport.
• MayaLlmIntegrationLayer<TTransport> — transport-generic integration layer with MayaLlmProviderStats / MayaLlmIntegrationStats.
• MayaLlmIntegrationError — error enum.

Other crate modules: big_five_personality, behavior_tree_system, goap_planning, episodic_memory, emotional_memory, emotional_state_machine, emotional_decay_transitions, memory_consolidation, memory_embedding, memory_forgetting_curves, memory_importance_scoring, memory_persistence, memory_retrieval, memory_search, conversation_branching, conversation_context, conversation_steering, character_arc_tracking, character_knowledge_base, character_personality_prompt, character_voice_consistency, community_dynamics_simulation, cultural_norm_enforcement, daily_schedule_routine_system, faction_group_membership, family_kinship_system, forbidden_topic_guardrails, friendship_rivalry_dynamics, influence_persuasion_systems, job_occupation_behaviors, mood_system, motivation_goal_system, multimodal_input_handling, need_satisfaction_behaviors, npc_interruption_handling, npc_to_npc_autonomous_interactions, nvidia_ace_integration, opinion_formation_change, and more.

maya-nexus — Multiplayer (77 files)#

The multiplayer crate models a three-tier topology: gateways admit clients and negotiate protocol versions; simulation nodes own authoritative state for a spatial authority domain; clients send commands and consume snapshots and events. All communication travels over typed envelopes — the implementation is transport-agnostic so the underlying network layer can be swapped.

Deterministic client-server networking core. Topology model: gateways admit clients, negotiate protocol versions, and issue session tickets; simulation nodes own authoritative session state for an authority domain; clients send commands and consume snapshots/events; cluster snapshots expose topology, load, and reservations.

Key types: NexusAuthorityDomainId, NexusServerNodeDescriptor / NexusServerNodeRole (Gateway, Simulation), NexusCluster / NexusClusterConfig, NexusClientRuntime / NexusClientConfig, NexusProtocolVersion, NexusInMemoryLink. The implementation is transport-agnostic — typed envelopes and a session lifecycle, on top of which the ~77 crate modules add interest_management, client_prediction, entity_interpolation, lag_compensation, delta_compression, bandwidth_adaptation, authoritative_simulation, load_balancing, capacity_scaling, mesh_topology, edge_server_deployment, cross_region_connectivity, cross_world_identity / cross_world_asset_transfer / cross_world_events / cross_world_friend_visibility, friend_system / friend_request_flow, guild_clan_system / guild_ranks_permissions / guild_management_tools / guild_events_activities, party_group_system / party_invite_joining, block_mute_system, featured_world_system, activity_feed, metaverse_navigation_system, and persistence modules (building_construction_persistence, economic_state_persistence, inventory_persistence, npc_state_persistence, incremental_world_save_system).

maya-immersion — VR/XR (76 files)#

The XR crate wraps every supported headset behind platform-agnostic Rust types. External SDK dependencies are hidden behind abstract structs/traits — only glam, serde, and bitflags are compile-time dependencies — so the vendor SDK integrations are scaffolded interfaces rather than linked libraries.

Device modules: openxr_runtime_integration, meta_quest_sdk, steamvr_integration, apple_vision_pro, pico_sdk, playstation_vr2, htc_vive_focus, device_capability_detection, controller_abstraction, button_axis_mapping, haptic_feedback_abstraction, device_runtime_switching, device_specific_optimizations, feature_fallback, device_debugging_tools. Hand-tracking modules: native_hand_tracking, hand_skeleton, finger_joint_tracking, gesture_recognition, pinch_grab_detection.

maya-genesis-terrain / -urban / -flora — Procedural Generation Crates#

These three Rust crates are the runtime procedural generators that produce terrain, cities, and vegetation at world scale. Each crate's module count reflects its complexity: urban generation (139 files) is the deepest because it covers the full pipeline from road networks down to individual building facades.

• maya-genesis-terrain — deterministic multi-octave height synthesis (improved Perlin, simplex), cellular Worley masks, domain warping, ridged multifractal, Swiss turbulence, hybrid multifractal, real-world DEM import (SRTM .HGT, ASTER GeoTIFF), heightmap compositing, planetary cube-sphere terrain, quadtree terrain LOD with screen-space CLOD.
• maya-genesis-urban — L-system road grammar, tensor-field road alignment, organic/grid/radial road-pattern synthesis, hybrid topology composition, terrain-adaptive road placement with cut/fill estimation, road hierarchy classification, intersection generation, highway interchange generation. (139 files — the deepest genesis crate.)
• maya-genesis-flora — deterministic L-system tree generation (3D turtle interpretation, branch-state stacking, stochastic successors, tropism steering), space-colonization growth, species presets, branch mesh generation, bark texture synthesis, leaf placement/billboarding, leaf cluster generation, seasonal leaf color (driven by maya-time seasonal state), tree growth animation.

TypeScript Facade (engine-core/src/index.ts)#

The thin TypeScript facade at the top of the engine workspace provides a readiness check for a virtual-environment capture session. It exposes one evaluation function, the types it consumes, and the readiness enum it returns.

MayaEngineCoreReadiness = 'ready' | 'needs-attention' | 'blocked'.

createMayaEngineCoreVirtualEnvironmentFrame(input) evaluates a virtual environment for capture-stage readiness. Input (MayaEngineCoreVirtualEnvironmentInput): environmentId, label, targetFrameRateFps, maxFrameLatencyMs, cameraTracked, genlockAligned, drawCallCount, triangleCount, streamingCellCount, materials (MayaEngineCorePbrMaterial[]), lights (MayaEngineCoreRenderLight[]).

The two main input array types carry the following fields:

• MayaEngineCorePbrMaterial — materialId, label, baseColorLinear (linear RGB triple), metallic, roughness, normalMapPresent, roughnessMapPresent, metallicMapPresent, texelDensityPxPerMeter. Physically valid when colour channels ∈ [0,1], metallic ∈ [0,1], roughness ∈ [0.02,1], and texelDensityPxPerMeter ≥ 512.
• MayaEngineCoreRenderLight — lightId, label, type ('directional' | 'area' | 'point' | 'image-based'), intensityLux, colorTemperatureKelvin, castsShadows.

Output (MayaEngineCoreVirtualEnvironmentFrame): readiness, pbrCoverageRatio, lightingCoverageRatio, syncCoverageRatio, realtimeFrameRatio, estimatedFrameLatencyMs, estimatedFrameRateFps, issues. Issue types: camera-untracked, genlock-unaligned, pbr-material-invalid, pbr-texture-incomplete, lighting-incomplete, frame-budget-exceeded. Estimated frame latency = base 4 ms + draw-call cost

• triangle cost + streaming-cell cost + material cost + shadow-light cost.

Readiness-Evaluation Facade Libraries#

The seven single-module libraries — libs/maya/{genesis-terrain,genesis-urban,genesis-flora,physics,renderer, scene,world} — share a uniform design pattern. Understanding the pattern once lets you read any of the seven without surprises:

• Each library exports a single evaluateMaya* function.
• The function takes a *Input description type (configuration of the engine feature to be evaluated).
• Each issue carries a discriminated issueType union and severity: 'warning' | 'blocking'.
• The *Evaluation output carries per-aspect coverage ratios, latency/memory estimates, and an issues array.
• Readiness is 'blocked' if any blocking issue exists, 'needs-attention' if only warnings exist, else 'ready'.

They evaluate engine configuration; the corresponding runtimes are engine-core Rust crates.

@maya/genesis-terrain#

evaluateMayaGenesisTerrainEnvironment(input) scores terrain generation readiness. The input is broken into config blocks, each evaluated separately.

• MayaGenesisTerrainScale — 'set-extension' | 'regional-backlot' | 'hero-landscape'.
• MayaGenesisTerrainBiomeMode — 'earthlike' | 'alien' | 'fantasy' | 'painted-override'.
• Config blocks: MayaGenesisTerrainHeightfieldConfig (resolution, size, noise octaves, heightmap, domain warping, compositing layers, spherical patch); …ClimateBiomeConfig (global climate, temperature gradient, precipitation/moisture, Whittaker biomes, boundary blending, altitude zones, microclimate, seasonal variation); …ErosionHydrologyConfig (hydraulic, thermal, wind/coastal erosion, river network, sediment transport, flow map, cave/overhang); …StreamingLodConfig (LOD hierarchy, streaming planner, virtual texturing, crack-free morphing, resident-tile ratio, preload coverage); …MaterialExportConfig (height/slope material blend, biome preview, texture coverage, collision mesh, render export).
• Issue types: terrain-disabled, determinism-missing, heightfield-coverage-low, climate-biome-coverage-low, erosion-hydrology-coverage-low, streaming-lod-coverage-low, material-export-coverage-low, generation-budget-exceeded, memory-budget-exceeded.

@maya/genesis-urban#

evaluateMayaGenesisUrbanEnvironment(input) scores urban generation readiness, from road network down to render export.

• MayaGenesisUrbanScale — 'street-set' | 'district' | 'city-backdrop'.
• MayaGenesisUrbanArchetype — 'new-york' | 'tokyo' | 'hong-kong' | 'dubai' | 'solarpunk' | 'cyberpunk' | 'alien-megacity'.
• Config blocks: …RoadNetworkConfig, …ParcelZoningConfig, …BuildingConfig (building-type selection, massing grammar, facade grammar, roof generation, interior layout, style archetype, generated vs target building count), …InfrastructureConfig (power / water / sewage / telecom / transit / civic services), …RenderExportConfig (material assignment, signage props, lighting placement, LOD streaming, CityJSON export, renderer handoff, texture coverage).
• Issue types: urban-disabled, determinism-missing, road-network-low, parcel-zoning-low, building-generation-low, infrastructure-low, render-export-low, generation-budget-exceeded, memory-budget-exceeded.

@maya/genesis-flora#

evaluateMayaGenesisFloraLandscape(input) scores vegetation generation readiness across tree generation, biome distribution, ecology simulation, and render export.

• MayaGenesisFloraScale — 'hero-tree' | 'forest-set' | 'landscape-backdrop'.
• MayaGenesisFloraBiome — 'temperate-forest' | 'wetland' | 'meadow' | 'urban-park' | 'tropical-jungle' | 'alien-biome' | 'enchanted-forest'.
• Config blocks: …TreeGenerationConfig (L-system trees, space-colonization trees, species presets, branch mesh, bark textures, leaf billboards, generated vs target tree count); …DistributionConfig (biome rules, slope/altitude constraints, moisture, sunlight, density maps, Poisson sampling, clustering, undergrowth, grass/meadow, wetland/aquatic); …EcologyConfig (competition model, succession simulation, seasonal growth, soil/water/carbon, biodiversity metrics, health visualization, save/restore); …RenderExportConfig; …ExoticBiomeConfig (bioluminescent, crystalline, gaseous, silicon-based, carnivorous megaflora, symbiotic colonies, alien preset library).
• Issue types: flora-disabled, determinism-missing, tree-generation-low, distribution-low, ecology-low, render-export-low, exotic-biome-low, generation-budget-exceeded, memory-budget-exceeded.

@maya/physics#

evaluateMayaPhysicsSimulation(input) scores physics simulation readiness. The input describes the active simulation type and backend, plus optional per-domain configs for cloth, fluid, destruction, and particles.

• MayaPhysicsSimulationType — 'cloth' | 'fluid' | 'destruction' | 'particles'.
• MayaPhysicsBackend — 'cpu' | 'gpu' | 'hybrid'.
• Per-domain optional config: MayaPhysicsClothConfig (vertex count, constraint iterations, pin coverage, self-collision, wind coupling, LOD); …FluidConfig (particle count, grid cells, surface reconstruction, foam/spray, viscosity model, container boundary); …DestructionConfig (shard count, support-graph coverage, runtime fracture, debris budget, dust particles, persistence); …ParticleConfig (emitter count, max particles, GPU simulation, collision events, lifetime bound, LOD).
• Output adds solverCoverageRatio, collisionCoverageRatio, cacheSyncRatio, renderSyncRatio, realtimeStepRatio, estimatedStepLatencyMs, estimatedStepRateHz.
• Issue types: simulation-disabled, solver-coverage-low, collision-coverage-low, cache-sync-low, render-sync-low, frame-budget-exceeded, domain-config-missing, determinism-missing.

@maya/renderer#

evaluateMayaRendererPass(input) scores renderer readiness across three independently evaluated config blocks: global illumination, virtualized geometry, and neural rendering.

• MayaRendererGiMode — 'probe-grid' | 'radiance-cache' | 'hybrid-raytraced' | 'path-traced'.
• MayaRendererNeuralRepresentation — 'none' | 'nerf' | 'gaussian-splatting' | 'hybrid'. Required dataset view counts: nerf 48, gaussian-splatting 96, hybrid 128.
• Config blocks: MayaRendererGiConfig (mode, diffuse bounces, specular samples/pixel, probe ray count, radiance-cache entries, emissive injection, leak prevention, temporal denoising); …VirtualizedGeometryConfig (mesh shader, cluster count, requested/resident cluster pages, triangle count, streaming budget, working set, fallback mesh, occlusion culling); …NeuralRenderingConfig (enabled, representation, training converged, dataset view count, target resolution scale, inference latency, model memory, temporal stability score, reconstruction quality score).
• Output adds giCoverageRatio, virtualizedGeometryRatio, neuralRenderingRatio, realtimeFrameRatio, estimatedFrameLatencyMs, estimatedFrameRateFps, estimatedMemoryMb, estimatedQualityScore.
• Issue types: gi-coverage-low, virtualized-geometry-low, neural-rendering-low, neural-rendering-disabled, neural-training-incomplete, neural-inference-slow, frame-budget-exceeded, memory-budget-exceeded, quality-target-missed.

@maya/scene#

evaluateMayaSceneVirtualSet(input) scores scene readiness — whether all required assets are loaded, the scene graph is valid, nodes are tracked for capture, and persistent state is bound.

• MayaSceneAssetType — 'model' | 'texture' | 'material' | 'lighting' | 'audio' | 'script'.
• MayaSceneAsset — assetId, label, type, required, loaded, persistentCacheReady, integrityVerified, byteSize, dependencies.
• MayaSceneNode — nodeId, label, optional parentNodeId, optional assetId, active, transformValid, trackedForCapture, persistentStateBound.
• MayaSceneStatePersistence — snapshotId, enabled, schemaVersion, dirtyNodeCount, conflictCount, recoveryPointReady, replicatedToCaptureSession.
• Output: requiredAssetCoverageRatio, dependencyCoverageRatio, sceneGraphCoverageRatio, captureTrackingRatio, persistenceCoverageRatio, estimatedLoadLatencyMs.
• Issue types: required-asset-missing, asset-dependency-missing, asset-integrity-missing, scene-graph-invalid, capture-tracking-low, state-persistence-low, load-budget-exceeded.

@maya/world#

evaluateMayaWorldVirtualEnvironment(input) scores overall world readiness: streaming, time-of-day, weather, atmosphere, and water surface configuration are each scored against coverage thresholds.

• MayaWorldEnvironmentScale — 'stage-volume' | 'exterior-set' | 'open-world-backdrop'.
• MayaWorldWeatherMode — 'clear' | 'rain' | 'snow' | 'fog' | 'thunderstorm' | 'sandstorm' | 'alien-sky'.
• Config blocks: MayaWorldStreamingConfig (chunk streaming, LOD manager, culling pipeline, origin rebase, validation/repair, save/restore, active vs target chunk count, resident-chunk ratio, validation issue count); …TimeOfDayConfig (sun position, sun/moon rendering, day/night cycle, latitude day length, per-zone time, time lock, calendar/season, time acceleration); …WeatherConfig (state machine, forecast, transitions, precipitation particles, fog/mist, storm/wind, surface wetness, snow accumulation, visibility coverage, active hazard count); …AtmosphereConfig (physically based scattering, Rayleigh/Mie, volumetric clouds, cloud lighting/shadows, sky preset, celestial events, night sky, HDRI export, sky texture coverage); …WaterSurfaceConfig (ocean, lake/pond, river flow, reflections/refractions, caustics, ripples/foam); …RenderExportConfig.
• Issue types: world-disabled, determinism-missing, streaming-low, time-of-day-low, weather-low, atmosphere-low, water-surface-low, render-export-low, frame-budget-exceeded, memory-budget-exceeded.

Data Persistence (@maya/database)#

The database library provides domain schemas and a data-access layer as plain TypeScript — it has no Drizzle ORM dependency. Each schema module defines plain TypeScript interfaces, enums, a *Validator class, and a generate*TablesDDL() function that emits SQL DDL strings. The barrel src/index.ts re-exports them all.

Core Schemas#

The table below maps each schema module to its most important enums and types. Every module follows the same pattern: enums define the legal values, interfaces define the record shape, a *Validator enforces business rules, and generate*TablesDDL() emits the corresponding SQL.

WorldSchema / ZoneSchema (world-zone-schema.ts)#

The world and zone schemas are the central persistence types for the game world. A world is the top-level container; zones are the spatial subdivisions within it (open world, dungeon instances, lobbies, arenas, housing). The validator enforces the naming and coordinate limits shown in the comments below:

enum WorldVisibility {
  Public,
  Private,
  FriendsOnly,
  Unlisted,
}
enum ZoneType {
  OpenWorld,
  Instance,
  Lobby,
  Housing,
  Arena,
  Dungeon,
  Hub,
}

interface WorldSchema {
  worldId: string;
  creatorId: string;
  name: string;
  description: string;
  visibility: WorldVisibility;
  maxPlayers: number;
  currentPlayers: number;
  tags: string[];
  thumbnailUrl: string | null;
  rating: number;
  createdAt: Date;
  updatedAt: Date;
}

interface ZoneSchema {
  zoneId: string;
  worldId: string;
  type: ZoneType;
  name: string;
  spawnPoint: Vec3;
  bounds: BoundingBox;
  npcSpawnConfig: Record<string, unknown>;
  weatherConfig: Record<string, unknown>;
  createdAt: Date;
}

WorldSchemaValidator enforces: world name 1–80 chars, description ≤ 2000 chars, ≤ 20 tags of ≤ 32 chars each, coordinates within ±1,000,000.

Data-Access Layer#

The data-access layer provides the query and transaction infrastructure that sits between the schema modules and the database. Key types:

MayaRepository (with FilterOperator, SortOrder, QueryFilter, SortSpec, PaginationSpec, QueryResult, RepositoryStats); query builders SelectBuilder / InsertBuilder / UpdateBuilder / DeleteBuilder (emit BuiltQuery); MayaTransaction / MayaTransactionManager (TransactionIsolationLevel, DEFAULT_TRANSACTION_OPTIONS, TransactionTimeoutError); MayaCacheLayer (CacheStrategy, Redis-style RedisClient interface, CacheEntry, CacheStats); MayaReadReplicaRouter (ReadReplicaPolicy, ReplicaNode, NoHealthyReplicaError); MayaShardRouter (ShardKey, ShardRange, ShardConfig, ShardMigrationPlan).

Operations and Compliance#

The operations layer handles data lifecycle concerns — archival, backup, GDPR, and monitoring — as standalone managers with their own type surfaces:

MayaDataArchiver (ArchivalPolicy, ArchivalJob, ArchivalJobStatus); MayaDatabaseBackup (BackupType, BackupStatus, BackupManifest, RestoreOptions); MayaPitrManager point-in-time recovery (WalSegment, PitrTarget, PitrRecoveryPlan, PitrProgress); MayaDataExporter (ExportFormat, ExportStatus); MayaGdprManager (GdprRequestType, GdprRequestStatus, DataCategory, ErasurePlan); MayaDataAnonymizer (AnonymizationRule, AnonymizationConfig, AnonymizationReport); MayaDataRetentionManager (RetentionPolicy, RetentionRun, RetentionRunStatus); MayaDatabaseMonitor (DatabaseMetric, SlowQueryRecord, DatabaseHealthReport); MayaQueryOptimizer (QueryPlan, QueryOptimizationSuggestion).

Server Infrastructure (@maya/server)#

TypeScript Node.js service modules, barrelled through src/index.ts. The server library owns the game server runtime: the central simulation loop, session and player connection management, all live-service services, and operational tooling. Modules include: game-server-application, world-simulation-loop, player-connection-management, authentication-integration, authentication-service, session-management, anti-cheat-measures, server-side-physics, ai-npc-simulation, economy-service, economy-transactions, event-broadcasting, server-clustering, zone-handoff-protocol, server-metrics-monitoring, server-administration-tools, server-hot-reload, service-mesh-configuration, social-graph-service, matchmaking-service, achievement-service, leaderboard-service, content-moderation-service, asset-storage-service, analytics-service, user-management-service, inventory-service, payment-processing-integration, email-service-integration.

WorldSimulationLoop (world-simulation-loop.ts)#

The simulation loop is the heartbeat of the game server. It implements the classic Fix Your Timestep! accumulator pattern with a spiral-of-death prevention cap on maximum substeps per real-time frame. The configuration and tick types are:

interface SimulationLoopConfig {
  fixedTimestep_ms: number; // 16.67 for 60 Hz
  maxSubsteps: number; // cap per real-time frame
  catchUpFactor: number; // 0–1, fraction of accumulated time consumed
}

interface SimulationTick {
  tickNumber: number;
  simTime_ms: number;
  deltaTime_ms: number;
  isCatchUp: boolean;
}

WorldSimulationLoop registers TickCallbacks and drives them off a setInterval handle, tracking an accumulator, sim time, and tick count.

Client SDK (@maya/client)#

TypeScript library, barrelled through src/index.ts. The client SDK is the entry point for all platform-facing concerns: it wraps platform differences behind the enums and states below so game code is platform-agnostic.

• Platform abstraction — platform-abstraction-layer.ts defines MayaClientPlatformCapability (multi-window, single-window, display-control, local-storage, notifications, messaging, external-links, xr-session, haptics, keyboard-input, pointer-input, touch-input, controller-input, offline-cache), MayaClientWindowState (hidden, visible, minimized, maximized, fullscreen, closed), MayaClientXrSessionState (idle, ready, running, stopping, stopped).
• Build targets — windows-desktop-build, macos-desktop-build, linux-desktop-build, android-mobile-build, ios-mobile-build, webgpu-browser-build, webxr-browser-build, meta-quest-standalone-build, steamvr-build, apple-vision-pro-build.
• Distribution — app-store-distribution, play-store-distribution, steam-distribution, meta-quest-store-distribution, ci-cd-build-pipeline, launcher-integration, automatic-updates.
• Runtime — client-application-framework, asset-loading-and-caching, input-handling-system, window-display-management, configuration-management, user-settings-persistence, offline-mode-support, mod-and-plugin-loading, client-side-validation, client-performance-profiling, client-debugging-tools, crash-reporting-and-diagnostics.

Game Framework (@maya/games)#

TypeScript library, barrelled through src/index.ts, organised into 19 sub-directory modules: stats, progression, skills, abilities, inventory, items, equipment, crafting, gathering, survival, loot, mmo, classes, party, companions, quests, combat, hathor.

Combat (games/src/combat/)#

Real-time RPG combat built around a health-damage core. The health system defines the combatant lifecycle (Healthy through Defeated); the damage calculation system feeds into it from above.

health-damage-system.ts defines HealthStateKind (Healthy, Wounded, Critical, Downed, Defeated) and HealthDamageEventKind (CombatantSynced, DamageApplied, HealingApplied, CombatantDowned, CombatantRevived, …); it consumes damage-calculation-system.ts (DamageType, DamageSourceKind, DamageOutcome, DamageCalculationResult) and the stats module's CharacterStatSystem / ResourcePool. Other combat modules: weapon-system, melee-combat-system, ranged-combat-system, combo-attack-chain-system, blocking-parrying-system, dodge-roll-system, cover-system, projectile-physics-system, status-effect-system, ai-combat-behavior-system, group-combat-tactics-system, combat-difficulty-scaling-system, combat-analytics-system.

MMO (games/src/mmo/)#

MMO social and content systems: guild-system, guild-rank-permissions-system, guild-bank-storage-system, guild-housing-halls-system, dungeon-instancing-system, raid-encounter-system, boss-mechanics-framework, world-boss-spawning-system, pvp-system, battleground-arena-system, ranking-matchmaking-system, auction-house-system, mail-system, achievement-system, seasonal-content-system.

Survival (games/src/survival/)#

Survival gameplay systems covering player needs, base building, and the environment: hunger-thirst-system, temperature-exposure-system, sleep-rest-system, disease-illness-system, food-drink-item-system, tool-durability-system, base-building-system, building-upgrade-system, structure-placement-validation, base-defense-raid-system, shelter-mechanics-system, environmental-hazard-system, resource-node-system, wildlife-hunting-system, pet-taming-system.

Quests (games/src/quests/)#

Quest lifecycle from definition through consequence tracking: quest-definition-system, quest-objective-system, quest-chain-system, quest-tracking-system, quest-marker-system, quest-reward-system, quest-outcome-system, quest-consequence-system, quest-faction-reputation, quest-dialogue-integration, quest-procedural-generation, quest-radiant-system, quest-sharing-system, quest-state-persistence, quest-debugging-tools.

Hathor Integration (games/src/hathor/)#

The Hathor boundary is one-directional: Maya's game systems consume Hathor worldbuilding data; Hathor does not depend on Maya. This allows Maya worlds to be culturally grounded without coupling the narrative layer to the engine.

Modules: hathor-world-data-import, hathor-cultural-rules-integration, hathor-religion-belief-integration, hathor-language-naming-integration, hathor-economic-model-integration — import of worldbuilding data from the Hathor domain into Maya's game systems.

Inspiration Library (@maya/inspirations)#

TypeScript reference-data library, barrelled through src/index.ts. reference-types.ts defines the shared vocabulary used to type all reference data:

• CityReferenceDensity — low, moderate, high, hyper-dense
• CityReferenceGridPattern — commissioners-grid, diagonal-grid, organic-waterfront, hill-adapted-grid, campus-superblock
• CityReferenceTransitMode, CityReferenceLandUse, CityReferenceLightingTime, CityReferenceClimateProfile, CityReferenceMeasurement

The library ships parameter sets for real-world cities (Manhattan, Hong Kong, Tokyo/Neo-Tokyo, Dubai, Singapore, European historic cities, Paris/London/Rome, Middle Eastern and African and Southeast Asian urban patterns), fictional universes (Blade Runner LA 2049, Night City, Mega-City One, Matrix mega-city, Ghost in the Shell New Port City, Coruscant, Mass Effect Citadel, Halo New Mombasa, Final Fantasy Midgar, Game of Thrones / Lord of the Rings / Elder Scrolls cities, Mirror's Edge), biome references (temperate forest, tropical rainforest, desert/dune, tundra/arctic, mountain/alpine, ocean/coastal, cave/underground, bioluminescent, crystal/mineral, magical/enchanted forest, corrupted/tainted biomes), and style guides (original cyberpunk / fantasy, organic-biomechanical, character / vehicle / prop, audio, UI/UX). It also includes Yemaya integration test fixtures.

Testing Infrastructure (@maya/testing)#

TypeScript test-harness library, barrelled through src/index.ts, in three groups:

• Unit testing — unit-test-framework-setup, engine-core-unit-tests, renderer-unit-tests, physics-unit-tests, audio-unit-tests, networking-unit-tests, ai-unit-tests, economy-unit-tests, procedural-generation-tests, serialization-tests, math-library-tests, data-structure-tests, api-contract-tests, coverage-reporting, mutation-testing.
• Integration testing — integration-test-framework, client-server-integration-tests, database-integration-tests, authentication-flow-tests, multiplayer-scenario-tests, economy-transaction-tests, ugc-upload-download-tests, world-streaming-tests, save-load-tests, cross-platform-tests, vr-device-tests, performance-benchmark-tests, e2e-scenario-tests, chaos-engineering-tests, load-testing.
• Visual testing — screenshot-comparison-testing, render-regression-tests, perceptual-diff-tooling, cross-platform-visual-parity, hdr-tone-mapping-tests, post-processing-tests, particle-effect-tests, material-preview-tests, shader-validation-tests, lighting-validation-tests, animation-playback-tests, vr-stereo-rendering-tests, ui-screenshot-tests, automated-visual-qa, visual-test-reporting.

Development Tooling (@maya/tooling)#

TypeScript tooling library, barrelled through src/index.ts, in three groups:

• World editor — world-editor-application, viewport-navigation, selection-transform-tools, property-inspector-panel, hierarchy-outliner, asset-browser, terrain-editing-tools, foliage-painting-tools, lighting-setup-tools, material-editor, particle-effect-editor, animation-preview, audio-setup-tools, play-in-editor-mode, collaborative-editing.
• Profiling and debugging — frame-profiler, gpu-profiler-integration, memory-profiler, network-profiler, physics-debugger, audio-debugger, ai-debugger, render-debugger, console-logging, variable-watch-system, breakpoint-system, replay-time-travel-debug, crash-dump-analysis, telemetry-collection, performance-regression-testing.
• Asset tools — asset-converter-cli, texture-compression-tools, mesh-optimization-tools, lod-generation-tools, collision-generation-tools, navmesh-generation-tools, lightmap-baking-tools, audio-processing-tools, asset-validation-tools, asset-comparison-tools, asset-dependency-analyzer, asset-size-reporter, asset-migration-tools, batch-processing-tools, localization-tools.

Documentation Library (@maya/documentation)#

TypeScript library, barrelled through src/index.ts, in two groups:

• API documentation — typedoc-generation, api-reference-website, code-example-embedding, interactive-api-explorer, versioned-documentation, changelog-generation, deprecation-tracking, migration-guides, search-functionality, documentation-testing, localization-support, pdf-export, offline-documentation, api-diff-tools, documentation-ci-cd.
• Tutorials and guides — getting-started-guide, first-world-tutorial, avatar-customization-guide, building-basics-tutorial, scripting-introduction, multiplayer-guide, vr-development-guide, ai-npc-tutorial, procedural-generation-guide, asset-pipeline-guide, economy-setup-guide, optimization-guide, deployment-guide, best-practices-guide, video-tutorial-series.

Build System#

Maya integrates with Nx via the nx:run-commands executor. The engine-core Nx project exposes six cargo targets; TypeScript libraries each expose four standard targets.

engine-core (project.json, tags scope:maya, type:rust, layer:engine) exposes check, build, test, test:integration, lint (clippy), and format (cargo fmt --check) targets, each cd-ing into libs/maya/engine-core and invoking cargo. The whole workspace is also buildable via the package.json scripts cargo:check, cargo:build, cargo:test, cargo:test:integration, cargo:clippy, cargo:fmt.

TypeScript libraries each define build, lint, typecheck, and test targets that wrap tsc, eslint src --ext .ts, and vitest run.

Cross-Domain Integration#

Maya's integration surface today is intentionally narrow. The Hathor integration is implemented: games/src/hathor/* imports world data, cultural rules, religion/belief, language/naming, and economic-model data from Hathor into Maya's game systems. The boundary is one-directional by design — Hathor owns the cultural and narrative data; Maya consumes it. This prevents the engine from becoming entangled with narrative decisions and keeps both domains independently deployable.

The Yemaya integration surface is present as test fixtures (inspirations/src/yemaya-integration-test-fixtures.ts), establishing the data-handoff shape for future creative-asset integration. No event-bus, storage, queue, or other shared-package imports were found in Maya source; any broader integration with other Oshun domains is (planned).

Status Summary#

• Deepest implementation: engine-core Rust workspace — 28 crates, ~1074 files; the renderer, physics, audio, atmosphere, embodiment, souls, nexus, immersion, and genesis crates each carry 60–153 source files of domain logic.
• Substantial TypeScript libraries: games (~100 modules), inspirations (~75), testing and tooling (~48 each), client, database, server, documentation (~30 each) — all real domain code with enums, schemas, validators, and services.
• Readiness facades: the seven single-module libraries (genesis-terrain, genesis-urban, genesis-flora, physics, renderer, scene, world) plus engine-core/src/index.ts are real but evaluate readiness rather than run the engine.
• Not present: apps/maya/, services/maya/; concrete GPU / physics / audio vendor SDK bindings inside the Rust crates; a custom UDP netcode protocol; UGC scripting sandbox, economy/governance/modding services as shipped code. Those remain (planned).