Eve library

Bellona Domain

Guide

Revision 1

On this page

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

Supported Platforms#

WINDOWS, MACOS, LINUX, IOS, ANDROID, WEBGL, PLAYSTATION, XBOX, SWITCH

Export Formats#

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