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<T> of Chunk<T> addressed by integer ChunkCoord.
• ChunkState lifecycle FSM: Unloaded → Loading → Active ⇄ Frozen → Unloading → Unloaded.
• StreamingManager / StreamingPipeline schedule load/unload around FocusPoints; 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 SimulationTicks 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:

{
  "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:

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.