# Performer Gaming Guide

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

1. [Overview](#1-overview)
2. [Session Setup](#2-session-setup)
3. [Compositor & Layout Configuration](#3-compositor--layout-configuration)
4. [Camera & Feed Management](#4-camera--feed-management)
5. [Device Configuration for Gaming](#5-device-configuration-for-gaming)
6. [Scene Selection & Customisation](#6-scene-selection--customisation)
7. [Performer Integration with Scenes](#7-performer-integration-with-scenes)
8. [Viewer Interaction Management](#8-viewer-interaction-management)
9. [Monetisation Setup](#9-monetisation-setup)
10. [Gallery & Photo Mode](#10-gallery--photo-mode)
11. [Performance Tuning](#11-performance-tuning)
12. [Session Lifecycle](#12-session-lifecycle)
13. [Troubleshooting](#13-troubleshooting)
14. [Quick-Start Checklist](#14-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`.

```typescript
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  |

```typescript
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     |

```typescript
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.) |

```typescript
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:**

```typescript
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:

```typescript
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

```typescript
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:**

```typescript
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:**

```typescript
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`.

```typescript
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:**

```typescript
import { createEmptyScene } from '@aphrodite/scene-composer';

const scene = createEmptyScene('My Gaming Scene', 'FANTASY');
```

**Adding layers:**

```typescript
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:**

```typescript
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:**

```typescript
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:**

```typescript
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:

```typescript
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

```typescript
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:

```typescript
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 |

```typescript
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          |

```typescript
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:**

```typescript
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:**

```typescript
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:**

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:**

```typescript
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:

```typescript
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:

```typescript
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                     |

```typescript
// 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:

```typescript
// Each frame, report the time
settings.recordFrameTime(frameTimeMs);
// → auto-adjusts quality preset if performance target not met
```

Lock quality to prevent auto-scaling:

```typescript
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:

```typescript
// 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:

```typescript
// 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

1. **Check compositor stats** — `compositor.getStats()` for dropped frames
2. **Check frame budget** — `settings.recordFrameTime()` for auto-scaling
   triggers
3. **Check device latency** — monitor `DeviceState.lastCommand` timestamps
4. **Check effect queue** — if effects are delayed, reduce
   `maxConcurrentAnimations`
5. **Check stream quality** — monitor `quality.changed` events 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
