# Bellona — Systems Deep Dive

> The `libs/bellona/` area: ~40 Nx libraries that make up Bellona, Oshun's
> engine-bridge / DCC-automation / remote-creative-control-plane domain — the
> code that drives Unreal, Unity, Blender, Houdini, Maya, Godot, DaVinci and
> friends, moves assets between them, and exposes that whole surface to agents.

## What this area is

Bellona is Oshun's "make a real game / film / 3D asset" domain. Where most Oshun
libraries push JSON around services, Bellona reaches out of process to running
creative tools — game engines, DCC (Digital Content Creation) applications,
audio/video hardware — drives them, and shuttles assets through interchange
formats. The `libs/bellona/` tree is not one package but ~40 separate Nx
libraries, almost all tagged `scope:bellona`, that fall into a few distinct
generations and families.

The largest family is the **per-engine / per-DCC adapter** set:
`@bellona/unreal`, `@bellona/unity`, `@bellona/godot`, `@bellona/blender`,
`@bellona/houdini`, `@bellona/davinci`, plus the `@bellona/maya` and
`@bellona/3dsmax` runtime foundations. These are mostly TypeScript bridges that
speak each tool's remote protocol (WebSocket, Remote Control API, batchmode
stdio) and provide managers for scenes, assets, materials, animation and
rendering. `@bellona/unreal` and `@bellona/unity-agent` additionally ship real
native plugins (a 3900-line UE5 C++ command dispatcher; a Unity Package Manager
MCP server in C#). On top of the adapters sits a **shared bridge layer** —
`@bellona/adapters`, `bellona-bridge-core` — and an **asset-interchange layer**
— `@bellona/interchange`, `@bellona/interchange-models`,
`@bellona/asset-export`, `@bellona/openusd`, `@bellona/mocap` — that converts
and validates assets between GLTF/USD/FBX and the engines.

The second large family is the **Phase 180 Remote Creative Control Plane**: a
remote-agent stack that lets a (possibly cloud) agent drive a creative host
machine safely. `@bellona/remote-protocol` owns the canonical command/event
contracts; `@bellona/remote-adapters` is the adapter SDK + conformance suite;
`@bellona/mcp-gateway` exposes the plane as MCP tools/resources;
`@bellona/host-runtime` is the cross-platform host abstraction with tamper
detection; `@bellona/artifact-store`, `@bellona/creative-flows`,
`@bellona/release-evidence`, `@bellona/cross-dcc-consistency` and
`@bellona/editor-productization` provide artifact provenance, cross-app
orchestration flows, SBOM/release evidence, and editor-plugin productization.
Two SDKs (`bellona-sdk-cpp`, `bellona-sdk-python`) and a TS client
(`bellona-client`) let external code talk to the gateway/platform API.

The rest are domain/infra pieces: `@bellona/database` (Prisma schema for
builds/exports), `@bellona/event-publisher` + `@bellona/event-handlers` (the
event-bus seam to the rest of Oshun), `bellona-gameplay-systems` (runtime game
systems), `bellona-audio` / `bellona-video` / `@bellona/virtual-production` /
`bellona-xr` (media + virtual-production + XR adapters), `@bellona/metahuman`,
`@bellona/text-to-3d` (generative 3D), and `@bellona/integration` (Hathor/Isis
ingestion).

## How it fits the wider system

Bellona consumes content from other Oshun domains and turns it into engine-ready
assets and builds. `@bellona/event-handlers` subscribes to Hathor
(world-published), Isis (asset-generated) and Yemaya (build/export-requested)
events; `@bellona/integration` ingests Hathor lore and Isis assets directly; and
`@bellona/event-publisher` emits Bellona's own session/build/export events back
onto `@oshun/event-bus` using `BellonaEventTypes` from `@oshun/contracts`. The
adapter and interchange libraries compose with each other — e.g.
`@bellona/asset-export` imports `AssetFormat`/`ExportConfig` from
`@bellona/interchange`, and `@bellona/text-to-3d` runs GLB through
`@bellona/interchange` then `@bellona/unreal` to author a `.uasset`. Externally,
the remote-control-plane libraries are consumed by the `apps/bellona`
remote-gateway and host apps, and the SDKs (`bellona-sdk-cpp`,
`bellona-sdk-python`, `bellona-client`) are the public clients of that gateway.
Walk the "used by" edges on any node below to see exactly who depends on it.

## Entity reference

### @bellona/3dsmax

3ds Max bridge runtime + workflow foundation (`libs/bellona/3dsmax/src`). It is
a deterministic planning layer, not a live MaxScript driver: a library manifest
and supported-release policy (`bootstrap.ts`, `version-support-policy.ts`), a
typed bridge-runtime plan builder (`createBellona3dsMaxBridgeRuntimePlan` over
execution-channel/transport enums), a typed action schema, and import/export,
send-import, rigging-animation and UI-hook plan builders. Each module is a
`create*Plan` that returns a validated plan structure with matching `.test.ts`
coverage; the actual 3ds Max execution is left to a downstream bridge.

### @bellona/adapters

The base engine-adapter infrastructure shared by the Godot/Unreal/Unity/Blender
bridges (`libs/bellona/adapters/src`). It provides the reusable building blocks:
`BaseBridge` with heartbeat, reconnection and a message codec (`src/bridge/`); a
command pipeline (`command-queue`, `command-batcher`, `command-executor`); state
management with history and sync (`src/state/`); and a process launcher with a
version manager (`src/launcher/`). Concrete engine libs extend `BaseBridge`
rather than re-implementing connection/command/state plumbing.

### @bellona/artifact-store

The Phase-180 remote artifact store (`libs/bellona/artifact-store/src`,
180.C.22.05/.11/.12/.13). It is real: `createLocalArtifactStore` composes
`@oshun/storage`'s `LocalStorageClient` to write bytes to disk, verify hashes on
put and persist JSON-sidecar records; on top sit an asset `dependency-graph`, a
reference-`integrity` query layer (broken refs / missing source / stale /
upstream-invalidation), and an `impact-preview` consumed by the dry-run plans.
`oshun-storage-store.ts` is the S3/MinIO/local-backed implementation.

### @bellona/asset-export

A small, single-module CGI-scene export-readiness and conversion planner
(`libs/bellona/asset-export/src/index.ts`). It types a source asset
(mesh/material/ texture/animation/skeleton counts, unit scale, up-axis) and
produces an export plan across `usd`/`usda`/`usdc`/`usdz`/`gltf`/`glb`/`fbx`
targets, each carrying readiness flags (geometry-quality, material-binding,
texture-relink, animation-retarget, skeleton, coordinate/unit conversion,
package + checksum manifests). It reuses `AssetFormat`, `ExportConfig`,
`TransformPipeline` and `ValidationResult` from `@bellona/interchange` rather
than redefining them.

### bellona-audio

A professional audio adapter (`libs/bellona/audio/src`, package
`@bellona/audio`). The DSP here is genuinely real, not stubbed:
`processing/index.ts` (~1300 lines) implements ITU-R BS.1770-4 K-weighting
biquads with exact reference coefficients, plus
gain/compressor/parametric-EQ/limiter processors and an LUFS-style meter. Around
it sit capture (`SystemAudioCapture`, `AudioRingBuffer`), output, and a
routing/mixer module (`AudioMixer`, channel strips, bus nodes), with an Ardour
integration module.

### @bellona/blender-agent

The Phase-71 Blender-native agent runtime (`libs/bellona/blender-agent/src`, 62
files). It is a substantial deterministic agent surface: a Blender RPC bridge
over WebSocket-addon or headless stdin/stdout sessions
(`blender-rpc-bridge.ts`), a typed action schema, a natural-language →
typed-action planner (`natural-language-action-planner.ts`) plus an LLM planner
with a `StructuredPlanner` seam that throws `LlmPlannerNotConfiguredError` when
no model is wired (`llm-action-planner.ts`), and a large library of authoring
workflows (geometry-nodes authoring/diff-merge/templates, groom/hair macros,
kitbash, blend packaging, headless batch, execution-audit log). The README
documents the boundary honestly.

### @bellona/blender

The Blender integration adapter (`libs/bellona/blender/src`) and its Python
addon (`python/bellona_addon/`). The TS side exports a WebSocket bridge
(`BlenderConnection`, `CommandQueue`, `StateManager`, `BlenderClient`), scene/
object/collection managers, asset managers (material/image/file/geometry-nodes),
and animation + render modules. A real Blender addon (`server.py`,
`handlers.py`, `events.py`) provides the Blender-side counterpart, and a large
set of `addon-*.test.ts` files cover onboarding, packaging, update channels,
recovery and session-resilience for that addon.

### bellona-bridge-core

Core bridge infrastructure for engine communication
(`libs/bellona/bridge-core/src/index.ts`, package `@bellona/bridge-core`). A
single-module library built on `ws`: branded `ConnectionId`/`MessageId` types, a
`BridgeMessage`/`BridgeRequest`/`BridgeResponse`/ `BridgeEvent` protocol, and
WebSocket server/client + message-routing primitives. It is the lower-level
transport foundation that predates `@bellona/adapters`' higher-level
`BaseBridge`.

### bellona-client

The TypeScript client SDK for the Bellona platform (`libs/bellona/client/src`,
package `@oshun/bellona-client`). It wraps the platform REST API
(`BellonaApiClient`, generated types in `api/generated.ts`) with build/export/
engine-sync helpers (`triggerBuild`, `waitForBuild`, `exportForUnity`, …), and a
`remote/` sub-client + transport that targets the Phase-180 remote gateway. It
also carries OpenAPI/cross-service contract specs (`src/contracts/`) that assert
the SDK stays in sync with the gateway schema.

### @bellona/creative-flows

Cross-app creative-orchestration flows for the Remote Creative Control Plane
(`libs/bellona/creative-flows/src`, 180.C.22.06–.09/.14). Each flow orchestrates
existing command families plus `@bellona/artifact-store` provenance:
Isis→Blender, Blender→Unreal, Unreal-render→Yemaya, and
browser-research→asset-action (with a hard approval gate). Every
engine/cross-domain boundary is an injectable fail-loud seam (`provider.ts`,
`test-doubles.ts`); the optional production-tracking integration
(Flow/ftrack/Kitsu) returns a fail-loud `provider_not_configured` rather than
faking a connection.

### @bellona/cross-dcc-consistency

Cross-DCC workflow-consistency contracts for the bridges
(`libs/bellona/cross-dcc-consistency/src`). A deterministic plan-builder
library: a bridge-UX specification, cross-DCC handoff profiles, a compatibility
registry, telemetry-health and documentation/runbook plans, an enterprise
offline-delivery plan, a secrets/permission policy
(`createBellonaSecretsPermissionPolicy` over permission scopes + token-storage
modes), and a regression-benchmark suite. Like the other `bootstrap.ts`-style
libs, each module is a typed `create*` factory with test coverage.

### @bellona/database

The Prisma data layer for Bellona's engine/build/export services
(`libs/bellona/database`). It owns `prisma/schema.prisma` with migrations
(initial Phase-8 schema + a batch-export on-delete change), generated SQL, and
seed scripts; `src/client.ts` exports a configured client plus `connect`/
`disconnect`/`transaction`/`executeRaw`/`queryRaw`, and `src/index.ts`
re-exports the generated model types (Build, BuildArtifact, ExportJob,
EngineProject, BridgeSession, SyncConflict, …). It is the persistence backbone
the build/export side of Bellona writes to.

### @bellona/davinci

The DaVinci Resolve adapter (`libs/bellona/davinci/src`). It exposes a
`ResolveClient` bridge plus managers for projects/databases/timeline-lists
(`project/`), timeline operations (`timeline/`), a `ColorGrader` (nodes/curves/
qualifiers/power-windows), a media pool manager, and a Fusion compositing
manager. It is a TypeScript orchestration layer over Resolve's scripting API;
actual color/ edit operations execute inside a running Resolve instance.

### @bellona/editor-productization

Cross-editor release/onboarding/recovery/diagnostics contracts for Bellona's
host plugins (`libs/bellona/editor-productization/src`). Deterministic plan
builders keyed by `BellonaEditorHost`: plugin-distribution plans with release
channels, a connection wizard, an asset-browser plan, send-import workflows,
recovery-UX, update-channel and diagnostics plans. It productizes the
editor-plugin experience (install, connect, recover, diagnose) as typed,
testable plans.

### @bellona/event-handlers

The cross-domain event-subscription layer for Bellona's build/export system
(`libs/bellona/event-handlers/src`). It registers handlers for
`hathor-world-published`, `isis-asset-generated`, `yemaya-build-requested` and
`yemaya-export-requested` against `@oshun/event-bus`, with a
`BELLONA_SUBSCRIPTIONS` pattern map, a metrics module (`withMetrics`,
`HandlerStatsTracker` over `@oshun/metrics`), a world-data parser, and
Postgres/cache storage seams. This is how upstream domain events become Bellona
build/export jobs.

### @bellona/event-publisher

The outbound event publisher for the Bellona (Engine Bridge) domain
(`libs/bellona/event-publisher/src`). `BellonaEventPublisher` wraps
`createEventBus` from `@oshun/event-bus`, takes a typed config, and exposes
type-safe publish methods for session-started/ended, build-started/progress/
completed, and export-started/ready/asset-synced payloads, using
`BellonaEventTypes` from `@oshun/contracts`. It is the single seam through which
Bellona announces state to the rest of Oshun.

### bellona-gameplay-systems

Runtime game systems (`libs/bellona/gameplay-systems/src`, package
`@bellona/gameplay-systems`). Real, sizeable TypeScript gameplay logic rather
than engine bridging: an input system (keyboard/mouse/gamepad/touch/VR with an
action/ context builder DSL), a save system with pluggable storage, an
inventory/item database, a ~1200-line `CombatSystem` with an `AbilityBuilder`,
and an AI-behavior module (behavior trees, utility AI, GOAP, perception). The
`project.json` description is empty, but the code is substantive.

### @bellona/godot

The Godot engine adapter (`libs/bellona/godot/src`). It provides a WebSocket
`GodotBridge` with version discovery and process launching (`bridge/`), real
`project.godot` parsing/writing (`project/project-parser.ts`,
`project-writer.ts`), and `.tscn` scene parsing/writing
(`scene/scene-parser.ts`, `scene-writer.ts`), plus export and scripting modules.
Unlike the pure-bridge adapters, it can read and emit Godot's text project/scene
formats directly.

### @bellona/host-runtime

The cross-platform host runtime for the Remote Creative Control Plane
(`libs/bellona/host-runtime/src`, 180.C.26.16/.12/.15, 180.C.27.18,
180.C.37.02). A platform-neutral permission/process/screen-capture contract so
macOS/Linux/ Windows hosts plug in without duplicating adapter code, a Linux
Wayland/X11 capture strategy with a `LINUX_COMPOSITOR_MATRIX`, host tamper
detection (hash-integrity over binaries/helpers/plugins/update-manifests),
continuous DCC plugin-integrity verification on session start, and a continuous
integrity monitor that fails closed (refuses new sessions) on drift.
Security-oriented and real, with dedicated tests for each integrity concern.

### @bellona/houdini

The Houdini adapter (`libs/bellona/houdini/src`). A WebSocket `HoudiniClient`
bridge plus managers for the node network (SOP/DOP/VOP/CHOP), parameters and
takes, scene access, simulation (Vellum/Pyro/FLIP) and rendering, with a
documented PDG (Procedural Dependency Graph) surface. It is a TypeScript
orchestration layer over Houdini's Python/HOM API; procedural work runs inside a
live Houdini session.

### @bellona/integration

Integration adapters connecting Bellona to the Hathor and Isis domains
(`libs/bellona/integration/src`). `hathor/` consumes Hathor lore artifacts and
compiles them to engine formats (`artifact-consumer.ts`, `lore-compiler.ts`);
`isis/` consumes Isis-generated assets and converts them to engine-specific
formats (`asset-consumer.ts`, `asset-converter.ts`). It is the direct-ingestion
counterpart to the event-driven `@bellona/event-handlers`.

### @bellona/interchange-models

Engine-agnostic data models for cross-engine interchange
(`libs/bellona/interchange-models/src`). Type-safe builders and managers for
scenes (`SceneModelBuilder`, `SceneNodeBuilder`), animations
(clip/track/blend-tree builders), and materials, plus converters — the neutral
in-memory representation that asset conversion targets before it is serialized
to a concrete format. It pairs with `@bellona/interchange` (the format I/O) as
the model half of the interchange split.

### @bellona/interchange

The universal 3D-asset interchange pipeline (`libs/bellona/interchange/src`).
Real import/export modules for GLTF, USD and FBX (`gltf/`, `usd/`, `fbx/`) with
round-trip tests, a transform pipeline, and a validation module — including a
`usdc-geometry-fail-loud.test.ts` that asserts the USDC path fails loud rather
than emitting bogus geometry. It owns the `Asset`/`AssetFormat`/`ExportConfig`/
`ValidationResult` types reused across `@bellona/asset-export` and others.

### @bellona/maya

The Maya adapter + bridge-runtime foundation (`libs/bellona/maya/src`).
Structured exactly like `@bellona/3dsmax`: a library manifest and
supported-release policy, a typed bridge-runtime plan builder
(`createBellonaMayaBridgeRuntimePlan` over execution-channel/transport enums), a
typed action schema, and import/export, send-import, rigging-animation and
UI-hook plan builders, each with smoke-test coverage. It is the deterministic
planning/contract layer for Maya; live MEL/ Python execution is downstream.

### @bellona/mcp-gateway

The Remote-Control MCP gateway (`libs/bellona/mcp-gateway/src`, 47 files). It
exposes the remote plane to local/cloud agents: a stdio MCP server,
gateway-backed tools (`device.list`, `session.start/stop`, `blender.scene.info`,
`blender.object.create_primitive`, `browser.navigate/snapshot`,
`desktop.screenshot`) and resources, optional/required MCP auth-session binding,
and a `DccBridgeGateway` + `UeHttpCommandTransport`. A large set of `agent-*`
modules implement the agent-safety policy surface (preflight checks, mutation
locking, dry-run cost/impact estimators, tool-selection and visual-verification
policies, autonomous stop criteria, capability memory). Policy/approval/audit
live in the gateway, not in transport code.

### @bellona/metahuman

MetaHuman integration for character creation/animation
(`libs/bellona/metahuman/src`). It models MetaHuman identity, mesh types/LODs,
skeleton, textures/materials and a face rig (ARKit blendshape mapping,
face-board controls), with body presets and face customization, and provides a
real mesh importer and face-rig mapper (`import/mesh-importer.ts`,
`import/face-rig-mapper.ts`) with tests and Blender transcript fixtures, plus a
Live Link client and appearance editor. (Its `index.ts` doc-comment still reads
`@yemaya/metahuman`, but the project/package name is `@bellona/metahuman`.)

### bellona-mocap

The motion-capture adapter (`libs/bellona/mocap/src`, package `@bellona/mocap`).
Multi-vendor streaming (OptiTrack/Vicon/Xsens/Rokoko), skeleton templates and
skeleton-to-skeleton retargeting with bone mapping, recording/playback,
coordinate transforms, and BVH/C3D/TRC parsing + Unity/Unreal clip generation.
It also includes an `auto-rig` module, a `frame-snap` aligner (with spec tests),
and an `audio2face` module — a real animation-data toolkit, not a thin bridge.

### @bellona/openusd

OpenUSD pipeline integration (`libs/bellona/openusd/src`). A USD
stage/layer/prim type model, a stage manager, an LIVRPS composition manager
(with a `composition-livrps.spec.ts`), variant management, MaterialX shader
support, an asset-IO manager, and pipeline tools — plus a USDA attribute/variant
serialization suite and a real-runtime test gated on a `pxr` install.
`io/usdc-fail-loud.test.ts` keeps the binary-USDC path honest (fails loud rather
than faking geometry).

### @bellona/release-evidence

Release-evidence generation for the seven Remote-Control-Plane components
(`libs/bellona/release-evidence/src`, 180.C.26.10). The SBOM + license logic is
real: `sbom.ts` builds CycloneDX SBOMs (`buildPurl`, `generateSbom`,
`serializeSbom`) from installed-package manifests, `license-policy.ts` enforces
license compliance, and a `release-evidence.ts` aggregates per-component
evidence (host app, gateway, Control Room, Blender addon, Unreal plugin, browser
helper, native helpers). The live vuln/malware scanners are injected fail-loud
seams, as the header states.

### @bellona/remote-adapters

The Remote-Creative-Control-Plane adapter SDK
(`libs/bellona/remote-adapters/src`, 180.C.32). It defines a stable
`RemoteAdapter` contract (capability handshake, command dispatch,
progress/result emission, audit hooks, policy preflight, rollback metadata,
health reporting), a `conformance` test suite every adapter must pass,
`define-adapter`/`dcc-adapter-kit` helpers, host-compat, hot-reload, packaging,
distribution, telemetry-hooks and a policy-sandbox. It ships reference adapters
(a text-file example plus Maya/Houdini/Cinema4D/Nuke/Substance/Resolve/
Figma/Photoshop-AfterEffects reference adapters built on the adapter kit with
injected fail-loud host-backend seams) exercising the contract.

### @bellona/remote-protocol

The canonical remote-control protocol package (`libs/bellona/remote-protocol`,
148 files, 180.C.03). It owns the typed contracts for the Phase-180 plane —
devices/ capabilities/adapters/permissions, sessions/participants/surfaces,
command envelopes (priority/timeout/risk/target), command
results/progress/errors/retry, and a large set of per-surface command modules
(`blender.ts`, `browser.ts`, `audio-track.ts`, `color-management.ts`,
audit-chain, actor-attribution, …). It also generates
JSON-Schema/OpenAPI/proto-manifest artifacts under `contracts/`. Gateway, host,
MCP, adapters and SDKs all import shapes from here rather than redefining them;
`index.ts` is a thin descriptor barrel over the per-module contracts.

### bellona-sdk-cpp

The Bellona C++ SDK (`libs/bellona/sdk-cpp`, project `bellona-sdk-cpp`). A real
CMake C++ library: a unified `bellona/bellona.hpp` umbrella header, a `Client`,
config/error/HTTP/types implementations under `src/`, and resource clients for
projects/assets/builds/exports/engines (both `.hpp` and `.cpp`), with example
programs (`basic_example.cpp`, `async_example.cpp`) and
`test_config`/`test_types` unit tests. It is the native-C++ client of the
Bellona platform/gateway API.

### bellona-sdk-python

The Bellona Remote Creative Control Plane Python SDK (`libs/bellona/sdk-python`,
project `bellona-sdk-python`, package `bellona-remote`, 180.C.29.05). A typed
Python client over the remote gateway covering all twelve operation families
(devices/sessions/commands/stream/approvals/artifacts/audit + blender/unreal/
browser/desktop/file): `client.py`, `transport.py`, `models.py`,
`compensating_actions.py`, with `py.typed` and a real pytest suite
(`test_client`, `test_http_transport`, `test_envelope_validity`). The five
adapter families build a fully validated `RemoteCommandEnvelope` that fails loud
client-side before any network call, mirroring `@bellona/remote-protocol`.

### @bellona/text-to-3d

Text/image-to-3D mesh generation (`libs/bellona/text-to-3d/src`, audit Phase
10.1). Real provider transports — `createMeshyTransport`, `createTripoTransport`
— speak the Meshy/Tripo REST contracts (submit → poll → download GLB) over an
injectable `fetch`, Bearer-authenticated, throwing `TextTo3dCredentialsError`
when no API key is present. `TextTo3dGenerator` drives a wired transport to real
GLB bytes (never empty; `EmptyMeshError`/`TextTo3dProviderNotConfiguredError`
otherwise), then the pipe parses GLB through `@bellona/interchange`, validates
with `@oshun/content-eval`, and authors a byte-valid `.uasset` via
`@bellona/unreal` on-box.

### @bellona/unity-agent

The Unity-native MCP foundation (`libs/bellona/unity-agent`, 464 files, Phase
71). Two parts: a thin TypeScript MCP client wrapper + batchmode launch-plan
helper (`src/`), and a real Unity Package Manager package at
`plugin/com.bellona.agent` implementing a C# MCP server — server
bootstrap/host/session, HTTP and stdio transport hosts, an attribute-driven tool
registry, async execution over `EditorApplication.update` with progress
notifications, multi-scene editing, serialized-property bridge, semantic
selection, build pipeline, permission policy and an execution audit log. It is
the Unity counterpart to `@bellona/mcp-gateway`'s agent surface.

### @bellona/unity

The Unity Engine adapter (`libs/bellona/unity/src`). A WebSocket `UnityBridge`
plus asset import/generation, multi-platform build automation, scene assembly,
C# code generation and project management. It additionally ships a real
Gaussian-splatting Unity package (`plugin/com.bellona.gaussian-splatting/`) with
a compute-shader sort, splat asset importer/renderer and HLSL shader, surfaced
through `src/gaussian-splatting/`. Live editor work runs inside Unity; the TS
side orchestrates it.

### @bellona/unreal

The Unreal Engine adapter (`libs/bellona/unreal`, 134 files) — the most complete
engine integration in the area. The TS side provides a Remote-Control-API
WebSocket `UnrealBridge`, version discovery, `.uproject` management, actor/
Blueprint/asset operations and a Linux cook container. The native side is a
real, compiled UE5 C++ editor plugin (`plugin/BellonaUnrealEditor/`) whose
~3900-line `BellonaCommandDispatcher.cpp` + author-commandlet authors `.uasset`s
(static-mesh/material/material-instance/blueprint), driven headlessly via the
`onbox/python/` commandlet scripts. This is the path `@bellona/text-to-3d` lands
generated meshes on.

### bellona-video

The video adapter (`libs/bellona/video/src`, package `@bellona/video`). Multi-
protocol capture (NDI/SDI/HDMI/USB/screen), output
(NDI/streaming/virtual-camera), and a processing pipeline (scaling, color
correction, compositing) with broadcast features (genlock, timecode, ancillary
data). It is the video counterpart to `bellona-audio` for
virtual-production/broadcast workflows; concrete I/O binds to real
capture/output backends at the device layer.

### @bellona/virtual-production

The virtual-production adapter (`libs/bellona/virtual-production/src`). Camera-
tracking integration (Ncam/Mo-Sys/OptiTrack/Vicon/Stype), LED-wall control and
calibration (nDisplay/Disguise/Brompton), ICVFX compositing config
(frustum/inner- frustum/chromakey/light-cards), genlock + timecode sync, and
multi-system coordination — with a real virtual-camera module
(`virtual-camera/index.ts` + tests). It coordinates the physical/virtual
elements of an LED-volume stage.

### bellona-xr

The cross-platform XR library (`libs/bellona/xr/src`, package `@bellona/xr`).
Supports visionOS (Apple Vision Pro), Meta Quest and WebXR with session
management, hand/eye tracking, spatial anchors, scene understanding, hit testing
and spatial audio. The `spatial-ar/` sub-area is the most developed — real,
test-covered modules for world-scale spatial mapping, a visual positioning
system, and persistent AR content anchoring — alongside the `quest/` and
`visionos/` platform modules.