Eve library

Scene Composer API Reference

Guide

Revision 1

On this page

@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

@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
typescript
const DEFAULT_GALLERY_ENGINE_CONFIG = {
  maxCaptures: 1000,
  maxAlbums: 100,
  autoSaveToGallery: true,
  enablePhotoMode: true,
};