# Creative Tools API

Integration with Blender, Unreal Engine, Godot, Houdini, and other creative
tools.

## Overview

The Creative Tools API provides bidirectional integration with industry-standard
creative software, enabling remote control, asset synchronization, and automated
workflows.

## Available Integrations

| Tool          | Base Path        | Description                       |
| ------------- | ---------------- | --------------------------------- |
| Blender       | `/v1/blender`    | 3D modeling, animation, rendering |
| Unreal Engine | `/v1/unreal`     | Game engine integration           |
| Godot         | `/v1/godot`      | Open-source game engine           |
| Houdini       | `/v1/procedural` | Procedural generation             |

---

# Blender Integration

**Base Path:** `/v1/blender`

Connect to and control Blender instances for 3D content creation.

## Connection Management

### Connect to Blender

Establish connection to a Blender instance.

```http
POST /v1/blender/connect
Authorization: Bearer <token>
Content-Type: application/json

{
  "host": "localhost",
  "port": 9876,
  "protocol": "websocket",
  "version": "4.0",
  "timeout": 30000
}
```

**Response:**

```json
{
  "success": true,
  "data": {
    "connectionId": "blender_conn_abc123",
    "status": "connected",
    "blenderVersion": "4.0.2",
    "pythonVersion": "3.11.4",
    "capabilities": ["modeling", "animation", "rendering", "scripting"],
    "activeScene": "Scene",
    "selectedObjects": []
  }
}
```

### Get Connection Status

```http
GET /v1/blender/status
Authorization: Bearer <token>
```

### Disconnect

```http
POST /v1/blender/disconnect
Authorization: Bearer <token>
```

## Scene Operations

### Get Scene Info

```http
GET /v1/blender/scene
Authorization: Bearer <token>
```

**Response:**

```json
{
  "success": true,
  "data": {
    "name": "Scene",
    "frameStart": 1,
    "frameEnd": 250,
    "frameCurrent": 1,
    "fps": 24,
    "resolution": { "x": 1920, "y": 1080 },
    "objects": [
      { "name": "Camera", "type": "CAMERA" },
      { "name": "Light", "type": "LIGHT" },
      { "name": "Cube", "type": "MESH" }
    ],
    "collections": ["Collection"],
    "worldSettings": {
      "backgroundColor": [0.05, 0.05, 0.05]
    }
  }
}
```

### Create Object

```http
POST /v1/blender/objects
Authorization: Bearer <token>
Content-Type: application/json

{
  "type": "mesh",
  "primitive": "cube",
  "name": "MyCube",
  "location": [0, 0, 0],
  "rotation": [0, 0, 0],
  "scale": [1, 1, 1],
  "collection": "Collection"
}
```

**Primitive Types:** `cube`, `sphere`, `cylinder`, `plane`, `cone`, `torus`,
`monkey`, `empty`

### Modify Object

```http
PATCH /v1/blender/objects/{objectName}
Authorization: Bearer <token>
Content-Type: application/json

{
  "location": [5, 0, 2],
  "rotation": [0, 45, 0],
  "scale": [2, 2, 2],
  "modifiers": [
    { "type": "SUBSURF", "levels": 2 },
    { "type": "BEVEL", "width": 0.1 }
  ]
}
```

### Delete Object

```http
DELETE /v1/blender/objects/{objectName}
Authorization: Bearer <token>
```

## Import/Export

### Import Asset

```http
POST /v1/blender/import
Authorization: Bearer <token>
Content-Type: application/json

{
  "url": "https://example.com/model.fbx",
  "format": "fbx",
  "options": {
    "applyTransform": true,
    "importAnimation": true,
    "importMaterials": true,
    "scale": 1.0
  }
}
```

**Supported Formats:** `fbx`, `obj`, `gltf`, `glb`, `dae`, `stl`, `ply`, `abc`,
`usd`

### Export Scene

```http
POST /v1/blender/export
Authorization: Bearer <token>
Content-Type: application/json

{
  "format": "glb",
  "objects": ["Character", "Weapon"],
  "options": {
    "applyModifiers": true,
    "exportAnimations": true,
    "exportMaterials": true,
    "compression": true
  }
}
```

**Response:**

```json
{
  "success": true,
  "data": {
    "url": "https://cdn.yemaya.io/exports/scene_abc123.glb",
    "format": "glb",
    "fileSize": 15000000,
    "exportedObjects": ["Character", "Weapon"],
    "animationClips": ["Walk", "Run", "Idle"]
  }
}
```

## Rendering

### Render Frame

```http
POST /v1/blender/render
Authorization: Bearer <token>
Content-Type: application/json

{
  "type": "image",
  "frame": 1,
  "camera": "Camera",
  "resolution": { "x": 1920, "y": 1080 },
  "samples": 128,
  "engine": "CYCLES",
  "format": "PNG",
  "colorDepth": 16
}
```

### Render Animation

```http
POST /v1/blender/render/animation
Authorization: Bearer <token>
Content-Type: application/json

{
  "frameStart": 1,
  "frameEnd": 250,
  "format": "FFMPEG",
  "codec": "H264",
  "quality": "HIGH",
  "fps": 24
}
```

## Python Scripting

### Execute Script

Run Python code in Blender.

```http
POST /v1/blender/script
Authorization: Bearer <token>
Content-Type: application/json

{
  "code": "import bpy\nbpy.ops.mesh.primitive_cube_add()\nresult = bpy.context.active_object.name",
  "timeout": 30000,
  "returnVariables": ["result"]
}
```

**Response:**

```json
{
  "success": true,
  "data": {
    "executed": true,
    "output": "",
    "variables": {
      "result": "Cube.001"
    },
    "executionTime": 45
  }
}
```

---

# Unreal Engine Integration

**Base Path:** `/v1/unreal`

Control Unreal Engine for game development and real-time rendering.

## Connection

### Connect to Unreal

```http
POST /v1/unreal/connect
Authorization: Bearer <token>
Content-Type: application/json

{
  "host": "localhost",
  "port": 30010,
  "projectName": "MyGame",
  "engineVersion": "5.3"
}
```

## Level Operations

### Get Level Info

```http
GET /v1/unreal/level
Authorization: Bearer <token>
```

### Spawn Actor

```http
POST /v1/unreal/actors
Authorization: Bearer <token>
Content-Type: application/json

{
  "class": "/Game/Blueprints/BP_Enemy",
  "name": "Enemy_001",
  "location": { "x": 100, "y": 200, "z": 0 },
  "rotation": { "pitch": 0, "yaw": 90, "roll": 0 },
  "scale": { "x": 1, "y": 1, "z": 1 },
  "properties": {
    "Health": 100,
    "Team": "Enemy"
  }
}
```

### Modify Actor

```http
PATCH /v1/unreal/actors/{actorName}
Authorization: Bearer <token>
Content-Type: application/json

{
  "location": { "x": 150, "y": 200, "z": 0 },
  "properties": {
    "Health": 50
  }
}
```

### Delete Actor

```http
DELETE /v1/unreal/actors/{actorName}
Authorization: Bearer <token>
```

## Blueprint Operations

### Call Blueprint Function

```http
POST /v1/unreal/blueprint/call
Authorization: Bearer <token>
Content-Type: application/json

{
  "actor": "Enemy_001",
  "function": "TakeDamage",
  "parameters": {
    "DamageAmount": 25,
    "DamageType": "Fire"
  }
}
```

### Get Blueprint Property

```http
GET /v1/unreal/blueprint/property?actor=Enemy_001&property=Health
Authorization: Bearer <token>
```

## Asset Management

### Import Asset

```http
POST /v1/unreal/assets/import
Authorization: Bearer <token>
Content-Type: application/json

{
  "url": "https://example.com/character.fbx",
  "destinationPath": "/Game/Characters",
  "options": {
    "importMaterials": true,
    "importTextures": true,
    "importAnimations": true,
    "skeletonAsset": "/Game/Skeletons/Humanoid"
  }
}
```

### Export Asset

```http
POST /v1/unreal/assets/export
Authorization: Bearer <token>
Content-Type: application/json

{
  "assetPath": "/Game/Characters/Hero",
  "format": "fbx",
  "options": {
    "exportAnimations": true,
    "exportMorphTargets": true
  }
}
```

## Play-in-Editor Control

### Start PIE

```http
POST /v1/unreal/pie/start
Authorization: Bearer <token>
Content-Type: application/json

{
  "mode": "play",
  "startLocation": "PlayerStart",
  "numberOfPlayers": 1
}
```

### Stop PIE

```http
POST /v1/unreal/pie/stop
Authorization: Bearer <token>
```

## Sequencer

### Play Sequence

```http
POST /v1/unreal/sequencer/play
Authorization: Bearer <token>
Content-Type: application/json

{
  "sequencePath": "/Game/Cinematics/Intro",
  "startFrame": 0,
  "playRate": 1.0
}
```

### Render Sequence

```http
POST /v1/unreal/sequencer/render
Authorization: Bearer <token>
Content-Type: application/json

{
  "sequencePath": "/Game/Cinematics/Intro",
  "outputPath": "/Renders/Intro",
  "format": "PNG",
  "resolution": { "x": 3840, "y": 2160 },
  "frameRate": 24,
  "antiAliasing": "TAA"
}
```

---

# Godot Integration

**Base Path:** `/v1/godot`

Control Godot Engine for 2D/3D game development.

## Connection

### Connect to Godot

```http
POST /v1/godot/connect
Authorization: Bearer <token>
Content-Type: application/json

{
  "host": "localhost",
  "port": 6007,
  "projectPath": "/path/to/project",
  "version": "4.2"
}
```

## Scene Management

### Get Scene Tree

```http
GET /v1/godot/scene/tree
Authorization: Bearer <token>
```

**Response:**

```json
{
  "success": true,
  "data": {
    "root": {
      "name": "Main",
      "type": "Node3D",
      "children": [
        {
          "name": "Player",
          "type": "CharacterBody3D",
          "children": [
            { "name": "CollisionShape3D", "type": "CollisionShape3D" },
            { "name": "MeshInstance3D", "type": "MeshInstance3D" }
          ]
        },
        {
          "name": "Environment",
          "type": "Node3D",
          "children": []
        }
      ]
    }
  }
}
```

### Add Node

```http
POST /v1/godot/nodes
Authorization: Bearer <token>
Content-Type: application/json

{
  "parent": "Main",
  "type": "MeshInstance3D",
  "name": "NewMesh",
  "properties": {
    "transform": {
      "origin": [0, 0, 0],
      "rotation": [0, 0, 0],
      "scale": [1, 1, 1]
    },
    "mesh": "res://meshes/cube.tres"
  }
}
```

### Update Node

```http
PATCH /v1/godot/nodes/{nodePath}
Authorization: Bearer <token>
Content-Type: application/json

{
  "properties": {
    "transform.origin": [5, 0, 0],
    "visible": true
  }
}
```

### Delete Node

```http
DELETE /v1/godot/nodes/{nodePath}
Authorization: Bearer <token>
```

## GDScript Execution

### Run GDScript

```http
POST /v1/godot/script
Authorization: Bearer <token>
Content-Type: application/json

{
  "code": "var player = get_node('/root/Main/Player')\nplayer.position.x += 10\nreturn player.position",
  "timeout": 5000
}
```

## Resource Management

### Import Resource

```http
POST /v1/godot/resources/import
Authorization: Bearer <token>
Content-Type: application/json

{
  "url": "https://example.com/texture.png",
  "destinationPath": "res://textures/",
  "resourceType": "Texture2D",
  "importOptions": {
    "compress": true,
    "generateMipmaps": true
  }
}
```

### Export Scene

```http
POST /v1/godot/scene/export
Authorization: Bearer <token>
Content-Type: application/json

{
  "scenePath": "res://scenes/level1.tscn",
  "format": "glb",
  "includeAnimations": true
}
```

## Editor Control

### Run Project

```http
POST /v1/godot/editor/run
Authorization: Bearer <token>
Content-Type: application/json

{
  "scene": "res://scenes/main.tscn",
  "debug": true,
  "arguments": ["--verbose"]
}
```

### Stop Project

```http
POST /v1/godot/editor/stop
Authorization: Bearer <token>
```

---

# Houdini Integration

**Base Path:** `/v1/procedural`

Procedural generation with Houdini Engine.

## Connection

### Connect to Houdini

```http
POST /v1/procedural/connect
Authorization: Bearer <token>
Content-Type: application/json

{
  "host": "localhost",
  "port": 9090,
  "license": "indie"
}
```

## HDA Operations

### Load HDA

```http
POST /v1/procedural/hda/load
Authorization: Bearer <token>
Content-Type: application/json

{
  "hdaUrl": "https://example.com/terrain_generator.hda",
  "name": "TerrainGenerator"
}
```

### Set Parameters

```http
POST /v1/procedural/hda/{hdaId}/parameters
Authorization: Bearer <token>
Content-Type: application/json

{
  "parameters": {
    "size": 1000,
    "height_scale": 50,
    "noise_frequency": 0.01,
    "seed": 12345,
    "erosion_iterations": 100
  }
}
```

### Cook HDA

Execute the HDA and generate output.

```http
POST /v1/procedural/hda/{hdaId}/cook
Authorization: Bearer <token>
Content-Type: application/json

{
  "outputFormat": "fbx",
  "generateLODs": true,
  "lodLevels": [100, 50, 25]
}
```

**Response:**

```json
{
  "success": true,
  "data": {
    "cookTime": 15.5,
    "outputs": [
      {
        "name": "terrain_mesh",
        "type": "geometry",
        "url": "https://cdn.yemaya.io/hda/terrain_abc123.fbx",
        "polyCount": 500000,
        "lods": [
          { "level": 0, "polyCount": 500000 },
          { "level": 1, "polyCount": 250000 },
          { "level": 2, "polyCount": 125000 }
        ]
      },
      {
        "name": "heightmap",
        "type": "texture",
        "url": "https://cdn.yemaya.io/hda/heightmap_abc123.exr",
        "resolution": [4096, 4096]
      }
    ]
  }
}
```

## Procedural Generation Presets

### Generate Terrain

```http
POST /v1/procedural/generate/terrain
Authorization: Bearer <token>
Content-Type: application/json

{
  "preset": "mountains",
  "size": { "x": 2000, "z": 2000 },
  "heightRange": { "min": 0, "max": 500 },
  "features": ["peaks", "valleys", "rivers", "lakes"],
  "biomes": ["alpine", "forest", "meadow"],
  "seed": 42
}
```

### Generate City

```http
POST /v1/procedural/generate/city
Authorization: Bearer <token>
Content-Type: application/json

{
  "preset": "medieval",
  "size": { "x": 500, "z": 500 },
  "population": 5000,
  "features": {
    "castle": true,
    "walls": true,
    "market": true,
    "houses": true,
    "roads": true
  },
  "style": "european_medieval",
  "seed": 123
}
```

### Generate Vegetation

```http
POST /v1/procedural/generate/vegetation
Authorization: Bearer <token>
Content-Type: application/json

{
  "terrainMesh": "https://example.com/terrain.fbx",
  "biomeMap": "https://example.com/biomes.png",
  "density": 0.7,
  "types": ["trees", "bushes", "grass", "flowers", "rocks"],
  "lod": true,
  "instanceCount": 100000
}
```

---

## WebSocket Events

All creative tool integrations support real-time events via WebSocket.

### Subscribe to Tool Events

```json
{
  "type": "subscribe",
  "channel": "tool",
  "resourceId": "blender_conn_abc123",
  "events": ["object:created", "object:modified", "render:progress"]
}
```

### Event Types

| Event               | Description              |
| ------------------- | ------------------------ |
| `connection:status` | Connection state changed |
| `object:created`    | Object was created       |
| `object:modified`   | Object was modified      |
| `object:deleted`    | Object was deleted       |
| `render:started`    | Render job started       |
| `render:progress`   | Render progress update   |
| `render:complete`   | Render finished          |
| `export:complete`   | Export finished          |
| `script:output`     | Script execution output  |

---

## Error Codes

| Code                  | Description                    |
| --------------------- | ------------------------------ |
| `CONNECTION_FAILED`   | Failed to connect to tool      |
| `CONNECTION_TIMEOUT`  | Connection timed out           |
| `TOOL_NOT_RUNNING`    | Target tool is not running     |
| `OBJECT_NOT_FOUND`    | Specified object doesn't exist |
| `SCRIPT_ERROR`        | Script execution failed        |
| `RENDER_FAILED`       | Render operation failed        |
| `IMPORT_FAILED`       | Asset import failed            |
| `EXPORT_FAILED`       | Asset export failed            |
| `HDA_COOK_FAILED`     | Houdini HDA cooking failed     |
| `UNSUPPORTED_VERSION` | Tool version not supported     |

---

## Rate Limits

| Operation             | Limit      |
| --------------------- | ---------- |
| Connection management | 10/minute  |
| Object operations     | 100/minute |
| Script execution      | 20/minute  |
| Render requests       | 5/minute   |
| Import/Export         | 20/minute  |
