Eve library

@bellona - Build & Bridge Platform

Other

Revision 1

On this page

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.