# Yemaya Feature Documentation

Comprehensive documentation of Yemaya platform features.

## Table of Contents

- [Pre-Production Suite](#pre-production-suite)
- [Asset Management](#asset-management)
- [AI Agents](#ai-agents)
- [Engine Integrations](#engine-integrations)
- [Real-time Collaboration](#real-time-collaboration)
- [Audio & Video](#audio--video)
- [XR & Spatial Computing](#xr--spatial-computing)

---

## Pre-Production Suite

The Pre-Production Suite provides tools for the creative development phase of
film and game projects.

### Yemaya Writer (Scriptwriting)

Professional screenwriting editor with industry-standard features.

#### Fountain Format Support

Write scripts using Fountain markup language with automatic formatting:

```fountain
INT. COFFEE SHOP - DAY

SARAH, 30s, sits alone at a corner table. She stares at her phone.

SARAH
(muttering)
Why won't he call?

The BELL above the door JINGLES. DAVID, 40s, enters.

DAVID
Sorry I'm late.

SARAH
Three hours, David. Three hours.
```

Features:

- Real-time syntax highlighting
- Auto-formatting for scene headings, action, dialogue
- Character name auto-completion
- Dual dialogue support
- Scene numbering
- Revision tracking with colored pages

#### Story Structure Analysis

Built-in templates for narrative structure:

| Structure      | Description                     |
| -------------- | ------------------------------- |
| 3-Act          | Classic beginning, middle, end  |
| 4-Act          | Television format with midpoint |
| Hero's Journey | 12-stage mythological structure |
| Save the Cat   | Blake Snyder's beat sheet       |
| Kishōtenketsu  | Japanese 4-act structure        |

The analyzer provides:

- Beat alignment visualization
- Pacing analysis
- AI-powered structure suggestions
- Custom structure builder

#### Character Bible

Comprehensive character management:

- **Profile Editor**: Name, age, description, backstory
- **Relationship Mapper**: Visual graph of character connections
- **Arc Tracker**: Character development across the story
- **Personality System**: MBTI, Big Five, custom traits
- **Dialogue Style Guide**: Voice consistency rules
- **AI Character Generation**: Create characters from prompts

#### World Bible

World-building documentation system:

- Geography and location editor with maps
- Historical timeline management
- Culture and society documentation
- Magic/technology system rules
- Political faction tracker
- Lore consistency checker
- AI world generation

### Concept Art & Design

#### Mood Board Generator

Create visual references for your project:

- Drag-and-drop canvas
- Web image search integration
- AI image generation (FLUX, Midjourney, DALL-E)
- Color palette extraction
- Templates and export options

#### Character Designer

Design characters with multiple views:

- 2D character sheet canvas
- Front/side/back view templates
- AI concept generation from descriptions
- Style transfer between references
- Turnaround and expression sheet generators
- Export for 3D modeling reference

#### Environment Concepting

Environment design tools:

- Layered canvas with perspective guides
- AI panorama generation
- Color script integration
- Time-of-day variations
- Callout annotations

### Storyboarding & Animatics

#### Storyboard Canvas

Create frame-by-frame storyboards:

- Drawing tools (brush, pencil, shapes)
- Layer system
- Aspect ratio templates (16:9, 2.39:1, etc.)
- Camera movement indicators
- Action lines and arrows
- AI shot composition suggestions

#### Animatic Editor

Turn storyboards into timed sequences:

- Timeline interface
- Frame duration controls
- Transitions between frames
- Scratch audio recording
- AI timing suggestions
- Export to video/EDL/XML

#### Camera Planner

Plan virtual camera movements:

- 3D camera path visualization
- Dolly, pan, tilt, crane presets
- Focus pull planning
- Lens selection calculator
- Export to Unreal/Blender

### Production Planning

#### Scheduling Engine

- Gantt chart and calendar views
- Task dependencies
- Milestone tracking
- Resource allocation
- AI schedule optimization
- Critical path analysis

#### Budget Calculator

- Industry-standard templates
- Line item editor
- Historical cost database
- AI cost prediction
- Variance analysis
- Multi-currency support

#### Cast/Crew Management

- Contact database with skill tagging
- Availability calendars
- Call sheet generator
- Contract management
- AI skill matching

#### Location Scout

- Location database with photos/videos
- Map integration
- Requirements checklists
- Permit tracking
- Weather data
- AI location suggestions

---

## Asset Management

Comprehensive digital asset management for production workflows.

### Asset Storage

#### File Organization

Assets are organized in projects with folder hierarchies:

```
project/
├── characters/
│   ├── hero/
│   │   ├── model.fbx
│   │   ├── textures/
│   │   └── animations/
│   └── npc/
├── environments/
├── props/
├── audio/
└── documents/
```

#### Supported Formats

| Category  | Formats                           |
| --------- | --------------------------------- |
| 3D Models | FBX, glTF, GLB, OBJ, USD, Alembic |
| Textures  | PNG, JPG, EXR, TGA, PSD           |
| Audio     | WAV, MP3, OGG, FLAC               |
| Video     | MP4, MOV, ProRes                  |
| Documents | PDF, Fountain, FDX                |

#### Upload Methods

- Direct browser upload
- Presigned URL for large files
- CLI tool for batch uploads
- Engine plugin sync

### Version Control

#### Asset Versioning

Every asset maintains version history:

- Automatic versioning on upload
- Changelog per version
- Rollback to any version
- Visual diff for images
- 3D model comparison

#### File Locking

Prevent conflicts with file locks:

```bash
# Lock a file
yemaya asset lock project_abc/characters/hero.fbx

# Check lock status
yemaya asset status hero.fbx

# Unlock when done
yemaya asset unlock project_abc/characters/hero.fbx
```

### Asset Processing

#### Automatic Processing

On upload, assets are automatically processed:

- **Thumbnails**: Generated for preview
- **Proxies**: Lower-res versions for streaming
- **Metadata**: Extracted technical information
- **Validation**: Format and integrity checks

#### Manual Processing

Trigger additional processing:

- LOD generation from high-poly models
- Texture optimization and compression
- Audio normalization
- Video transcoding

### Search & Discovery

#### Full-Text Search

Search across all asset metadata:

```
model hero sword animation
```

#### Filters

Narrow results with filters:

- Asset type (model, texture, audio, etc.)
- File format
- Date range
- Tags
- Folder location
- Owner

#### Smart Collections

Dynamic collections based on rules:

- All assets modified this week
- Textures larger than 4K
- Unused assets
- Assets pending review

---

## AI Agents

Multi-agent system for automated creative tasks.

### Agent Types

#### Story Director

Oversees narrative consistency:

- Reviews scripts for plot holes
- Suggests story improvements
- Maintains continuity across scenes
- Coordinates other creative agents

#### Character Writer

Creates and develops characters:

- Generates character profiles from prompts
- Writes character-specific dialogue
- Maintains voice consistency
- Suggests character arcs

#### World Builder

Designs fictional worlds:

- Generates world lore
- Creates consistent rules and systems
- Builds interconnected locations
- Maintains world bible

#### Concept Artist (Prompt Generator)

Creates visual concept prompts:

- Generates image prompts from descriptions
- Maintains style consistency
- Creates character and environment concepts
- Works with AI image generators

#### 3D Modeler

Orchestrates 3D asset creation:

- Generates modeling instructions
- Coordinates with AI 3D generation APIs
- Reviews and refines results
- Manages asset quality

#### Animator

Plans and creates animations:

- Generates animation descriptions
- Creates keyframe suggestions
- Reviews motion quality
- Coordinates with mocap data

### Agent Configuration

Configure agent behavior:

```yaml
# agent-config.yaml
story_director:
  model: claude-opus-4
  temperature: 0.7
  max_tokens: 4000

  guidelines:
    - Maintain narrative coherence
    - Respect existing world rules
    - Suggest, don't override

  permissions:
    can_edit_script: false
    can_suggest_changes: true
    can_approve_content: false
```

### Human-AI Collaboration Modes

| Mode       | Description                           |
| ---------- | ------------------------------------- |
| Manual     | Human does everything, AI inactive    |
| AI-Tool    | AI provides suggestions on request    |
| AI-Partner | AI actively assists, human approves   |
| AI-Lead    | AI creates, human reviews and adjusts |

### Approval Gates

Critical actions require human approval:

- Script changes
- Final asset approval
- Character design signoff
- Publishing decisions

Configure gates per project:

```typescript
const project = await createProject({
  name: 'My Film',
  agentSettings: {
    approvalGates: {
      scriptChanges: 'required',
      assetCreation: 'notify',
      characterDesign: 'required',
    },
  },
});
```

---

## Engine Integrations

Deep integration with game and DCC tools.

### Blender Integration

#### Connection Methods

1. **Addon**: Install the Yemaya Blender addon
2. **WebSocket**: Real-time communication
3. **Command Queue**: Batched operations
4. **Headless Mode**: Background processing

#### Supported Operations

**Modeling:**

- Primitive creation
- Mesh editing (extrude, bevel, boolean)
- Modifier management
- UV mapping
- Geometry Nodes

**Animation:**

- Keyframe management
- Armature manipulation
- Shape keys
- NLA operations
- Motion paths

**Rendering:**

- Cycles/EEVEE settings
- Render queue management
- Compositing nodes
- Output configuration

#### Example Usage

```typescript
import { blender } from '@yemaya/blender';

// Connect to running Blender instance
await blender.connect('ws://localhost:9876');

// Create a mesh
const mesh = await blender.mesh.create({
  type: 'cube',
  size: 2,
  location: [0, 0, 1],
});

// Apply modifier
await blender.modifier.add(mesh.id, {
  type: 'BEVEL',
  width: 0.1,
  segments: 3,
});

// Export
await blender.export.gltf({
  objects: [mesh.id],
  path: '/output/cube.glb',
});
```

### Godot Integration

#### GDExtension Plugin

Install the Yemaya GDExtension for Godot 4.x:

```
res://addons/yemaya/
├── yemaya.gdextension
├── bin/
└── scripts/
```

#### Scene Management

```gdscript
# Connect to Yemaya
var yemaya = Yemaya.connect("localhost:3000", api_key)

# Sync project assets
var assets = await yemaya.project.sync_assets()

# Load asset into scene
var character = await yemaya.assets.instantiate("char_hero_001")
add_child(character)

# Push changes back
await yemaya.scene.save()
```

#### Features

- Scene tree synchronization
- Asset import pipeline
- Script generation
- Collision shape generation
- TileMap support
- Animation automation

### Unreal Engine Integration

#### Plugin Installation

1. Copy plugin to `Plugins/Yemaya/`
2. Enable in Plugin settings
3. Configure API connection

#### Blueprint Integration

Access Yemaya from Blueprints:

- YemayaLoadAsset
- YemayaSaveAsset
- YemayaSyncProject
- YemayaGenerateWith AI

#### C++ API

```cpp
// Load asset from Yemaya
UYemayaSubsystem* Yemaya = GetGameInstance()->GetSubsystem<UYemayaSubsystem>();
UYemayaAsset* Asset = Yemaya->LoadAsset(AssetId);

// Apply to actor
Asset->ApplyToActor(TargetActor);

// Sync changes
Yemaya->PushChanges();
```

#### Features

- Nanite mesh import
- Material conversion
- Sequencer automation
- PCG integration
- nDisplay support
- MetaHuman integration

---

## Real-time Collaboration

Work together in real-time across all tools.

### Presence System

See who's working on what:

- User cursors and selections
- Active tool indicators
- Online/offline status
- Activity feed

### Document Sync

All documents use CRDT-based synchronization:

- Scripts
- Storyboards
- Notes
- Comments

#### Conflict Resolution

Automatic merge of concurrent edits:

```
User A types: "Hello World"
User B types: "Hello Everyone"

Result: "Hello WorldEveryone" or based on cursor position
```

### Review & Feedback

#### Comments

Add comments to any asset or document:

- Threaded discussions
- @mentions for notifications
- Resolution tracking
- Pin to specific locations

#### Annotations

Draw annotations on:

- Images
- Videos (with timestamp)
- 3D models (with camera position)
- Documents

### Change Tracking

Every change is tracked:

```json
{
  "id": "change_abc123",
  "type": "asset.updated",
  "user": { "id": "usr_123", "name": "Jane" },
  "timestamp": "2024-01-15T10:30:00Z",
  "changes": {
    "name": { "from": "hero_v1", "to": "hero_v2" }
  }
}
```

---

## Audio & Video

Production audio and video tools.

### Ardour Integration

Professional audio workstation integration:

- Session control via OSC
- Track creation and routing
- Plugin management
- Export automation

### AI Audio Generation

#### Music Generation

Generate music with AI:

```typescript
const music = await ai.music.generate({
  prompt: 'Epic orchestral battle theme, 120 BPM',
  duration: 60,
  style: 'cinematic',
});
```

Supported providers:

- Suno
- Udio
- Stable Audio

#### Voice Generation

Generate character voices:

```typescript
const voice = await ai.voice.generate({
  text: 'Welcome to the kingdom, brave adventurer.',
  voice: 'medieval_male_01',
  emotion: 'welcoming',
});
```

Features:

- Voice cloning
- Emotional control
- Batch processing
- Real-time preview

### DaVinci Resolve Integration

Connect to DaVinci Resolve for:

- Timeline import/export
- Media synchronization
- Render queue
- Color grading presets
- AI features (IntelliScript, Magic Mask)

### AI Video Generation

Generate video clips with AI:

```typescript
const video = await ai.video.generate({
  prompt: 'A spaceship flying through an asteroid field',
  referenceImage: 'scene_concept.png',
  duration: 5,
  aspectRatio: '16:9',
  cameraMove: 'dolly_forward',
});
```

Supported providers:

- Runway Gen-4
- Kling AI
- Pika
- Luma Ray2
- Google Veo

---

## XR & Spatial Computing

Tools for immersive experiences.

### Apple Vision Pro

Build spatial experiences:

- SwiftUI spatial components
- RealityKit content pipeline
- Hand tracking
- Eye tracking analytics
- Spatial audio

### Meta Quest

OpenXR integration:

- Hand tracking
- Passthrough AR
- Controller mapping
- Guardian system

### Volumetric Content

#### 3D Gaussian Splatting

Capture and render volumetric content:

```typescript
// Process video for splat generation
const splat = await volumetric.process({
  videoPath: 'capture.mp4',
  quality: 'high',
  outputFormat: 'spz',
});

// Render in real-time
viewer.load(splat);
```

#### NeRF Pipeline

Neural Radiance Fields processing:

- Video preprocessing
- Training pipeline
- Export to game engines
- Streaming support

### Virtual Production

#### nDisplay

Multi-display LED wall setup:

- Cluster configuration
- Viewport calibration
- Color calibration

#### Camera Tracking

Integrate tracking systems:

- Vicon
- OptiTrack
- HTC Vive Trackers
- iPhone/iPad

#### LiveLink

Real-time motion capture:

- Skeletal retargeting
- Facial capture
- Prop tracking
- Latency compensation

---

## Further Reading

- [Getting Started Guide](../getting-started/README.md)
- [API Reference](../api/README.md)
- [Architecture Overview](../architecture/README.md)
- [Tutorial Series](../tutorials/README.md)
