# Yemaya Tutorials

Step-by-step tutorials to help you master the Yemaya platform.

## Getting Started Tutorials

### 1. Creating Your First Project

Learn the basics of creating and configuring a project.

**Time:** 10 minutes **Difficulty:** Beginner

#### Step 1: Create a New Project

1. Log in to Yemaya web app or desktop application
2. Click "New Project" in the dashboard
3. Choose a project type:
   - **Film** - For movies and video content
   - **Game** - For video game development
   - **Animation** - For animated content
   - **Mixed** - For multimedia projects

#### Step 2: Configure Project Settings

Fill in the project details:

```
Name: My First Project
Description: Learning the Yemaya platform
Visibility: Private
```

Advanced settings (optional):

- Target platforms (PC, console, mobile)
- Game engine (Godot, Unreal)
- Collaboration settings

#### Step 3: Set Up Folders

Organize your project with folders:

```
my-first-project/
├── 01-preproduction/
│   ├── scripts/
│   ├── concepts/
│   └── storyboards/
├── 02-assets/
│   ├── characters/
│   ├── environments/
│   └── props/
└── 03-production/
```

#### Step 4: Invite Team Members

1. Go to Project Settings > Team
2. Click "Invite Member"
3. Enter email address and select role
4. Send invitation

**Roles:**

- **Owner** - Full access
- **Admin** - Manage team and settings
- **Editor** - Create and edit content
- **Viewer** - Read-only access

---

### 2. Writing Your First Script

Use Yemaya Writer to create a screenplay.

**Time:** 20 minutes **Difficulty:** Beginner

#### Step 1: Open the Script Editor

1. Navigate to your project
2. Go to Pre-Production > Scripts
3. Click "New Script"

#### Step 2: Learn Fountain Formatting

Fountain is a plain-text format for screenplays:

```fountain
# ACT ONE

INT. APARTMENT - MORNING

ALEX, 25, stumbles out of bed, hair disheveled.

ALEX
(yawning)
Monday again.

She checks her phone. Her eyes widen.

ALEX (CONT'D)
Fifty missed calls?

CUT TO:
```

**Quick Reference:**

- Scene headings: `INT.` or `EXT.` at line start
- Character names: ALL CAPS before dialogue
- Parentheticals: In parentheses under character name
- Transitions: End with `TO:` (right-aligned)
- Action: Regular text

#### Step 3: Use Auto-Completion

As you type:

- Character names auto-complete after first use
- Scene headings suggest locations
- Transitions appear in dropdown

#### Step 4: Apply Story Structure

1. Click "Structure" in toolbar
2. Select "Save the Cat Beat Sheet"
3. Map your scenes to beats:
   - Opening Image (p.1)
   - Theme Stated (p.5)
   - Set-Up (p.1-10)
   - Catalyst (p.12)
   - And so on...

#### Step 5: Export Your Script

Export options:

- **PDF** - Industry-standard formatting
- **Fountain** - Plain text
- **FDX** - Final Draft format
- **HTML** - Web viewing

---

### 3. Working with Assets

Upload, organize, and manage project assets.

**Time:** 15 minutes **Difficulty:** Beginner

#### Step 1: Upload Assets

**Method 1: Drag and Drop**

1. Navigate to Assets in your project
2. Drag files onto the browser window
3. Wait for upload and processing

**Method 2: Upload Button**

1. Click "Upload" button
2. Select files
3. Choose destination folder
4. Click "Start Upload"

**Method 3: CLI (for large files)**

```bash
yemaya upload ./models/character.fbx \
  --project proj_abc123 \
  --folder characters/hero
```

#### Step 2: Organize with Folders

Create a logical folder structure:

```bash
# Create folders via CLI
yemaya folder create characters/hero
yemaya folder create characters/npcs
yemaya folder create environments/levels
```

Or use the web interface to create and rename folders.

#### Step 3: Add Metadata

Select an asset and add:

- **Tags**: Keywords for search (e.g., "hero", "main character", "rigged")
- **Description**: What the asset is and how it's used
- **Custom Fields**: Project-specific metadata

#### Step 4: Version Assets

When updating an asset:

1. Click the asset
2. Click "Upload New Version"
3. Select the new file
4. Add changelog notes
5. Upload

Previous versions remain accessible in version history.

#### Step 5: Share Assets

Generate share links:

1. Right-click asset
2. Select "Share"
3. Choose expiration time
4. Copy link

---

## Intermediate Tutorials

### 4. Blender Integration

Connect Blender to your Yemaya project.

**Time:** 30 minutes **Difficulty:** Intermediate

#### Step 1: Install the Addon

1. Download the Yemaya Blender addon
2. In Blender: Edit > Preferences > Add-ons
3. Click "Install" and select the downloaded file
4. Enable "Yemaya Bridge"

#### Step 2: Configure Connection

1. In the addon preferences, enter:
   - API URL: `https://api.yemaya.io`
   - API Key: Your API key from Yemaya settings
2. Click "Test Connection"
3. Select your project from the dropdown

#### Step 3: Sync Assets

```
Yemaya panel (in Sidebar) > Sync
```

This syncs:

- Downloads project assets to local cache
- Shows assets available in project
- Enables one-click import

#### Step 4: Import Assets

1. Browse assets in the Yemaya panel
2. Click an asset to preview
3. Click "Import" to add to scene
4. Asset appears in your Blender scene

#### Step 5: Export to Yemaya

After making changes:

1. Select objects to export
2. Click "Export to Yemaya" in panel
3. Configure export settings:
   - Format: glTF, FBX, USD
   - Include animations: Yes/No
   - Destination folder
4. Click "Export"

The asset is uploaded and versioned automatically.

#### Step 6: Automated Workflows

Set up automation:

```python
# Blender script for automated export
import bpy
import yemaya

# Connect to Yemaya
client = yemaya.BlenderClient()
client.connect()

# Export all mesh objects
for obj in bpy.data.objects:
    if obj.type == 'MESH':
        client.export_asset(obj, folder='exported')
```

---

### 5. AI-Assisted Character Creation

Use AI agents to help create game characters.

**Time:** 45 minutes **Difficulty:** Intermediate

#### Step 1: Start a Character Session

1. Go to AI Studio in your project
2. Click "New Session"
3. Select "Character Creator" workflow

#### Step 2: Describe Your Character

Provide a detailed description:

```
Create a main character for a fantasy RPG:
- Female warrior, late 20s
- Scarred veteran of many battles
- Wields a two-handed sword
- Wears practical, battle-worn armor
- Personality: Stoic but compassionate
- Name: Kira Blackwood
```

#### Step 3: Generate Character Profile

The AI creates:

- Full character biography
- Personality traits (MBTI: ISTJ)
- Backstory
- Key relationships
- Character arc suggestions
- Visual description

Review and edit as needed.

#### Step 4: Generate Concept Art

1. Click "Generate Visual Concepts"
2. The AI creates image prompts
3. Select style preferences:
   - Art style: Realistic, stylized, anime
   - Pose: Standing, action, portrait
   - Lighting: Dramatic, natural, moody
4. Generate images

Review results and select favorites.

#### Step 5: Refine Designs

Iterate on chosen concepts:

```
Prompt refinement:
- Make armor more worn and battle-damaged
- Add subtle scars on left cheek
- Sword should have a distinctive hilt design
```

#### Step 6: Generate 3D Model

1. Select final concept image
2. Click "Generate 3D Model"
3. Choose generation settings:
   - Quality: Draft, Standard, High
   - Topology: Game-ready, High-poly
   - Include textures: Yes
4. Generate and wait for processing

#### Step 7: Review and Refine

The generated model may need refinement:

1. Download to Blender
2. Clean up topology
3. Add details manually
4. Re-upload as final version

---

### 6. Setting Up Real-time Collaboration

Enable team collaboration on your project.

**Time:** 20 minutes **Difficulty:** Intermediate

#### Step 1: Enable Collaboration Features

1. Project Settings > Collaboration
2. Enable "Real-time Sync"
3. Configure options:
   - Auto-save interval: 30 seconds
   - Show cursor positions: Yes
   - Activity notifications: Yes

#### Step 2: Set Up Presence

Team members now see:

- Who's online
- What they're working on
- Active selections

#### Step 3: Create Review Sessions

1. Go to Reviews > New Session
2. Select content to review:
   - Scripts
   - Storyboards
   - Assets
   - Videos
3. Invite reviewers
4. Set deadline

#### Step 4: Add Comments and Annotations

During review:

- Click anywhere to add comment
- Draw annotations on images
- Add timestamps to video comments
- @mention team members

#### Step 5: Track Changes

View change history:

1. Go to History tab
2. Filter by:
   - User
   - Date range
   - Content type
3. Click any change to see details
4. Restore previous versions if needed

---

## Advanced Tutorials

### 7. Building Custom Pipelines

Create automated production pipelines.

**Time:** 60 minutes **Difficulty:** Advanced

#### Step 1: Understand Pipeline Components

A pipeline consists of:

- **Triggers**: What starts the pipeline
- **Steps**: Actions to perform
- **Conditions**: Logic for branching
- **Outputs**: Results and artifacts

#### Step 2: Create a Simple Pipeline

Example: Auto-process uploaded textures

```yaml
# pipeline.yaml
name: Texture Processing
trigger:
  event: asset.uploaded
  filters:
    type: texture
    folder: raw-textures/*

steps:
  - name: Generate Mipmaps
    action: image.generate_mipmaps
    input: ${{ trigger.asset }}

  - name: Create Compressed Version
    action: image.compress
    input: ${{ steps.generate_mipmaps.output }}
    settings:
      format: bc7
      quality: high

  - name: Move to Processed Folder
    action: asset.move
    input: ${{ steps.compress.output }}
    destination: processed-textures/
```

#### Step 3: Add Approval Gates

```yaml
steps:
  - name: Generate Model
    action: ai.generate_3d
    input: ${{ trigger.concept_image }}

  - name: QA Review
    action: approval.request
    reviewers:
      - role: art_lead
    timeout: 24h
    on_reject:
      - action: notification.send
        to: ${{ trigger.user }}
        message: 'Model rejected: ${{ approval.reason }}'

  - name: Import to Engine
    action: unreal.import
    input: ${{ steps.generate_model.output }}
    condition: ${{ steps.qa_review.approved }}
```

#### Step 4: Monitor Pipelines

View pipeline status:

1. Go to Pipelines > Running
2. See all active executions
3. Click to view step details
4. Debug failed steps

---

### 8. Integrating with Unreal Engine

Full integration with Unreal Engine projects.

**Time:** 90 minutes **Difficulty:** Advanced

#### Step 1: Install the Plugin

1. Download the Yemaya UE Plugin
2. Copy to your project's `Plugins/` folder
3. Restart Unreal Editor
4. Enable plugin in Edit > Plugins

#### Step 2: Configure Project

1. Project Settings > Yemaya
2. Enter API credentials
3. Link to Yemaya project
4. Configure sync settings

#### Step 3: Sync Assets

```
Content Browser > Yemaya > Sync
```

Assets sync to:

```
/Game/Yemaya/
├── Characters/
├── Environments/
├── Props/
└── Materials/
```

#### Step 4: Use in Blueprints

Add Yemaya nodes:

```
Event BeginPlay
    → Yemaya Initialize
    → Yemaya Load Asset (ID: "char_hero")
    → Spawn Actor
```

#### Step 5: Set Up Sequencer Sync

Sync Sequencer with Yemaya timeline:

1. Create a Yemaya Sequence Track
2. Link to animatic in Yemaya
3. Timing syncs automatically
4. Camera cuts match storyboard

#### Step 6: Implement Virtual Production

For LED wall productions:

1. Configure nDisplay cluster
2. Set up camera tracking
3. Enable Yemaya LiveLink
4. Sync scene to production

---

### 9. Custom AI Agent Development

Create custom AI agents for your workflow.

**Time:** 120 minutes **Difficulty:** Advanced

#### Step 1: Understand Agent Architecture

Agents consist of:

- **Brain**: LLM-powered decision making
- **Tools**: Actions the agent can take
- **Memory**: Context and knowledge
- **Guardrails**: Safety constraints

#### Step 2: Define Your Agent

```typescript
// custom-agent.ts
import { Agent, Tool, Memory } from '@yemaya/agents';

const qualityReviewAgent = new Agent({
  name: 'Quality Reviewer',
  description: 'Reviews assets for quality standards',

  model: {
    provider: 'anthropic',
    model: 'claude-sonnet-4-20250514',
  },

  systemPrompt: `
    You are a quality reviewer for game assets.
    Your role is to evaluate assets against our quality standards.
    Be constructive but thorough in your feedback.
  `,

  tools: ['asset.read', 'asset.analyze', 'comment.create', 'approval.submit'],

  memory: {
    type: 'project',
    context: ['quality-guidelines', 'style-guide'],
  },

  guardrails: {
    maxTokensPerResponse: 2000,
    requireApprovalFor: ['approval.submit'],
  },
});
```

#### Step 3: Create Custom Tools

```typescript
// tools/analyze-mesh.ts
import { Tool } from '@yemaya/agents';

export const analyzeMeshTool: Tool = {
  name: 'analyze_mesh',
  description: 'Analyzes a 3D mesh for quality metrics',

  parameters: {
    assetId: {
      type: 'string',
      description: 'The ID of the mesh asset',
    },
  },

  execute: async ({ assetId }) => {
    const mesh = await loadMesh(assetId);

    return {
      triangleCount: mesh.triangles.length,
      vertexCount: mesh.vertices.length,
      hasUVs: mesh.uvs !== null,
      materialCount: mesh.materials.length,
      boundingBox: mesh.getBoundingBox(),
      issues: detectMeshIssues(mesh),
    };
  },
};
```

#### Step 4: Add Memory and Context

```typescript
// Configure agent memory
const memory = new ProjectMemory({
  projectId: 'proj_abc123',

  // Load these documents for context
  documents: ['docs/quality-guidelines.md', 'docs/style-guide.md'],

  // Remember previous reviews
  conversationHistory: true,
  maxHistoryLength: 50,
});
```

#### Step 5: Deploy Your Agent

```typescript
// Register agent with the system
await agentRegistry.register(qualityReviewAgent);

// Trigger on asset upload
await pipeline.addTrigger({
  event: 'asset.uploaded',
  action: async (asset) => {
    const result = await qualityReviewAgent.run({
      task: `Review the newly uploaded asset: ${asset.name}`,
      context: { assetId: asset.id },
    });

    return result;
  },
});
```

---

## Tutorial Index

| Tutorial                                                            | Level        | Time    | Topic            |
| ------------------------------------------------------------------- | ------------ | ------- | ---------------- |
| [Creating Your First Project](#1-creating-your-first-project)       | Beginner     | 10 min  | Project setup    |
| [Writing Your First Script](#2-writing-your-first-script)           | Beginner     | 20 min  | Scriptwriting    |
| [Working with Assets](#3-working-with-assets)                       | Beginner     | 15 min  | Asset management |
| [Blender Integration](#4-blender-integration)                       | Intermediate | 30 min  | Blender          |
| [AI-Assisted Character Creation](#5-ai-assisted-character-creation) | Intermediate | 45 min  | AI Agents        |
| [Real-time Collaboration](#6-setting-up-real-time-collaboration)    | Intermediate | 20 min  | Collaboration    |
| [Building Custom Pipelines](#7-building-custom-pipelines)           | Advanced     | 60 min  | Automation       |
| [Unreal Engine Integration](#8-integrating-with-unreal-engine)      | Advanced     | 90 min  | Unreal           |
| [Custom AI Agents](#9-custom-ai-agent-development)                  | Advanced     | 120 min | AI Development   |

---

## Next Steps

After completing these tutorials:

- Explore [Feature Documentation](../features/README.md) for deeper dives
- Join the [Community Discord](https://discord.gg/yemaya) for help
- Check [API Reference](../api/README.md) for programmatic access
- Browse [Example Projects](https://github.com/yemaya/examples) for inspiration
