# Viewer Interaction Guide

Complete guide for viewers participating in interactive gaming sessions on the
Aphrodite platform. This document explains how to interact with games through
chat commands, token tips, virtual gifts, and device control — and describes
every effect viewers can trigger.

---

## Table of Contents

1. [Overview](#1-overview)
2. [Getting Started](#2-getting-started)
3. [Chat Commands](#3-chat-commands)
4. [Token Economy](#4-token-economy)
5. [Tip Effects & Tiers](#5-tip-effects--tiers)
6. [Power-Ups & Game Effects](#6-power-ups--game-effects)
7. [Virtual Gifts](#7-virtual-gifts)
8. [Stream Goals & Milestones](#8-stream-goals--milestones)
9. [Interactive Device Control](#9-interactive-device-control)
10. [Viewer Actions & Events](#10-viewer-actions--events)
11. [Combo System](#11-combo-system)
12. [Badges & Privileges](#12-badges--privileges)
13. [Reference Tables](#13-reference-tables)

---

## 1. Overview

Interactive gaming sessions on Aphrodite let viewers directly influence the
game, the performer, and the environment in real time. Every tip, chat command,
and viewer action can trigger visual effects, gameplay changes, haptic device
responses, and more.

### Ways to Interact

| Method                 | What it does                                           | Cost          |
| ---------------------- | ------------------------------------------------------ | ------------- |
| **Chat commands**      | Trigger performer animations (`!wave`, `!dance`)       | Free          |
| **Token tips**         | Fire visual effects, power-ups, boss spawns            | Tokens        |
| **Virtual gifts**      | Send animated gifts with sound effects                 | Tokens        |
| **Goal contributions** | Fund milestones that unlock game content               | Tokens        |
| **Device control**     | Control performer's connected devices via tips/sliders | Tokens / Free |
| **Viewer actions**     | Follow, subscribe, raid — each triggers effects        | Free / Sub    |

### How Effects Work

```
Viewer Action (tip, command, follow, etc.)
     │
     ├──► Animation System ──► Visual effect on screen
     │
     ├──► Game Engine ──► Power-up, obstacle, or boss spawn
     │
     ├──► Scene System ──► Weather change, lighting shift
     │
     ├──► Device Engine ──► Haptic feedback on performer's device
     │
     └──► Audio System ──► Sound effect, music change
```

Every effect is bounded by safety limits and cooldowns to prevent abuse and
ensure a comfortable experience for the performer.

---

## 2. Getting Started

### Joining a Session

When you enter a gaming stream, you are automatically tracked as a viewer. Your
presence contributes to:

- **Viewer count milestones** — the stream may trigger special effects at viewer
  count thresholds (10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000)
- **Analytics** — your watch time, messages, and interactions are tracked for
  session summaries

### What You Need

- **An account** to chat and use commands
- **Tokens** to tip, send gifts, or contribute to goals (purchased separately)
- **A subscription** (optional) to access subscriber-only commands and features

---

## 3. Chat Commands

Chat commands let you trigger performer animations for free. Type them in the
chat with the `!` prefix.

### Default Commands

| Command  | Animation       | Who can use | Cooldown   |
| -------- | --------------- | ----------- | ---------- |
| `!wave`  | Greeting wave   | Everyone    | 3 seconds  |
| `!dance` | Dance animation | Subscribers | 10 seconds |
| `!pose`  | Confident pose  | Subscribers | 5 seconds  |
| `!wink`  | Wink emote      | Everyone    | 3 seconds  |

### Command Rules

- **Prefix**: All commands start with `!` (case-insensitive)
- **Global cooldown**: 0.5 seconds between any two commands
- **Per-command cooldown**: Each command has its own cooldown timer
- **Queue**: If a command arrives during an active animation, it may be queued
  (up to 10 in the queue)
- **Combos**: Sending the same command rapidly triggers a combo counter (see
  [Combo System](#11-combo-system))

### Permission Levels

Commands may require a minimum role:

| Level          | Who qualifies               | Access                 |
| -------------- | --------------------------- | ---------------------- |
| **Viewer**     | Everyone                    | Basic commands         |
| **Subscriber** | Tier 1, 2, or 3 subscribers | Subscriber commands    |
| **VIP**        | Viewers with VIP status     | VIP-exclusive commands |
| **Moderator**  | Channel moderators          | Mod-only commands      |

Higher tiers may unlock additional commands or reduce cooldowns. Performers can
create custom commands with any permission level.

### Custom Commands

Performers may register custom chat commands specific to their session. These
follow the same rules as default commands but can trigger any animation or game
effect the performer has configured.

### Chat Settings

The performer controls chat settings that affect your messaging:

| Setting              | Effect on viewers                       |
| -------------------- | --------------------------------------- |
| **Slow mode**        | Minimum seconds between your messages   |
| **Subscribers only** | Only subscribers can send messages      |
| **Emote only**       | Only emotes/stickers allowed, no text   |
| **Links blocked**    | URLs are filtered from messages         |
| **Word filter**      | Certain words are automatically blocked |
| **Max length**       | Maximum characters per message          |
| **Auto-moderation**  | Automated filter for offensive content  |

---

## 4. Token Economy

Tokens are the platform currency used to tip performers, buy gifts, fund goals,
and trigger game effects.

### How Tokens Are Spent

| Transaction Type    | Description                              |
| ------------------- | ---------------------------------------- |
| `tip`               | Direct tip to the performer              |
| `gift`              | Send a virtual gift (animated or static) |
| `goal_contribution` | Contribute toward a visible stream goal  |
| `game_wager`        | Wager tokens on in-game outcomes         |
| `content_purchase`  | Purchase access to premium content       |
| `subscription`      | Subscribe to the performer's channel     |
| `private_show`      | Pay for a private session                |

### Tipping

When you send a tip:

1. Your tokens are deducted immediately
2. The tip is classified into a **tier** based on amount
3. Any matching **tip effects** fire automatically
4. The performer sees your username, amount, and optional message
5. You can tip **anonymously** to hide your name

### Transaction Status

| Status      | Meaning                         |
| ----------- | ------------------------------- |
| `completed` | Tokens transferred successfully |
| `pending`   | Processing (usually instant)    |
| `failed`    | Transaction could not complete  |
| `refunded`  | Tokens returned to your balance |
| `disputed`  | Under review                    |

---

## 5. Tip Effects & Tiers

Every tip is automatically classified into a tier. Higher tiers produce
stronger, longer-lasting effects.

### Tip Tier Table

| Tier       | Token Range | Colour           | Intensity | Duration |
| ---------- | ----------- | ---------------- | --------- | -------- |
| **Micro**  | 1 – 10      | Grey (#9E9E9E)   | 0.3×      | 0.5×     |
| **Small**  | 11 – 50     | Green (#4CAF50)  | 0.5×      | 0.75×    |
| **Medium** | 51 – 200    | Blue (#2196F3)   | 0.75×     | 1.0×     |
| **Large**  | 201 – 500   | Purple (#9C27B0) | 1.0×      | 1.25×    |
| **Huge**   | 501 – 1000  | Orange (#FF9800) | 1.5×      | 1.5×     |
| **Whale**  | 1001+       | Red (#F44336)    | 2.0×      | 2.0×     |

- **Intensity** scales the visual/audio power of the effect
- **Duration** scales how long the effect lasts
- **Colour** is displayed on the tip notification in chat

### Effect Categories

Tips can trigger effects across eight categories:

| Category        | What happens                                             |
| --------------- | -------------------------------------------------------- |
| **Visual**      | Particles, explosions, confetti, colour shifts on screen |
| **Audio**       | Sound effects, fanfares, music changes                   |
| **Gameplay**    | Power-ups, speed boosts, gravity changes                 |
| **Environment** | Weather shifts, time-of-day changes, fog, lighting       |
| **Character**   | Costume changes, glow auras, size scaling                |
| **Spawn**       | Spawn items, allies, obstacles, or bosses                |
| **Device**      | Trigger haptic patterns on performer's connected devices |
| **Combo**       | Compound effects combining multiple categories           |

### Effect Scaling Modes

Performers choose how effects scale with tip amount:

| Mode            | How it scales                                   |
| --------------- | ----------------------------------------------- |
| **Tier Fixed**  | Same intensity for all tips in the same tier    |
| **Linear**      | Smoothly increases with tip amount              |
| **Logarithmic** | Big jumps at lower tiers, diminishing at higher |
| **Exponential** | Small effect at low tips, dramatic at high tips |
| **Step**        | Discrete jumps at fixed points within each tier |

### Effect Trigger Modes

| Mode           | What happens                                       |
| -------------- | -------------------------------------------------- |
| **Instant**    | Fires immediately when you tip                     |
| **Queued**     | Added to a queue and plays in order                |
| **Accumulate** | Tips accumulate until a threshold triggers it      |
| **Stack**      | Stacks with existing effects (up to max stacks)    |
| **Replace**    | Replaces any currently playing effect of same type |

### Cooldowns and Limits

- **Per-effect cooldown**: Default 3 seconds (varies per effect)
- **Max concurrent effects**: 10 on screen simultaneously
- **Max stacks**: 5 per effect type
- **Max intensity**: Capped at 1.0 regardless of tip amount
- **Max duration**: 60 seconds per effect

---

## 6. Power-Ups & Game Effects

The performer can configure specific game-altering effects that viewers trigger
with tips. These fall into five categories.

### Buffs (Beneficial Power-Ups)

| Power-Up          | Min Tokens | Duration   | Effect                     |
| ----------------- | ---------- | ---------- | -------------------------- |
| **Speed Boost**   | 10         | 8 seconds  | 1.5× movement speed        |
| **Shield**        | 25         | 12 seconds | 3 hit points of protection |
| **Double Points** | 50         | 15 seconds | 2× score multiplier        |

Duration scales up with tip amount — a larger tip means a longer buff.

### Obstacles (Challenges)

| Power-Up         | Min Tokens | Duration  | Effect                   |
| ---------------- | ---------- | --------- | ------------------------ |
| **Gravity Flip** | 20         | 6 seconds | Flips gravity vertically |
| **Screen Shake** | 15         | 3 seconds | Shakes the game screen   |

Maximum 2 concurrent obstacles to keep the game playable.

### Boss Spawns

| Boss          | Token Range | Duration   | Difficulty                         | Cooldown  |
| ------------- | ----------- | ---------- | ---------------------------------- | --------- |
| **Mini Boss** | 100 – 499   | 30 seconds | 1.0× health, 1.5× reward           | 2 minutes |
| **Raid Boss** | 500+        | 60 seconds | 3.0× health, 5.0× reward, 3 phases | 5 minutes |

Boss spawns are dramatic events with significant cooldowns to keep them special.

### Spectacles (Visual Events)

| Spectacle           | Min Tokens | Duration  | Effect                         |
| ------------------- | ---------- | --------- | ------------------------------ |
| **Fireworks**       | 10         | 5 seconds | 50 burst particles, rainbow    |
| **Lightning Storm** | 50         | 8 seconds | 3 bolts/second, bright flashes |

Fireworks stack up to 3 times. Lightning Storm has a 15-second cooldown.

### Device Boosts

| Boost               | Min Tokens | Duration   | Effect                           |
| ------------------- | ---------- | ---------- | -------------------------------- |
| **Intensity Surge** | 25         | 10 seconds | 1.5× device intensity multiplier |
| **Pattern Change**  | 30         | 15 seconds | Switches to pulse pattern        |

Device boosts are capped at 0.9 maximum intensity for safety.

### Power-Up Limits

| Setting                  | Default    | Purpose                           |
| ------------------------ | ---------- | --------------------------------- |
| Max total active         | 5          | Concurrent power-ups on screen    |
| Global cooldown          | 2 seconds  | Between any two power-up triggers |
| Auto-activate            | Yes        | Triggers immediately on purchase  |
| Max queue size           | 10         | Queued power-ups waiting          |
| Announce to chat         | Yes        | Chat notification on trigger      |
| Boss spawn cooldown      | 60 seconds | Between boss spawn attempts       |
| Max concurrent obstacles | 2          | Simultaneous challenge effects    |

---

## 7. Virtual Gifts

Virtual gifts are animated items you send to the performer. Each gift has a
unique visual and sound effect.

### Gift Properties

| Property      | Description                           |
| ------------- | ------------------------------------- |
| **Name**      | Display name of the gift              |
| **Icon**      | Static icon shown in chat             |
| **Animation** | Animated version that plays on screen |
| **Sound**     | Sound effect played when received     |
| **Price**     | Token cost                            |

### Gift Categories

| Category      | Description                           | Price Range |
| ------------- | ------------------------------------- | ----------- |
| **Basic**     | Simple, everyday gifts                | Low         |
| **Premium**   | Higher-quality animations and effects | Medium      |
| **Exclusive** | Rare, limited-availability gifts      | High        |
| **Seasonal**  | Time-limited holiday/event gifts      | Varies      |

- **Limited gifts** are available only for a set period
- **Animated gifts** play a full-screen or overlay animation
- Gifts contribute to stream goals if applicable

---

## 8. Stream Goals & Milestones

### Stream Goals

Performers set visible goals that viewers collectively fund with token
contributions.

| Property        | Description                               |
| --------------- | ----------------------------------------- |
| **Title**       | What the goal unlocks (e.g., "Hard Mode") |
| **Description** | Details about the reward                  |
| **Target**      | Total tokens needed                       |
| **Progress**    | Current tokens contributed                |
| **Reward**      | What happens when fully funded            |

**Progress notifications** appear at 25%, 50%, 75%, and 90% of the target.

### Game Milestones

Milestones are goals linked to specific game events:

| Status          | Meaning                               |
| --------------- | ------------------------------------- |
| **Locked**      | Not yet available for contributions   |
| **In Progress** | Accepting contributions               |
| **Funded**      | Target reached, awaiting activation   |
| **Activated**   | Reward has been deployed in the game  |
| **Expired**     | Time ran out before funding completed |
| **Cancelled**   | Performer cancelled the milestone     |

### What Milestones Can Unlock

When a milestone is fully funded, it can trigger:

- **Scene changes** — swap to a new environment (e.g., boss arena)
- **Mode changes** — unlock a new game mode
- **Weather changes** — shift to thunderstorm, aurora, etc.
- **Effect chains** — fire a sequence of visual/audio effects
- **Boss encounters** — spawn a special boss fight

### Milestone Chains

Some milestones are chained in sequence — you must complete earlier milestones
before later ones become available:

```
Floor 1 (2000 tokens) → Floor 2 (3000 tokens) → Final Boss (5000 tokens)
```

Completing the entire chain triggers a special bonus celebration effect.

---

## 9. Interactive Device Control

In sessions with connected devices, viewers can interact with the performer's
hardware through tips and real-time controls.

### Device Control Modes

The performer selects the active control mode:

| Mode               | How viewers interact                                  |
| ------------------ | ----------------------------------------------------- |
| **Disabled**       | No viewer control — devices off or manual only        |
| **Tip-controlled** | Your tip amount maps to device intensity and duration |
| **Interactive**    | Real-time slider control (if enabled by performer)    |
| **Pattern**        | Devices run a preset pattern                          |

### Tip-Controlled Mode

When the performer enables tip-controlled devices:

1. You send a token tip
2. The tip amount determines **intensity** (higher tip = stronger)
3. The tip tier determines **duration** (higher tier = longer)
4. The device activates immediately with those parameters

### Device Commands

| Command   | What it does                          |
| --------- | ------------------------------------- |
| `vibrate` | Vibration at the tip-determined level |
| `rotate`  | Rotation at the tip-determined speed  |
| `pump`    | Pumping/inflate action                |
| `stroke`  | Linear stroke movement                |
| `pattern` | Activate a named haptic pattern       |

### Interactive Mode

When interactive mode is enabled, you may have access to real-time controls:

- **Intensity slider** — 0 to 100 scale
- **Pattern selection** — choose from available patterns
- **Direction control** — clockwise, counterclockwise, alternating

Available pattern categories for interactive control:

| Pattern      | Description                          |
| ------------ | ------------------------------------ |
| `steady`     | Constant intensity                   |
| `pulse`      | Rhythmic on/off pulsing              |
| `wave`       | Smooth sinusoidal waves              |
| `escalate`   | Gradually building intensity         |
| `random`     | Unpredictable variation              |
| `tease`      | Teasing low-intensity patterns       |
| `intense`    | High-intensity sustained patterns    |
| `music_sync` | Synchronised with game/session audio |
| `ambient`    | Subtle background-level effects      |

### Device Boost Effects

Viewers can also trigger device boosts via tips (see
[Power-Ups](#6-power-ups--game-effects)):

- **Intensity Surge** (25+ tokens) — multiplies current device intensity by 1.5×
  for 10 seconds
- **Pattern Change** (30+ tokens) — forces a new pattern for 15 seconds

### Safety

All device interactions are bounded by safety limits:

- Maximum intensity is capped at 0.9 for device boosts
- Maximum single-command duration is limited
- Cooldowns prevent rapid successive high-intensity commands
- The performer can emergency-stop all devices at any time

---

## 10. Viewer Actions & Events

Certain viewer lifecycle actions automatically trigger effects in the session.

### Action Triggers

| Action        | When it happens              | Typical effect             |
| ------------- | ---------------------------- | -------------------------- |
| **Follow**    | You follow the channel       | Welcome animation + sound  |
| **Subscribe** | You subscribe (any tier)     | Confetti + celebration     |
| **Gift Sub**  | You gift a sub to someone    | Special gift animation     |
| **Raid**      | You raid from another stream | Raid alert + visual effect |
| **Host**      | You host the stream          | Host acknowledgement       |
| **Share**     | You share to social media    | Share celebration          |

- Subscribe effects scale with tier — Tier 3 triggers a bigger celebration than
  Tier 1
- Gift subs may trigger multiplied effects based on the number of subs gifted
- Raids can carry a viewer count that impacts the milestone/threshold system

### Viewer Count Milestones

The session automatically triggers special effects when the viewer count crosses
these thresholds (upward crossings only):

| Viewers | Milestone        |
| ------- | ---------------- |
| 10      | First milestone  |
| 25      | Growing audience |
| 50      | Popular stream   |
| 100     | Crowd milestone  |
| 250     | Large audience   |
| 500     | Huge audience    |
| 1,000   | Thousand viewers |
| 2,500   | Major event      |
| 5,000   | Massive stream   |
| 10,000  | Legendary        |

Each threshold can trigger a unique visual effect configured by the performer.

---

## 11. Combo System

The combo system rewards rapid repeated interactions with escalating effects.

### How Combos Work

1. You (or multiple viewers) trigger the same effect type rapidly
2. A **combo counter** starts incrementing
3. Each combo level increases the visual intensity
4. The combo resets after the **combo window** expires

### Combo Settings

| Setting             | Default   | Description                        |
| ------------------- | --------- | ---------------------------------- |
| **Combo window**    | 5 seconds | Time to chain the next trigger     |
| **Max combo count** | 10        | Maximum combo multiplier           |
| **Enable combos**   | On        | Whether the combo system is active |

### Combo Interaction

- Combos work with both **tip effects** and **chat commands**
- Multiple viewers can contribute to the same combo chain
- The combo counter is visible on screen
- Higher combo counts produce more dramatic visual feedback

---

## 12. Badges & Privileges

### Badge Types

| Badge          | How you get it                    | Displayed as |
| -------------- | --------------------------------- | ------------ |
| **Subscriber** | Active subscription (Tier 1–3)    | Tier icon    |
| **VIP**        | Granted by performer/platform     | VIP icon     |
| **Moderator**  | Appointed by performer            | Mod icon     |
| **Top Tipper** | Highest tipper in current session | Crown icon   |
| **Verified**   | Platform-verified account         | Check icon   |
| **Custom**     | Performer-created badge           | Custom icon  |

### Subscriber Tiers

| Tier   | Benefits                                            |
| ------ | --------------------------------------------------- |
| Tier 1 | Subscriber badge, subscriber-only chat commands     |
| Tier 2 | All Tier 1 + additional commands, reduced cooldowns |
| Tier 3 | All Tier 2 + exclusive commands, priority queue     |

### Privilege Hierarchy

Privileges are cumulative — higher levels include all lower-level access:

```
Viewer → Subscriber → VIP → Moderator → Broadcaster
```

| Level      | Chat commands | Reduced cooldowns | Priority queue | Mod tools |
| ---------- | ------------- | ----------------- | -------------- | --------- |
| Viewer     | Basic only    | No                | No             | No        |
| Subscriber | Sub commands  | Some              | No             | No        |
| VIP        | VIP commands  | Yes               | Yes            | No        |
| Moderator  | All commands  | Yes               | Yes            | Yes       |

---

## 13. Reference Tables

### All Chat Message Types

| Type      | Description                     |
| --------- | ------------------------------- |
| `text`    | Standard text message           |
| `tip`     | Message attached to a token tip |
| `system`  | System notification             |
| `emote`   | Emote/sticker message           |
| `media`   | Image or video attachment       |
| `gift`    | Virtual gift notification       |
| `command` | Chat command (starts with `!`)  |

### All Token Transaction Types

| Type                | Description                 |
| ------------------- | --------------------------- |
| `tip`               | Direct tip to performer     |
| `content_purchase`  | Buy access to content       |
| `subscription`      | Subscribe to channel        |
| `private_show`      | Pay for private session     |
| `gift`              | Purchase a virtual gift     |
| `goal_contribution` | Contribute to a stream goal |
| `game_wager`        | Wager on game outcomes      |

### All Tip Tiers

| Tier   | Range    | Colour  | Intensity | Duration |
| ------ | -------- | ------- | --------- | -------- |
| Micro  | 1–10     | #9E9E9E | 0.3×      | 0.5×     |
| Small  | 11–50    | #4CAF50 | 0.5×      | 0.75×    |
| Medium | 51–200   | #2196F3 | 0.75×     | 1.0×     |
| Large  | 201–500  | #9C27B0 | 1.0×      | 1.25×    |
| Huge   | 501–1000 | #FF9800 | 1.5×      | 1.5×     |
| Whale  | 1001+    | #F44336 | 2.0×      | 2.0×     |

### All Effect Categories

| Category    | Effect type                                    |
| ----------- | ---------------------------------------------- |
| Visual      | Particles, explosions, confetti, colour shifts |
| Audio       | Sound effects, fanfares, music changes         |
| Gameplay    | Power-ups, speed boosts, gravity changes       |
| Environment | Weather, time-of-day, fog, lighting            |
| Character   | Costumes, auras, size changes                  |
| Spawn       | Items, creatures, obstacles, bosses            |
| Device      | Haptic patterns on performer's devices         |
| Combo       | Multiple categories combined                   |

### All Power-Up Types

| Power-Up        | Category  | Min Tokens | Duration   | Cooldown   |
| --------------- | --------- | ---------- | ---------- | ---------- |
| Speed Boost     | Buff      | 10         | 8 seconds  | Default    |
| Shield          | Buff      | 25         | 12 seconds | Default    |
| Double Points   | Buff      | 50         | 15 seconds | Default    |
| Gravity Flip    | Obstacle  | 20         | 6 seconds  | Default    |
| Screen Shake    | Obstacle  | 15         | 3 seconds  | Default    |
| Mini Boss       | Boss      | 100        | 30 seconds | 2 minutes  |
| Raid Boss       | Boss      | 500        | 60 seconds | 5 minutes  |
| Fireworks       | Spectacle | 10         | 5 seconds  | Default    |
| Lightning Storm | Spectacle | 50         | 8 seconds  | 15 seconds |
| Intensity Surge | Device    | 25         | 10 seconds | Default    |
| Pattern Change  | Device    | 30         | 15 seconds | 20 seconds |

### All Interactive Patterns

| Pattern      | Description              |
| ------------ | ------------------------ |
| `steady`     | Constant intensity       |
| `pulse`      | Rhythmic on/off          |
| `wave`       | Smooth sinusoidal        |
| `escalate`   | Gradually building       |
| `random`     | Unpredictable variation  |
| `tease`      | Low-intensity teasing    |
| `intense`    | High-intensity sustained |
| `music_sync` | Synced to audio          |
| `ambient`    | Subtle background level  |

### Viewer Count Milestones

| Threshold | Effect trigger            |
| --------- | ------------------------- |
| 10        | Small celebration         |
| 25        | Growing audience effect   |
| 50        | Popular stream effect     |
| 100       | Crowd celebration         |
| 250       | Large audience effect     |
| 500       | Huge audience celebration |
| 1,000     | Thousand viewer spectacle |
| 2,500     | Major event celebration   |
| 5,000     | Massive stream spectacle  |
| 10,000    | Legendary celebration     |
