Domain · Features

Bellona Domain — Feature Reference

Each supported engine has a dedicated WebSocket bridge that runs alongside the engine editor.

26sections45 minread

On this page
Supporting documentation. This domain also carries 85 operational supporting docs under docs/domains/bellona/ (API notes, ADRs, deep topic guides) — reconciled here by linking, kept beside the code as supporting material rather than a second canonical source (§2, §13).

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.

text
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.

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 packageslibs/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.