# Bellona Domain — Feature Reference > Build Orchestration, Asset Interchange, Engine Bridge, and Remote-Control > Platform Bellona is the Build and Bridge Platform of the Oshun ecosystem — the production pipeline that connects Oshun's creative domains with the game engines and digital content creation (DCC) tools that development and production teams use every day. Whether the task is pushing a finished world from Hathor into Unreal Engine 5, round-tripping character models between Blender and Unity, running a virtual production LED volume stage, or packaging a multi-platform game build from CI/CD, Bellona provides the connective tissue. It is organized around three concerns: real-time engine communication (bridges and MCP agents), asset handling (interchange, build, export, sync), and production tooling (virtual production, XR, mocap, MetaHuman, USD, DaVinci, Houdini). **Domain responsibility boundaries:** Bellona owns engine bridges, build pipeline, render pipeline, asset interchange, and runtime integration. **Neith** owns sovereign engine and DCC primitives. **Yemaya** owns creative production orchestration (Bellona executes the builds Yemaya requests). **Hathor** owns narrative and world modeling (Bellona only consumes Hathor artifacts). **Isis** owns generative media (Bellona adapts and packages its outputs). **Library prefix:** `@bellona/*` | **34 libraries, 12 apps** --- ## 1. Live Engine Bridges Each supported engine has a dedicated WebSocket bridge that runs alongside the engine editor. Once connected, commands can be issued, assets pushed, and real-time state updates received without switching windows. The bridge protocol is the lowest-level connection layer — all higher-level features (MCP agents, sync, build) are built on top of it. | Engine | Supported Versions | Bridge Port | Typed Commands | | ------- | ------------------ | ----------- | -------------- | | Blender | 3.6 – 4.0 | 9001 | 6 | | Godot | 4.0 – 4.2 | 9002 | 9 | | Unreal | 5.0 – 5.3 | 9003 | 11 | | Unity | 2022 – 2023 | 9004 | 14 | ### 1.1 Unity Bridge — `@bellona/unity` The Unity bridge exposes 14 typed commands for runtime and editor control: - **`getSceneInfo`**: Retrieves the full scene hierarchy, component lists, transform values, and metadata for the active scene without requiring the Unity Editor to be in focus. - **`createGameObject` / `destroyGameObject`**: Spawns new objects at specified world positions (including prefab-based creation with hierarchy) or removes objects by name or instance ID. - **`addComponent` / `setComponentProperty`**: Attaches any registered component to a GameObject and writes serialized property values — covering every Inspector-visible field. - **`loadScene` / `unloadScene`**: Switches the active scene or additively loads a second scene alongside the current one; unloads scenes from multi-scene configurations. - **`instantiatePrefab`**: Places a prefab instance at a specified world position and rotation, applying optional property overrides on instantiation. - **`setTransform`**: Moves, rotates, and scales any object in world-space or local-space coordinates, identified by path or instance ID. - **`playAnimation` / `setAnimatorParameter`**: Triggers animation clips directly and drives Animator state machine parameters without manual Editor interaction. - **`applyForce`**: Sends impulse, continuous, or torque forces to any `Rigidbody` component for physics simulation control during testing. - **`performRaycast`**: Executes ray intersection queries from any world-space origin and direction, returning hit objects, distances, and surface normals. - **`sendMessage`**: Invokes any public method on any component via Unity's `SendMessage` mechanism, enabling custom logic triggers from outside the engine. ### 1.2 Unreal Engine Bridge — `@bellona/unreal` The Unreal bridge exposes 11 typed commands for Unreal Engine 5: - **`getWorldInfo`**: Retrieves loaded levels, actor lists, streaming level status, and world settings. - **`spawnActor` / `destroyActor`**: Creates actors from any UClass at a specified transform; removes existing actors by unique ID. - **`setActorProperty`**: Writes any UPROPERTY on any actor by property path, supporting all Blueprint-compatible types. - **`callBlueprintFunction`**: Invokes any Blueprint-exposed function on any actor, passing typed arguments and receiving return values. - **`loadLevel` / `unloadLevel`**: Manages both streaming and persistent level loading and unloading. - **`setMaterialParameter`**: Sets scalar, vector, or texture parameters on material instances applied to any mesh component. - **`controlSequencer`**: Plays, pauses, stops, and scrubs the Sequencer timeline for cinematic preview and recording control. - **`executeConsoleCommand`**: Runs any Unreal console command remotely, enabling full engine configuration without opening the Editor UI. - **`captureScreenshot`**: Triggers a high-resolution screenshot capture at any specified resolution. ### 1.3 Godot Bridge — `@bellona/godot` The Godot bridge registers 9 commands for Godot 4: - **`godot:get-scene-tree`**: Returns the current scene tree structure. - **`godot:create-node`**: Creates a new node in the scene tree. - **`godot:set-node-property`**: Writes a property value on a node. - **`godot:call-node-method`**: Calls a method on a node in the scene. - **`godot:load-scene`**: Loads a scene file from a resource path. - **`godot:load-resource`**: Loads a Godot resource file and makes it available to the running scene. - **`godot:emit-signal`**: Programmatically triggers a signal on a node, enabling event-driven workflows from outside the engine. - **`godot:execute-gdscript`**: Runs a GDScript snippet at runtime, providing access to Godot's scripting API. - **`godot:get-project-settings`**: Reads Godot project settings. ### 1.4 Blender Bridge — `@bellona/blender` The Blender bridge exposes 6 commands plus cross-domain event publishing: - **`getSceneInfo`**: Retrieves objects, materials, cameras, lights, and collection hierarchy from the active Blender scene. - **`createObject`**: Adds meshes, lights, cameras, and empty objects at specified positions in the scene. - **`importAsset` / `exportAsset`**: Imports files in GLTF, FBX, or Blend format; exports objects to any supported format. - **`setCurrentFrame`**: Moves the animation timeline to a specified frame for remote timeline scrubbing. - **`triggerRender`**: Initiates a render from the current camera and settings with an optional output path. ### 1.5 Bridge Core — `@bellona/bridge-core` and `@bellona/adapters` All bridges share a common protocol layer that every engine connection depends on: - **Typed command routing**: Commands carry strongly-typed request and response schemas — no untyped JSON blobs. Type errors are caught at the API boundary before reaching the engine. - **Heartbeat and reconnection**: Automatic connection health monitoring with configurable reconnection intervals and exponential backoff so transient interruptions resolve without manual intervention. - **Session tracking**: Every connection is recorded with start time, commands executed, duration, and disconnect reason in the `bridge_sessions` database table. - **JSON message protocol**: Requests and responses are JSON-encoded (`JSON.stringify` / `JSON.parse`) with a `type` / `messageId` / `data` envelope and a request/response correlation pattern. - **CommandQueue** (`@bellona/adapters`): Ordered async command queuing for burst scenarios where commands arrive faster than the engine can process them. - **StateManager** (`@bellona/adapters`): Maintains a local mirror of engine state (with state history and state sync) to reduce round-trips for frequently read values. - **ProcessLauncher** (`@bellona/adapters`): Manages engine process lifecycle for headless build pipelines where the engine runs without a display. - **VersionManager** (`@bellona/adapters`): Handles engine version discovery and compatibility validation when multiple engine versions coexist. --- ## 2. MCP Agent Integration — AI-Driven Engine Control MCP (Model Context Protocol) is a standard for AI tool integration that allows any MCP-compatible AI client — such as Claude Code or custom LLM agents — to drive software by calling typed tools. Bellona's MCP agents expose engine APIs as MCP tools, so the LLM handles tool selection and sequencing natively, transforming natural language instructions into engine operations. This is categorically different from the WebSocket bridges: the bridges are command transports, while MCP agents are AI-native control planes where an LLM reasons about what to do. ### 2.1 Blender Agent — `@bellona/blender-agent` The Blender-native agent runtime. All nine of its runtime modules (`bridge`, `actions`, `planning`, `selection`, `scene-context`, `transactions`, `batch`, `audit`, `policy`) are implemented. It drives `bpy` (Blender's Python API) operations through an RPC bridge that supports both WebSocket and stdin transports for interactive and headless execution. - **Object tools**: Create, delete, duplicate, link, instance, and group 3D objects. The LLM can issue "duplicate all door handle objects" and the tool resolves which objects match and performs the operation. - **Mesh tools**: Enter edit mode, select vertices, edges, or faces, and perform mesh operations — the same operations available in Blender's Edit Mode, exposed as callable tools. - **Armature tools**: Create bones, set up constraints, and configure IK (inverse kinematics, where the desired end-effector position drives the joint chain) and FK (forward kinematics, where each joint is driven explicitly) for character rigging. - **Modifier tools**: Add, configure, apply, and reorder any Blender modifier (Subdivision Surface, Boolean, Solidify, etc.) in the modifier stack. - **Material tools**: Author Principled BSDF materials and build shader node graphs for physically-based rendering from natural language material descriptions. - **Node tools**: Create and connect Geometry Nodes graphs for procedural modeling and shader node networks. - **Camera and light tools**: Place cameras and lights, adjust settings, and apply common lighting presets (three-point, HDRI, studio) via simple instructions. - **Render tools**: Configure render settings and trigger renders to collect output images. - **Semantic selection resolver**: Maps natural language descriptions to concrete Blender object references — "find all emissive materials" resolves to every material with an emissive shader node. - **Geometry Nodes automation**: Generates and modifies Geometry Nodes graphs from structured intents including foliage scatter, cable runs, kitbash panel arrays, terrain dressing, and modular building facades. - **Rigging and animation macros**: High-level macros for rig generation from bone specifications, IK/FK setup, driver configuration, custom control shapes, NLA (Non-Linear Animation) track setup, and animation retargeting. - **Physics setup macros**: One-command setup for cloth simulations (garments, capes), rigid body destruction previews, and soft-body deformations. - **Reversible transactions**: Every operation is wrapped in a named undo checkpoint; a dry-run mode previews changes before applying them. - **Headless batch mode**: The stdio transport enables render farms and automated pipelines to drive Blender without a display, using the same tool interface as interactive use. - **Scene assembly**: Authors complete scene graphs from prompts — sets up collections, parent-child hierarchies, naming conventions, places assets with collision checks and scale normalization. - **Library publishing**: Publishes Blender asset libraries with package manifests, rebuild recipes, thumbnail capture, and benchmark reports. ### 2.2 Unity Agent — `@bellona/unity-agent` The Unity Editor MCP server package and orchestration wrapper, implemented as a large library (over 100 workflow modules) with a JSON-RPC client, an HTTP transport, and a batch-mode launcher. The same tools operate in both interactive Editor mode and `-batchmode -executeMethod` CI/CD builds. - **Tool input validation**: Every MCP call is checked against the current project's render pipeline (URP/HDRP/Built-in), Unity version, installed packages, and target platform before execution. - **Semantic selection resolver**: Maps natural language descriptions ("all enemies with NavMeshAgent", "the main camera's post-processing volume") to concrete GameObject and Component references. - **Scene context resource**: Serves a structured snapshot of the scene hierarchy, component types, transform positions, prefab overrides, LOD configuration, and lighting setup as an MCP resource for LLM situational awareness. - **Reversible transactions**: Wraps Unity's `Undo.RecordObject` system so every LLM-driven change can be undone through the normal Editor undo stack. - **Asset operations**: Import, reimport, move, rename, delete, duplicate, and label assets via `AssetDatabase`. - **SerializedObject bridge**: Read and write any serialized field on any Unity object by property path with full type safety and undo integration. - **Build pipeline**: Trigger `BuildPipeline.BuildPlayer`, asset bundle builds, and Addressable content builds with full configuration and progress tracking. - **Project settings**: Read and write all Unity project settings: `PlayerSettings`, `QualitySettings`, `PhysicsSettings`, `TagManager`, and more. - **Shader Graph automation**: Full Shader Graph document model with node catalog, graph authoring, property binding, sub-graph creation, and master stack configuration. - **VFX Graph automation**: VFX Graph context model covering Spawn, Initialize, Update, and Output contexts with particle system authoring and event binding. - **Animator automation**: Animator Controller management — state machine authoring, blend tree creation, transition condition setup, and AvatarMask binding. - **Terrain automation**: Procedural terrain workflows including vegetation painting, detail mesh placement, terrain texture layering, and navmesh baking. - **Addressables automation**: Addressable Asset System management — group management, address assignment, label configuration, and build profile management. --- ## 3. Asset Interchange `@bellona/interchange` manages the import, validate, transform, and export pipeline for 3D assets across all supported formats. It is the format-agnostic translation layer that allows assets created in any tool to be consumed by any engine. ### 3.1 Supported Formats The following table lists every supported format and whether it can be used as an import source, an export target, or both. Import-only formats are typically tool-specific or specialized formats that have limited export ecosystems. | Format | Import | Export | Notes | | ------ | ------ | ------ | ------------------------------------------ | | GLTF | Yes | Yes | Text-based GL Transmission Format | | GLB | Yes | Yes | Binary GLTF — smaller file size | | USD | Yes | Yes | Pixar Universal Scene Description | | USDA | Yes | Yes | ASCII (human-readable) USD variant | | USDC | Yes | Yes | Crate (binary) USD variant | | USDZ | Yes | Yes | Compressed USD package for Apple platforms | | FBX | Yes | Yes | Autodesk Filmbox exchange format | | OBJ | Yes | — | Wavefront legacy mesh format | | ABC | Yes | — | Alembic baked animation cache format | | PLY | Yes | — | Stanford polygon / point cloud format | | STL | Yes | — | Stereolithography format for 3D printing | | DAE | Yes | — | Collada open interchange format | | Blend | Yes | — | Blender native scene format | ### 3.2 Interchange Pipeline The pipeline processes assets through four sequential stages. Each stage is optional except Import and Export — you can run Import → Export for a pure format conversion, or run all four stages for a fully validated and optimized conversion. 1. **Import**: Auto-detect format from the file extension, or accept an explicit format hint. Parse the file into Bellona's internal intermediate representation. 2. **Validate**: Optional integrity checks for mesh topology (degenerate polygons, non-manifold geometry), material reference completeness, and scale consistency. Auto-fixes common issues including flipped normals and missing UV maps. 3. **Transform**: Configurable pipeline of operations — scale normalization, axis rotation (converting between Y-up and Z-up coordinate conventions), origin re-centering, mesh merge or split, material optimization, and polygon count reduction. 4. **Export**: Write the transformed representation to any supported export format with optional export-time validation. - **Batch conversion**: Process entire asset libraries sequentially or in parallel. Continue-on-error mode ensures one corrupt file does not abort the entire batch; per-file success/failure results are always reported. - **Asset cache**: An in-memory LRU (Least Recently Used — evicting the entry accessed longest ago when at capacity) cache for parsed assets, eliminating redundant re-reads during iterative build pipelines. Configurable capacity, with explicit lookup, insertion, invalidation, and clear operations. - **Format registry**: A pluggable registry that allows custom importers and exporters to be registered at runtime, built-in handlers to be overridden, and available formats to be enumerated. - **Interchange models** (`@bellona/interchange-models`): Shared data schemas for the internal intermediate representation — meshes, materials, animations, cameras, and lights — ensuring all transform pipelines operate on a consistent in-memory object model. --- ## 4. Build System The build system provides a Redis-backed, content-addressable pipeline for compiling game projects and assets into platform-specific deployment artifacts. It is the automation layer that converts source assets and project configurations into packages ready for distribution. ### 4.1 Multi-Platform Build Targets Bellona supports building for nine platforms across desktop, mobile, web, and console. The target platform drives which compression formats, shader variants, and asset pipelines are activated during a build job. - **Desktop**: Windows, macOS, Linux - **Mobile**: iOS, Android - **Web**: WebGL - **Console**: PlayStation, Xbox, Nintendo Switch ### 4.2 Build Job Types The `build-worker` defines four job types (`JobType`), each with a dedicated worker module: | Job Type | Description | | ------------------------- | --------------------------------------------------------------------------------- | | `asset-bake` | Texture, mesh, audio, and animation baking for a target platform | | `validate` | Build-input and output validation, compatibility checks, quality gates | | `engine-project-generate` | Generate engine project scaffold files for Unity, Unreal, or Godot | | `export-package` | Package artifacts into distributable formats (ZIP, TAR_GZ, `.unitypackage`, etc.) | The `asset-bake` worker subsumes texture compression (BC7, ASTC, ETC2), mesh optimization and LOD generation, audio transcoding, and animation processing through its `TextureBakeOptions`, `ModelBakeOptions`, `AudioBakeOptions`, and `AnimationBakeOptions` request types. ### 4.3 Build Status Lifecycle A build job progresses through the following states. A cache hit moves a job directly to COMPLETED without any worker processing, bypassing QUEUED and RUNNING entirely. ``` PENDING → QUEUED → RUNNING → COMPLETED → FAILED → CANCELLED → (cache hit) → COMPLETED (instant, no work required) ``` A cache hit occurs when the content-addressable cache already holds a result for the same input checksums — the build completes immediately without executing any work, which is critical in CI/CD pipelines where the same assets are rebuilt repeatedly. ### 4.4 Content-Addressable Build Cache The `BuildCacheService` caches build outputs by content hash, so identical inputs always resolve to the same cached output. This eliminates redundant computation across CI runs and between developers with matching source trees. - **Multi-level storage**: An in-memory tier (100 MB default), a Redis tier, and a disk tier; the in-memory and total cache size limits are configurable via `BUILD_CACHE_MEMORY_SIZE` and `BUILD_CACHE_MAX_SIZE`. - **Automatic deduplication**: The same asset compiled for the same target is never built twice, regardless of which process submitted the job. - **Redis PubSub invalidation**: When a cache entry is invalidated, other processes are notified to prevent stale results from being served. - **Cache health metrics**: Hit rate and total entry count are reported through `getHealthStatus()`. ### 4.5 Build Templates Named, reusable build configurations that save complete build setups including preset platform combinations, default optimization levels, engine-specific settings (Unity scripting backend, Unreal cook configuration, Godot export templates), and plugin selections. ### 4.6 Build Worker A poll-based worker that pulls jobs from the queue and executes them. Multiple workers run in parallel for horizontal scaling. Workers declare which platforms they can build and which engines they have installed; the scheduler routes jobs only to capable workers. Workers report health at configurable intervals; dead workers are detected and their in-progress jobs are rescheduled. --- ## 5. Export Pipeline The export pipeline packages compiled build artifacts into the formats required by each engine's import workflow. ### 5.1 Export Formats | Format | Extension | Target Use Case | | ------------- | --------------- | --------------------------------------- | | ZIP | `.zip` | General-purpose distribution | | TAR_GZ | `.tar.gz` | Linux systems and CI/CD pipelines | | Unity Package | `.unitypackage` | Unity Asset Store and project import | | Unreal Asset | `.uasset` | Unreal Engine Content Browser import | | Godot Pack | `.pck` | Godot resource pack for runtime loading | Each engine-specific format requires more than just packaging — it must match the engine's exact internal conventions for the package to be importable without additional configuration. - **Unity export**: Generates `.unitypackage` archives with the correct Unity folder structure, `.meta` files, and asset GUIDs matching Unity conventions — importable directly into any Unity project. - **Unreal export**: Produces `.uasset` and `.umap` files organized into Unreal's content folder hierarchy, importable through the Content Browser without additional configuration. - **Godot export**: Creates `.pck` files with resource paths matching Godot project conventions, compatible with Godot's runtime resource loader for DLC and modular content delivery. - **Workflow convenience methods**: `buildAndWait()` submits a build job and blocks until completion; `exportAndWait()` submits and polls for the export package; `exportAndDownload()` combines all three steps into a single call for CI/CD scripts. --- ## 6. Engine Synchronization The sync system handles bidirectional asset exchange between Oshun and connected engine projects, keeping the engine's asset state aligned with Oshun's canonical state as both sides evolve. ### 6.1 Sync Directions | Mode | Description | | ------------- | --------------------------------------------------------------------------- | | Push | Send assets from Oshun to the connected engine project | | Pull | Retrieve assets from the engine back into Oshun | | Bidirectional | Two-way sync with conflict detection — changes on both sides are identified | ### 6.2 Conflict Resolution When the same asset has been modified in both Oshun and the engine, three resolution strategies are available: automatic "local wins" (Oshun prevails), automatic "remote wins" (engine prevails), or manual resolution where each conflict is reviewed individually with resolution timestamp and reviewer identity stored for audit purposes. ### 6.3 Engine-Specific Sync Helpers Each engine has its own internal format conventions for tracking asset identity. These helpers handle those conventions so that a sync operation does not break the engine's internal references. - **`syncWithUnity()`**: Auto-detects the Unity project path, manages `.meta` file creation and updates, and syncs prefabs and scene assets with correct GUID handling to prevent Unity reference corruption. - **`syncWithUnreal()`**: Syncs to the Unreal content directory, tracks Blueprint references, and handles `.uasset` metadata to prevent Unreal's dependency graph from breaking. - **`syncWithGodot()`**: Syncs `.tres` and `.tscn` resource files and manages the `project.godot` configuration file to reflect new assets. --- ## 7. Gameplay Runtime Systems `@bellona/gameplay-systems` provides production-ready engine-agnostic gameplay systems that implement common gameplay features. These systems implement the logic layer and integrate with whichever engine handles rendering and physics. ### 7.1 Input System A unified input abstraction across all input sources. Game logic binds to semantic actions ("Jump", "Attack", "Interact") rather than hardware signals; the input system routes the correct hardware events to those actions. | Source | Features | | -------- | ------------------------------------------------------------------- | | Keyboard | Key binding, multi-key combos, hold/tap/double-tap detection | | Mouse | Button mapping, cursor position and delta, scroll wheel events | | Gamepad | Stick axes, triggers, face buttons, shoulder buttons, rumble output | | Touch | Tap, swipe, pinch-to-zoom, multi-touch gesture recognition | | VR | Controller buttons, grip, trigger, trackpad, and hand pose | **Input contexts** allow switching the active binding set between gameplay, pause menus, cutscenes, and vehicle control without code changes. ### 7.2 Save/Load System - **Quick save / quick load**: Single API call saves and restores complete game state to a designated quick-save slot. - **Named save slots**: Multiple independent game saves, each with a name, timestamp, and thumbnail. - **Save file versioning**: Schema migration support for game updates that change the save format — old saves are automatically migrated to the new schema on load. - **Cloud sync**: Optional synchronization of save files to a cloud backend for cross-device play and backup. - **Autosave**: Configurable interval-based automatic saving. - **Backend drivers**: In-memory driver for testing, local filesystem driver for standalone games, and cloud storage driver for connected titles. ### 7.3 Inventory System - **Item database**: Defines item types with properties (name, description, icon, weight, value, max stack size) and custom metadata fields for game-specific attributes. - **Inventory management**: Add, remove, stack, split, and transfer items between inventory containers — player backpack, chest, vendor. - **Item categories**: Weapon, consumable, crafting material, quest item, currency, equipment. - **Crafting system**: Define recipes with ingredient lists and produce output items, supporting conditional recipes (crafting station required, player level threshold, etc.). - **Equipment slots**: Bind items to named equipment slots and apply stat modifiers that affect character attributes when equipped. ### 7.4 Combat System - **Ability registration**: Define abilities with cooldown durations, resource costs (mana, stamina), range and area-of-effect shapes, and effect lists. - **Damage calculation**: Typed damage (physical, fire, lightning, magic) with per-target resistance and vulnerability multipliers. - **Status effects**: Buffs and debuffs with duration, stack count rules, periodic tick damage, and compound effects that interact with other status effects. - **Resource management**: Track health, mana, stamina, rage, or any custom resource with configurable regeneration rates and maximum values. - **Ability builder**: A declarative fluent API for composing data-driven abilities that the combat system interprets without hardcoded logic. ### 7.5 AI Behavior Systems | System | Description | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | Behavior Trees | Composable tree nodes: sequence (all children must succeed), selector (first success wins), parallel, decorators (conditions), and guards | | Utility AI | Scored action selection — each possible action is evaluated against weighted context factors; the highest-scoring action is chosen | | GOAP | Goal-Oriented Action Planning — the AI defines desired goal states and searches for action sequences that achieve them | | Perception | Sensory subsystem for sight (cone/sphere volumes), hearing (radius-based), and proximity detection with per-sense configuration | | Blackboard | Shared key-value state container accessible by any behavior tree node, enabling AI components to share state without direct coupling | **Pre-built behavior patterns**: Patrol (waypoint traversal with configurable wait times), Flee (movement away from a threat source), Attack (range and cooldown-aware engagement), and Idle (ambient behavior with random animation and look-at variation). --- ## 8. Virtual Production `@bellona/virtual-production` supports professional film and broadcast productions using LED volume stages with real-time Unreal Engine rendering — the technology behind productions like The Mandalorian. ### 8.1 Camera Tracking Integration Real-time 6DOF (six degrees of freedom — position X/Y/Z and rotation pitch/yaw/roll) camera tracking: the physical camera's exact position and orientation is captured and transmitted to drive the virtual camera in Unreal Engine, keeping the perspective-correct LED background synchronized with the real camera's point of view. | Vendor | Protocol | Key Strengths | | --------- | ----------- | ----------------------------------------------------- | | Ncam | Proprietary | Sub-millimeter accuracy, optical lens distortion data | | Mo-Sys | StarTracker | Multi-camera support, star-pattern optical tracking | | OptiTrack | NatNet | Marker-based, high precision, very low latency | | Vicon | DataStream | Large volume tracking, full skeletal body support | | Stype | RedSpy | Optimized specifically for LED volume environments | Additional features: real-time lens distortion capture, coordinate system transformation between tracking and engine conventions, and multi-camera calibration tools. ### 8.2 LED Wall Control - **Panel layout management**: Section and wall configuration with pixel pitch specification, resolution definition, and curvature compensation for curved LED installations. - **Color calibration**: White point correction, color gamut mapping, and EOTF (Electro-Optical Transfer Function — the curve mapping electrical signal to light output) correction per panel to ensure consistent color reproduction across the full wall surface. - **Test patterns**: Alignment grids, gradient patterns, and white/black frames for wall verification. - **Processor integration**: Brompton (ChromaTune), Megapixel (Helios), Novastar — the three major LED wall processors used in professional virtual production. ### 8.3 ICVFX Compositing ICVFX (In-Camera Visual Effects) is the technique of compositing virtual environments with real actors in-camera: the virtual background rendered on the LED wall is captured by the film camera without requiring post-production compositing. - **Inner frustum configuration**: Independent render settings for the inner frustum (the portion of the LED wall visible in the camera lens) versus the surround area, allowing higher-quality rendering for exactly what the camera sees. - **Chromakey integration**: Green/blue screen support for elements that still require traditional VFX compositing. - **Light cards**: Virtual luminous surfaces placed in 3D space to project colored light onto real actors, replacing physical foam-core bounce cards with controllable virtual equivalents. - **Per-layer color correction**: Independent color grading for each compositing layer in the ICVFX pipeline. - **Media plates**: Pre-rendered or pre-shot background footage blended into the live LED render. - **Edge blending tools**: Gradient and mask tools for seamless transitions at wall boundaries and junctions. ### 8.4 Synchronization All systems on an LED volume stage must be frame-synchronized to prevent tearing artifacts: - **Genlock**: Hardware synchronization signal that forces all rendering systems, LED processors, and cameras onto the same frame clock. - **Timecode**: SMPTE timecode (the Society of Motion Picture and Television Engineers standard for synchronizing all systems to a common time reference) generation and distribution. - **Supported frame rates**: 23.976, 24, 25, 29.97, 30, 50, 59.94, 60, and up to 240 fps. ### 8.5 Stage Presets | Preset | System Type | Use Case | | ---------------- | ------------ | -------------------------------------------- | | Basic LED Stage | nDisplay | Single camera, simple LED wall configuration | | ICVFX Stage | Unreal ICVFX | Multi-camera professional LED volume | | Disguise Volume | Disguise | Stages managed by the Disguise media server | | Broadcast Studio | Zero Density | Virtual broadcast set production | --- ## 9. Extended Reality (XR) `@bellona/xr` provides platform-specific XR capabilities plus a shared abstraction layer that works across all supported headsets and browsers. ### 9.1 Platform Support | Platform | Devices | Session Types | | ---------- | --------------------------- | ------------------------------ | | visionOS | Apple Vision Pro | Window, Volumetric, Full Space | | Meta Quest | Quest 2, Quest Pro, Quest 3 | Immersive VR, Passthrough MR | | WebXR | Any WebXR-capable device | Immersive VR, Immersive AR | ### 9.2 Apple Vision Pro (visionOS) Features - **Window, Volumetric, and Full Immersive Space sessions**: Progressive levels of spatial presence from floating 2D panels to complete visual field takeover. - **Volume management**: Create and position multiple independent 3D volumes within a single session. - **SharePlay and Persona**: Virtual presence features for multi-user shared spatial experiences. - **Articulated hand tracking**: Full 26-joint hand skeleton tracking per hand for natural gesture interaction. - **Eye and gaze tracking**: Precise detection of where the user is looking, including dwell-based selection. ### 9.3 Meta Quest Features - **Passthrough modes**: Full color passthrough (see the real world), reconstructed mesh passthrough, or selective passthrough. - **Guardian system**: Boundary management API for defining the safe play area and showing boundary visualization. - **Scene anchors**: Semantic understanding of detected room geometry labeled as floor, ceiling, wall, table, couch, and door. - **Face tracking**: Expression capture from the headset's inward-facing cameras for avatar-driven social experiences. - **Articulated hand tracking**: Finger joint positions and recognition of a library of named hand gestures. ### 9.4 Shared XR Capabilities - **Hit testing**: Ray intersection testing against real-world detected surfaces for AR object placement. - **Spatial anchors**: Persistent anchors attached to physical locations that survive session restarts. - **Scene understanding**: Plane detection, mesh reconstruction, and surface normal estimation of the physical environment. - **Spatial audio**: Distance-based audio attenuation with HRTF (Head-Related Transfer Function — a binaural filter that simulates how sound reaches each ear differently) spatialization. - **3D math library**: Complete set of 3D primitives — vectors, quaternions, matrices, transforms, rays, and AABBs (Axis-Aligned Bounding Boxes) — with intersection test functions. --- ## 10. Motion Capture `@bellona/mocap` provides the complete motion capture workflow from live hardware streaming through skeleton retargeting to final animation export. ### 10.1 Multi-Vendor Hardware Streaming | Vendor | Technology | Protocol | | --------- | --------------- | ----------- | | OptiTrack | Optical markers | NatNet | | Vicon | Optical markers | DataStream | | Xsens | Inertial IMUs | UDP | | Rokoko | Inertial/Hybrid | Studio Live | Each vendor integration handles vendor-specific packet formats, coordinate system conventions, and data quality indicators. ### 10.2 Skeleton Management - **Built-in templates**: Pre-defined skeleton configurations for Mixamo, Unreal Mannequin, OptiTrack standard body, and Xsens full-body suit. - **Custom skeleton definition**: Define any joint hierarchy with parent-child relationships for non-standard characters or articulated props. - **Joint limits**: Configurable rotation limits per joint for biomechanically plausible constraint-based filtering of noisy data. - **Rotation order**: XYZ, ZYX, ZXY, and other rotation order conventions per joint to match specific engine and DCC tool conventions. ### 10.3 Retargeting Retargeting maps captured animation from the performer's skeleton to a different character skeleton, allowing a performer's motion to drive a character with different proportions. - **Skeleton-to-skeleton mapping**: Configurable bone name mapping with support for hierarchies that differ between source and target. - **Root motion extraction**: Separates global character movement from local limb animation so the game engine can apply its own locomotion system. - **Mirror configuration**: Flip left/right for symmetrical animation or creating mirrored performances from a single capture. - **IK settings**: Foot planting constraints and hand-reach inverse kinematics to prevent floating feet and missed hand targets. - **Post-processing pipeline**: Smoothing filters, noise reduction, and velocity clamping to clean up raw capture data. ### 10.4 Recording and Playback - **Multi-subject sessions**: Record multiple performers simultaneously as independent subjects in the same take. - **Take management**: Named takes with metadata, production notes, and timestamps for editorial organization. - **Quality tracking**: Per-frame quality indicators including marker occlusion counts and tracking confidence scores. - **Recording control**: Start, stop, pause, and resume recording with clean take boundaries. ### 10.5 File Format Support | Format | Read | Write | Description | | ------ | ---- | ----- | ---------------------------------------------- | | BVH | Yes | Yes | Biovision Hierarchy — universal mocap standard | | C3D | Yes | Yes | Biomechanics motion lab marker data standard | | TRC | Yes | Yes | Track Row Column marker trajectory format | ### 10.6 Animation Output - **Unity animation clips**: Humanoid (full-body retargeted) and Generic (custom skeleton) animation clips ready for Unity import. - **Unreal animation sequences**: Animation sequences with correct bone naming conventions for Unreal's Skeleton system. - **Keyframe reduction**: Remove redundant keyframes while preserving visual fidelity, reducing file sizes and import times. - **Finger and facial tracking**: Capture and export hand finger joint data and facial performance data alongside body animation. --- ## 11. MetaHuman Pipeline `@bellona/metahuman` handles the complete MetaHuman workflow — Unreal Engine's photorealistic digital human system — enabling MetaHuman characters to be customized and animated within Oshun. ### 11.1 Mesh Import - **Component import**: Import MetaHuman mesh components individually — head geometry, body mesh, eyes, teeth, and hair simulation geometry. - **LOD management**: Levels of Detail LOD0 (highest quality) through LOD7 (lowest polygon count) for performance scaling across hardware targets. - **Texture import**: Diffuse, normal, roughness, specular, subsurface scatter, and cavity maps — the complete texture set required by MetaHuman's skin shading model. ### 11.2 Face Rig - **ARKit blendshape mapping**: Maps the 52 Apple ARKit standard blendshapes (the same system used for Face ID) to MetaHuman face controls, enabling live face capture to drive MetaHuman characters. - **Face control categories**: Organized controls for brow movements, eye shapes, cheek deformations, nose, mouth, jaw, and tongue, matching MetaHuman's Rig Logic system. - **Blendshape-to-control mapping**: Conversion between raw blendshape values and MetaHuman's higher-level face control system for procedural animation pipelines. ### 11.3 Body Customization - **Body type presets**: Pre-defined body type configurations for rapid character setup. - **Proportion controls**: Height, weight distribution, muscle mass, and shape parameter adjustments for character variation. - **AI-assisted customization**: Describe a character in text ("tall, athletic build") and receive parameter suggestions matching that description. ### 11.4 Live Link Animation Live Link is Unreal Engine's protocol for streaming real-time animation data from external sources: - **Real-time face streaming**: Stream face performance data into Unreal Engine in real-time for live virtual production or interactive applications. - **Multi-actor support**: Stream multiple performers simultaneously, each as separate subjects in Unreal's Live Link panel. - **Supported sources**: iPhone ARKit (TrueDepth front camera), Faceware optical face tracking, and custom Live Link source plugins. --- ## 12. OpenUSD Pipeline `@bellona/openusd` provides a comprehensive USD (Universal Scene Description — Pixar's open standard for describing 3D scenes) pipeline. Unlike simple file formats, USD uses a composition model where multiple layers combine non-destructively into a final scene, making it the backbone of VFX production pipelines at major studios. ### 12.1 Stage Management A USD "stage" is a composed 3D scene assembled from multiple "layers" — analogous to a Photoshop document made of composited layers, but for 3D scenes: - **Stage lifecycle**: Create, open, save, and close USD stages with configurable load policies. - **Prim authoring**: Author the USD prim hierarchy including Xform (transform containers), Mesh, Scope (organizational groups), Material, Camera, and Light prim types. - **Attribute editing**: Read and write USD attributes with full type support — float, vector3, matrix4, path, string, token, and all other USD value types. - **Load policies**: Full load, lazy load (non-essential data deferred), or deferred load for large scenes with payload arcs. ### 12.2 Layer and Composition USD's power comes from its composition model, where multiple layers combine according to defined rules: - **Sublayer ordering**: Control the priority of layers in the composition stack — stronger layers override weaker ones, analogous to Photoshop layer order. - **Reference arcs**: Include an external USD file by reference so multiple scenes share the same asset definition without duplication. - **Payload arcs**: Like references, but the referenced data is not loaded until explicitly triggered — used for large prop assets that should defer loading. - **Layer offsets**: Shift the time offset of animation in referenced files to align them with the scene's timeline. - **Inherit and Specialize arcs**: Class-based inheritance for shared material assignments, and per-instance specializations that override inherited values. ### 12.3 Variant Management USD variants store multiple configurations of the same prim and allow switching between them without duplicating data — essential for LOD management, material swaps, and configuration options: - **Create variant sets**: Define named variant sets (e.g., "LevelOfDetail") with named variants per set (e.g., "LOD0", "LOD1", "LOD2"). - **Switch active variant**: Select the active variant to change which configuration is applied for a specific prim. - **Batch operations**: Apply variant switching across entire hierarchies for bulk LOD switching or material variant selection. ### 12.4 MaterialX Integration MaterialX is an open standard for defining shader networks independent of any specific renderer: - **Document creation**: Create MaterialX documents and author node graphs describing shader networks. - **USD binding**: Bind MaterialX shader networks to USD prims for renderer-agnostic look development. - **Standard shader support**: Standard Surface (physically-based), Unlit Surface, and custom shader types. ### 12.5 Pipeline Tools - **Validation**: Structural and semantic issue checking for USD scenes, reporting warnings and errors with severity levels and specific prim locations. - **Diff**: Compare two USD stages to identify added prims, removed prims, and modified attributes — essential for reviewing changes in collaborative pipeline environments. - **Merge**: Three-way merge of USD stages with conflict detection for combining changes from multiple artists working on the same asset. - **Publish**: Versioned asset publishing to a configured destination path with version metadata and a complete publish history. --- ## 13. Audio Production `@bellona/audio` provides audio processing and spatial audio capabilities integrated into the production pipeline. - **Spatial audio**: 3D positional audio with distance attenuation curves, occlusion simulation (muffling when sound passes through walls), and HRTF-based binaural rendering for headphone playback. - **Ambisonics**: First-order and higher-order Ambisonic (a format encoding sound from all directions in a sphere) support for VR audio and dome theater installations. - **Format transcoding**: Convert between WAV, AIFF, FLAC, OGG Vorbis, MP3, Opus, and engine-native audio formats — covering all common game engine and professional audio requirements. - **Loudness normalization**: EBU R128 and ITU BS.1770 loudness analysis and correction — the broadcast standards for consistent perceptual loudness levels across all audio assets. - **Metadata extraction**: BPM detection, musical key analysis, spectral feature extraction, and loudness metrics for content-aware audio organization. - **Waveform generation**: Visual waveform data for display in editor timelines and audio browsers. - **Batch processing**: Pipeline-compatible batch transcoding and normalization for entire audio asset libraries. - **Ardour integration**: Routing to and from the open-source Ardour DAW for professional mixing workflows. --- ## 14. Video Production `@bellona/video` handles video processing within the production pipeline. - **Format conversion**: Transcode between MP4, MOV, WebM, MKV, and engine-compatible video container formats. - **Codec support**: H.264, H.265/HEVC, AV1, and VP9 for web and streaming delivery; ProRes and DNxHD for professional post-production workflows where quality preservation is critical. - **Resolution handling**: Upscale, downscale, and crop video content for different platform requirements — from mobile 720p to desktop 4K. - **Frame extraction**: Extract specific frames or frame ranges as PNG/EXR image sequences for compositing or texture work. - **Thumbnail generation**: Automatic thumbnail extraction from video assets for asset browser previews. - **Metadata embedding**: Write and read video container metadata including title, description, and technical parameters. - **Timeline export**: Export video sequences with SMPTE timecode metadata for handoff to editorial workflows. --- ## 15. DaVinci Resolve Integration `@bellona/davinci` bridges 3D content creation and video post-production, enabling renders and assets to flow directly into DaVinci Resolve (Blackmagic Design's industry-standard color grading and video editing application) projects. - **Project import**: Import DaVinci Resolve project files (`.drp`) to read timeline structure and media references. - **Timeline synchronization**: Sync rendered image sequences from Bellona build outputs into specific Resolve timeline tracks with correct timecode alignment. - **Color space management**: Communicate scene-linear HDR render outputs with correct color space metadata — ACEScg for visual effects, Linear, and ACES2065-1 for archival interchange. - **Fusion integration**: Connect to DaVinci Resolve's Fusion node-based compositing module for VFX work requiring render-layer compositing. - **Render output handoff**: Deliver finished renders from Bellona's build pipeline directly into Resolve's media pool, ready for color grading. --- ## 16. Houdini Integration `@bellona/houdini` integrates Houdini 19.5+ — SideFX's industry-standard procedural effects and simulation application — into the Oshun build pipeline. ### 16.1 HDA Asset Pipeline Houdini Digital Assets (HDAs) are reusable, self-contained Houdini nodes that encapsulate procedural workflows — the primary way VFX studios share and reuse Houdini setups: - **HDA import/export**: Import HDA files into the build pipeline and distribute them to production teams. - **Parameter exposure**: Expose and modify HDA parameters from outside Houdini, enabling parameterized procedural generation without requiring Houdini expertise. - **Procedural pipeline integration**: Connect HDAs to Oshun's environment generation pipeline for terrain dressing, crowd simulation, and effects. ### 16.2 USD Pipeline Houdini has native USD authoring at both the SOP (Surface Operator — geometry level) and LOP (Layout Operator — scene assembly level) contexts: - **Solaris LOP integration**: Houdini's Solaris environment for USD scene assembly, look development, and rendering integrates with Bellona's USD layer management. - **SOP-level USD**: Export Houdini geometry networks as USD geometry directly from the SOP context. - **LOP look development**: Material assignment, lighting configuration, and render settings authored in Houdini's LOP network integrate with Bellona's USD pipeline. --- ## 17. Command-Line Interface `apps/bellona/cli` provides terminal-based access to all Bellona capabilities, built with Commander.js for scriptable automation. | Command | Alias | Description | | --------- | ----- | ------------------------------------------------------------------------- | | `build` | `b` | Submit build jobs, check status, list recent builds, cancel jobs | | `export` | `e` | Create export packages and download them to the local filesystem | | `sync` | — | Sync assets with connected engine projects (push, pull, or bidirectional) | | `config` | — | Manage API keys, default project, and named environment profiles | | `health` | — | Check Bellona service health and active bridge connection status | | `project` | — | Manage engine projects: list, add, remove, and set default project | | `detect` | — | Auto-detect Unity, Unreal, and Godot projects in the current directory | - **`bellona.yaml` project config**: A commit-safe YAML configuration file storing project IDs, engine paths, and default build targets alongside source code. - **Profile management**: Named profiles for dev, staging, and production environments so the same CLI commands target different Bellona instances. - **`--json` output mode**: Machine-readable JSON output for use in CI/CD shell scripts that need to parse build results or artifact URLs. --- ## 18. TypeScript SDK `@bellona/client` provides a fully typed client for all Bellona operations, used by web frontends, CI/CD automation scripts, and cross-domain integrations across the Oshun monorepo. - **Build operations**: `triggerBuild`, `triggerAssetBuild`, `triggerFullBuild`, `triggerDebugBuild` — submit typed build jobs; `getBuild`, `listBuilds`, `cancelBuild`, `retryBuild` — query and manage jobs; `waitForBuild` — poll until completion; `buildAndWait`, `downloadArtifact` — convenience methods combining submission, polling, and download. - **Export operations**: `createExport`, `exportForUnity`, `exportForUnreal`, `exportForGodot` — create engine-targeted packages; `getExport`, `listExports`, `waitForExport`, `exportAndDownload` — monitor and download. - **Engine sync operations**: `registerEngine`, `disconnectEngine`, `listEngines` — manage connections; `pushToEngine`, `pullFromEngine`, `bidirectionalSync` — execute sync; `getConflicts`, `resolveConflict` — handle conflicts; `syncWithUnity`, `syncWithUnreal`, `syncWithGodot` — engine-specific convenience methods. - **Typed API surface**: Every request and response is fully typed. Type errors are caught at compile time, not discovered at runtime. --- ## 19. C++ Native SDK `@bellona/sdk-cpp` enables native engine plugins and CI/CD agents to communicate with the Bellona platform without requiring a TypeScript or Node.js runtime — necessary for Unity native plugins, Unreal Engine C++ modules, Godot GDExtensions, high-performance asset loading in engine runtimes, and build machine agents where Node.js is not installed. --- ## 20. GPU Rendering `apps/bellona/render-api` is a render-job module that manages GPU-accelerated rendering through a queued workflow. It runs as an embedded Node.js module (`initialize()` / `shutdown()` lifecycle) rather than a standalone HTTP service. - **GPU device allocation**: Schedule render jobs across available GPU devices, tracking each device's current workload and capacity to prevent overcommit. - **Redis-backed result cache**: Completed render results are cached in Redis with PubSub notification so downstream consumers know when a render is available without polling. - **Output validation**: Automated quality checks on render outputs — detecting black frames, corrupted images, or resolution mismatches — before delivery to downstream consumers. - **Quality presets**: Draft (low samples, fast), Preview (medium quality), Production (high samples, denoised), and Final (maximum quality, full denoising) — each with different ray bounce counts, sample counts, and denoising settings. - **Frame range rendering**: Render individual frames, contiguous frame ranges, or complete animation sequences. --- ## 21. Cross-Domain Integration `@bellona/event-handlers` subscribes to events from other Oshun domains and `@bellona/event-publisher` emits events consumed by those domains, making Bellona a participant in the Oshun event mesh. ### 21.1 Automatic Asset Ingestion The four inbound event subscriptions below are what drive Bellona's build pipeline automatically — no manual invocation is required when these upstream domains publish content. | Source Domain | Event | Bellona Action | | ------------- | ------------------------- | ------------------------------------------------------ | | Hathor | `hathor.world.published` | Generate engine project files for the published world | | Isis | `isis.asset.generated` | Convert and import newly generated textures and models | | Yemaya | `yemaya.build.requested` | Enqueue a build job from creative studio export output | | Yemaya | `yemaya.export.requested` | Start the export pipeline for studio-produced assets | ### 21.2 Lore-to-Engine Compilation When Hathor publishes a world, Bellona's `LoreToEngineCompiler` transforms narrative data (quests, dialogues, NPCs, factions, world rules) into engine-native code: dialogue trees to conversation systems, quest structures to quest node graphs, and engine-specific code stubs (GDScript for Godot, Blueprint references for Unreal, C# partial classes for Unity). ### 21.3 AI Asset Pipeline When Isis generates content, Bellona automatically adapts it for game engine use: textures are resized and compressed to GPU formats (BC7 for PC, ASTC for mobile, ETC2 for Android/WebGL); models are re-meshed if polygon count exceeds the engine's polygon budget target. ### 21.4 Events Published | Event | When | Primary Consumers | | ------------------------- | ----------------------------- | ------------------------------------ | | `bellona.session.started` | Bridge connection established | Analytics, monitoring dashboards | | `bellona.session.ended` | Bridge connection terminated | Analytics, session duration tracking | | `bellona.build.started` | Build job begins processing | UI dashboards, notification service | | `bellona.build.completed` | Build job finishes | Asset availability notifications | | `bellona.export.ready` | Export package ready | Download notification service | | `bellona.asset.synced` | Asset synced with engine | Asset tracking and analytics | ### 21.5 V2 Fighting-Game Runtime Consumer (Sister Monorepo) The V2 fighting-game project (`V2/`) is a named Bellona consumer with fighting-game-specific cook requirements. V2's deterministic combat inner loop is sovereign — Bellona does not bridge into `V2Combat`, `V2Gameplay`, `V2Input`, or `V2Netcode`. Every other V2 content surface flows through Bellona at cook time. See `V2/V2_ARCHITECTURE.md` § "Sister-Monorepo Integration Surface" and `V2/V2_DEPENDENCIES.md` § 68 for the V2-side contract. #### 21.5.1 V2 cook channels | Channel | Bellona path | V2 destination | | ------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------- | | Isis cosmetic variants | `@isis/3d-generation` + `@isis/ai-texturing` → `@bellona/interchange` → `@bellona/unreal` | `V2/ue/Content/Generated/Cosmetics/` | | Isis stage variants | `@isis/3d-scene-assembly` + `@bellona/openusd` → `@bellona/unreal` | `V2/ue/Content/Generated/Stages/` | | Real-world venue capture | `@isis/gaussian-splatting` → `@bellona/openusd` → `@bellona/unreal` Nanite cook | `V2/ue/Content/Stages/Licensed/` | | Hathor narrative export | `@hathor/lore-compiler` → `@bellona/interchange` → `@bellona/unreal` | `V2/ue/Content/Generated/Dialogue/` + Sequencer presets | | Aja mocap → frame-snap | `@aja/motion-pipeline-sdk` → `@bellona/mocap` → `@bellona/unreal` Live Link | `V2/ue/Content/Animation/Mocap/` | | MetaHuman commentator | `@bellona/metahuman` (ARKit blendshapes + face rig + Live Link) | `V2/ue/Content/Characters/Commentators/` | | Euterpe music stems | `@euterpe/genesis` + `@euterpe/master` → `@bellona/audio` | `V2/ue/Content/Audio/Music/Generated/` | | Isis auto-edit highlight | `@isis/ai-video` + `@calliope/cinema` → `@bellona/video` | V2 replay export pipeline | #### 21.5.2 V2-specific cook gates Beyond Bellona's default validation, V2 cooks add fighting-game-specific quality gates: - **Animation frame alignment** — every Aja-retargeted animation must be resampled to integer-frame multiples at the V2 deterministic tick rate (60 Hz minimum) with sub-frame interpolation across the original mocap cadence. **Authoring boundary correction (from adversarial review):** notify segments (hit-active, armor, cancel-window) are **authored** in UE AnimMontage, not extracted from source mocap — `@bellona/mocap` aligns the _animation timeline_ to 60 Hz so authored notifies land on integer frames; it does not create notify segments. The reciprocal task in § 21.5.4 #2 covers timeline resampling only. - **Provenance lineage required** — every cooked asset under `V2/ue/Content/Generated/` must trace back to an Isis / Hathor / Aja / Euterpe job ID via Bellona's content-addressable manifest. V2 CI rejects untraced assets. - **Rights-cleared at cook time** — every shipping asset must carry a Themis rights stamp (cross-ref Themis NIL ledger). Bellona refuses to publish uncleared assets. - **Moderation pre-pass** — every player-derived asset (CAW upload, decal, stage share, music swap) must pass `@kuanyin/precognition` before Bellona enqueues a cook. #### 21.5.3 V2 events V2 publishes / Bellona consumes | Event | Bellona Action | | ------------------------------ | ---------------------------------------------------------------------- | | `v2.cosmetic.requested` | Enqueue cosmetic-variant cook from Isis manifest | | `v2.stage.variant.requested` | Enqueue stage-variant cook (weather / time / crowd) from Hathor + Isis | | `v2.dialogue.requested` | Enqueue Hathor narrative export cook for Story / Side Story / Krypt | | `v2.mocap.captured` | Enqueue Aja → Bellona/mocap retarget + frame-snap cook | | `v2.replay.export.requested` | Enqueue Isis highlight-reel auto-edit + video cook | | `v2.balance.dataset.published` | Build the frame-data spreadsheet artifact for Sophia ingestion | #### 21.5.4 Forthcoming reciprocal work These items are V2 dependencies the Bellona domain owns. Track in Bellona backlog, not V2 backlog. Each line is a Bellona-side specification task to be expanded in `DOMAINS/bellona/specifications.md`. 1. **`BellonaUnrealRuntime`** — runtime-shipped UE plugin companion to `BellonaUnrealEditor`. Today Bellona ships an editor-only plugin (`libs/bellona/unreal/plugin/BellonaUnrealEditor/`). V2 requires a runtime plugin shipped inside the cooked game build for live cosmetic catalog pulls, friend presence, AI commentary stream subscription, and live-ops content drops. Must respect rollback isolation: any runtime call originating from this plugin is off-rollback and never feeds the deterministic simulation. 2. **`@bellona/mocap` 60 Hz resampling + sub-frame alignment** — extend the existing mocap pipeline with timeline resampling that aligns the animation curve to integer frames at a target tick rate (60 Hz default; configurable per project). **Scope correction from prior draft:** this covers timeline-level alignment of the animation, not notify-segment authoring; notify-segment authoring stays in the UE AnimMontage editor. Required so Aja-cleaned animations preserve rollback determinism when imported. 3. **`@bellona/unreal` GAS-aware import** — when Bellona imports an animation montage, recognize V2's GAS gameplay-tag conventions (`State.Stance.*`, `Action.Cancel.*`) and emit appropriate notify states automatically. 4. **`@bellona/openusd` per-region variant emission** — Aphrodite per-region content rules (China / Germany / Australia / NZ / KR gore variants) emit USD variant sets so V2's per-region build pulls the correct variant at cook time without per-region asset duplication. 5. **`@bellona/audio` MetaSounds graph emission** — Euterpe music + Iris commentary outputs land in V2 as MetaSounds graphs, not raw audio files, so V2's `V2Audio` module can adjust dynamic mix at runtime. --- ## 22. Audit and Monitoring - **Audit log**: Every build, export, sync, and bridge operation is recorded with timestamp, actor identity (user or service), previous state, and new state — a complete, tamper-evident history for debugging and compliance. - **Build worker monitoring**: Worker registration records, capability declarations, concurrency utilization, and health status per worker. Dead workers are detected and their in-progress jobs are rescheduled. - **Cache health endpoint**: Reports hit rate, total entry count, current memory usage, and eviction count — enabling cache tuning based on real workload data. - **Session metrics**: Per bridge session — total duration, commands executed, disconnect reason, and sync conflict count — to identify problematic sessions and debug connectivity issues. --- ## 23. Remote Control Bellona includes a browser-first remote-control subsystem that lets a web operator console drive engine hosts, desktop applications, and headless browsers on a remote machine. It is built from two libraries and three apps and is described in its own package metadata as a walking-skeleton service layer. ### 23.1 Remote Protocol — `@bellona/remote-protocol` The canonical protocol contract layer for remote control. It carries the package descriptor, schema-status metadata (`version-negotiation`), and a schema-ownership boundary. Contracts are partitioned into modules for actors, audit, commands, devices, sessions, state, streams, policy, dry-run, logging, results, and engine-specific surfaces (Blender, Unreal, browser, desktop). The protocol defines **13 command namespaces**: `device`, `session`, `stream`, `agent`, `state`, `blender`, `unreal`, `browser`, `desktop`, `file`, `process`, `approval`, and `diagnostic`. ### 23.2 MCP Gateway — `@bellona/mcp-gateway` A remote-control MCP gateway server with a local stdio transport, distributed with a `bellona-mcp-gateway` binary. It exposes remote-control tools and resources to MCP clients, manages authenticated sessions, and provides an agent control layer covering capability memory, autonomous stop criteria, dry-run planning and cost/time/impact estimation, mutation locking, preflight checks, tool-selection policy, handoff paths, long-running jobs, and visual verification policy. ### 23.3 Remote Gateway — `apps/bellona/remote-gateway` The gateway service that brokers between operator consoles and remote hosts. It provides a device registry, session lifecycle management, an approval service, a command dispatcher, pairing codes and host-token exchange, device revocation, an audit log with redaction, and telemetry. ### 23.4 Remote Host — `apps/bellona/remote-host` The host agent that runs on the controlled machine. It exposes an adapter registry with Blender, Unreal, browser, and desktop adapters; a command executor; a gateway connection; a pairing client and identity store; and macOS permission handling. Desktop adapters cover clicking, typing, clipboard, screenshots, window management, display enumeration, and an emergency stop. ### 23.5 Control Room — `apps/bellona/control-room` The browser-first React/Vite operator UI. It provides an approval queue, a command palette, a device list, a session timeline, a stream preview with WebRTC loopback, a mobile approval PWA, and a first-session tour. The UI is gated behind the `VITE_BELLONA_CONTROL_ROOM_ENABLED` environment flag. ### 23.6 Phase 180 Planned Envelope — Remote Creative Control Plane The subsystem above is the walking-skeleton stage of the Phase 180 Remote Creative Control Plane (`TODOS/phase-180.md`, with expanded architecture in `TODOS/phase-180-reference.md` and the gap analysis in `TODOS/phase-180-gaps.md`). The full envelope turns it into a secure, observable, agent-native control fabric that lets Oshun agents on a primary MacBook, Hetzner, AWS, or any trusted compute environment drive Blender, Unreal, Chrome, and selected desktop workflows on a remote host over the same LAN or across networks. Planned capabilities beyond the current skeleton: - **Additional packages** — `libs/bellona/remote-adapters` (adapter interfaces for Blender, Unreal, browser, desktop, files, and process control), `libs/bellona/mac-host-runtime` (macOS TCC permissions, process launching, window focus, screen capture, signing/update helpers), `libs/psyche/desktop-fallback` (reusable screenshot/click/type/window fallback shared with Psyche Computer Use), and `testing/bellona/remote-control` (integration, e2e, fixture, and network-impairment tests). - **Deep integration first** — typed Blender, Unreal, and browser (CDP / Playwright / Browser Use) adapters take precedence over desktop fallback; Computer Use is reserved for applications without a reliable API path. Production command coverage spans Blender scene/render/automation, Unreal scene mutation, Sequencer, render, build, and diagnostics, and browser production automation. - **Networking and cloud gateway** — WebRTC live streaming (beyond loopback preview) with TURN relays, optional Tailscale/WireGuard networking, cloud-deployed gateway for cross-network sessions, and transport hardening; Blender/Unreal/browser debug ports stay localhost-only on the host. - **Security, trust, and governance** — device pairing and trust lifecycle, approval gates before privileged actions, no hidden privileged path (no arbitrary shell / Blender Python / Unreal console / real browser profiles before policy, approval, and audit primitives exist), end-to-end encryption posture, consent and recording-law handling, adapter supply-chain integrity, and agent-to-agent identity. - **Observability and replay** — audit-grade traces of every instruction, command, screenshot, render, file change, and approval decision, with timeline replay in the Control Room. - **Host platform expansion** — signed/notarized macOS host packaging with auto-update, then Windows and Linux host support, multi-host fleet operations, and coexistence with (then deprecation of) the existing `bridge-blender` / `bridge-unreal` apps. - **Ecosystem** — a third-party adapter SDK with a conformance suite, tier-2 DCC adapter onboarding, timecode/color/media pipeline handling for streamed review, notifications and external event sinks, and MCP composition with other servers so cloud-hosted Oshun agents can operate remote devices as MCP tools. Cross-domain roles: Psyche contributes Computer Use fallback primitives, Yemaya Studio surfaces production review, Iris/Nous host the controlling agents, and Contracts/OpenAPI/Proto carry the shared command schemas sourced from `@bellona/remote-protocol`. --- ## Library Summary The following table is a quick-reference index of all 34 libraries in the domain. See earlier sections for full feature descriptions. | Library | Package | Primary Capability | | ------------------------------- | -------------------------------- | ---------------------------------------------------------------------- | | `bellona/3dsmax` | `@bellona/3dsmax` | 3ds Max bridge runtime and workflow contracts | | `bellona/adapters` | `@bellona/adapters` | Engine-adapter infrastructure — BaseBridge, command routing, state | | `bellona/asset-export` | `@bellona/asset-export` | CGI-scene asset export readiness and conversion planning | | `bellona/audio` | `@bellona/audio` | Audio processing, ambisonics, transcoding, loudness normalization | | `bellona/blender` | `@bellona/blender` | Blender WebSocket bridge — 6 typed commands | | `bellona/blender-agent` | `@bellona/blender-agent` | Blender-native agent runtime — RPC bridge, action schemas, macros | | `bellona/bridge-core` | `@bellona/bridge-core` | Shared WebSocket bridge protocol, heartbeat, reconnection | | `bellona/client` | `@bellona/client` | TypeScript SDK — builds, exports, sync, engine management | | `bellona/cross-dcc-consistency` | `@bellona/cross-dcc-consistency` | Cross-DCC workflow consistency and compatibility contracts | | `bellona/database` | `@bellona/database` | Build job, session, and artifact persistence (Prisma) | | `bellona/davinci` | `@bellona/davinci` | DaVinci Resolve project import, timeline sync, color space handoff | | `bellona/editor-productization` | `@bellona/editor-productization` | Editor release, onboarding, recovery, diagnostics contracts | | `bellona/event-handlers` | `@bellona/event-handlers` | Cross-domain event consumption from Hathor, Isis, Yemaya | | `bellona/event-publisher` | `@bellona/event-publisher` | Cross-domain event emission — build, export, session, sync events | | `bellona/gameplay-systems` | `@bellona/gameplay-systems` | Input, save/load, inventory, combat, AI behavior trees | | `bellona/godot` | `@bellona/godot` | Godot WebSocket bridge — 9 typed commands | | `bellona/houdini` | `@bellona/houdini` | HDA pipeline, Solaris LOP integration, USD authoring | | `bellona/integration` | `@bellona/integration` | Cross-domain Hathor / Isis consumers and compilers | | `bellona/interchange` | `@bellona/interchange` | Multi-format import/export, transform pipeline, batch conversion | | `bellona/interchange-models` | `@bellona/interchange-models` | Shared intermediate representation schemas for 3D assets | | `bellona/maya` | `@bellona/maya` | Maya bridge runtime and workflow contracts | | `bellona/mcp-gateway` | `@bellona/mcp-gateway` | Remote-control MCP gateway server and stdio transport | | `bellona/metahuman` | `@bellona/metahuman` | MetaHuman mesh import, face rig, ARKit blendshapes, Live Link | | `bellona/mocap` | `@bellona/mocap` | Multi-vendor mocap streaming, retargeting, BVH/C3D/TRC, frame-snap | | `bellona/openusd` | `@bellona/openusd` | USD stage management, composition, variants, MaterialX, pipeline tools | | `bellona/remote-protocol` | `@bellona/remote-protocol` | Canonical remote-control protocol contracts | | `bellona/sdk-cpp` | `@bellona/sdk-cpp` | C++ native SDK for engine plugins and build machine agents | | `bellona/unity` | `@bellona/unity` | Unity WebSocket bridge — 14 typed commands | | `bellona/unity-agent` | `@bellona/unity-agent` | Unity Editor MCP server package and orchestration wrapper | | `bellona/unreal` | `@bellona/unreal` | Unreal Engine WebSocket bridge — 11 typed commands | | `bellona/video` | `@bellona/video` | Video transcoding, codec support, frame extraction, thumbnail gen | | `bellona/virtual-production` | `@bellona/virtual-production` | LED wall control, camera tracking, ICVFX, genlock, timecode | | `bellona/xr` | `@bellona/xr` | visionOS, Meta Quest, WebXR — hand tracking, spatial anchors, scene | --- ## Application Summary | App | Primary Capability | | ----------------------------- | --------------------------------------------------------------- | | `apps/bellona/build-api` | Event-driven build/export orchestration module | | `apps/bellona/build-worker` | Background job processor — 4 worker types | | `apps/bellona/render-api` | Render-job caching, GPU queue, output validation module | | `apps/bellona/cli` | `bellona` command-line tool (Commander.js) | | `apps/bellona/bridge-unity` | Unity WebSocket bridge (port 9004) | | `apps/bellona/bridge-unreal` | Unreal WebSocket bridge (port 9003) | | `apps/bellona/bridge-godot` | Godot WebSocket bridge (port 9002) | | `apps/bellona/bridge-blender` | Blender WebSocket bridge (port 9001) | | `apps/bellona/control-room` | Browser-first remote-control operator UI (React/Vite) | | `apps/bellona/remote-gateway` | Remote-control gateway service (device/session/approval broker) | | `apps/bellona/remote-host` | Remote-control host agent (engine + desktop + browser adapters) | --- ## Neith Engine and DCC Parity Dependencies (Phases 135, 137-174) Bellona owns integration with external engines, DCC bridges, build/export workers, and runtime handoff. Neith owns the sovereign engine, renderer, DCC, profiling, online, live-service, and final Unreal/Blender parity systems that Bellona will bridge, export, validate, and package. - **VFX/post and virtual production (Phase 135)**: Bellona receives the pipeline handoff from `@neith/foundry`/`@neith/conform` and the virtual production stack — engine-side render handoff, LED-volume content packaging, and camera-tracking data exchange with Bellona's own virtual-production bridges. - **Platform, cloud, and live service (Phases 137, 140, 159, 164, 165)**: Bellona integrates platform HAL, console/mobile/Steam targets, cross-platform identity, matchmaking, lobbies, rollback, dedicated servers, cloud-game streaming, online subsystem abstraction, replication, RPC, prediction, transport, voice, stats, achievements, replay, pixel streaming, anti-cheat, monetization, LiveOps, and creator marketplace outputs into build pipelines and engine runtime packages. - **Rendering and compute (Phases 138, 143, 144, 154, 168-170)**: Bellona bridges Neith's sculpting, procedural FX, material/texturing tools, DCC competitor workflows, real-time visualization renderers, EEVEE-class rasterizer, modern GI, GPU compute, sculpting depth, NPR/Freestyle rendering, and final render-preview systems into exchange formats, preview tools, validation jobs, and external engine adapters. - **Animation, VFX, simulation, and humans (Phases 141, 153, 155-158, 161-163)**: Bellona consumes Neith's 2D animation suite, matchmove, hair/grooming, Grease Pencil-class 2D-in-3D, fluid/smoke/fire/particle simulation, VSE, Niagara-class GPU VFX authoring, MetaHuman-class digital humans, and virtual production stack as bridgeable asset types and runtime/export targets. - **Diagnostics and final parity sweeps (Phases 160-174)**: Bellona integrates frame profiling, GPU debugging, network/audio/asset/cook profilers, postmortem crash data, Verse/UEFN-class scripting, LWC, level instances, MegaLights, runtime virtual textures, modeling mode, Geometry Script, mesh distance fields, Smart Objects, Chooser, pose search, Enhanced Input, GameplayTags, GAS, MRQ, DMX, Concert, Switchboard, Live Link XR, PCG, Gauntlet, cook pipeline, localization, Visual Logger, material layers, Control Rig, IK, ML Deformer, Geometry Cache, Mover, Mutable, NavMesh, Mass Traffic, Dataflow, subsystems, Sequencer, Push Model replication, Online Services v2, Interchange, Blueprints, Composure, source control, asset diff/merge, foliage, Modular Gameplay, Niagara Data Channels, Rewind Debugger, Unreal math types, and Blender's modifier, UV, Python, Cycles, VDB, armature, sculpt, shader, compositor, particle, snapping, transform, workspace, operator, add-on, input-device, viewport, and image-editor parity features.