# Scene Composer API Reference

`@aphrodite/scene-composer` — Layered scene definition, composition, and editing
with environment control, post-processing effects, camera systems, and audio.

Related libraries: `@aphrodite/scene-nature`, `@aphrodite/scene-gallery`,
`@aphrodite/performer-integration`

---

## Scene Definition

### SceneDefinition

The top-level scene format.

```typescript
interface SceneDefinition {
  id: string;
  name: string;
  description: string;
  version: number;
  category: SceneCategory;
  tags: string[];
  thumbnail: string;
  layers: SceneLayer[];
  effects: SceneEffect[];
  cameras: SceneCamera[];
  audioSources: AudioSource[];
  environment: EnvironmentParams;
  parameters: SceneParameter[];
  bounds: BoundingBox;
  metadata: Record<string, unknown>;
  createdAt: number;
  updatedAt: number;
}
```

### Scene Categories

| Category     | Description                          |
| ------------ | ------------------------------------ |
| `NATURE`     | Forests, beaches, mountains, gardens |
| `URBAN`      | City streets, rooftops, interiors    |
| `FANTASY`    | Magical, mythical environments       |
| `SCIFI`      | Futuristic, space, cyberpunk         |
| `ABSTRACT`   | Non-representational, geometric      |
| `UNDERWATER` | Aquatic environments                 |
| `CELESTIAL`  | Sky, space, cosmic                   |
| `HISTORICAL` | Period settings                      |
| `SURREAL`    | Dreamlike, impossible spaces         |
| `MINIMALIST` | Clean, simple, focused               |

---

## Layer System

### Layer Types (15)

| Type           | Z-Order Range | Purpose                       |
| -------------- | ------------- | ----------------------------- |
| `BACKGROUND`   | 0–9           | Distant backdrop              |
| `SKY`          | 10–19         | Sky, clouds, celestial bodies |
| `TERRAIN`      | 20–29         | Ground, landscape             |
| `WATER`        | 30–39         | Water surfaces, reflections   |
| `ATMOSPHERE`   | 40–49         | Fog, haze, volumetric light   |
| `PARTICLES`    | 50–59         | Particle systems              |
| `PROPS`        | 60–69         | Static objects                |
| `FAUNA`        | 70–79         | Animals, creatures            |
| `VEGETATION`   | 80–89         | Trees, plants, grass          |
| `ARCHITECTURE` | 90–99         | Buildings, structures         |
| `EMISSIVE`     | 100–109       | Light-emitting objects        |
| `OVERLAY`      | 110–119       | 2D overlays                   |
| `PERFORMER`    | 120–129       | Performer integration layer   |
| `HUD`          | 130–139       | Heads-up display              |
| `CUSTOM`       | 140+          | User-defined layers           |

### SceneLayer Interface

```typescript
interface SceneLayer {
  id: string;
  name: string;
  type: LayerType;
  enabled: boolean;
  visible: boolean;
  zOrder: number;
  opacity: number; // 0–1
  blendMode: BlendMode; // 'normal' | 'multiply' | 'screen' | 'overlay' | 'add' | 'soft_light'
  transform: LayerTransform;
  params: Record<string, unknown>;
  tags: string[];
  bounds: BoundingBox;
}
```

### Factory Function

```typescript
function createLayer(
  type: LayerType,
  name: string,
  overrides?: Partial<SceneLayer>
): SceneLayer;
```

---

## Effect System

### Effect Types (16)

| Type                   | Category   | Description                    |
| ---------------------- | ---------- | ------------------------------ |
| `SSAO`                 | Lighting   | Screen-space ambient occlusion |
| `BLOOM`                | Glow       | Bright area glow/bleed         |
| `DOF`                  | Focus      | Depth of field blur            |
| `MOTION_BLUR`          | Motion     | Movement blur                  |
| `COLOR_GRADE`          | Colour     | Colour grading/LUT             |
| `VIGNETTE`             | Frame      | Edge darkening                 |
| `CHROMATIC_ABERRATION` | Lens       | Colour fringing                |
| `FILM_GRAIN`           | Texture    | Film grain noise               |
| `GOD_RAYS`             | Lighting   | Volumetric light shafts        |
| `SSR`                  | Reflection | Screen-space reflections       |
| `FOG`                  | Atmosphere | Distance/height fog            |
| `HEAT_DISTORTION`      | Distortion | Heat haze effect               |
| `LENS_FLARE`           | Lens       | Sun/light flare                |
| `TONE_MAP`             | Colour     | HDR tone mapping               |
| `SHARPEN`              | Detail     | Sharpening filter              |
| `CUSTOM`               | User       | User-defined effect            |

### SceneEffect Interface

```typescript
interface SceneEffect {
  id: string;
  name: string;
  type: EffectType;
  enabled: boolean;
  priority: number; // processing order (lower = first)
  params: Record<string, unknown>;
}
```

### Factory Function

```typescript
function createEffect(
  type: EffectType,
  name: string,
  overrides?: Partial<SceneEffect>
): SceneEffect;
```

---

## Camera System

### Camera Modes (8)

| Mode         | Description              | Key Properties            |
| ------------ | ------------------------ | ------------------------- |
| `STATIC`     | Fixed position and angle | position, target, fov     |
| `ORBIT`      | Orbits around target     | orbitRadius, orbitSpeed   |
| `PATH`       | Follows predefined path  | path waypoints            |
| `TRACK`      | Tracks a moving target   | target, smoothing         |
| `FREE`       | Free-look camera         | position, rotation        |
| `DOLLY_ZOOM` | Dolly zoom (vertigo)     | dollySpeed, zoomRate      |
| `CRANE`      | Crane/jib movement       | height, reach, rotation   |
| `HANDHELD`   | Simulated handheld shake | shakeIntensity, frequency |

### SceneCamera Interface

```typescript
interface SceneCamera {
  id: string;
  name: string;
  mode: CameraMode;
  position: [number, number, number];
  target: [number, number, number];
  up: [number, number, number];
  fov: number; // degrees
  nearClip: number;
  farClip: number;
  aspectRatio: number;
  // Mode-specific properties
  orbitRadius?: number;
  orbitSpeed?: number;
  pathData?: CameraPathWaypoint[];
  shakeConfig?: CameraShakeConfig;
}
```

### Factory Function

```typescript
function createCamera(
  mode: CameraMode,
  name: string,
  overrides?: Partial<SceneCamera>
): SceneCamera;
```

---

## Audio System

### Audio Source Types

| Type         | Description              |
| ------------ | ------------------------ |
| `AMBIENT`    | Background ambient sound |
| `POSITIONAL` | 3D positioned sound      |
| `MUSIC`      | Background music track   |
| `SFX`        | Sound effects            |
| `REVERB`     | Reverb zone              |

### AudioSource Interface

```typescript
interface AudioSource {
  id: string;
  name: string;
  type: AudioSourceType;
  assetRef: string;
  volume: number; // 0–1
  pan: number; // -1 (left) to 1 (right)
  loop: boolean;
  position?: [number, number, number]; // for POSITIONAL
  attenuationRadius?: number;
  reverbSend?: number;
  fadeIn?: number; // ms
  fadeOut?: number; // ms
}
```

### Audio Configuration

```typescript
interface AudioConfig {
  masterVolume: number;
  ambientVolume: number;
  musicVolume: number;
  sfxVolume: number;
  reverbType: ReverbType;
  reverbMix: number;
  filters: AudioFilter[];
}
```

### Reverb Types

`none`, `small_room`, `large_hall`, `cathedral`, `outdoor`, `cave`, `underwater`

### Factory Function

```typescript
function createAudioSource(
  type: AudioSourceType,
  name: string,
  assetRef: string,
  overrides?: Partial<AudioSource>
): AudioSource;
```

---

## Environment Parameters

### Time of Day

| Value       | Description                   |
| ----------- | ----------------------------- |
| `DAWN`      | Early morning, warm low light |
| `MORNING`   | Bright morning                |
| `NOON`      | Overhead sun, harsh shadows   |
| `AFTERNOON` | Warm afternoon light          |
| `SUNSET`    | Golden/orange sunset          |
| `DUSK`      | Fading light, blue tones      |
| `NIGHT`     | Dark, moonlight               |
| `MIDNIGHT`  | Deepest night                 |

### Weather Types

| Value           | Description               |
| --------------- | ------------------------- |
| `CLEAR`         | Clear skies               |
| `PARTLY_CLOUDY` | Some clouds               |
| `OVERCAST`      | Full cloud cover          |
| `RAIN`          | Light rain                |
| `HEAVY_RAIN`    | Heavy downpour            |
| `THUNDERSTORM`  | Lightning and thunder     |
| `SNOW`          | Light snowfall            |
| `BLIZZARD`      | Heavy snow and wind       |
| `FOG`           | Dense fog                 |
| `SANDSTORM`     | Sand/dust storm           |
| `AURORA`        | Aurora borealis/australis |

### Seasons

`SPRING`, `SUMMER`, `AUTUMN`, `WINTER`

### Lighting Parameters

```typescript
interface LightingParams {
  sunDirection: [number, number, number];
  sunColor: string; // hex
  sunIntensity: number; // 0–1
  ambientColor: string; // hex
  ambientIntensity: number; // 0–1
  shadowDarkness: number; // 0–1
  shadowSoftness: number; // 0–1
  volumetricLighting: boolean;
}
```

### Atmosphere Parameters

```typescript
interface AtmosphereParams {
  fogDensity: number;
  fogColor: string;
  fogStart: number;
  fogEnd: number;
  cloudCoverage: number; // 0–1
  cloudSpeed: number;
  windDirection: [number, number, number];
  windStrength: number; // 0–1
  mieScattering: number;
  rayleighScattering: number;
}
```

---

## Custom Parameters

Runtime-adjustable scene parameters.

### Parameter Types

| Type     | Description              |
| -------- | ------------------------ |
| `FLOAT`  | Floating-point number    |
| `INT`    | Integer                  |
| `BOOL`   | Boolean toggle           |
| `COLOR`  | Hex colour string        |
| `VEC2`   | 2D vector [x, y]         |
| `VEC3`   | 3D vector [x, y, z]      |
| `ENUM`   | String from options list |
| `STRING` | Free-form text           |

### SceneParameter Interface

```typescript
interface SceneParameter {
  id: string;
  name: string;
  description: string;
  type: ParameterType;
  defaultValue: unknown;
  currentValue: unknown;
  min?: number;
  max?: number;
  step?: number;
  options?: string[]; // for ENUM type
  category: string;
  animatable: boolean;
}
```

### Factory Function

```typescript
function createParameter(
  id: string,
  name: string,
  type: ParameterType,
  defaultValue: unknown,
  overrides?: Partial<SceneParameter>
): SceneParameter;
```

---

## Scene Presets

### ScenePresetInfo

```typescript
interface ScenePresetInfo {
  id: string;
  name: string;
  description: string;
  category: SceneCategory;
  tags: string[];
  thumbnail: string;
  complexity: number; // 1–5
  layerCount: number;
  author: string;
}
```

---

## Editor Operations

### EditorAction Enum

| Action            | Description                  |
| ----------------- | ---------------------------- |
| `ADD_LAYER`       | Add a new layer              |
| `REMOVE_LAYER`    | Remove a layer               |
| `UPDATE_LAYER`    | Update layer properties      |
| `REORDER_LAYERS`  | Change layer z-ordering      |
| `ADD_EFFECT`      | Add a post-processing effect |
| `REMOVE_EFFECT`   | Remove an effect             |
| `UPDATE_EFFECT`   | Update effect parameters     |
| `SET_CAMERA`      | Set the active camera        |
| `UPDATE_CAMERA`   | Update camera properties     |
| `ADD_AUDIO`       | Add an audio source          |
| `REMOVE_AUDIO`    | Remove an audio source       |
| `UPDATE_AUDIO`    | Update audio properties      |
| `SET_PARAMETER`   | Update a custom parameter    |
| `SET_ENVIRONMENT` | Change environment settings  |
| `APPLY_PRESET`    | Apply a scene preset         |
| `UNDO`            | Undo last action             |
| `REDO`            | Redo undone action           |

### History

Each editor action creates an `EditorHistoryEntry` with before/after snapshots.
Maximum history depth: 100 entries.

---

## Scene Validation

```typescript
function validateScene(scene: SceneDefinition): ValidationResult;

interface ValidationResult {
  valid: boolean;
  errors: ValidationError[];
  warnings: ValidationWarning[];
}
```

---

## Scene Factory

```typescript
function createEmptyScene(
  name: string,
  category: SceneCategory
): SceneDefinition;
```

---

## Default Configuration

```typescript
const DEFAULT_SCENE_COMPOSER_CONFIG = {
  maxLoadedScenes: 10,
  maxLayersPerScene: 50,
  maxEffectsPerScene: 20,
  maxHistoryDepth: 100,
  validateOnLoad: true,
};
```

---

## Performer Integration

`@aphrodite/performer-integration`

### Placement

```typescript
interface PerformerPlacement {
  position: [number, number, number];
  rotation: [number, number, number];
  scale: [number, number, number];
  placementMode: PlacementMode;
  scaleMode: ScaleMode;
  groundOffset: number;
  pathWaypoints?: PathWaypoint[];
  pathProgress?: number;
}
```

| PlacementMode     | Description            |
| ----------------- | ---------------------- |
| `FIXED`           | Stationary position    |
| `CENTER_GROUNDED` | Centred on ground      |
| `PATH`            | Follows path waypoints |
| `STAGE_MARK`      | Named stage positions  |
| `FREEFORM`        | No constraints         |

| ScaleMode           | Description           |
| ------------------- | --------------------- |
| `ABSOLUTE`          | Fixed size            |
| `RELATIVE_TO_SCENE` | Proportional to scene |
| `AUTO_FIT`          | Automatic sizing      |

### Lighting Integration

```typescript
interface PerformerLightingConfig {
  mode: LightingIntegrationMode;
  lights: PerformerLight[];
  sceneAmbientInfluence: number;
  sceneDirectionalInfluence: number;
  emissionParams?: EmissionParams;
  shadowEnabled: boolean;
}
```

| Mode         | Description              |
| ------------ | ------------------------ |
| `SCENE_ONLY` | Lit by scene lights only |
| `DEDICATED`  | Independent lighting rig |
| `HYBRID`     | Scene + dedicated lights |
| `EMISSIVE`   | Performer emits light    |

### Movement Influence

| Type                   | Effect                           |
| ---------------------- | -------------------------------- |
| `PARTICLE_DISTURBANCE` | Particles scatter near performer |
| `WATER_RIPPLE`         | Ripples from performer position  |
| `VEGETATION_SWAY`      | Plants bend from movement        |
| `GROUND_IMPACT`        | Footstep terrain effects         |
| `WIND_DISTURBANCE`     | Local wind from fast movement    |
| `LIGHT_TRAIL`          | Luminous trail                   |
| `SOUND_PROPAGATION`    | Spatial audio response           |

### Biometric Mapping

```typescript
interface BiometricMapping {
  source: BiometricType;
  target: SceneReactionTarget;
  curve: 'linear' | 'exponential' | 'logarithmic' | 'sigmoid';
  inputRange: { min: number; max: number };
  outputRange: { min: number; max: number };
  smoothing: number;
  enabled: boolean;
}
```

| BiometricType       | Target Options                                                               |
| ------------------- | ---------------------------------------------------------------------------- |
| `HEART_RATE`        | LIGHTING, PARTICLES, ATMOSPHERE, AUDIO, EFFECTS, PARAMETERS, SKY, ANIMATIONS |
| `BREATH_RATE`       | Same as above                                                                |
| `SKIN_CONDUCTANCE`  | Same as above                                                                |
| `BODY_TEMPERATURE`  | Same as above                                                                |
| `MUSCLE_TENSION`    | Same as above                                                                |
| `VOCAL_ENERGY`      | Same as above                                                                |
| `FACIAL_EXPRESSION` | Same as above                                                                |
| `MOVEMENT_ENERGY`   | Same as above                                                                |

### Performer Camera Modes

| Mode            | Description                   |
| --------------- | ----------------------------- |
| `ORBIT`         | Orbits performer              |
| `OVER_SHOULDER` | Over-the-shoulder view        |
| `CLOSE_UP`      | Tight face/upper body framing |
| `FULL_BODY`     | Wide full-body shot           |
| `FOLLOW`        | Follow with lag               |
| `DOLLY`         | Smooth approach/retreat       |
| `AERIAL`        | Top-down / high angle         |
| `FIRST_PERSON`  | Performer's POV               |

---

## Gallery & Photo Mode

`@aphrodite/scene-gallery`

### Photo Filters (14)

| Filter        | Effect              |
| ------------- | ------------------- |
| `NONE`        | No filter           |
| `WARM`        | Golden warmth       |
| `COOL`        | Blue cool tones     |
| `DRAMATIC`    | High contrast       |
| `VINTAGE`     | Desaturated + grain |
| `NOIR`        | Black and white     |
| `VIVID`       | Boosted saturation  |
| `PASTEL`      | Soft muted tones    |
| `SEPIA`       | Classic sepia       |
| `CINEMATIC`   | Film-like grading   |
| `GOLDEN_HOUR` | Warm sunset         |
| `MOONLIT`     | Cool silver         |
| `CYBERPUNK`   | Neon tinted         |
| `ETHEREAL`    | Dreamy glow         |

### Capture Formats

| Format | Quality  |
| ------ | -------- |
| `PNG`  | Lossless |
| `JPEG` | 0.0–1.0  |
| `WEBP` | 0.0–1.0  |
| `AVIF` | 0.0–1.0  |
| `TIFF` | Lossless |

### Resolution Presets

| Preset     | Resolution   |
| ---------- | ------------ |
| `STANDARD` | 1920 × 1080  |
| `HIGH`     | 3840 × 2160  |
| `ULTRA`    | 7680 × 4320  |
| `CUSTOM`   | User-defined |

### Social Sharing

| Platform    | Constraints                            |
| ----------- | -------------------------------------- |
| `TWITTER`   | Platform-specific dimensions, JPEG/PNG |
| `INSTAGRAM` | Platform-specific dimensions, JPEG     |
| `FACEBOOK`  | Platform-specific dimensions, JPEG/PNG |
| `DISCORD`   | Higher quality allowed, PNG/WEBP       |
| `PINTEREST` | Vertical orientation, JPEG/PNG         |
| `GENERIC`   | Unconstrained                          |

### Gallery Configuration

```typescript
const DEFAULT_GALLERY_ENGINE_CONFIG = {
  maxCaptures: 1000,
  maxAlbums: 100,
  autoSaveToGallery: true,
  enablePhotoMode: true,
};
```
