@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,
};