# Maya Domain — Architecture > Architectural overview of the Maya domain: library organization, polyglot > technology choices, design patterns, and dependency graph. --- Maya is Oshun's Infinite Virtual Universe Creation domain — the engineering stack that lets teams build interlinked metaverses, VR social platforms, liveable virtual cities, and games. Getting there requires a polyglot architecture: the parts of the engine that must be extremely fast (world simulation, rendering, physics, audio, NPC AI) live as **Rust crates**, while the parts that benefit from rapid iteration and broad ecosystem tooling (platform abstraction, services, schemas, tooling, developer documentation) live as **TypeScript/Node.js libraries**. Today the domain ships **17 libraries under `libs/maya/`** — one Rust Cargo workspace (`engine-core`) holding **28 crates**, nine substantial TypeScript libraries, and seven single-module TypeScript readiness-evaluation facades. There is no `apps/maya/` or `services/maya/`. The sections below explain how these pieces fit together, why each technology boundary exists where it does, and what the intended deployment topology looks like. --- ## Guiding Principles 1. **Polyglot by necessity** — Performance-critical subsystems (engine kernel, renderer, physics, audio, world partitioning, NPC AI, multiplayer, procedural generation) are written in Rust as crates in the `engine-core` Cargo workspace. Platform, service, schema, tooling, and reference layers are TypeScript/Node.js libraries. 2. **One engine workspace, many crates** — Rather than a separate `libs/maya/` directory per engine subsystem, the engine is **one Cargo workspace** (`engine-core`) of 28 crates. Crate-to-crate dependencies are declared explicitly in the workspace `Cargo.toml`. 3. **Readiness facades over runtimes** — Seven single-module TypeScript libraries (`genesis-*`, `physics`, `renderer`, `scene`, `world`) provide typed `evaluateMaya*` readiness scoring for the corresponding `engine-core` crates; they let orchestration code reason about engine configuration without depending on the Rust runtime directly. 4. **AI-native** — `maya-souls` integrates LLM-powered NPCs behind a provider-neutral chat-completion layer; AI calls are async and latency tolerant outside the real-time tick loop. 5. **Backend-agnostic abstractions** — The renderer, physics, audio, and XR crates model their domains with vendor-neutral Rust types. Concrete GPU, physics-engine, audio, and headset SDK bindings are abstracted behind traits/structs and are not yet bound to a specific vendor. > An earlier draft listed a `wasm-bindgen` / `wasm-pack` / `napi-rs` "WASM > bridge" principle. No WASM or native-binding tooling is present in the > `engine-core` workspace today; that bridge is `(planned)`. --- ## High-Level Architecture The diagram below shows the four main vertical layers — client, engine, server, and database — and the supporting TypeScript libraries that sit alongside them. Data flows from top to bottom at runtime: clients talk to the TypeScript SDK, which talks to the engine (Rust), which the server orchestrates, which the database persists. ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ CLIENT LAYER │ │ Desktop · Mobile · WebGPU/WebXR browser · VR (Quest/SteamVR/Vision Pro) │ └──────────────────────────────────┬──────────────────────────────────────────┘ │ ┌──────────────────────────────────▼──────────────────────────────────────────┐ │ @maya/client (TypeScript SDK) │ │ Platform abstraction · Per-platform builds · Asset loading · Input │ └──────────────────────────────────┬──────────────────────────────────────────┘ │ ┌──────────────────────────────────▼──────────────────────────────────────────┐ │ @maya/engine-core — Rust Cargo workspace │ │ Kernel · ECS · jobs/fibers · math/alloc/spatial · world/time · renderer · │ │ physics · audio · atmosphere · embodiment · souls · nexus · immersion · │ │ genesis-terrain/urban/flora (28 crates; TS readiness facade on top) │ └──────────────────────────────────┬──────────────────────────────────────────┘ │ ┌──────────────────────────────────▼──────────────────────────────────────────┐ │ @maya/server (TypeScript) │ │ Fixed-timestep world loop · sessions · zone handoff · social · economy │ └──────────────────────────────────┬──────────────────────────────────────────┘ │ ┌──────────────────────────────────▼──────────────────────────────────────────┐ │ @maya/database (TypeScript) │ │ Schemas + validators + DDL generators · repository / query-builder layer │ └─────────────────────────────────────────────────────────────────────────────┘ @maya/games · @maya/inspirations · @maya/testing · @maya/tooling · @maya/documentation — supporting TypeScript libraries @maya/{genesis-terrain,genesis-urban,genesis-flora,physics,renderer, scene,world} — single-module readiness-evaluation facades ``` --- ## Library Organization **17 libraries exist today** under `libs/maya/`. There is no `apps/maya/` or `services/maya/`. The polyglot story is real but smaller than the planned ~120-library hierarchy earlier drafts of this document described: the engine kernel, renderer, physics, audio, atmosphere, avatars, NPCs, multiplayer, VR/XR, and procedural-generation runtimes all live as **Rust crates inside the single `engine-core` Cargo workspace** — not as separate top-level `libs/maya/engine`, `libs/maya/nexus`, `libs/maya/souls`, etc. directories. The tree below uses indented comments to name the 28 engine crates and labels each TypeScript library with its primary responsibility: ``` libs/maya/ │ │ ── Polyglot Rust workspace ───────────────────────────────────────── ├── engine-core/ # Cargo workspace, 28 crates (~1074 files): │ │ # maya-kernel, maya-ecs, maya-jobs, │ │ # maya-fibers, maya-alloc, maya-math, │ │ # maya-spatial, maya-scene, maya-resource, │ │ # maya-hot-reload, maya-serialize, │ │ # maya-reflect, maya-events, maya-world, │ │ # maya-time, maya-renderer, maya-physics, │ │ # maya-audio, maya-atmosphere, │ │ # maya-embodiment, maya-souls, maya-nexus, │ │ # maya-immersion, maya-genesis-terrain, │ │ # maya-genesis-urban, maya-genesis-flora, │ │ # maya-plugin-api, maya-integration-tests. │ └── src/index.ts # Thin TS readiness facade over the engine. │ │ ── TypeScript libraries (real domain code) ───────────────────────── ├── client/ # Client SDK: platform abstraction, per-platform builds ├── database/ # Schemas, validators, DDL generators, data-access layer ├── documentation/ # API-doc generation + tutorial modules ├── games/ # 19 sub-modules: combat, mmo, survival, quests, … ├── inspirations/ # City / fictional-universe / biome reference data ├── server/ # Node.js service modules (world loop, sessions, …) ├── testing/ # Unit / integration / visual test harness modules ├── tooling/ # World-editor, profiling, and asset-tool modules │ │ ── TypeScript readiness-evaluation facades (single-module each) ───── ├── genesis-terrain/ # evaluateMayaGenesisTerrainEnvironment() ├── genesis-urban/ # evaluateMayaGenesisUrbanEnvironment() ├── genesis-flora/ # evaluateMayaGenesisFloraLandscape() ├── physics/ # evaluateMayaPhysicsSimulation() ├── renderer/ # evaluateMayaRendererPass() ├── scene/ # evaluateMayaSceneVirtualSet() └── world/ # evaluateMayaWorldVirtualEnvironment() ``` The seven single-module libraries are **readiness-evaluation facades**, not empty scaffolds and not full procedural-generation engines. Each exports a domain-specific `evaluateMaya*` function with real scoring formulas plus its input/issue/evaluation types — their `package.json` descriptions say so verbatim (e.g. `@maya/renderer` is the _"TypeScript facade for Maya renderer GI, virtualized geometry, and neural rendering readiness"_). The runtime engines they describe are the `maya-renderer`, `maya-physics`, `maya-world`, and `maya-genesis-*` Rust crates inside `engine-core`. > The earlier draft listed `engine-core` as a "TypeScript scaffold; Rust/WASM > planned". That is stale: `engine-core` is a 28-crate Rust Cargo workspace > today. The `engine`, `genesis`, `embodiment`, `souls`, `nexus`, `immersion`, > `forge`, `treasury`, `mirror`, `atmosphere`, `standards`, and `spatial-ar` > top-level library groups described in older drafts do **not** exist as > `libs/maya/` directories — their functionality is either an `engine-core` > crate or `(planned)`. --- ## Rust Crate Architecture (`@maya/engine-core`) `libs/maya/engine-core/` is a Cargo workspace configured for maximum performance: `edition = "2021"`, resolver 2, release profile `lto = true` / `codegen-units = 1` / `opt-level = "s"`. It contains **28 member crates**. Importantly, the crates depend only on standard ecosystem crates — `serde`, `bincode`, `thiserror`, `libloading`, `notify`, `parking_lot`, `crossbeam-*`, `uuid`, `semver`, `bitflags`, `glam`, `bytemuck`. There is **no `wgpu`, `rapier`, `cpal`, `wasm-bindgen`, or vendor SDK** in the workspace today; the renderer, physics, and audio crates are backend-agnostic Rust modules with their concrete vendor bindings still to come. ### Engine Kernel — `maya-kernel` The kernel is the runtime's boot-and-plugin manager. It ties together three subsystems: - `EngineKernel` ties together a `PluginRegistry`, a `HotReloadWatcher` (built on the `notify` crate), and a `DependencyResolver` (topological sort with circular-dependency detection). - `NativePluginLoader` loads dynamic native plugins via `libloading`. - The frame loop runs phased plugin dispatch; inter-plugin messages travel over `crossbeam-channel`. ### ECS, Jobs, Fibers — `maya-ecs` / `maya-jobs` / `maya-fibers` These three crates form Maya's data and execution model: entities and components describe _what exists_; jobs and fibers describe _how it runs_. - `maya-ecs` — archetype-based ECS with generational `Entity` indices, Structure-of-Arrays component columns (`BlobVec`), and an archetype graph. Systems iterate components with cache-friendly linear access. - `maya-jobs` — Chase-Lev work-stealing job pool (`crossbeam-deque`) with DAG dependencies, job groups, scoped execution, and parallel-for. Distributes CPU-bound work across all available cores. - `maya-fibers` — cooperative coroutine executor over Rust `async`/`await`, tick-driven, suspension only at `.await`. Allows long-running async operations (e.g. network calls) to coexist with the real-time tick loop. ### Renderer — `maya-renderer` The renderer is a frame-graph pipeline, meaning render passes are declared as nodes in a directed acyclic graph rather than hardcoded in a fixed sequence. This lets the runtime infer barriers, resource lifetimes, and pass ordering automatically. - Frame-graph render pipeline: `render_graph` builds a DAG of render passes with automatic resource lifetime, barrier, and ordering inference. - ~94 feature modules (shadows, anti-aliasing, adaptive resolution, async compute, auto-LOD, bindless, materials, …). - Backend-agnostic — no concrete GPU API binding present in the crate. ### Physics — `maya-physics` The physics crate provides a complete multi-physics layer covering rigid bodies, cloth, fluids, destruction, and character simulation. A backend-selection registry allows different solver implementations to be plugged in without changing the public API: - `PhysicsBackendRegistry` selects a backend from requested capabilities; `PhysicsSceneConfig`, `CollisionLayerSet`, `PhysicsMaterialSet`, `ConstraintSet`, `RagdollArticulation`, `VehicleConfig`, `BuoyancySimulator`, `PhysicsInterpolator`, `CollisionEventDispatcher`. - Cloth solvers (`MassSpringCloth`, `PbdCloth`, `GpuClothSolver`), fluid (FLIP/GPU/cache), Voronoi destruction, and secondary-motion modules. - Backend-agnostic — no Rapier/Havok/PhysX FFI binding present in the crate. ### World Partitioning — `maya-world` Large open worlds exceed the size where all data can live in memory. The world crate manages a streaming chunk grid so that only the player's local neighbourhood is ever loaded: - `WorldGrid` of `Chunk` addressed by integer `ChunkCoord`. - `ChunkState` lifecycle FSM: `Unloaded → Loading → Active ⇄ Frozen → Unloading → Unloaded`. - `StreamingManager` / `StreamingPipeline` schedule load/unload around `FocusPoint`s; `LodCalculator` assigns distance-based LOD; `OriginRebase` rebases the coordinate origin near the player for large-world floating-point precision. --- ## TypeScript Service Architecture ### `@maya/server` `server` is a TypeScript Node.js library (`src/index.ts` barrel) of ~27 service modules. The central runtime piece is `WorldSimulationLoop` (`world-simulation-loop.ts`) — a fixed-timestep loop with spiral-of-death prevention configured by `SimulationLoopConfig` (`fixedTimestep_ms`, `maxSubsteps`, `catchUpFactor`) and emitting `SimulationTick`s to registered callbacks. Surrounding the simulation loop, the server library covers the full range of live-service concerns: game-server application lifecycle, player connection management, session management, anti-cheat, server-side physics, AI-NPC simulation, economy transactions, event broadcasting, server clustering, zone handoff, metrics, administration, hot-reload, social graph, matchmaking, achievements, leaderboards, content moderation, asset storage, analytics, user management, inventory, payment processing, and email integration. > No HTTP framework (Hono), WebSocket package, or Kafka event-bus import was > found in `@maya/server` source. The earlier draft's claims of a Hono API, > `@oshun/websocket` sync, worker-thread-per-zone, and a Kafka bus are > **(planned)**, not shipped. ### UGC Scripting Sandbox — (planned) The Maya feature roadmap describes a capability-gated UGC scripting sandbox with a `MayaScriptingAPI` global and per-tick resource limits. **No scripting sandbox library exists on disk** (`vm2` / `isolated-vm` are not in Maya's dependency set); this remains `(planned)`. --- ## Nx Build Targets Nx orchestrates both the Rust and TypeScript builds through the `nx:run-commands` executor. The `engine-core` project targets currently compile a **10-crate subset** of the full workspace for speed — the remaining 18 crates are built via the `package.json` cargo scripts. The exact 10 crates in the Nx subset are shown in the `project.json` snippet below: ```json { "name": "maya-engine-core", "tags": ["scope:maya", "type:rust", "layer:engine"], "targets": { "check": { "executor": "nx:run-commands", "options": { "command": "cd libs/maya/engine-core && cargo check -p maya-kernel -p maya-renderer -p maya-scene -p maya-world -p maya-resource -p maya-ecs -p maya-math -p maya-plugin-api -p maya-jobs -p maya-time" } }, "build": { "executor": "nx:run-commands", "options": { "command": "cd libs/maya/engine-core && cargo build --release -p maya-kernel -p maya-renderer -p maya-scene -p maya-world -p maya-resource -p maya-ecs -p maya-math -p maya-plugin-api -p maya-jobs -p maya-time" } }, "test": { "executor": "nx:run-commands", "options": { "command": "cd libs/maya/engine-core && cargo test -p maya-kernel -p maya-renderer -p maya-scene -p maya-world -p maya-resource -p maya-ecs -p maya-math -p maya-plugin-api -p maya-jobs -p maya-time" } }, "test:integration": { "executor": "nx:run-commands", "options": { "command": "cd libs/maya/engine-core && cargo test -p maya-integration-tests -- --nocapture" } }, "lint": { "executor": "nx:run-commands", "options": { "command": "cd libs/maya/engine-core && cargo clippy -p maya-kernel -p maya-renderer -p maya-scene -p maya-world -p maya-resource -p maya-ecs -p maya-math -p maya-plugin-api -p maya-jobs -p maya-time" } }, "format": { "executor": "nx:run-commands", "options": { "command": "cd libs/maya/engine-core && cargo fmt --all -- --check" } } } } ``` The full 28-crate workspace also builds via the `engine-core/package.json` scripts `cargo:check`, `cargo:build`, `cargo:test`, `cargo:test:integration`, `cargo:clippy`, and `cargo:fmt`. No `wasm-pack` target exists. Each TypeScript library defines `build` (`tsc -p tsconfig.lib.json`), `lint` (`eslint src --ext .ts`), `typecheck`, and `test` (`vitest run`) targets. --- ## Design Patterns ### Entity-Component-System (ECS) `maya-ecs` implements an archetype-based ECS inspired by `bevy_ecs` / `hecs` / `legion`. The key insight of an archetype ECS is that entities sharing the same component signature are stored together in the same table, so iterating over all "physics bodies" or all "renderable meshes" is a tight linear memory scan with no pointer chasing. Entities are generational indices; components live in Structure-of-Arrays archetype columns (`BlobVec`) for cache-friendly linear iteration. The `World` exposes `spawn` / `despawn` / `add_component` / `remove_component` and `query` / `query2` / `query3` iteration over archetypes matching a component signature. ### Frame-Graph Rendering `maya-renderer`'s `render_graph` module models the renderer as a directed acyclic graph of render passes. Rather than manually scheduling barriers and resource transitions (a major source of GPU bugs in traditional engines), the graph declares what each pass reads and writes — and the compiler infers correct ordering. The graph builder declares texture resources (`TextureDesc`, `TextureFormat`, `ResourceUsage` flags) and per-pass read/write attachments; `compile()` infers resource lifetimes and pass ordering. The renderer is currently backend-agnostic — no concrete Vulkan/Metal/DX12/WebGPU backend is bound in the crate. ### Spatial Acceleration Several engine systems need to answer proximity queries quickly: the renderer asks "which objects are in the camera frustum?", physics asks "which bodies might be touching?", AI asks "which NPCs are within perception range?". Maya provides three complementary data structures for these queries: - `maya-spatial` provides a loose octree for dynamic scenes, a binned-SAH BVH for static geometry ray intersection, and a balanced k-d tree for nearest-neighbour queries. - `maya-world` adds chunk-grid streaming with distance-based LOD assignment for large worlds. ### Mod Sandboxing — (planned) A capability-gated mod sandbox (permissions declared at install time, no runtime escalation) is part of the Maya roadmap. No modding library exists on disk; this pattern is `(planned)`. --- ## Cross-Domain Dependencies Maya is deliberately a mostly self-contained domain at this stage of development. It owns its engine, services, and data schemas internally rather than depending on shared Oshun infrastructure. This keeps the engine build hermetic and ensures that iterating on the Maya stack does not require changes in other domains. The only implemented cross-domain coupling today is the **Hathor integration**: `games/src/hathor/*` imports worldbuilding data (world data, cultural rules, religion/belief, language/naming, economic model) into Maya's game systems. Hathor owns the narrative simulation layer that gives Maya worlds cultural depth, so the dependency flows in one direction — Maya consumes Hathor data, not vice versa. A **Yemaya** integration surface exists as test fixtures (`inspirations/src/yemaya-integration-test-fixtures.ts`), establishing the reference handoff shape for when creative-asset integration is built out. All other cross-domain connections are planned but not yet implemented. No `@oshun/database`, `@oshun/event-bus`, `@oshun/auth`, `@oshun/storage`, `@oshun/queue`, `@oshun/proto`, `@oshun/contracts`, `@aje/*`, `@isis/*`, or `@bellona/*` package imports were found in Maya source. Those integrations — shared persistence, a cross-domain event bus, generative-AI job dispatch, blockchain, and the Blender/Unity asset bridge — are **(planned)**. The table below summarizes the intended cross-domain boundary for reference: | Dependency | Direction | Status | Purpose | | --------------- | -------------- | ------------- | ------------------------------------------ | | `@hathor/*` | maya → hathor | Implemented | Worldbuilding data import (`games/hathor`) | | `@yemaya/*` | maya → yemaya | Test fixtures | Creative-asset reference handoff | | Shared/`@oshun` | maya → shared | (planned) | Persistence, events, auth, storage, queue | | `@isis/*` | maya → isis | (planned) | Generative-AI job dispatch | | `@aje/*` | maya → aje | (planned) | Optional blockchain/NFT | | `@bellona/*` | maya → bellona | (planned) | Build pipeline / DCC asset bridge | --- ## Scaling Strategy The scaling architecture distributes the world simulation across many server processes, each owning a spatial zone. The `maya-nexus` crate models this topology through its `mesh_topology`, `load_balancing`, `capacity_scaling`, `edge_server_deployment`, and `cross_region_connectivity` modules. The deployment pipeline (CDN, Kubernetes pods) is an operational concern rather than source code and remains a design target. - **World zones** are the intended unit of horizontal scaling, each running as an independent process. `maya-nexus` simulation nodes own authoritative state for an authority domain (`NexusAuthorityDomainId`). - **Server mesh** routes players to a zone server; `mesh_topology` and `load_balancing` model the routing and rebalancing. - **Stateless assets** are intended to be CDN-served; only world state and player sessions sit on the server mesh. - **Physics** is intended to run server-side per zone at a fixed tick; `WorldSimulationLoop` provides the fixed-timestep driver. - **NPC AI** calls are asynchronous and do not block the simulation tick; `maya-souls`' LLM integration layer is async by construction. --- ## Implementation Phases The crate/library names below refer to `engine-core` Cargo crates and `libs/maya/` TypeScript libraries. The phases are sequential: each phase builds on the foundation laid by the one before it. | Phase | Focus | Key Deliverables | | ----- | ---------------------- | ------------------------------------------------------------------------------------------------------- | | 1 | Engine foundation | `maya-kernel`, `maya-ecs`, `maya-jobs`, `maya-renderer`, `maya-physics`, `maya-audio`, `maya-immersion` | | 2 | World generation | `maya-genesis-terrain` / `-urban` / `-flora`, `maya-atmosphere`, `maya-world`, `maya-time` | | 3 | Avatars and characters | `maya-embodiment`, `maya-souls`, `maya-nexus` | | 4 | TypeScript platform | `@maya/client`, `@maya/server`, `@maya/database`, `@maya/games` | | 5 | Tooling and references | `@maya/tooling`, `@maya/testing`, `@maya/inspirations`, `@maya/documentation` | | 6 | (planned) | UGC scripting sandbox, economy, governance, modding, shared-domain integration |