# @bellona - Build & Bridge Platform

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

```
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](/CLAUDE.md) for detailed local development setup.

## Related Documentation

- [API Reference](/docs/api/bellona/)
- [Engine Integration Guide](/docs/guides/engine-integration.md)
- [Asset Pipeline](/docs/guides/asset-pipeline.md)
- [Cross-Domain Integration](/docs/guides/cross-domain-integration.md)
