Bellona - Build and Bridge Platform
Bellona handles engine adapters, asset export, build systems, and runtime
integrations for game engines and creative tools. It bridges the Oshun ecosystem
with Unity, Unreal Engine, Godot, Blender, and Houdini via real-time WebSocket
connections, asset interchange pipelines, and content-addressable build caching.
Architecture#
Apps (8)#
App
Port
Purpose
build-api
4005
Build system API with Redis-backed caching (100MB memory, 10GB max), event bus integration, and build/export queue adapters
build-worker
-
Poll-based worker processing 4 job types: asset-bake, validate, engine-project-generate, export-package
render-api
-
Redis-backed render cache with health checks, exports RenderCacheService, OutputValidator, GpuRenderQueue
cli
-
Commander.js CLI with build, export, sync, config, health, project, detect commands
bridge-unity
9004
WebSocket bridge for Unity with 14 engine-specific commands
bridge-unreal
9003
WebSocket bridge for Unreal Engine with 11 engine-specific commands
bridge-godot
9002
WebSocket bridge for Godot with 9 engine-specific commands
bridge-blender
9001
WebSocket bridge for Blender with 6 commands and cross-domain event publishing
Libraries (24)#
Core:
Library
Key Exports
@bellona/client
BellonaClient SDK (~519 lines) with build, export, and engine sync operations
@bellona/database
Prisma schema (674 lines, 11 models) for builds, exports, sessions, and caching
@bellona/bridge-core
BridgeServer/BridgeClient (~944 lines): WebSocket framework with typed events, command routing, message encoding, heartbeat, reconnection
@bellona/adapters
BaseBridge, CommandQueue, StateManager, ProcessLauncher, VersionManager for engine adapter infrastructure
@bellona/interchange
InterchangeManager (~990 lines) with FormatRegistry (GLTF/USD/FBX), JobManager, AssetCache, transform/validation pipelines
@bellona/interchange-models
Interchange data schemas for cross-format asset representation
@bellona/integration
HathorArtifactConsumer, LoreToEngineCompiler, IsisAssetConsumer, AssetConverter for cross-domain integration
Engine Integrations:
Library
Purpose
@bellona/godot
Godot 4.0-4.2 (GLTF, TRES, GDScript)
@bellona/unreal
Unreal 5.0-5.3 (FBX, Blueprint)
@bellona/unity
Unity 2022-2023 (FBX, Prefab)
@bellona/blender
Blender 3.6-4.0 (GLTF, FBX, Blend)
@bellona/houdini
Houdini 19.5+ (HDA, USD) - Beta
@bellona/davinci
DaVinci Resolve integration
@bellona/openusd
OpenUSD/USD support
Specialized:
Library
Purpose
@bellona/metahuman
MetaHuman pipeline for digital humans
@bellona/mocap
Motion capture data processing and retargeting
@bellona/xr
VR/AR/MR support (OpenXR integration)
@bellona/virtual-production
Real-time virtual production workflows
@bellona/gameplay-systems
Runtime gameplay systems (physics, AI, networking)
@bellona/audio
Audio processing and spatial audio
@bellona/video
Video processing and encoding
@bellona/sdk-cpp
C++ SDK for native engine integration
@bellona/event-handlers
Cross-domain event subscriptions (~349 lines): subscribes to hathor.world.published, isis.asset.generated, yemaya.build.requested, yemaya.export.requested
@bellona/event-publisher
Typed event publishing for session, build, and export events
Technology Stack#
Layer
Technologies
Framework
Hono
Database
PostgreSQL with Prisma ORM (schema: bellona)
Build Cache
Content-addressable caching via Redis (100MB memory, 10GB max)
Bridges
WebSocket (ports 9001-9004)
Native SDK
C++ via @bellona/sdk-cpp
Events
@oshun/event-bus (Redis Streams, bellona source domain, 24h TTL, exponential retry)
Caching
@oshun/cache (Redis-backed)
Logging
@oshun/logging (Pino-based structured logging)
Build
@nx/js:tsc
Testing
Vitest
Database Schema#
11 models in libs/bellona/database/prisma/schema.prisma (674 lines):
Model
Table
Purpose
Build
builds
Build job tracking with status and optimization levels
BuildArtifact
build_artifacts
Build output files and checksums
BuildLog
build_logs
Debug, info, warning, and error logs
ExportJob
export_jobs
Format conversion and artifact management
EngineProject
engine_projects
Engine-specific project configurations
BridgeSession
bridge_sessions
Active WebSocket bridge session tracking
SyncConflict
sync_conflicts
Engine sync conflict resolution records
BuildWorker
build_workers
Worker registration and capability reporting
AssetCache
asset_cache
Content-addressable build artifact caching
BuildTemplate
build_templates
Reusable build configuration templates
AuditLog
audit_log
Operation audit trail
WINDOWS, MACOS, LINUX, IOS, ANDROID, WEBGL, PLAYSTATION, XBOX,
SWITCH
ZIP, TAR_GZ, UNITYPACKAGE, UASSET, GODOT_PCK
API Endpoints#
Base URL: http://localhost:4005
Exports#
Method
Path
Description
POST
/v1/exports
Create export job
GET
/v1/exports/:id
Get export status
GET
/v1/exports/:id/artifacts
List artifacts
GET
/v1/exports/:id/download
Download artifacts
Builds#
Method
Path
Description
POST
/v1/builds
Create build
GET
/v1/builds/:id
Get build status
Engines#
Method
Path
Description
GET
/v1/engines
List supported engines
Conversion#
Method
Path
Description
POST
/v1/convert
Asset format conversion
WebSocket Bridges#
Port
Engine
Commands
9001
Blender
6 commands (import, export, render, scene sync, material sync, session management)
9002
Godot
9 commands (scene import/export, node management, resource sync, project management)
9003
Unreal
11 commands (level management, blueprint sync, material sync, build, packaging)
9004
Unity
14 commands (prefab sync, scene management, asset import, material sync, build pipeline)
Engine Support Matrix#
Engine
Versions
Import Formats
Bridge Port
Status
Godot
4.0-4.2
GLTF, TRES, GDScript
9002
Stable
Unreal
5.0-5.3
FBX, Blueprint
9003
Stable
Unity
2022-2023
FBX, Prefab
9004
Stable
Blender
3.6-4.0
GLTF, FBX, Blend
9001
Stable
Houdini
19.5+
HDA, USD
-
Beta
Cross-Domain Integration#
Events Consumed#
Source Event
Handler
hathor.world.published
Triggers asset export for published worlds
isis.asset.generated
Imports AI-generated assets into engine projects
yemaya.build.requested
Initiates build jobs from creative studio requests
yemaya.export.requested
Starts export pipelines for studio output
Events Published#
bellona.session.started / bellona.session.ended - Bridge session lifecycle
bellona.build.started / bellona.build.completed / bellona.build.failed -
Build pipeline events
bellona.export.completed - Export artifact availability
Environment Variables#
bash Copy
BELLONA_DATABASE_URL=postgresql://oshun:oshun_dev@localhost:5432/bellona
REDIS_URL=redis://localhost:6379
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
Development#
bash Copy
# Start infrastructure
docker compose -f docker/docker-compose.dev.yml up -d
# Run the build API
pnpm nx dev @bellona/build-api
# Run a specific bridge (e.g., Godot)
pnpm nx dev @bellona/bridge-godot
# Run tests
pnpm nx test @bellona/client
pnpm nx test @bellona/bridge-core
pnpm nx test @bellona/interchange
# Build all Bellona libraries
pnpm nx run-many --target=build --projects=tag:scope:bellona
# Run database migrations
pnpm nx run @bellona/database:prisma:migrate
pnpm nx run @bellona/database:prisma:generate
CI/CD#
Bellona uses the core CI pipeline (ci.yml) and the general ECS deployment
pipeline (deploy-ecs.yml). Database migrations run via database.yml.