Complete guide for performers setting up, running, and monetising interactive gaming sessions on the Aphrodite platform. This document covers every step from initial session creation through device configuration, scene customisation, viewer interaction management, and revenue optimisation.
Table of Contents#
- Overview
- Session Setup
- Compositor & Layout Configuration
- Camera & Feed Management
- Device Configuration for Gaming
- Scene Selection & Customisation
- Performer Integration with Scenes
- Viewer Interaction Management
- Monetisation Setup
- Gallery & Photo Mode
- Performance Tuning
- Session Lifecycle
- Troubleshooting
- Quick-Start Checklist
1. Overview#
A gaming session on Aphrodite combines six coordinated subsystems into a single streaming experience:
| Subsystem | Library | Purpose |
|---|---|---|
| Stream Management | @aphrodite/streaming-core |
Session lifecycle, viewer tracking, stream state |
| Video Composition | @aphrodite/performer-compositor |
Layout, adaptive framing, transitions |
| Device Reactions | @aphrodite/device-reaction-engine |
Haptic feedback mapped to game events |
| Scene Rendering | @aphrodite/scene-composer |
Layered environments, effects, cameras |
| Viewer Interaction | @aphrodite/animation-triggers |
Chat commands, tip animations, combos |
| Monetisation | @aphrodite/game-monetization |
Tip effects, milestones, revenue tracking |
Data-Flow Summary#
Game Event Bus
│
├──► Device Reaction Engine ──► Haptic Commands ──► Connected Devices
│
├──► Adaptive Layout Engine ──► Layout Change ──► Compositor
│
├──► Tip Effect Mapper ──► Visual/Audio Effect ──► Scene Renderer
│
├──► Animation Trigger Manager ──► Performer Animation
│
└──► Revenue Event Emitter ──► Analytics / Session Summary
Design Principles#
- Event-driven — Every subsystem communicates through typed events on the game event bus. No direct coupling between modules.
- Genre-aware — Setting the game genre propagates through all subsystems: layout preferences, haptic profiles, music palettes, and visual effects all adapt automatically.
- Safety-bounded — Device intensity and duration are clamped by global safety limits that cannot be overridden by genre profiles or tip effects.
- Performer-first — The performer retains full manual override over every automated behaviour. Any adaptive rule can be paused, disabled, or replaced at any point during a session.
2. Session Setup#
2.1 Creating a Stream Session#
Every gaming stream starts with a StreamSession from
@aphrodite/streaming-core.
import type {
StreamSession,
StreamManagerConfig,
} from '@aphrodite/streaming-core';
// IStreamManager API
const session: StreamSession = await streamManager.createSession(
broadcasterId,
{
resolution: { width: 1920, height: 1080 },
bitrate: 6000, // kbps
framerate: 60,
}
);
StreamSession properties:
| Field | Type | Description |
|---|---|---|
id |
string |
Unique session identifier |
broadcasterId |
string |
Performer's user ID |
state |
'idle' | 'starting' | 'live' | 'ended' |
Current lifecycle state |
config |
StreamConfig |
Resolution, bitrate, framerate |
viewerCount |
number |
Current viewer count |
createdAt |
number |
Unix timestamp of creation |
startedAt |
number | null |
Unix timestamp when stream went live |
StreamManagerConfig defaults:
| Setting | Default | Notes |
|---|---|---|
maxConcurrentStreams |
varies | Platform-level limit |
maxViewersPerStream |
varies | Capacity limit |
defaultBitrate |
4500 | kbps — use 6000+ for gaming at 1080p60 |
defaultFramerate |
30 | Override to 60 for gaming |
defaultResolution |
1080p | 1920 × 1080 |
sessionTimeout |
varies | Auto-end after inactivity |
viewerHeartbeatInterval |
varies | Viewer connection ping frequency |
enableDvrByDefault |
false |
DVR (rewind) increases storage/bandwidth |
Session events emitted:
| Event | Payload | When |
|---|---|---|
session.created |
{ session } |
Session object initialised |
session.started |
{ session } |
Stream goes live |
session.ended |
{ session } |
Stream ends |
session.stateChange |
{ session, prev, next } |
Any state transition |
viewer.joined |
{ viewerId, count } |
A viewer enters |
viewer.left |
{ viewerId, count } |
A viewer leaves |
quality.changed |
QualityMetrics |
Adaptive bitrate/resolution change |
2.2 Recommended Streaming Presets#
| Use Case | Resolution | Bitrate | FPS | Notes |
|---|---|---|---|---|
| Casual gaming | 1080p | 4500 kbps | 30 | Lower bandwidth, wide compat |
| Standard gaming | 1080p | 6000 kbps | 60 | Balanced quality and smoothness |
| Competitive gaming | 1080p | 8000 kbps | 60 | High bitrate for fast motion |
| Showcase / 4K | 2160p | 15000 kbps | 30 | High-res at lower framerate |
3. Compositor & Layout Configuration#
The @aphrodite/performer-compositor library handles how the performer's camera
feed and the game content are composed into a single output frame.
3.1 Choosing a Compositor#
Four factory functions create a compositor pre-tuned for different use cases:
| Factory | Resolution | FPS | Quality | Best for |
|---|---|---|---|---|
createVideoCompositor() |
Custom | Custom | Custom | Full manual control |
createHDCompositor() |
1920×1080 | 60 | High | Standard 1080p gaming streams |
create4KCompositor() |
3840×2160 | 30 | Ultra | High-res showcase streams |
createStreamingCompositor() |
Adaptive | Adaptive | Balanced | Low-latency, bandwidth-aware |
import { createHDCompositor } from '@aphrodite/performer-compositor';
const compositor = createHDCompositor();
Compositor capabilities:
- Up to 32–64 compositing layers with independent blend modes
- Blend modes:
Normal,Multiply,Screen,Overlay,SoftLight,Additive - Per-layer transforms: translate, scale, rotate, anchor points
- Multiple output targets:
StreamEncoder,LocalPreview,Recording,Screenshot - Frame statistics:
totalFrames,droppedFrames,avgFrameTimeMs,layerCount
3.2 Layout Presets#
The LayoutPresetManager provides ready-made arrangements for performer + game
content.
| Preset | Description | Best for |
|---|---|---|
PictureInPicture |
Game fills screen; performer is small overlay (corner) | FPS, Racing — gameplay focus |
SideBySide |
Performer and game split horizontally (50/50) | RPG, Puzzle — balanced view |
TopBottom |
Performer and game stacked vertically | Mobile viewers |
FloatingWindow |
Game fills canvas; performer in freely movable window | General purpose |
FullFramePerformer |
Performer fills frame; game is small overlay | Reaction-focused streams |
GameAsBackground |
Game as full background; centred performer | Casual / social streams |
Custom |
User-defined layout with manual region placement | Advanced configurations |
Factory functions for layout managers:
| Factory | Optimisation |
|---|---|
createStreamingLayoutManager() |
Preloaded PIP, SideBySide, Floating |
createMobileLayoutManager() |
Portrait (1080×1920) optimised |
createStudioLayoutManager() |
4K (3840×2160), 100 presets max |
import { createStreamingLayoutManager } from '@aphrodite/performer-compositor';
const layouts = createStreamingLayoutManager();
layouts.applyPreset('PictureInPicture');
Region customisation:
Each layout defines Region objects — rectangular areas that can be
repositioned and resized:
- Grid snapping and edge snapping for clean alignment
- Min/max size constraints prevent accidental zero-size regions
- Drag and resize flags per region
- Clamping to canvas bounds
3.3 Adaptive Layout Engine#
The adaptive engine automatically adjusts layout based on game context. This is where the performer experience becomes genre-aware.
Factory functions:
| Factory | Behaviour |
|---|---|
createAdaptiveLayoutEngine() |
General purpose — balanced rules |
createReactionFocusedEngine() |
Aggressive performer scaling (1.2–2.0×) |
createGenreFocusedEngine() |
Conservative, genre-driven layout changes |
createMinimalAdaptiveEngine() |
Fewer rules, minimal disruption |
Adaptation triggers:
| Trigger | Source | Effect |
|---|---|---|
| Genre detection | setGenre(genre) |
Switches to genre-preferred layout |
| Reaction intensity | setReactionIntensity(0–1) |
Scales performer window (1.0–1.8×) |
| Game moment | setGameMoment(moment) |
Adapts framing to action/menu/cutscene |
| Viewer device | setViewerDevice(device) |
Optimises for desktop/mobile/tablet/VR |
| Custom rules | User-defined predicates | Priority-based, enable/disable per-rule |
Genre-to-layout preferences:
| Genre | Preferred Layout | Performer Size | Position |
|---|---|---|---|
| FPS | PictureInPicture | Small | Bottom-right |
| RPG | SideBySide | Medium | Left |
| Racing | PictureInPicture | Small | Top-right |
| Platformer | FloatingWindow | Medium | Varies |
| Puzzle | SideBySide | Large | Left |
| Strategy | PictureInPicture | Small | Bottom-left |
| Fighting | TopBottom | Medium | Bottom |
| Horror | FullFramePerformer | Large | Centre |
| Sports | PictureInPicture | Small | Top-left |
| Rhythm | GameAsBackground | Large | Centre |
| OpenWorld | FloatingWindow | Medium | Varies |
| Simulation | SideBySide | Medium | Right |
| MOBA | PictureInPicture | Small | Bottom-right |
| BattleRoyale | PictureInPicture | Small | Top-right |
Reaction intensity scaling:
| Intensity Level | Range | Performer Scale |
|---|---|---|
| None | 0.00 – 0.19 | 1.0× |
| Mild | 0.20 – 0.39 | 1.1× |
| Moderate | 0.40 – 0.59 | 1.25× |
| Strong | 0.60 – 0.79 | 1.5× |
| Extreme | 0.80 – 1.00 | 1.8× |
Game moment adaptations:
| Moment | Layout adjustment |
|---|---|
Normal |
Genre default |
Action |
Shrink performer, maximise game view |
Cutscene |
Hide performer overlay |
Menu |
Enlarge performer, shrink game |
Loading |
Enlarge performer, show loading indicator |
Victory |
Centre performer, celebration layout |
Defeat |
Centre performer, reaction layout |
BossEncounter |
PIP with pulsing border |
QTE |
Maximise game, minimal performer |
Exploration |
FloatingWindow, relaxed framing |
3.4 Transitions#
Layout changes can be animated using the TransitionManager:
| Factory | Duration | Style |
|---|---|---|
createCinematicTransitionManager() |
600–800 ms | Smooth, cinematic |
createSnappyTransitionManager() |
150–300 ms | Fast, responsive |
createReactiveTransitionManager() |
Adaptive | Context-dependent |
Transition types: Wipe (Linear, Radial, Iris), Particle, Dissolve, Slide, Zoom
Easing options: Linear, EaseIn, EaseOut, EaseBoth, Bounce, Elastic
4. Camera & Feed Management#
4.1 Setting Up the Performer Feed#
The PerformerFeedManager handles camera input, quality enhancement, and
automatic failover.
Factory functions:
| Factory | Optimisation |
|---|---|
createPerformerFeedManager() |
General purpose |
createStudioFeedManager() |
Multiple cameras, high quality |
createMobileFeedManager() |
Mobile-optimised, single camera |
createStreamingFeedManager() |
Streaming-optimised, balanced quality |
4.2 Camera Types#
Register one or more cameras with priority ordering:
| Camera Type | Use Case |
|---|---|
Webcam |
Standard USB/integrated webcam |
Phone |
Mobile device as camera (via app) |
StudioCamera |
Professional capture device |
ScreenCapture |
Screen/window capture for game feed |
VirtualCamera |
Software camera (OBS virtual cam, etc.) |
import { createStreamingFeedManager } from '@aphrodite/performer-compositor';
const feed = createStreamingFeedManager();
// Register primary camera
feed.registerCamera({
id: 'main-webcam',
type: 'Webcam',
name: 'Logitech C920',
resolution: { width: 1920, height: 1080 },
frameRate: 60,
priority: 1, // highest priority = primary
});
// Register backup camera
feed.registerCamera({
id: 'phone-backup',
type: 'Phone',
name: 'iPhone Camera',
resolution: { width: 1920, height: 1080 },
frameRate: 30,
priority: 2, // lower priority = failover
});
4.3 Background Removal#
Five background removal modes available:
| Mode | Quality | CPU Cost | Notes |
|---|---|---|---|
None |
N/A | Zero | No processing |
MediaPipe |
Good | Medium | ML-based segmentation, no setup |
GreenScreen |
Excellent | Low | Requires physical green screen |
AI |
Best | High | Deep learning, handles complex scenes |
Manual |
Variable | Low | User-defined mask |
Green screen configuration:
feed.setBackgroundRemoval({
mode: 'GreenScreen',
greenScreen: {
keyColor: '#00FF00',
similarity: 0.4, // colour match tolerance
smoothness: 0.1, // edge blending
spillSuppression: 0.5, // remove green spill on skin
},
edgeSmoothing: 0.3,
});
4.4 Quality Enhancement#
Fine-tune the camera feed without external software:
| Parameter | Range | Default | Effect |
|---|---|---|---|
denoising |
0.0 – 1.0 | 0.0 | Reduce noise in low-light feeds |
sharpening |
0.0 – 1.0 | 0.0 | Sharpen edges |
brightness |
-1.0 – 1.0 | 0.0 | Lighten or darken |
contrast |
-1.0 – 1.0 | 0.0 | Increase/decrease contrast |
saturation |
-1.0 – 1.0 | 0.0 | Colour vividness |
whiteBalance |
2500 – 10000 K | auto | Colour temperature |
autoExposure |
boolean |
true |
Automatic brightness adjustment |
4.5 Failover Configuration#
Automatic camera switching when the primary feed disconnects:
feed.setFailoverConfig({
enabled: true,
maxDisconnectMs: 3000, // wait 3s before switching
priorityOrder: ['main-webcam', 'phone-backup'],
autoReconnect: true,
reconnectIntervalMs: 5000, // retry every 5s
});
Feed states:
| State | Meaning |
|---|---|
Disconnected |
No camera connected |
Connecting |
Establishing camera connection |
Active |
Camera feed live and compositing |
Paused |
Feed paused (manual or system) |
Error |
Camera error, waiting for intervention |
Failover |
Switched to backup camera automatically |
5. Device Configuration for Gaming#
5.1 Supported Device Brands#
The @aphrodite/device-protocols library supports the following device brands:
| Brand | Connection Methods | Notes |
|---|---|---|
lovense |
Bluetooth, WiFi, Cloud | Most popular, wide range |
kiiroo |
Bluetooth, WiFi | Bi-directional support |
ohmibod |
Bluetooth | Music-reactive models |
we_vibe |
Bluetooth | Quiet, discreet |
handy |
WiFi, Cloud | Stroker specialisation |
satisfyer |
Bluetooth | Budget-friendly |
buttplug |
Bluetooth, USB, WiFi, Dongle | Protocol aggregator |
generic |
Varies | Fallback for unknown HW |
5.2 Device Types#
| Type | Capabilities |
|---|---|
vibrator |
Vibrate, Oscillate |
rotator |
Rotate, Vibrate |
stroker |
Linear (stroke), Vibrate |
pump |
Inflate, Constrict |
plug |
Vibrate, Rotate |
clamp |
Constrict, Vibrate |
edge |
Vibrate, Oscillate |
wand |
Vibrate (high power) |
ring |
Vibrate |
prostate |
Vibrate, Rotate |
kegel |
Constrict, Vibrate |
other |
Varies |
5.3 Device Capabilities#
All device commands operate on these capability channels:
| Capability | Description | Typical devices |
|---|---|---|
Vibrate |
Motor vibration | All vibrating devices |
Rotate |
Rotational movement | Rotators, some plugs |
Linear |
Linear stroke/thrust | Strokers, pumps |
Constrict |
Tightening/squeezing | Clamps, kegel trainers |
Oscillate |
Rapid back-and-forth | Edge devices, some vibrators |
Inflate |
Expansion/inflation | Pumps |
Heat |
Temperature increase | Heated devices |
Cool |
Temperature decrease | Cooling devices |
Electro |
Electrical stimulation | E-stim devices |
Suction |
Vacuum/suction | Suction devices |
5.4 Connecting Devices#
import type { DeviceInfo, DeviceStatus } from '@aphrodite/device-protocols';
// Device state tracking
interface DeviceState {
deviceId: string;
status: DeviceStatus; // disconnected → connecting → connected → active
batteryLevel: number; // 0–100
signalStrength: number; // 0–100
motorStates: MotorState[];
activePattern: PatternExecutionState | null;
temperature: number | null;
firmwareVersion: string;
}
Device status lifecycle:
disconnected → connecting → connected → active
↓ ↓
error pairing
5.5 Game-to-Device Mapping (Reaction Engine)#
The @aphrodite/device-reaction-engine translates game events into device
commands using translation rules.
Translation rule structure:
interface TranslationRule {
name: string;
eventPattern: string; // wildcard support: 'combat.*', 'vehicle.collision'
targetCapability: DeviceCapability;
strategy: 'Direct' | 'Scaled' | 'Mapped' | 'Composite' | 'Fallback';
intensityMapping: (eventData: unknown) => number; // 0–1
durationMapping: (eventData: unknown) => number; // milliseconds
fallbackCapability?: DeviceCapability;
priority: number;
enabled: boolean;
}
Built-in translation rules:
| Rule | Event | Mapping |
|---|---|---|
COLLISION_TO_VIBRATE |
Collision force | force → intensity, force × 2 → duration (50–2000 ms) |
DAMAGE_TO_VIBRATE |
Damage taken | damage/maxHealth → intensity, proportional duration |
EXPLOSION_TO_PULSE |
Explosion | proximity → intensity, radius → duration |
RHYTHM_BEAT_TO_VIBRATE |
Music beat | beat strength → intensity, BPM → pulse length |
5.6 Genre-Specific Device Profiles#
Each genre includes a complete set of event-to-device mappings with factory functions for difficulty levels.
| Genre | Key Events | Factory Levels |
|---|---|---|
| FPS | Weapon fire, damage direction, explosions, kills, reloads | casual / competitive / hardcore |
| Racing | Engine RPM, collisions, drift, terrain, nitro, gear shifts | casual / competitive / hardcore |
| Platformer | Jumps, landings, collectibles, wall slides, enemy stomps | casual / competitive / hardcore |
| Puzzle | Tile matches, combos, time pressure, level complete | casual / competitive / hardcore |
| RPG | Spell casts, melee attacks, level-ups, critical hits, bosses | casual / competitive / hardcore |
| Fighting | Strikes, blocks, combos, super moves, grabs, counters | casual / competitive / hardcore |
| Strategy | Unit selection, battles, resources, buildings, research | casual / competitive / hardcore |
| Horror | Ambient dread, jump scares, heartbeat, tension, relief | casual / competitive / hardcore |
| Sports | Ball impact, sprints, goals, crowd reactions, tackles | casual / competitive / hardcore |
| Rhythm | Beat hits, misses, combos, bass drops, song sections | casual / competitive / hardcore |
| Simulation | Vehicle operation, success/failure, milestones, weather | casual / competitive / hardcore |
| Open World | Weather, discoveries, combat, mounts, quests, hazards | casual / competitive / hardcore |
Example — Setting up FPS device profile:
import { createFPSProfile } from '@aphrodite/device-reaction-engine';
// Choose intensity level
const profile = createFPSProfile('competitive');
// Profile contains rules for:
// - weapon.fire → short vibration burst matching weapon type
// - damage.received → directional intensity based on damage amount
// - explosion.nearby → proximity-scaled pulse with falloff
// - player.kill → satisfying confirmation pulse
// - player.death → strong sustained vibration
// - weapon.reload → subtle rhythmic pattern
// - heartbeat.low_hp → pulsing heartbeat increasing as HP drops
5.7 Pattern Library#
The reaction engine includes a library of pre-built haptic patterns plus waveform generators for custom patterns.
Pattern categories:
| Category | Examples |
|---|---|
Impact |
Single hit, double tap, slam, shockwave |
Rhythmic |
Heartbeat, pulse train, gallop, march |
Continuous |
Steady vibration, ramp up, ramp down, wave |
Texture |
Rain, gravel, smooth, rough, electric |
Composite |
Multi-phase sequences combining the above |
Waveform generators:
| Generator | Parameters | Output |
|---|---|---|
generateSineWave |
frequency, duration, sampleRate | Smooth periodic wave |
generateSquareWave |
frequency, duration, rate, duty | On/off pulses |
generateTriangleWave |
frequency, duration, sampleRate | Ramping peaks |
Pattern blending:
Combine multiple patterns using blend modes: Add, Multiply, Max,
Average, Replace.
import { blendPatterns } from '@aphrodite/device-reaction-engine';
const combined = blendPatterns(heartbeatPattern, ambientPattern, 'Add', 0.6);
5.8 Safety Limits#
Global safety limits cannot be overridden by any genre profile or tip effect.
| Limit | Default | Description |
|---|---|---|
| Max intensity | 1.0 | Absolute cap on any device output |
| Max duration | varies | Maximum single-command duration |
| Cooldown between bursts | varies | Minimum gap between high-intensity events |
| Emergency stop | always | Instant kill switch on all devices |
The safety system enforces these constraints at the device command level — after genre profiles and tip effects have been processed but before commands reach the physical device.
6. Scene Selection & Customisation#
6.1 Scene Architecture#
Scenes in Aphrodite are built from layered definitions managed by
@aphrodite/scene-composer:
SceneDefinition
├── Layers (up to 50 per scene)
│ ├── BACKGROUND, SKY, TERRAIN, WATER
│ ├── ATMOSPHERE, PARTICLES, PROPS
│ ├── FAUNA, VEGETATION, ARCHITECTURE
│ ├── EMISSIVE, OVERLAY, PERFORMER
│ └── HUD, CUSTOM
├── Effects chain (up to 20 per scene)
│ ├── SSAO, BLOOM, DOF, MOTION_BLUR
│ ├── COLOR_GRADE, VIGNETTE, CHROMATIC_ABERRATION
│ ├── FILM_GRAIN, GOD_RAYS, SSR, FOG
│ └── HEAT_DISTORTION, LENS_FLARE, TONE_MAP, SHARPEN
├── Cameras
│ └── STATIC, ORBIT, PATH, TRACK, FREE, DOLLY_ZOOM, CRANE, HANDHELD
├── Audio sources
│ └── AMBIENT, POSITIONAL, MUSIC, SFX, REVERB
├── Environment params
│ └── Time of day, weather, season, lighting, atmosphere
└── Custom parameters
└── Performer-editable values (floats, colours, enums)
6.2 Scene Categories#
Browse and select from the following scene categories:
| Category | Description | Example scenes |
|---|---|---|
NATURE |
Forests, beaches, mountains, gardens | Zen garden, tropical beach |
URBAN |
City streets, rooftops, interiors | Neon alley, penthouse |
FANTASY |
Magical, mythical environments | Enchanted forest, crystal cave |
SCIFI |
Futuristic, space, cyberpunk | Space station, neon cityscape |
ABSTRACT |
Non-representational, geometric | Particle field, void |
UNDERWATER |
Aquatic environments | Coral reef, deep ocean |
CELESTIAL |
Sky, space, cosmic | Nebula, aurora borealis |
HISTORICAL |
Period settings | Roman temple, Victorian manor |
SURREAL |
Dreamlike, impossible spaces | Floating islands, mirror realm |
MINIMALIST |
Clean, simple, focused | White room, gradient backdrop |
Scene preset info:
Each preset in the catalogue includes:
- Name, description, category, tags
- Thumbnail preview
- Complexity rating (1–5)
- Layer count
- Author
6.3 Creating and Editing Scenes#
Creating a blank scene:
import { createEmptyScene } from '@aphrodite/scene-composer';
const scene = createEmptyScene('My Gaming Scene', 'FANTASY');
Adding layers:
import { createLayer } from '@aphrodite/scene-composer';
const background = createLayer('BACKGROUND', 'Fantasy Sky', {
zOrder: 0,
opacity: 1.0,
blendMode: 'normal',
});
const particles = createLayer('PARTICLES', 'Magic Sparkles', {
zOrder: 10,
opacity: 0.7,
blendMode: 'add',
});
Adding post-processing effects:
import { createEffect } from '@aphrodite/scene-composer';
const bloom = createEffect('BLOOM', 'Glow', {
priority: 1,
params: { intensity: 0.6, threshold: 0.8 },
});
const colourGrade = createEffect('COLOR_GRADE', 'Warm Tone', {
priority: 2,
params: { temperature: 0.3, saturation: 0.1 },
});
Setting the camera:
import { createCamera } from '@aphrodite/scene-composer';
const orbitCam = createCamera('ORBIT', 'Slow Pan', {
position: [0, 2, 5],
target: [0, 1, 0],
fov: 60,
// Orbit-specific properties
orbitRadius: 5,
orbitSpeed: 0.1,
});
Setting environment:
scene.environment = {
timeOfDay: 'SUNSET',
weather: 'CLEAR',
season: 'AUTUMN',
lighting: {
sunDirection: [0.3, 0.7, 0.5],
sunColor: '#FFA040',
sunIntensity: 0.8,
ambientColor: '#302040',
ambientIntensity: 0.3,
shadowDarkness: 0.5,
shadowSoftness: 0.6,
volumetricLighting: true,
},
atmosphere: {
fogDensity: 0.02,
fogColor: '#806040',
cloudCoverage: 0.3,
windStrength: 0.4,
},
};
6.4 Custom Parameters#
Scene parameters let the performer adjust values at runtime without editing the scene definition directly:
import { createParameter } from '@aphrodite/scene-composer';
const fogIntensity = createParameter(
'fog_intensity',
'Fog Intensity',
'FLOAT',
0.5,
{ min: 0.0, max: 1.0, step: 0.05, category: 'Atmosphere', animatable: true }
);
const themeColour = createParameter(
'theme_colour',
'Theme Colour',
'COLOR',
'#FF6090',
{ category: 'Style' }
);
Parameter types: FLOAT, INT, BOOL, COLOR, VEC2, VEC3, ENUM,
STRING
6.5 Audio Configuration#
import { createAudioSource } from '@aphrodite/scene-composer';
const ambientAudio = createAudioSource(
'AMBIENT',
'Forest Ambience',
'forest_loop.ogg',
{
volume: 0.4,
loop: true,
fadeIn: 2000,
}
);
const musicTrack = createAudioSource('MUSIC', 'BGM', 'gaming_bgm.ogg', {
volume: 0.3,
loop: true,
});
Reverb types: none, small_room, large_hall, cathedral, outdoor,
cave, underwater
6.6 Scene Validation#
Always validate before going live:
import { validateScene } from '@aphrodite/scene-composer';
const result = validateScene(scene);
if (!result.valid) {
console.error('Scene errors:', result.errors);
console.warn('Scene warnings:', result.warnings);
}
6.7 Editor Operations#
The scene editor supports a full undo/redo history with the following operations:
| Action | Description |
|---|---|
ADD_LAYER |
Add a new layer to the scene |
REMOVE_LAYER |
Remove a layer |
UPDATE_LAYER |
Change layer properties |
REORDER_LAYERS |
Change layer z-ordering |
ADD_EFFECT |
Add a post-processing effect |
REMOVE_EFFECT |
Remove an effect |
UPDATE_EFFECT |
Change effect parameters |
SET_CAMERA |
Set the active camera |
UPDATE_CAMERA |
Change camera properties |
ADD_AUDIO |
Add an audio source |
REMOVE_AUDIO |
Remove an audio source |
UPDATE_AUDIO |
Change audio properties |
SET_PARAMETER |
Update a custom parameter value |
SET_ENVIRONMENT |
Change environment settings |
APPLY_PRESET |
Apply a scene preset |
UNDO / REDO |
Step through history (up to 100 entries) |
7. Performer Integration with Scenes#
7.1 Performer Placement#
Configure how the performer appears within the 3D scene:
Placement modes:
| Mode | Description |
|---|---|
FIXED |
Stationary at a set position |
CENTER_GROUNDED |
Centred on ground plane |
PATH |
Follows a predefined path with waypoints |
STAGE_MARK |
Snaps to named stage positions in the scene |
FREEFORM |
Manual positioning with no constraints |
Scale modes:
| Mode | Description |
|---|---|
ABSOLUTE |
Fixed pixel/unit size |
RELATIVE_TO_SCENE |
Scaled proportional to scene dimensions |
AUTO_FIT |
Automatically sized to fit scene context |
const placement: PerformerPlacement = {
position: [0, 0, 3],
rotation: [0, 0, 0],
scale: [1, 1, 1],
placementMode: 'CENTER_GROUNDED',
scaleMode: 'RELATIVE_TO_SCENE',
groundOffset: 0.0,
};
7.2 Performer Lighting#
Dedicated lighting for the performer within the scene context:
Lighting modes:
| Mode | Description |
|---|---|
SCENE_ONLY |
Performer lit entirely by scene lights |
DEDICATED |
Performer has independent lighting rig |
HYBRID |
Scene lights + supplementary dedicated lights |
EMISSIVE |
Performer emits light (glow effect) |
Light types for performer rig:
| Type | Purpose |
|---|---|
key |
Primary directional light |
fill |
Softer light reducing shadows |
rim |
Back/edge light for separation from scene |
ambient |
Low-level omnidirectional fill |
spot |
Focused beam for dramatic effect |
const lightingConfig: PerformerLightingConfig = {
mode: 'HYBRID',
lights: [
{
id: 'key',
type: 'key',
position: [2, 3, 2],
color: '#FFFFFF',
intensity: 0.8,
followsPerformer: true,
},
{
id: 'rim',
type: 'rim',
position: [-1, 2, -1],
color: '#6080FF',
intensity: 0.5,
followsPerformer: true,
},
],
sceneAmbientInfluence: 0.3, // 30% of scene ambient affects performer
sceneDirectionalInfluence: 0.2, // 20% of scene sun affects performer
shadowEnabled: true,
};
7.3 Movement Influence#
The performer's movement can affect the scene environment:
| Influence Type | Effect |
|---|---|
PARTICLE_DISTURBANCE |
Nearby particles scatter when performer moves |
WATER_RIPPLE |
Ripples emanate from performer position |
VEGETATION_SWAY |
Plants bend away from movement |
GROUND_IMPACT |
Footstep effects on terrain |
WIND_DISTURBANCE |
Localised wind effect from fast movement |
LIGHT_TRAIL |
Luminous trail following performer |
SOUND_PROPAGATION |
Spatial audio responds to performer position |
7.4 Biometric Scene Reactions#
Map biometric data from connected sensors to scene parameters for immersive reactive environments:
Biometric sources:
| Source | Description | Typical range |
|---|---|---|
HEART_RATE |
Heart rate (BPM) | 60–180 |
BREATH_RATE |
Breaths per minute | 12–30 |
SKIN_CONDUCTANCE |
Galvanic skin response | 0.0–1.0 |
BODY_TEMPERATURE |
Core temperature delta | -1.0–2.0 |
MUSCLE_TENSION |
EMG tension level | 0.0–1.0 |
VOCAL_ENERGY |
Voice volume/intensity | 0.0–1.0 |
FACIAL_EXPRESSION |
Expression intensity | 0.0–1.0 |
MOVEMENT_ENERGY |
Overall body motion energy | 0.0–1.0 |
Scene reaction targets:
| Target | What changes |
|---|---|
LIGHTING |
Light colour, intensity, flicker |
PARTICLES |
Particle density, speed, colour |
ATMOSPHERE |
Fog density, wind strength, clouds |
AUDIO |
Volume, reverb, filter parameters |
EFFECTS |
Post-processing intensity (bloom, vignette) |
PARAMETERS |
Any custom scene parameter |
SKY |
Sky colour, sun position, star density |
ANIMATIONS |
Scene animation speed, triggers |
Mapping curves: linear, exponential, logarithmic, sigmoid
Example — heart rate controls particle density:
const biometricMapping: BiometricMapping = {
source: 'HEART_RATE',
target: 'PARTICLES',
curve: 'exponential',
inputRange: { min: 60, max: 180 },
outputRange: { min: 0.1, max: 1.0 },
smoothing: 0.3, // smooths rapid fluctuations
enabled: true,
};
7.5 Performer Camera Modes#
Dedicated camera modes for framing the performer within the scene:
| Mode | Description |
|---|---|
ORBIT |
Camera orbits around performer |
OVER_SHOULDER |
Looking over the performer's shoulder |
CLOSE_UP |
Tight framing on face/upper body |
FULL_BODY |
Wide shot showing entire performer |
FOLLOW |
Camera follows performer movement with lag |
DOLLY |
Smooth approach/retreat along a rail |
AERIAL |
Top-down or high-angle view |
FIRST_PERSON |
Performer's point of view |
8. Viewer Interaction Management#
8.1 Chat & Messaging#
The @aphrodite/core session types define the chat system:
Chat message types:
| Type | Description |
|---|---|
text |
Standard text message |
tip |
Tip-attached message |
system |
System notification |
emote |
Emote/sticker message |
media |
Media attachment (image, clip) |
gift |
Virtual gift |
command |
Chat command (starts with !) |
Chat room settings the performer controls:
| Setting | Type | Description |
|---|---|---|
slowMode |
number |
Seconds between messages per user |
subscribersOnly |
boolean |
Only subscribers can chat |
emoteOnly |
boolean |
Only emotes/stickers allowed |
linksAllowed |
boolean |
Allow URLs in messages |
automatedModeration |
boolean |
Auto-filter offensive content |
bannedWords |
string[] |
Custom word filter list |
maxMessageLength |
number |
Maximum characters per message |
8.2 Animation Triggers#
The @aphrodite/animation-triggers library connects viewer actions to in-game
animations.
Trigger types:
| Type | Source | Example |
|---|---|---|
tip |
Token tip received | Fireworks on 500+ token tip |
chat_command |
Chat command entered | !dance triggers dance animation |
viewer_action |
Follow, subscribe, raid | Confetti on new subscriber |
time_based |
Scheduled timer | Hourly special effect |
random |
Random probability | Surprise lightning strike |
api |
External API call | Integration triggers |
8.3 Tip Animation Presets#
Default tip animation tiers:
| Preset | Token Range | Animation | Cooldown |
|---|---|---|---|
small_tip |
1 – 49 | Subtle sparkle/glow | Short |
medium_tip |
50 – 199 | Medium visual effect | Medium |
large_tip |
200 – 499 | Large dramatic effect | Medium |
mega_tip |
500+ | Full-screen spectacular | Long |
8.4 Chat Command Presets#
Default chat commands viewers can use:
| Command | Animation | Min Role | Cooldown |
|---|---|---|---|
!wave |
Performer waves | Any | Short |
!dance |
Dance animation | Any | Medium |
!pose |
Strike a pose | Any | Medium |
!wink |
Wink animation | Any | Short |
8.5 Viewer Actions#
Viewer lifecycle events that can trigger effects:
| Action | When it fires | Typical effect |
|---|---|---|
follow |
New follower | Welcome notification |
subscribe |
New subscription | Confetti + sound |
gift_sub |
Gifted subscription | Special gift animation |
raid |
Incoming raid from another room | Raid alert + animation |
host |
Being hosted by another room | Host acknowledgement |
share |
Session shared on social media | Share celebration |
8.6 Combo System#
The trigger manager supports animation combos — rapid successive triggers that escalate the visual response:
| Setting | Description |
|---|---|
enableCombos |
Turn combo system on/off |
comboWindow |
Time window to chain triggers (ms) |
maxComboCount |
Maximum combo multiplier |
maxConcurrentAnimations |
Simultaneous animations limit |
globalCooldown |
Minimum time between any two triggers |
maxQueueSize |
Maximum queued animations |
8.7 Interactive Device Sessions#
Viewers can interact with the performer's connected devices through the token system:
Device control modes:
| Mode | Description |
|---|---|
disabled |
No viewer control |
tip_controlled |
Tips trigger device commands (amount → intensity) |
manual |
Performer controls manually |
pattern |
Running a preset pattern |
interactive |
Real-time viewer control (e.g., via slider) |
Device command types viewers can trigger:
| Command | Description |
|---|---|
vibrate |
Vibration at specified intensity |
rotate |
Rotation at specified speed |
pump |
Pump/inflate action |
stroke |
Linear stroke movement |
pattern |
Execute a named pattern |
stop |
Stop all active commands |
Each command includes:
intensity(0–100)duration(milliseconds)triggeredBy(viewer ID)tipAmount(tokens that triggered it)
9. Monetisation Setup#
9.1 Token Economy Overview#
The @aphrodite/game-monetization library provides a complete economic layer
for gaming sessions.
Token transaction types:
| Type | Description |
|---|---|
tip |
Direct tip to performer |
content_purchase |
Purchase access to content |
subscription |
Recurring subscription payment |
private_show |
Private session payment |
gift |
Virtual gift purchase |
goal_contribution |
Contribution toward a stream goal |
game_wager |
In-game wagering |
9.2 Tip Tier System#
Tips are automatically classified into tiers that drive effect scaling:
| Tier | Token Range | Label | Colour | Intensity Multiplier | Duration Multiplier |
|---|---|---|---|---|---|
MICRO |
1 – 10 | Micro | Assigned | Low | Low |
SMALL |
11 – 50 | Small | Assigned | Moderate | Moderate |
MEDIUM |
51 – 200 | Medium | Assigned | Medium | Medium |
LARGE |
201 – 500 | Large | Assigned | High | High |
HUGE |
501 – 1000 | Huge | Assigned | Very High | Very High |
WHALE |
1001+ | Whale | Assigned | Maximum | Maximum |
Tier classification API:
import { TipTierClassifier } from '@aphrodite/game-monetization';
const classifier = new TipTierClassifier();
const tier = classifier.classify(250); // → LARGE
const multiplier = classifier.getIntensityMultiplier(tier);
const label = classifier.getLabel(tier);
const colour = classifier.getColour(tier);
9.3 Tip-to-Effect Mapping#
Map token tips to in-game effects across eight categories:
| Category | Examples |
|---|---|
VISUAL |
Screen-wide particle effects, colour shifts |
AUDIO |
Sound effects, music changes, voice effects |
GAMEPLAY |
Speed boosts, gravity changes, power-ups |
ENVIRONMENT |
Weather changes, time-of-day shifts, fog |
CHARACTER |
Costume changes, auras, size scaling |
SPAWN |
Spawn items, creatures, obstacles |
DEVICE |
Trigger haptic patterns on connected devices |
COMBO |
Compound effects combining multiple categories |
Effect rule configuration:
import type { TipEffectRule } from '@aphrodite/game-monetization';
const fireworksRule: TipEffectRule = {
ruleId: 'fireworks_500',
name: 'Fireworks Display',
description: 'Giant fireworks when someone tips 500+',
category: 'VISUAL',
// Tier requirements
minAmount: 500,
maxAmount: Infinity,
requiredTier: 'HUGE',
// Trigger behaviour
triggerMode: 'INSTANT', // fire immediately
baseParams: {
intensity: 0.9,
durationMs: 5000,
radius: 1.0, // full screen
count: 50, // 50 firework bursts
colour: '#FF4400',
},
// Scaling
scalingMode: 'LOGARITHMIC', // diminishing returns above threshold
// Cooldown
cooldownMs: 30000, // 30 second cooldown
maxStacks: 1,
priority: 10,
exclusive: false, // can combine with other effects
// Scheduling (optional)
activeFrom: null, // always active
activeUntil: null,
tags: ['celebration', 'visual'],
status: 'ACTIVE',
};
Trigger modes:
| Mode | Behaviour |
|---|---|
INSTANT |
Fire effect immediately on tip |
QUEUED |
Add to effect queue, play in order |
ACCUMULATE |
Accumulate tips until threshold, then trigger |
STACK |
Stack multiple instances (up to maxStacks) |
REPLACE |
Replace currently playing effect of same rule |
Scaling modes:
| Mode | Behaviour |
|---|---|
TIER_FIXED |
Fixed parameters per tier — no amount scaling |
LINEAR |
Parameters scale linearly with tip amount |
LOGARITHMIC |
Diminishing returns (good for large tips) |
EXPONENTIAL |
Accelerating returns (reward bigger tips) |
STEP |
Discrete jumps at tier boundaries |
9.4 Game Milestones#
Link tip goals to game milestones that unlock content when funded:
import type { GameMilestone } from '@aphrodite/game-monetization';
const bossBattle: GameMilestone = {
milestoneId: 'boss_1',
tipGoalId: 'goal_boss_fight', // links to @aphrodite/payments
name: 'Unlock Boss Battle',
description: 'Fund this goal to unlock an epic boss encounter!',
threshold: 5000, // 5000 tokens to unlock
currentAmount: 0,
progress: 0,
status: 'IN_PROGRESS',
// What happens when funded
rewardRuleIds: ['boss_spawn_effect', 'epic_music_change'],
unlockSceneId: 'boss_arena',
unlockModeId: 'boss_fight_mode',
environmentChange: {
weather: 'THUNDERSTORM',
timeOfDay: 'DUSK',
},
expiresAt: 0, // no expiry
};
Milestone statuses:
| Status | Description |
|---|---|
LOCKED |
Not yet available |
IN_PROGRESS |
Accepting contributions |
FUNDED |
Threshold reached, awaiting activation |
ACTIVATED |
Rewards deployed in game |
EXPIRED |
Time limit reached without funding |
CANCELLED |
Manually cancelled by performer |
9.5 Milestone Chains#
Link milestones into ordered chains for progressive unlocks:
import type { MilestoneChain } from '@aphrodite/game-monetization';
const dungeonChain: MilestoneChain = {
chainId: 'dungeon_progression',
name: 'Dungeon Crawl',
milestoneIds: ['unlock_floor_1', 'unlock_floor_2', 'unlock_boss'],
sequential: true, // must complete in order
chainCompleteRuleId: 'dungeon_complete_celebration',
};
9.6 Revenue Thresholds#
Trigger effects when cumulative session revenue crosses defined thresholds:
import type { RevenueThreshold } from '@aphrodite/game-monetization';
const thresholds: RevenueThreshold[] = [
{
thresholdId: 'bronze',
amount: 1000,
label: 'Bronze',
crossed: false,
crossedAt: null,
rewardRuleIds: ['bronze_celebration'],
},
{
thresholdId: 'silver',
amount: 5000,
label: 'Silver',
crossed: false,
crossedAt: null,
rewardRuleIds: ['silver_celebration'],
},
{
thresholdId: 'gold',
amount: 10000,
label: 'Gold',
crossed: false,
crossedAt: null,
rewardRuleIds: ['gold_celebration'],
},
{
thresholdId: 'diamond',
amount: 25000,
label: 'Diamond',
crossed: false,
crossedAt: null,
rewardRuleIds: ['diamond_celebration'],
},
];
9.7 Revenue Event Bus#
All monetary events flow through the RevenueEventEmitter:
| Event Type | When |
|---|---|
TIP_RECEIVED |
Any tip lands |
TIP_GOAL_REACHED |
A tip goal hits its target |
TIP_GOAL_PROGRESS |
A contribution moves a goal forward |
MILESTONE_UNLOCKED |
A game milestone becomes funded |
EFFECT_TRIGGERED |
A tip effect fires |
SUBSCRIPTION_RECEIVED |
New or renewed subscription |
REVENUE_THRESHOLD |
Session revenue crosses a threshold |
SESSION_SUMMARY |
End-of-session revenue summary |
Monetisation event payload:
interface RevenueEvent {
eventId: string;
type: RevenueEventType;
timestamp: number;
sessionId: string;
sourceUserId: string;
sourceDisplayName: string;
amount: number;
tier: TipTier | null;
tipGoalId: string | null;
milestoneId: string | null;
effectInstanceId: string | null;
sessionRevenue: number; // cumulative total at this point
metadata: Record<string, unknown>;
}
9.8 Virtual Gifts#
| Property | Description |
|---|---|
name |
Display name of the gift |
iconUrl |
Static icon image |
animationUrl |
Animated version (if isAnimated) |
soundUrl |
Sound effect played on receipt |
price |
Token cost |
category |
basic, premium, exclusive, seasonal |
isLimited |
Limited-time availability |
availableUntil |
Expiry timestamp for seasonal/limited gifts |
9.9 Stream Goals#
Visible goals that viewers contribute toward:
interface StreamGoal {
id: string;
streamId: string;
title: string; // 'Unlock Hard Mode'
description: string;
targetAmount: number; // tokens needed
currentAmount: number; // tokens received
reward: string; // what happens when funded
}
9.10 Game Monetisation Events#
The full event surface from GameMonetizationEvents:
| Event | Payload |
|---|---|
tipProcessed |
tipperId, displayName, amount, tier, sessionRevenue |
effectTriggered |
instance (TipEffectInstance), rule (TipEffectRule) |
effectEnded |
instanceId, ruleId |
effectAccumulated |
ruleId, currentAmount, threshold |
effectStacked |
instanceId, stacks, maxStacks |
milestoneProgress |
milestone, previousAmount |
milestoneUnlocked |
milestone |
milestoneActivated |
milestone |
milestoneChainCompleted |
chain |
revenueThresholdCrossed |
threshold, sessionRevenue |
revenueEvent |
event (RevenueEvent) |
sessionSummary |
totalRevenue, tipCount, uniqueTippers, tierBreakdown, topTipper |
10. Gallery & Photo Mode#
10.1 Photo Mode#
The @aphrodite/scene-gallery library provides a full photo mode for capturing
promotional images and viewer-facing content during gaming sessions.
Photo filters:
| Filter | Effect |
|---|---|
NONE |
No filter |
WARM |
Golden tones, increased warmth |
COOL |
Blue tones, cooler temperature |
DRAMATIC |
High contrast, deep shadows |
VINTAGE |
Desaturated, grain, vignette |
NOIR |
Black and white with deep contrast |
VIVID |
Boosted saturation and vibrancy |
PASTEL |
Soft, light, muted colours |
SEPIA |
Classic sepia tone |
CINEMATIC |
Film-like colour grading |
GOLDEN_HOUR |
Warm sunset lighting simulation |
MOONLIT |
Cool, silvery moonlight effect |
CYBERPUNK |
Neon-tinted, high saturation |
ETHEREAL |
Dreamy, glowing, soft focus |
Depth of field configuration:
| Setting | Description |
|---|---|
focalDistance |
Distance to focus plane |
aperture |
f-stop (lower = more blur) |
focalLength |
Lens focal length (mm) |
bokehShape |
Shape of out-of-focus highlights |
blurRadius |
Maximum blur amount |
10.2 Capture Settings#
| Format | Quality Range | Best for |
|---|---|---|
PNG |
Lossless | Maximum quality, large files |
JPEG |
0.0 – 1.0 | Good balance, web sharing |
WEBP |
0.0 – 1.0 | Small files, modern browsers |
AVIF |
0.0 – 1.0 | Best compression, newer |
TIFF |
Lossless | Professional/archival |
Resolution presets:
| Preset | Resolution |
|---|---|
STANDARD |
1920 × 1080 |
HIGH |
3840 × 2160 |
ULTRA |
7680 × 4320 |
CUSTOM |
User-defined |
10.3 Gallery Management#
- Albums with cover images, tagging, and metadata
- Query by tags, album, rating, date range, format
- Sorting by date, rating, name, file size
- Pagination for large collections
10.4 Social Sharing#
Platform-specific export optimisation:
| Platform | Max Dimensions | Format | Notes |
|---|---|---|---|
TWITTER |
Platform limit | JPEG/PNG | Auto-cropped to ratio |
INSTAGRAM |
Platform limit | JPEG | Square/portrait options |
FACEBOOK |
Platform limit | JPEG/PNG | Multiple aspect ratios |
DISCORD |
Platform limit | PNG/WEBP | Higher quality allowed |
PINTEREST |
Platform limit | JPEG/PNG | Vertical orientation |
GENERIC |
Unconstrained | Any | Full quality |
Sharing includes: caption, hashtags, metadata inclusion toggle, and platform-aware aspect ratio cropping.
11. Performance Tuning#
11.1 Hardware Detection#
The @aphrodite/game-runtime SettingsManager automatically detects hardware
capabilities and assigns a tier:
import { SettingsManager } from '@aphrodite/game-runtime';
const settings = new SettingsManager();
settings.detectHardware(adapterInfo);
// → classifies hardware into tier (low/medium/high/ultra)
// → applies appropriate quality preset
11.2 Genre-Aware Quality Profiles#
Each genre has tuned priority weights that trade off visual quality for performance:
| Genre | Target FPS | Priority Focus |
|---|---|---|
| FPS | 120 | Anti-aliasing, low latency, no motion blur |
| RPG | 60 | Draw distance, shadows, effects |
| Racing | 60 | Motion blur, draw distance |
| Platformer | 60 | Effects, anti-aliasing |
| Puzzle | 30–60 | Post-processing, effects |
| Strategy | 30–60 | Draw distance, shadows |
| Horror | 60 | Shadows, atmosphere, post-processing |
| Fighting | 60 | Anti-aliasing, effects |
// Apply genre-specific optimisations
settings.setGenre('FPS');
// → adjusts all quality weights for framerate priority
11.3 Dynamic Quality Scaling#
Feed frame times for automatic adjustment:
// Each frame, report the time
settings.recordFrameTime(frameTimeMs);
// → auto-adjusts quality preset if performance target not met
Lock quality to prevent auto-scaling:
settings.lockQuality('HIGH');
11.4 Compositor Performance#
Monitor compositor frame statistics:
| Metric | Description | Target |
|---|---|---|
totalFrames |
Total frames composed | — |
droppedFrames |
Frames missed due to processing time | < 0.1% |
avgFrameTimeMs |
Average compositing time per frame | < 16.67 ms |
layerCount |
Active layers in composition | < 32 typical |
11.5 Settings Persistence#
Save and restore quality settings across sessions:
// Serialise to storage
const saved = settings.serialize();
localStorage.setItem('quality_settings', JSON.stringify(saved));
// Restore from storage
const loaded = JSON.parse(localStorage.getItem('quality_settings'));
settings.deserialize(loaded);
12. Session Lifecycle#
12.1 Complete Session Flow#
┌─────────────────────────────────────────────────────────────────┐
│ 1. PRE-SESSION SETUP │
│ ├── Create StreamSession (streaming-core) │
│ ├── Initialise Compositor + Adaptive Layout Engine │
│ ├── Register performer camera feed │
│ ├── Connect and configure devices │
│ ├── Select and load scene │
│ ├── Configure performer placement and lighting │
│ ├── Register monetisation rules (tip effects, milestones) │
│ ├── Set up animation triggers (tips, chat, viewer actions) │
│ └── Set genre → propagates to all subsystems │
├─────────────────────────────────────────────────────────────────┤
│ 2. GO LIVE │
│ ├── Start compositor pipeline │
│ ├── Begin streaming to output targets │
│ └── session.state → 'live' │
├─────────────────────────────────────────────────────────────────┤
│ 3. LIVE SESSION │
│ ├── Game events → device reactions, layout adaptation │
│ ├── Viewer tips → effect mapper → visual/audio/device effects│
│ ├── Chat commands → animation triggers → performer reactions │
│ ├── Viewer actions → follow/sub/raid animations │
│ ├── Biometric data → scene parameter changes │
│ ├── Game moments → adaptive layout adjustments │
│ ├── Milestone progress → unlock notifications │
│ ├── Revenue thresholds → celebration effects │
│ └── Photo mode captures → gallery │
├─────────────────────────────────────────────────────────────────┤
│ 4. END SESSION │
│ ├── session.state → 'ended' │
│ ├── Revenue event emitter → session summary │
│ ├── Analytics finalised (watch time, tips, interactions) │
│ ├── Compositor pipeline stopped │
│ └── Devices disconnected safely │
└─────────────────────────────────────────────────────────────────┘
12.2 Event Listeners for Session Management#
Key events to subscribe to during a session:
// Stream events
streamManager.on('viewer.joined', ({ viewerId, count }) => {
/* update UI */
});
streamManager.on('viewer.left', ({ viewerId, count }) => {
/* update UI */
});
streamManager.on('quality.changed', (metrics) => {
/* alert if degraded */
});
// Monetisation events
monetization.on('tipProcessed', ({ amount, tier, sessionRevenue }) => {
/* show tip */
});
monetization.on('milestoneUnlocked', ({ milestone }) => {
/* activate reward */
});
monetization.on('revenueThresholdCrossed', ({ threshold }) => {
/* celebrate */
});
monetization.on('sessionSummary', (summary) => {
/* display end-screen */
});
// Layout events
adaptiveLayout.on('layoutChanged', ({ layout, reason }) => {
/* log */
});
// Device events
reactionEngine.on('commandSent', ({ deviceId, command }) => {
/* log */
});
12.3 Viewer Analytics#
Track viewer engagement throughout the session:
| Metric | Description |
|---|---|
watchTime |
Total seconds watched |
chatMessages |
Messages sent by viewer |
tipsGiven |
Number of tips from viewer |
tipAmount |
Total tokens tipped by viewer |
interactions |
Total interaction events |
quality |
Average stream quality experienced |
buffering |
Buffering events count |
13. Troubleshooting#
Common Issues#
| Problem | Cause | Solution |
|---|---|---|
| Layout not adapting to genre | Genre not set on adaptive engine | Call adaptiveLayout.setGenre() after init |
| Device not responding to game events | Translation rule disabled or missing | Check rule enabled flag and event pattern |
| Tip effects not firing | Rule status is PAUSED/DISABLED |
Set rule status: 'ACTIVE' |
| Dropped compositor frames | Too many layers or effects | Reduce layer count, simplify effects chain |
| Camera failover not working | Failover config not set | Call feed.setFailoverConfig() with backup |
| Scene validation failing | Missing required layers or params | Run validateScene() and fix reported errors |
| Biometric mapping not responding | Mapping enabled: false |
Set enabled: true on the biometric mapping |
| Milestone stuck in FUNDED state | Not activated after funding | Call milestoneManager.activate(milestoneId) |
| Viewer device layout wrong | Device not detected | Call adaptiveLayout.setViewerDevice(device) |
| Photo capture failing | Resolution too high for GPU | Use STANDARD or HIGH resolution preset |
Performance Diagnostics#
- Check compositor stats —
compositor.getStats()for dropped frames - Check frame budget —
settings.recordFrameTime()for auto-scaling triggers - Check device latency — monitor
DeviceState.lastCommandtimestamps - Check effect queue — if effects are delayed, reduce
maxConcurrentAnimations - Check stream quality — monitor
quality.changedevents for degradation
14. Quick-Start Checklist#
Use this checklist to set up a gaming session:
Pre-Session#
- Create stream session with appropriate resolution/bitrate/FPS
- Initialise compositor (HD for most gaming, 4K for showcase)
- Choose layout preset (PIP for action games, SideBySide for slower games)
- Enable adaptive layout engine (reaction-focused for viewer-heavy sessions)
- Register primary camera with quality enhancement
- Register backup camera with failover config
- Set up background removal if needed
- Connect and test all haptic devices
- Select game genre to propagate settings to all subsystems
- Choose device reaction profile difficulty (casual/competitive/hardcore)
Scene Setup#
- Browse scene catalogue and select appropriate scene
- Customise environment (time of day, weather, season)
- Add/adjust post-processing effects
- Configure performer placement and lighting
- Set up biometric mappings (if sensors connected)
- Validate scene before going live
Monetisation#
- Configure tip effect rules (map tiers to game effects)
- Set up game milestones linked to tip goals
- Define revenue thresholds with celebration effects
- Create milestone chains for progressive unlocks
- Set up virtual gifts if using custom gifts
- Create visible stream goals
Viewer Interaction#
- Configure chat room settings (slow mode, subscribers only, etc.)
- Set up chat command animations
- Configure tip animation presets per tier
- Set up viewer action triggers (follow, subscribe, raid)
- Enable combo system with appropriate window and limits
- Set device control mode (tip_controlled, interactive, etc.)
Go Live#
- Start compositor pipeline
- Verify all feeds compositing correctly
- Begin streaming
- Monitor compositor stats for dropped frames
- Verify tip effects and chat commands work with test inputs
Post-Session#
- Review session summary (revenue, viewers, engagement)
- Export captured photos from gallery
- Save quality settings for next session