gamercomp/frontend/public/docs/CONTEXT_CATALOG.md

# Context Catalog

## Overview

26 game contexts that place avatars in themed scenarios.
3 categories: Vehicles (12), Costumes (10), Pure (4).

Each context defines:
- **Avatar Mode**: How much of the avatar is visible (HEAD_ONLY, HEAD_AND_SHOULDERS, UPPER_BODY, FULL_BODY)
- **Animations**: Available animation states for the avatar
- **Accessory Visibility**: Which avatar accessories (eyewear, headwear, effects) are visible
- **Effects**: Visual effects triggered by game states
- **Recommended For**: Game types that work well with this context

---

## Vehicle Contexts (12)

Vehicles place the avatar inside cockpits, vehicles, or as part of a flying/riding scenario.

---

### spaceship-cockpit

- **ID**: `spaceship-cockpit`
- **Mode**: HEAD_ONLY
- **Description**: Pilot a spacecraft through space
- **Background**: Dark space with animated starfield, cockpit interior frame with side panels
- **Foreground**: Cockpit glass with blue tint, HUD targeting reticle, control panel with blinking buttons, speed indicator
- **Animations**: idle, bob, celebrate, hurt
- **Effects**:
  - `boost`: Particle flames from rear
  - `damage`: Screen shake (intensity 5)
- **Accessory Visibility**: Eyewear visible, Headwear visible, Effects visible
- **Best For**: Space shooters, sci-fi games, arcade
- **Recommended Music**: Epic/Intense
- **Recommended Backgrounds**: Space, nebula, asteroid fields

---

### race-car

- **ID**: `race-car`
- **Mode**: HEAD_AND_SHOULDERS
- **Description**: Race at high speed on the track
- **Background**: Sky gradient, road rushing past with animated lane markers, speed lines on sides
- **Foreground**: Dashboard with curve, steering wheel, side mirrors with road reflections, speedometer and RPM gauges with animated needles
- **Animations**: idle, bob, celebrate, hurt, turn-left, turn-right
- **Effects**:
  - `accelerate`: Vertical blur
  - `drift`: Side particle effects
  - `damage`: Screen shake (intensity 8)
- **Accessory Visibility**: Eyewear visible, Headwear visible, Effects visible
- **Best For**: Racing games, driving simulations, arcade racers
- **Recommended Music**: Intense, electronic
- **Recommended Backgrounds**: Urban, track, highway

---

### airplane

- **ID**: `airplane`
- **Mode**: HEAD_AND_SHOULDERS
- **Description**: Fly through the clouds as a pilot
- **Background**: Sky gradient (blue), animated clouds streaming past, cockpit interior sides
- **Foreground**: Windshield frame with center divider, instrument panel with 5 gauges (animated needles), yoke/control column, altitude and heading displays
- **Animations**: idle, bob, celebrate, hurt
- **Effects**:
  - `turbulence`: Screen shake (intensity 3)
  - `dive`: Vertical blur
  - `damage`: Screen shake (intensity 10)
- **Accessory Visibility**: Eyewear visible, Headwear visible, Effects visible
- **Best For**: Flight simulators, arcade flyers
- **Recommended Music**: Adventurous, orchestral
- **Recommended Backgrounds**: Clouds, sky, mountains

---

### flappy-style

- **ID**: `flappy-style`
- **Mode**: HEAD_ONLY
- **Description**: Flap through obstacles as a flying character
- **Background**: Transparent (game provides its own)
- **Foreground**: Animated wing sprites on left and right sides with flapping motion, wing detail lines
- **Animations**: idle, flap, fall, hurt
- **Effects**:
  - `flap`: Vertical blur (intensity 2)
  - `fall`: Downward stretch
  - `damage`: Red flash
- **Accessory Visibility**: Eyewear visible, Headwear hidden, Effects visible
- **Best For**: Flappy-style games, casual mobile games, arcade
- **Recommended Music**: Playful, casual
- **Recommended Backgrounds**: Sky, pipes, obstacles

---

### tank

- **ID**: `tank`
- **Mode**: HEAD_ONLY
- **Description**: Command a battle tank
- **Background**: Military green interior with radial gradient, riveted panel details, side screens with static effect
- **Foreground**: Circular tank hatch frame with bolts, periscope view with crosshair at top, control panel with warning lights, ammo counter display
- **Animations**: idle, bob, celebrate, hurt, aim
- **Effects**:
  - `fire`: Yellow flash (intensity 10)
  - `rumble`: Screen shake (intensity 4)
  - `damage`: Screen shake (intensity 12)
- **Accessory Visibility**: Eyewear visible, Headwear visible, Effects visible
- **Best For**: Military shooters, strategy games, arcade combat
- **Recommended Music**: Intense, military
- **Recommended Backgrounds**: Battlefield, desert, urban warfare

---

### pacman-style

- **ID**: `pacman-style`
- **Mode**: HEAD_ONLY
- **Description**: Navigate mazes and eat pellets
- **Background**: Transparent (game provides maze)
- **Foreground**: Subtle mouth/chomp overlay effect
- **Animations**: idle, chomp, hurt, power
- **Effects**:
  - `chomp`: Scale pulse (rate 12)
  - `power`: Cyan glow
  - `damage`: Red flash
- **Accessory Visibility**: Eyewear hidden, Headwear hidden, Effects visible
- **Best For**: Maze games, arcade classics, retro games
- **Recommended Music**: Retro, chiptune
- **Recommended Backgrounds**: Maze walls, pellets

---

### hoverboard

- **ID**: `hoverboard`
- **Mode**: UPPER_BODY
- **Description**: Ride a futuristic hoverboard
- **Background**: Ground rushing beneath with speed lines, shadow beneath board
- **Foreground**: Animated hoverboard with hover glow effect, board body with gradient, cyan lights, hover jets with flicker
- **Animations**: idle, bob, celebrate, hurt, lean-left, lean-right, jump
- **Effects**:
  - `idle`: Bob motion (amplitude 3, rate 4)
  - `boost`: Cyan particle trail behind
  - `jump`: Upward stretch
  - `damage`: Screen shake (intensity 6)
- **Accessory Visibility**: Eyewear visible, Headwear visible, Effects visible
- **Best For**: Endless runners, racing games, arcade
- **Recommended Music**: Electronic, futuristic
- **Recommended Backgrounds**: City streets, futuristic

---

### jetpack

- **ID**: `jetpack`
- **Mode**: UPPER_BODY
- **Description**: Fly with a jetpack strapped to your back
- **Background**: Sky gradient, clouds below, jetpack unit behind avatar (main body, fuel gauge, exhaust nozzles)
- **Foreground**: Animated jet flames with flicker, smoke trail particles
- **Animations**: idle, bob, celebrate, hurt, boost
- **Effects**:
  - `idle`: Bob motion (amplitude 2, rate 2)
  - `boost`: Orange particle trail downward
  - `damage`: Screen shake (intensity 8)
- **Accessory Visibility**: Eyewear visible, Headwear visible, Effects visible
- **Best For**: Flying games, endless flyers, arcade shooters
- **Recommended Music**: Action, adventure
- **Recommended Backgrounds**: Sky, clouds, obstacles

---

### mech-suit

- **ID**: `mech-suit`
- **Mode**: HEAD_ONLY
- **Description**: Pilot a powerful mech suit
- **Background**: Mech interior with radial gradient, side screens (radar with sweep, system status), interior frame elements
- **Foreground**: Hexagonal chest window frame, HUD targeting brackets, control panel with joysticks, warning lights (blinking), status text
- **Animations**: idle, bob, celebrate, hurt
- **Effects**:
  - `walk`: Screen shake (intensity 2)
  - `fire`: Yellow flash
  - `damage`: Screen shake (intensity 10)
- **Accessory Visibility**: Eyewear hidden, Headwear hidden, Effects visible
- **Best For**: Mech combat, shooters, action games
- **Recommended Music**: Epic, industrial
- **Recommended Backgrounds**: City destruction, battlefield

---

### submarine

- **ID**: `submarine`
- **Mode**: HEAD_AND_SHOULDERS
- **Description**: Explore the depths in a submarine
- **Background**: Underwater gradient (dark blue), rising bubbles with wobble animation, submarine interior with pipes and joints
- **Foreground**: Circular porthole frame with rivets, glass reflection, water distortion overlay, control panel with depth gauge, pressure gauge, sonar ping effect, periscope controls
- **Animations**: idle, bob, celebrate, hurt
- **Effects**:
  - `idle`: Bob motion (amplitude 2, rate 1)
  - `pressure`: Distortion effect (intensity 3)
  - `damage`: Screen shake (intensity 6)
- **Accessory Visibility**: Eyewear visible, Headwear visible, Effects visible
- **Best For**: Underwater exploration, arcade games
- **Recommended Music**: Ambient, mysterious
- **Recommended Backgrounds**: Ocean depths, coral, sea creatures

---

### dragon-rider

- **ID**: `dragon-rider`
- **Mode**: FULL_BODY
- **Description**: Soar through the skies on a dragon
- **Background**: Sunset sky gradient, clouds, dragon neck with scales, animated wings (flapping), saddle beneath rider
- **Foreground**: Dragon horns and ears framing view, dragon body/tail below, dragon legs with claws
- **Animations**: idle, bob, celebrate, hurt, lean
- **Effects**:
  - `idle`: Bob motion (amplitude 5, rate 2)
  - `fireBreath`: Orange glow
  - `dive`: Vertical blur
  - `damage`: Screen shake (intensity 8)
- **Accessory Visibility**: Eyewear visible, Headwear visible, Effects visible
- **Best For**: Fantasy adventures, flying games, RPGs
- **Recommended Music**: Epic, fantasy orchestral
- **Recommended Backgrounds**: Mountains, castles, sky

---

### motorcycle

- **ID**: `motorcycle`
- **Mode**: FULL_BODY
- **Description**: Race on a high-speed motorcycle
- **Background**: Sunset sky, road with animated lane markers, environment blur on sides, motion blur lines
- **Foreground**: Full motorcycle with body, fuel tank with stripe, engine with details, exhaust pipes, front and rear wheels with spinning spokes, handlebars, mirrors, headlight, seat, wheel speed blur
- **Animations**: idle, bob, celebrate, hurt, lean-left, lean-right
- **Effects**:
  - `accelerate`: Vertical blur
  - `wheelie`: Rotation (-15 degrees)
  - `lean`: Rotation (20 degrees)
  - `damage`: Screen shake (intensity 8)
- **Accessory Visibility**: Eyewear visible, Headwear visible, Effects visible
- **Best For**: Racing games, endless runners, arcade action
- **Recommended Music**: Rock, intense
- **Recommended Backgrounds**: Highway, city streets

---

## Costume Contexts (10)

Costumes dress the avatar in themed outfits with props and accessories.

---

### knight-armor

- **ID**: `knight-armor`
- **Mode**: FULL_BODY
- **Description**: Medieval knight in shining armor
- **Costume Details**:
  - **Under Layer**: Flowing red cape with gold trim, silver chestplate with ridge details, leg armor (greaves) with knee guards, armored boots
  - **Over Layer**: Shoulder pauldrons with spikes, helmet with visor (eye slits), red helmet crest
- **Props**:
  - Sword (right hand): Silver blade, gold guard, leather handle
  - Shield (left arm): Silver with red emblem and gold cross
- **Animations**: idle, walk, attack, hurt, celebrate
- **Effects**:
  - `attack`: Silver slash
  - `hurt`: Orange sparks
- **Accessory Visibility**: Eyewear hidden (behind visor), Headwear visible (above helmet), Effects visible
- **Best For**: RPGs, medieval games, action adventures
- **Recommended Music**: Epic, heroic

---

### space-suit

- **ID**: `space-suit`
- **Mode**: FULL_BODY
- **Description**: Astronaut ready for space exploration
- **Costume Details**:
  - **Under Layer**: White suit body with blue accent stripes, oxygen pack on back with blinking lights, legs with stripes, magnetic boots
  - **Over Layer**: Transparent helmet bubble with reflection, helmet ring, blue accent dome, antenna with red tip, white gloves with blue centers
- **Props**: None
- **Animations**: idle, walk, attack, hurt, celebrate
- **Effects**:
  - `hurt`: Cyan sparks
- **Accessory Visibility**: Eyewear visible (through helmet), Headwear visible (above helmet), Effects visible
- **Best For**: Action games, adventure, physics puzzles
- **Recommended Music**: Ambient, electronic

---

### ninja-outfit

- **ID**: `ninja-outfit`
- **Mode**: FULL_BODY
- **Description**: Stealthy ninja warrior
- **Costume Details**:
  - **Under Layer**: Black body suit, katana on back (scabbard with red handle wrap, gold guard), gray belt with throwing stars, black leg wraps, tabi boots (split-toe)
  - **Over Layer**: Black arm wraps, face mask covering lower face, red headband with flowing tail (animated)
- **Props**:
  - Katana (on back)
- **Animations**: idle, walk, attack, hurt, celebrate
- **Effects**:
  - `attack`: Dark slash
  - `hurt`: Gray smoke
- **Accessory Visibility**: Eyewear visible (through eye slit), Headwear hidden (mask covers), Effects visible
- **Best For**: Action games, stealth adventures, RPGs
- **Recommended Music**: Tense, mysterious

---

### wizard-robes

- **ID**: `wizard-robes`
- **Mode**: FULL_BODY
- **Description**: Mystical wizard with flowing robes
- **Costume Details**:
  - **Under Layer**: Dark blue flowing robe (animated), inner fold, leather belt with gold buckle, side pouches, glowing purple runes on fabric (pulsing)
  - **Over Layer**: Wide sleeves, hood/collar, staff in right hand
- **Props**:
  - Staff (right hand): Brown wooden shaft, purple orb with glow effect
- **Animations**: idle, walk, attack, hurt, celebrate
- **Effects**:
  - `attack`: Purple magic burst
  - `celebrate`: Gold sparkles
- **Accessory Visibility**: Eyewear visible, Headwear visible (optional wizard hat), Effects visible
- **Best For**: RPGs, puzzle games, adventures
- **Recommended Music**: Mystical, fantasy

---

### superhero-cape

- **ID**: `superhero-cape`
- **Mode**: FULL_BODY
- **Description**: Classic superhero with billowing cape
- **Costume Details**:
  - **Under Layer**: Billowing cape (animated with waves), bodysuit in avatar's clothing color, gold belt with white buckle, colored trunks, legs in suit color, colored boots with gold tops
  - **Over Layer**: Suit arms, colored gloves with gold cuffs, gold chest emblem (star shape), colored mask with white eye holes
- **Props**: None
- **Animations**: idle, walk, attack, hurt, celebrate
- **Effects**:
  - `attack`: Yellow impact burst
  - `celebrate`: Gold sparkles
- **Accessory Visibility**: Eyewear visible (as mask), Headwear visible, Effects visible
- **Best For**: Action games, adventure
- **Recommended Music**: Heroic, triumphant

---

### athlete-uniform

- **ID**: `athlete-uniform`
- **Mode**: FULL_BODY
- **Description**: Athletic sports uniform with number 23
- **Costume Details**:
  - **Under Layer**: Red jersey with white stripes, number 23 on back, dark shorts with red side stripes, exposed legs, white socks with red stripes, black athletic shoes with red accents
  - **Over Layer**: Red sleeves with white stripes, red headband, white wristbands, small number 23 on front
- **Props**:
  - Ball (optional, right arm)
- **Animations**: idle, walk, attack, hurt, celebrate
- **Effects**:
  - `celebrate`: Gold confetti
- **Accessory Visibility**: Eyewear visible, Headwear visible, Effects visible
- **Best For**: Sports games, action, racing
- **Recommended Music**: Energetic, pump-up

---

### pirate-outfit

- **ID**: `pirate-outfit`
- **Mode**: FULL_BODY
- **Description**: Swashbuckling pirate captain
- **Costume Details**:
  - **Under Layer**: Dark red long coat (animated back), white ruffled shirt, leather belt with gold buckle, dark pants, brown boots with folded tops
  - **Over Layer**: Coat front panels with gold trim and buttons, cutlass in right hand (curved blade, gold guard, leather handle), black tricorn hat with gold trim and skull emblem
- **Props**:
  - Cutlass (right hand)
- **Animations**: idle, walk, attack, hurt, celebrate
- **Effects**:
  - `attack`: Silver slash
- **Accessory Visibility**: Eyewear visible (eyepatch optional), Headwear visible, Effects visible
- **Best For**: Adventure games, action, RPGs
- **Recommended Music**: Adventurous, sea shanty

---

### scientist-labcoat

- **ID**: `scientist-labcoat`
- **Mode**: FULL_BODY
- **Description**: Mad scientist ready to experiment
- **Costume Details**:
  - **Under Layer**: Blue shirt with dark tie, dark gray pants, brown sensible shoes
  - **Over Layer**: White lab coat (open front with collar), sleeves, pocket protector with colored pens (blue, red, black), ID badge with photo, safety goggles on forehead
- **Props**:
  - Beaker (right hand): Glass container with bubbling green liquid and animated bubbles
- **Animations**: idle, walk, attack, hurt, celebrate
- **Effects**:
  - `attack`: Green bubbles
- **Accessory Visibility**: Eyewear visible (can wear both goggles and glasses), Headwear visible, Effects visible
- **Best For**: Puzzle games, physics games, creative games
- **Recommended Music**: Quirky, experimental

---

### chef-outfit

- **ID**: `chef-outfit`
- **Mode**: FULL_BODY
- **Description**: Master chef ready to cook
- **Costume Details**:
  - **Under Layer**: White double-breasted chef jacket with buttons, white apron with strings and pocket, dark pants, black shoes
  - **Over Layer**: White sleeves, red kitchen towel over shoulder with white stripes, tall white chef hat (toque) with puffy top, utensils in apron pocket
- **Props**:
  - Spatula (right hand): Brown handle, metal slotted head
- **Animations**: idle, walk, attack, hurt, celebrate
- **Effects**: None
- **Accessory Visibility**: Eyewear visible, Headwear visible (under chef hat), Effects visible
- **Best For**: Cooking games, creative games, puzzle
- **Recommended Music**: Upbeat, cheerful

---

### cowboy-gear

- **ID**: `cowboy-gear`
- **Mode**: FULL_BODY
- **Description**: Wild west cowboy
- **Costume Details**:
  - **Under Layer**: Tan shirt with pointed collar, brown vest, leather belt with large gold oval buckle, blue jeans with seam details, brown cowboy boots with heels and silver spurs
  - **Over Layer**: Tan sleeves, red bandana around neck with knot and animated tails, brown cowboy hat with curved brim and gold buckle on band
- **Props**:
  - Lasso (right hand, optional)
- **Animations**: idle, walk, attack, hurt, celebrate
- **Effects**: None
- **Accessory Visibility**: Eyewear visible, Headwear visible (under hat), Effects visible
- **Best For**: Western action, adventure games
- **Recommended Music**: Western, country

---

## Pure Contexts (4)

Pure contexts apply minimal modifications to the avatar, using only effects and subtle accessories. Avatar is fully visible in FULL_BODY mode.

---

### platformer-standard

- **ID**: `platformer-standard`
- **Mode**: FULL_BODY
- **Description**: Standard platforming character with no costume modifications
- **Modifications**: Dynamic shadow, dust effects only
- **Visual Effects**:
  - Shadow beneath avatar (scales with elevation)
  - Launch dust when jumping starts
  - Landing impact dust when touching ground
  - Running dust puffs
  - Circling stars when hurt
  - Celebratory confetti
- **Animations**: idle, walk, run, jump, fall, crouch, hurt, celebrate
- **State Effects**:
  - `running`: Dust puffs (frequency 0.1)
  - `jumping`: Launch dust (once)
  - `landing`: Impact dust (once)
  - `hurt`: Stars around head (duration 0.5s)
  - `celebrating`: Confetti (duration 3.0s)
- **Accessory Visibility**: All visible
- **Best For**: Platformers, adventure games, action games
- **Recommended Music**: Playful, heroic

---

### sports-player

- **ID**: `sports-player`
- **Mode**: FULL_BODY
- **Description**: Athletic character with minimal sports equipment (jersey number 7)
- **Modifications**: Sweatband on forehead, jersey number on back
- **Visual Effects**:
  - Elongated court/field shadow
  - Speed lines when running fast (threshold 0.7)
  - Motion blur when jumping at speed
  - Sparkles when scoring
  - Impact flash when hurt
- **Animations**: idle, walk, run, jump, fall, crouch, hurt, celebrate, throw, catch, kick
- **State Effects**:
  - `running`: Speed lines (threshold 0.7)
  - `jumping`: Motion blur
  - `scoring`: Sparkles (duration 1.0s)
  - `hurt`: Flash (duration 0.3s)
  - `celebrating`: Sparkles (duration 2.0s)
- **Accessory Visibility**: All visible
- **Best For**: Sports games, basketball, soccer, tennis, racing
- **Recommended Music**: Energetic

---

### adventure-hero

- **ID**: `adventure-hero`
- **Mode**: FULL_BODY
- **Description**: Adventurous character with backpack and utility belt
- **Modifications**: Small brown backpack on back, thin utility belt with pouches
- **Visual Effects**:
  - Dynamic shadow based on light source
  - Subtle heroic glow when idle (pulsing gold)
  - Determination lines (golden speed lines) when running
  - Cape-like motion trails when jumping (blue trailing lines)
  - Discovery sparkle effect
  - Damage flash when hurt
- **Animations**: idle, walk, run, jump, fall, crouch, hurt, celebrate, climb, push, pull
- **State Effects**:
  - `idle`: Glow (continuous)
  - `running`: Determination lines (continuous)
  - `jumping`: Cape motion trails (continuous)
  - `discovering`: Sparkle (duration 1.5s)
  - `hurt`: Damage flash (duration 0.4s)
- **Accessory Visibility**: All visible
- **Best For**: Adventure games, puzzle games, exploration, lite RPGs
- **Recommended Music**: Adventurous

---

### runner

- **ID**: `runner`
- **Mode**: FULL_BODY
- **Description**: Streamlined character optimized for endless runner games
- **Modifications**: None (pure avatar)
- **Visual Effects**:
  - Motion-blurred shadow (trails behind based on speed)
  - Constant speed lines (intensity based on speed)
  - Intensified speed effect when accelerating
  - Air trail when jumping/falling
  - Wind-swept hair effect (wind lines from head)
  - Ground friction sparks when sliding
  - Pickup sparkle when collecting items
  - Stumble effect with shake lines when hurt
  - Stars for big hits
- **Avatar Position**: Slightly left (x: 0.4) to show forward space
- **Default Animation**: run (not idle)
- **Animations**: idle, run, jump, slide, fall, hurt, celebrate
- **State Effects**:
  - `running`: Speed lines (continuous)
  - `accelerating`: Intensified speed (continuous)
  - `jumping`: Air trail (continuous)
  - `sliding`: Sparks (continuous)
  - `collecting`: Sparkle (duration 0.5s)
  - `hurt`: Stumble effect (duration 0.6s)
- **Accessory Visibility**: All visible
- **Best For**: Endless runners, racing, speed games
- **Recommended Music**: Fast-paced, electronic

---

## Context Selection Guide

### By Game Type

| Game Type | Recommended Contexts |
|-----------|---------------------|
| Space shooter | spaceship-cockpit, mech-suit |
| Racing | race-car, motorcycle, hoverboard |
| Flying/Flappy | flappy-style, airplane, jetpack, dragon-rider |
| Platformer | platformer-standard, adventure-hero, superhero-cape |
| Endless Runner | runner, hoverboard, motorcycle |
| RPG | knight-armor, wizard-robes, ninja-outfit, adventure-hero |
| Sports | athlete-uniform, sports-player |
| Puzzle | platformer-standard, scientist-labcoat, wizard-robes |
| Cooking | chef-outfit |
| Western | cowboy-gear |
| Underwater | submarine, space-suit |
| Fantasy | dragon-rider, knight-armor, wizard-robes |
| Arcade/Retro | pacman-style, flappy-style, spaceship-cockpit |
| Military | tank, mech-suit |
| Stealth | ninja-outfit |
| Pirate/Adventure | pirate-outfit, adventure-hero |

### By Avatar Mode

| Mode | Contexts |
|------|----------|
| HEAD_ONLY | spaceship-cockpit, tank, pacman-style, mech-suit, flappy-style |
| HEAD_AND_SHOULDERS | race-car, airplane, submarine |
| UPPER_BODY | hoverboard, jetpack |
| FULL_BODY | dragon-rider, motorcycle, all costumes (10), all pure (4) |

### By Category

| Category | Count | Contexts |
|----------|-------|----------|
| Vehicle | 12 | spaceship-cockpit, race-car, airplane, flappy-style, tank, pacman-style, hoverboard, jetpack, mech-suit, submarine, dragon-rider, motorcycle |
| Costume | 10 | knight-armor, space-suit, ninja-outfit, wizard-robes, superhero-cape, athlete-uniform, pirate-outfit, scientist-labcoat, chef-outfit, cowboy-gear |
| Pure | 4 | platformer-standard, sports-player, adventure-hero, runner |

---

## API Usage

### Getting Context Information

```javascript
// Get all contexts
const allContexts = ContextCatalog.getAll();

// Get a specific context by ID
const context = ContextCatalog.getById('spaceship-cockpit');

// Get contexts by category
const vehicles = ContextCatalog.getByCategory('vehicle');
const costumes = ContextCatalog.getByCategory('costume');
const pure = ContextCatalog.getByCategory('pure');

// Get contexts by avatar mode
const headOnly = ContextCatalog.getByMode('HEAD_ONLY');
const fullBody = ContextCatalog.getByMode('FULL_BODY');

// Get recommended contexts for a game type
const rpgContexts = ContextCatalog.getRecommendedFor('rpg');
const racingContexts = ContextCatalog.getRecommendedFor('racing');

// Search contexts
const matches = ContextCatalog.search('knight');

// Filter contexts
const filtered = ContextCatalog.filter({
  category: 'costume',
  mode: 'FULL_BODY',
  gameType: 'rpg'
});

// Get random context
const random = ContextCatalog.getRandom();
const randomForType = ContextCatalog.getRandomForGameType('platformer');
```

### Applying Context to Avatar

```javascript
// Apply context to an avatar object
const avatarWithContext = ContextRenderer.apply(avatar, 'spaceship-cockpit');

// Render the avatar with context
ContextRenderer.render(avatarWithContext, ctx, x, y, {
  scale: 1.0,
  time: elapsedTime
});

// Trigger an animation
ContextRenderer.animate(avatarWithContext, 'celebrate');

// Update state for effects
ContextRenderer.setState(avatarWithContext, {
  running: true,
  speed: 0.8,
  facingRight: true
});
```

### Context Object Structure

```javascript
{
  id: 'context-id',
  name: 'Human Readable Name',
  category: 'vehicle' | 'costume' | 'pure',
  avatarMode: 'HEAD_ONLY' | 'HEAD_AND_SHOULDERS' | 'UPPER_BODY' | 'FULL_BODY',
  animations: ['idle', 'walk', 'attack', ...],
  defaultAnimation: 'idle',
  accessoryVisibility: {
    eyewear: true | false,
    headwear: true | false,
    effects: true | false
  },
  layerOrder: ['background', 'avatar', 'foreground'],
  recommendedFor: ['game-type-1', 'game-type-2'],
  description: 'Short description',
  avatarPosition: { x: 0.5, y: 0.5 },
  avatarScale: 1.0,
  props: [
    { id: 'prop-id', anchor: 'rightArm', offset: { x: 0, y: 0 } }
  ],
  contextEffects: {
    effectName: { type: 'effect-type', ... }
  },
  renderBackground: function(ctx, width, height, time, options) { ... },
  renderForeground: function(ctx, width, height, time, options) { ... },
  renderCostumeUnder: function(ctx, avatar, x, y, scale, transforms, time) { ... },
  renderCostumeOver: function(ctx, avatar, x, y, scale, transforms, time) { ... }
}
```

---

## Statistics

- **Total Contexts**: 26
- **Vehicle Contexts**: 12
- **Costume Contexts**: 10
- **Pure Contexts**: 4
- **Version**: 1.0.0
- **Last Updated**: 2026-02-05

---

## Source Files

- `/frontend/public/assets/avatar/contextCatalog.js` - Main catalog aggregator
- `/frontend/public/assets/avatar/contextRenderer.js` - Rendering engine
- `/frontend/public/assets/avatar/contexts/vehicles.js` - Vehicle context definitions (12)
- `/frontend/public/assets/avatar/contexts/costumes.js` - Costume context definitions (10)
- `/frontend/public/assets/avatar/contexts/pure.js` - Pure context definitions (4)