bellona library

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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.

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.

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.

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.

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 .uassets (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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.