Bellona is Oshun's build and integration platform, handling engine adapters, asset export, and runtime systems for game engines and creative tools.
Overview#
| Aspect | Description |
|---|---|
| Domain | Build & Integration |
| Scope Tag | scope:bellona |
| API Port | 4005 |
| Database Schema | bellona |
Capabilities#
- Engine Adapters: Godot, Unreal, Unity, Blender integration
- Asset Export: Format conversion and optimization
- Runtime Systems: In-game systems and middleware
- OpenUSD Support: Universal Scene Description pipeline
- Motion Capture: MoCap data processing
- Virtual Production: Real-time production tools
- XR Integration: VR/AR/MR support
Libraries#
text
libs/bellona/
├── client/ # TypeScript client for other domains
├── database/ # Prisma schema & utilities
├── bridge-core/ # Core bridge infrastructure
├── adapters/ # Engine adapter interface
├── godot/ # Godot engine adapter
├── unreal/ # Unreal Engine adapter
├── unity/ # Unity adapter
├── blender/ # Blender integration
├── houdini/ # Houdini procedural tools
├── davinci/ # DaVinci Resolve
├── metahuman/ # MetaHuman pipeline
├── mocap/ # Motion capture
├── interchange/ # Asset interchange
├── interchange-models/ # Interchange schemas
├── openusd/ # OpenUSD support
├── xr/ # XR/VR integration
├── virtual-production/ # VP tools
├── gameplay-systems/ # Runtime systems
├── audio/ # Audio processing
├── video/ # Video processing
├── 3d-generation/ # 3D output handling
├── sdk-cpp/ # C++ SDK for engines
├── integration/ # Service integration
└── event-handlers/ # Event subscriptions
Quick Start#
Using the Client#
typescript
import { createBellonaClient } from '@bellona/client';
const bellona = createBellonaClient({
baseUrl: process.env.BELLONA_API_URL || 'http://localhost:4005',
});
// Create an export job
const exportJob = await bellona.exports.create({
projectId: 'proj-123',
engine: 'godot',
version: '4.2',
format: 'gltf',
options: {
includeAnimations: true,
lodLevels: [1.0, 0.5, 0.25],
textureSize: 2048,
},
});
// Monitor progress
bellona.exports.onProgress(exportJob.id, (progress) => {
console.log(`Export: ${progress.stage} - ${progress.percent}%`);
});
// Get artifacts when complete
const result = await bellona.exports.waitForCompletion(exportJob.id);
console.log(`Download: ${result.downloadUrl}`);
Running Locally#
bash
# Start Bellona API
nx serve bellona-api
# Run tests
nx test @bellona/client
# Build all Bellona libraries
nx run-many --target=build --projects=tag:scope:bellona
API Endpoints#
| Method | Endpoint | 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 package |
| POST | /v1/builds |
Create build |
| GET | /v1/builds/:id |
Get build status |
| GET | /v1/engines |
List supported engines |
| POST | /v1/convert |
Convert asset format |
Events#
| Event | Description |
|---|---|
bellona.export.started |
Export job started |
bellona.export.progress |
Export progress update |
bellona.export.completed |
Export finished |
bellona.export.failed |
Export failed |
bellona.build.started |
Build started |
bellona.build.completed |
Build finished |
bellona.artifact.ready |
Artifact available |
Supported Engines#
| Engine | Versions | Formats | Status |
|---|---|---|---|
| Godot | 4.0 - 4.2 | GLTF, TRES, GDScript | Stable |
| Unreal | 5.0 - 5.3 | FBX, Blueprint | Stable |
| Unity | 2022 - 2023 | FBX, Prefab | Stable |
| Blender | 3.6 - 4.0 | GLTF, FBX, Blend | Stable |
| Houdini | 19.5+ | HDA, USD | Beta |
Configuration#
bash
# Required
BELLONA_DATABASE_URL=postgresql://...?schema=bellona
REDIS_URL=redis://localhost:6379
# Storage
ARTIFACT_BUCKET=oshun-artifacts
ARTIFACT_CDN_URL=https://artifacts.oshun.io
# Worker
EXPORT_WORKER_CONCURRENCY=4
MAX_EXPORT_SIZE_MB=500
Export Options#
typescript
interface ExportOptions {
// Asset settings
includeTextures?: boolean;
textureFormat?: 'png' | 'jpg' | 'webp' | 'ktx2';
textureSize?: 512 | 1024 | 2048 | 4096;
// Mesh settings
meshFormat?: 'gltf' | 'fbx' | 'obj' | 'usd';
lodLevels?: number[];
optimizeMeshes?: boolean;
// Animation
includeAnimations?: boolean;
animationFormat?: 'native' | 'bvh' | 'fbx';
// Project
generateProjectFile?: boolean;
includeScripts?: boolean;
preserveHierarchy?: boolean;
}
Local Development#
Start the full development environment:
bash
# Start infrastructure (PostgreSQL, Redis, MinIO)
docker compose -f docker/docker-compose.dev.yml up -d
# Run database migrations
pnpm nx run @bellona/database:prisma:migrate:dev
# Start the Build Worker
pnpm nx serve bellona-build-worker
See CLAUDE.md for detailed local development setup.