Initial commit
This commit is contained in:
Allen
@@ -0,0 +1,266 @@
|
||||
# Adding New Assets
|
||||
|
||||
Guide for extending the GamerComp asset library.
|
||||
|
||||
## Adding New Music
|
||||
|
||||
### 1. Define Song in musicLibrary.js
|
||||
|
||||
```javascript
|
||||
{
|
||||
id: 'epic-21',
|
||||
name: 'Dawn of Heroes',
|
||||
mood: 'Epic',
|
||||
energy: 8,
|
||||
tempo: 130,
|
||||
key: 'G',
|
||||
scale: 'minor',
|
||||
tags: ['battle', 'adventure', 'cinematic'],
|
||||
desc: 'Triumphant orchestral piece for heroic moments',
|
||||
|
||||
// Instrument configuration
|
||||
synths: {
|
||||
melody: { type: 'AMSynth', options: { harmonicity: 2 } },
|
||||
bass: { type: 'FMSynth', options: { modulationIndex: 10 } },
|
||||
pad: { type: 'PolySynth', options: { voices: 4 } }
|
||||
},
|
||||
|
||||
// Effects chain
|
||||
fx: {
|
||||
reverb: { wet: 0.4, decay: 2 },
|
||||
delay: { wet: 0.2, time: '8n' }
|
||||
},
|
||||
|
||||
// Song sections with chord progressions
|
||||
sections: {
|
||||
intro: {
|
||||
chords: ['i', 'VI', 'III', 'VII'],
|
||||
duration: 8,
|
||||
instruments: ['pad']
|
||||
},
|
||||
verse: {
|
||||
chords: ['i', 'iv', 'VI', 'V'],
|
||||
duration: 16,
|
||||
instruments: ['melody', 'bass', 'pad']
|
||||
},
|
||||
chorus: {
|
||||
chords: ['VI', 'VII', 'i', 'i'],
|
||||
duration: 16,
|
||||
instruments: ['melody', 'bass', 'pad', 'drums']
|
||||
}
|
||||
},
|
||||
|
||||
// Section order
|
||||
form: ['intro', 'verse', 'chorus', 'verse', 'chorus', 'chorus']
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Update Catalog Stats
|
||||
|
||||
In `musicLibrary.js`, increment the count.
|
||||
|
||||
### 3. Test
|
||||
|
||||
```javascript
|
||||
MusicEngine.playSong('epic-21');
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Adding New Background Theme
|
||||
|
||||
### 1. Create Theme File
|
||||
|
||||
Create `themes/newtheme.js`:
|
||||
|
||||
```javascript
|
||||
(function(engine) {
|
||||
if (!engine) return;
|
||||
|
||||
engine.registerTheme('newtheme', {
|
||||
name: 'New Theme',
|
||||
description: 'Description of theme',
|
||||
|
||||
variants: {
|
||||
variant1: {
|
||||
meta: {
|
||||
name: 'Variant One',
|
||||
mood: 'wonder',
|
||||
tags: ['tag1', 'tag2'],
|
||||
description: 'Description',
|
||||
compatibleMusicMoods: ['Epic', 'Heroic'],
|
||||
recommendedFor: ['action', 'adventure']
|
||||
},
|
||||
colors: ['#000000', '#111111', '#222222', '#333333'],
|
||||
render: function(ctx, w, h, time, colors, opts) {
|
||||
// Background layer
|
||||
var gradient = ctx.createLinearGradient(0, 0, 0, h);
|
||||
gradient.addColorStop(0, colors[0]);
|
||||
gradient.addColorStop(1, colors[1]);
|
||||
ctx.fillStyle = gradient;
|
||||
ctx.fillRect(0, 0, w, h);
|
||||
|
||||
// Animated elements
|
||||
// Use 'time' for animation (seconds)
|
||||
}
|
||||
},
|
||||
|
||||
// Add 7 more variants for 8 total
|
||||
}
|
||||
});
|
||||
|
||||
})(window.BackgroundEngine);
|
||||
```
|
||||
|
||||
### 2. Add Script Include
|
||||
|
||||
In templates, add:
|
||||
```html
|
||||
<script src="/assets/backgrounds/themes/newtheme.js"></script>
|
||||
```
|
||||
|
||||
### 3. Update Catalog
|
||||
|
||||
Add to `THEME_VARIANTS` in `backgroundCatalog.js`.
|
||||
|
||||
### 4. Test
|
||||
|
||||
```javascript
|
||||
BackgroundEngine.render(ctx, 'newtheme', 'variant1', w, h, 0);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Adding New Avatar Accessory
|
||||
|
||||
### 1. Add to accessories.js
|
||||
|
||||
```javascript
|
||||
// In EYEWEAR, HEADWEAR, or EFFECTS array:
|
||||
{
|
||||
id: 'new-item',
|
||||
name: 'New Item',
|
||||
category: 'headwear',
|
||||
unlockLevel: 50,
|
||||
rarity: 'epic',
|
||||
zIndex: 10,
|
||||
anchor: 'top',
|
||||
offset: { x: 0, y: -15 },
|
||||
scale: 1.0,
|
||||
hasEffect: false,
|
||||
description: 'Description of item'
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Add Renderer in accessoryRenderer.js
|
||||
|
||||
```javascript
|
||||
// In appropriate RENDERERS object:
|
||||
'new-item': function(ctx, x, y, scale, color, time) {
|
||||
// Draw the accessory
|
||||
ctx.fillStyle = color || '#gold';
|
||||
ctx.beginPath();
|
||||
// ... drawing code
|
||||
ctx.fill();
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Test
|
||||
|
||||
```javascript
|
||||
AvatarSystem.equipAccessory(avatar, 'headwear', 'new-item');
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Adding New Avatar Context
|
||||
|
||||
### 1. Add to Appropriate File
|
||||
|
||||
For vehicles, add to `contexts/vehicles.js`:
|
||||
|
||||
```javascript
|
||||
{
|
||||
id: 'new-vehicle',
|
||||
name: 'New Vehicle',
|
||||
category: 'vehicle',
|
||||
avatarMode: 'HEAD_AND_SHOULDERS',
|
||||
animations: ['idle', 'hurt', 'celebrate'],
|
||||
defaultAnimation: 'idle',
|
||||
accessoryVisibility: { eyewear: true, headwear: true, effects: true },
|
||||
layerOrder: ['background', 'avatar', 'foreground'],
|
||||
recommendedFor: ['action', 'racing'],
|
||||
description: 'Description',
|
||||
|
||||
avatarPosition: { x: 0.5, y: 0.4 },
|
||||
avatarScale: 1.0,
|
||||
|
||||
renderBackground: function(ctx, w, h, time, state) {
|
||||
// Draw background
|
||||
},
|
||||
|
||||
renderForeground: function(ctx, w, h, time, state) {
|
||||
// Draw foreground overlay
|
||||
},
|
||||
|
||||
contextEffects: {
|
||||
hurt: { type: 'shake', intensity: 5 }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Update Catalog Mappings
|
||||
|
||||
In `contextCatalog.js`:
|
||||
- Add to `GAME_TYPE_CONTEXTS`
|
||||
- Will auto-aggregate via `getAll()`
|
||||
|
||||
### 3. Test
|
||||
|
||||
```javascript
|
||||
const awc = ContextRenderer.apply(avatar, 'new-vehicle');
|
||||
ContextRenderer.render(awc, ctx, x, y);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Adding New Preset
|
||||
|
||||
### 1. Add to presets.js
|
||||
|
||||
```javascript
|
||||
{
|
||||
id: 'style-theme-##',
|
||||
gameStyle: 'action-arcade',
|
||||
name: 'Preset Name',
|
||||
description: 'What this combination provides',
|
||||
music: { mood: 'Epic', energy: 8 },
|
||||
background: { theme: 'space', variant: 'nebula' },
|
||||
avatarContext: { mode: 'HEAD_ONLY', context: 'spaceship-cockpit' },
|
||||
colorPalette: 'space-blue',
|
||||
tags: ['tag1', 'tag2']
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Validate
|
||||
|
||||
```javascript
|
||||
const result = AssetCompatibility.validate(newPreset);
|
||||
console.log(result.score); // Should be > 70
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Guidelines
|
||||
|
||||
1. **Visual Testing**: Use asset-browser.html to preview
|
||||
2. **Compatibility**: Run `AssetCompatibility.validate()`
|
||||
3. **Performance**: Test animation at 60fps
|
||||
4. **Mobile**: Test touch interactions
|
||||
5. **Integration**: Test in actual game template
|
||||
|
||||
## File Size Guidelines
|
||||
|
||||
- Keep individual JS files under 100KB
|
||||
- Music library can be larger (songs are data)
|
||||
- Optimize render functions (no complex math in loops)
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,598 @@
|
||||
# GamerComp Asset Library
|
||||
|
||||
## Overview
|
||||
|
||||
The GamerComp Asset Library is a comprehensive procedural asset system providing:
|
||||
|
||||
- **160 Procedural Songs** - 8 moods x 20 songs each using Tone.js
|
||||
- **120 Procedural Backgrounds** - 15 themes x 8 variants using Canvas 2D
|
||||
- **Full Avatar System** - Mii-style customizable avatars with 45 accessories
|
||||
- **26 Game Contexts** - Place avatars in vehicles, costumes, or pure modes
|
||||
- **220 Presets** - Curated asset combinations for 11 game styles
|
||||
|
||||
All assets are procedurally generated - no external images or audio files needed.
|
||||
|
||||
---
|
||||
|
||||
## System Architecture
|
||||
|
||||
```
|
||||
+--------------------------------------------------------------------------------+
|
||||
| LAYER 4: ASSET MANAGER |
|
||||
| |
|
||||
| +----------------+ +----------------+ +-----------+ +----------------+ |
|
||||
| | assetManager.js| |assetCatalog.js | | presets.js| |compatibility.js| |
|
||||
| | (coordination) | |(unified query) | | (220) | | (validation) | |
|
||||
| +-------+--------+ +-------+--------+ +-----+-----+ +--------+-------+ |
|
||||
| | | | | |
|
||||
+-----------+-------------------+-----------------+-----------------+------------+
|
||||
| | | |
|
||||
v v v v
|
||||
+--------------------------------------------------------------------------------+
|
||||
| LAYER 3: CONTEXT SYSTEM |
|
||||
| |
|
||||
| +-------------+ +-------------+ +-------------+ +------------------+ |
|
||||
| | vehicles.js | | costumes.js | | pure.js | | contextRenderer | |
|
||||
| | (12) | | (10) | | (4) | | .js | |
|
||||
| +-------------+ +-------------+ +-------------+ +------------------+ |
|
||||
| |
|
||||
+--------------------------------------------------------------------------------+
|
||||
| | |
|
||||
v v v
|
||||
+--------------------------------------------------------------------------------+
|
||||
| LAYER 2: CONTENT LIBRARIES |
|
||||
| |
|
||||
| +------------------+ +------------------------+ +-----------------+ |
|
||||
| | musicLibrary.js | | 15 Background Theme | | avatarData.js | |
|
||||
| | (160 songs) | | Files (8 variants ea) | | accessories.js | |
|
||||
| +------------------+ +------------------------+ | (45 items) | |
|
||||
| | space.js nature.js | +-----------------+ |
|
||||
| | urban.js fantasy.js | |
|
||||
| | abstract.js retro.js | |
|
||||
| | indoor.js weather.js | |
|
||||
| | sports.js seasonal.js | |
|
||||
| | underwater.js sky.js | |
|
||||
| | mechanical.js spooky.js| |
|
||||
| | colorful.js | |
|
||||
| +------------------------+ |
|
||||
| |
|
||||
+--------------------------------------------------------------------------------+
|
||||
| | |
|
||||
v v v
|
||||
+--------------------------------------------------------------------------------+
|
||||
| LAYER 1: CORE ENGINES |
|
||||
| |
|
||||
| +------------------+ +--------------------+ +-------------------+ |
|
||||
| | MusicEngine | | BackgroundEngine | | AvatarSystem | |
|
||||
| | (Tone.js) | | (Canvas 2D) | | (Canvas 2D) | |
|
||||
| +------------------+ +--------------------+ +-------------------+ |
|
||||
| |
|
||||
+--------------------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Include Scripts
|
||||
|
||||
Scripts must be loaded in dependency order. Here is the recommended `<script>` order:
|
||||
|
||||
```html
|
||||
<!-- External dependency -->
|
||||
<script src="https://unpkg.com/tone@14.7.77/build/Tone.js"></script>
|
||||
|
||||
<!-- Layer 1: Core Engines -->
|
||||
<script src="/assets/music/musicEngine.js"></script>
|
||||
<script src="/assets/backgrounds/backgroundEngine.js"></script>
|
||||
<script src="/assets/backgrounds/effects.js"></script>
|
||||
<script src="/assets/avatar/avatarRenderer.js"></script>
|
||||
<script src="/assets/avatar/avatarSystem.js"></script>
|
||||
<script src="/assets/avatar/animations.js"></script>
|
||||
<script src="/assets/avatar/accessoryRenderer.js"></script>
|
||||
|
||||
<!-- Layer 2: Content Libraries -->
|
||||
<script src="/assets/music/musicLibrary.js"></script>
|
||||
<script src="/assets/music/moodCategories.js"></script>
|
||||
<script src="/assets/backgrounds/themes/space.js"></script>
|
||||
<script src="/assets/backgrounds/themes/nature.js"></script>
|
||||
<script src="/assets/backgrounds/themes/urban.js"></script>
|
||||
<script src="/assets/backgrounds/themes/fantasy.js"></script>
|
||||
<script src="/assets/backgrounds/themes/abstract.js"></script>
|
||||
<script src="/assets/backgrounds/themes/retro.js"></script>
|
||||
<script src="/assets/backgrounds/themes/indoor.js"></script>
|
||||
<script src="/assets/backgrounds/themes/weather.js"></script>
|
||||
<script src="/assets/backgrounds/themes/sports.js"></script>
|
||||
<script src="/assets/backgrounds/themes/seasonal.js"></script>
|
||||
<script src="/assets/backgrounds/themes/underwater.js"></script>
|
||||
<script src="/assets/backgrounds/themes/sky.js"></script>
|
||||
<script src="/assets/backgrounds/themes/mechanical.js"></script>
|
||||
<script src="/assets/backgrounds/themes/spooky.js"></script>
|
||||
<script src="/assets/backgrounds/themes/colorful.js"></script>
|
||||
<script src="/assets/backgrounds/backgroundCatalog.js"></script>
|
||||
<script src="/assets/avatar/avatarData.js"></script>
|
||||
<script src="/assets/avatar/accessories.js"></script>
|
||||
|
||||
<!-- Layer 3: Context System -->
|
||||
<script src="/assets/avatar/contexts/vehicles.js"></script>
|
||||
<script src="/assets/avatar/contexts/costumes.js"></script>
|
||||
<script src="/assets/avatar/contexts/pure.js"></script>
|
||||
<script src="/assets/avatar/contextCatalog.js"></script>
|
||||
<script src="/assets/avatar/contextRenderer.js"></script>
|
||||
|
||||
<!-- Layer 4: Asset Manager -->
|
||||
<script src="/assets/assetCatalog.js"></script>
|
||||
<script src="/assets/compatibility.js"></script>
|
||||
<script src="/assets/presets.js"></script>
|
||||
<script src="/assets/assetManager.js"></script>
|
||||
```
|
||||
|
||||
### 2. Initialize
|
||||
|
||||
```javascript
|
||||
AssetManager.initialize().then(function(stats) {
|
||||
console.log('Asset Library initialized:', stats);
|
||||
// {
|
||||
// music: { songs: 160 },
|
||||
// backgrounds: { count: 120 },
|
||||
// avatarContexts: { count: 26 },
|
||||
// presets: { count: 220 }
|
||||
// }
|
||||
});
|
||||
```
|
||||
|
||||
### 3. Get Recommendations
|
||||
|
||||
```javascript
|
||||
// Get AI-powered asset recommendations based on game description
|
||||
var recommendations = AssetManager.getRecommendations(
|
||||
'action-arcade', // Game style
|
||||
'space shooter with aliens', // Description/keywords
|
||||
'Epic' // Optional mood override
|
||||
);
|
||||
|
||||
// Returns top 3 recommendations with explanations
|
||||
// [
|
||||
// {
|
||||
// config: { music: {...}, background: {...}, avatarContext: {...} },
|
||||
// score: 85,
|
||||
// explanation: 'Epic high-energy music sets the mood; space nebula background...',
|
||||
// detectedTheme: 'space',
|
||||
// detectedMood: 'epic',
|
||||
// detectedMechanics: { mode: 'HEAD_ONLY', context: 'spaceship-cockpit' }
|
||||
// },
|
||||
// ...
|
||||
// ]
|
||||
```
|
||||
|
||||
### 4. Load Assets
|
||||
|
||||
```javascript
|
||||
await AssetManager.loadGameAssets({
|
||||
music: { mood: 'Epic', energy: 8 },
|
||||
background: { theme: 'space', variant: 'nebula' },
|
||||
avatarContext: { mode: 'HEAD_ONLY', context: 'spaceship-cockpit' }
|
||||
});
|
||||
|
||||
// Access loaded assets
|
||||
var assets = AssetManager.getLoadedAssets();
|
||||
// {
|
||||
// music: { id: 'epic_001', name: 'Siege of Thunder', ... },
|
||||
// background: { theme: 'space', variant: 'nebula', render: function(...) },
|
||||
// avatarContext: { mode: 'HEAD_ONLY', context: 'spaceship-cockpit' }
|
||||
// }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
| Benefit | Description |
|
||||
|---------|-------------|
|
||||
| **Zero External Dependencies** | Everything procedurally generated - no images, audio files, or CDN requirements |
|
||||
| **Consistent Style** | All assets designed to work together with unified color palettes and visual language |
|
||||
| **Intelligent Matching** | Compatibility system ensures good combinations with mood/theme/context scoring |
|
||||
| **Variety** | 220 presets provide instant diversity for any game style |
|
||||
| **Customizable** | Override any setting while keeping coherence through validation feedback |
|
||||
| **Lightweight** | All code compresses to ~150KB total (before gzip) |
|
||||
| **Offline-First** | Works without network after initial load |
|
||||
|
||||
---
|
||||
|
||||
## Asset Counts Summary
|
||||
|
||||
```
|
||||
+---------------------+--------+-----------------------------------------+
|
||||
| Category | Count | Details |
|
||||
+---------------------+--------+-----------------------------------------+
|
||||
| Music Songs | 160 | 8 moods x 20 songs each |
|
||||
| Background Variants | 120 | 15 themes x 8 variants each |
|
||||
| Avatar Accessories | 45 | Eyewear, headwear, effects, particles |
|
||||
| Game Contexts | 26 | 12 vehicles + 10 costumes + 4 pure |
|
||||
| Presets | 220 | 20 per game style x 11 game styles |
|
||||
| Game Styles | 11 | Action, Puzzle, Story, Racing, etc. |
|
||||
| Music Moods | 8 | Epic, Chill, Intense, Playful, etc. |
|
||||
| Background Themes | 15 | Space, Nature, Urban, Fantasy, etc. |
|
||||
| Color Palettes | 11 | Pre-defined harmonious color sets |
|
||||
+---------------------+--------+-----------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Music System
|
||||
|
||||
### Moods (8 total, 20 songs each)
|
||||
|
||||
| Mood | Energy Range | Description | Tags |
|
||||
|------|--------------|-------------|------|
|
||||
| **Epic** | 7-10 | Orchestral, triumphant, powerful | battle, hero, conquest |
|
||||
| **Chill** | 1-4 | Relaxed, ambient, peaceful | calm, zen, meditation |
|
||||
| **Intense** | 7-10 | Fast, aggressive, urgent | action, chase, combat |
|
||||
| **Playful** | 4-7 | Fun, bouncy, whimsical | happy, silly, cartoon |
|
||||
| **Mysterious** | 3-6 | Suspenseful, eerie, enigmatic | dark, secret, shadow |
|
||||
| **Heroic** | 6-9 | Triumphant, brave, noble | victory, champion, glory |
|
||||
| **Quirky** | 4-7 | Unusual, offbeat, eccentric | weird, wacky, unique |
|
||||
| **Ambient** | 1-4 | Atmospheric, floating, ethereal | space, dreamy, soft |
|
||||
|
||||
### Song Structure
|
||||
|
||||
Each song is defined with:
|
||||
- **id**: Unique identifier (e.g., `epic_001`)
|
||||
- **name**: Human-readable name
|
||||
- **mood**: One of the 8 mood categories
|
||||
- **energy**: 1-10 scale
|
||||
- **tempo**: BPM (60-180)
|
||||
- **key**: Musical key (C, D, E, etc.)
|
||||
- **scale**: Scale type (minor, major, dorian, phrygian, etc.)
|
||||
- **synths**: Lead, pad, and bass instrument types
|
||||
- **fx**: Reverb, delay, filter settings
|
||||
- **sections**: Intro, verse, chorus, bridge, outro with chord progressions
|
||||
- **form**: Section playback order
|
||||
|
||||
---
|
||||
|
||||
## Background System
|
||||
|
||||
### Themes (15 total, 8 variants each)
|
||||
|
||||
| Theme | Variants | Mood | Recommended For |
|
||||
|-------|----------|------|-----------------|
|
||||
| **space** | nebula, asteroidField, deepSpace, planets, spaceStation, warpSpeed, satellites, blackHole | wonder, epic | Shooters, Sci-Fi |
|
||||
| **nature** | forest, jungle, desert, mountains, ocean, underwater, waterfall, meadow | serene, peaceful | Adventure, Platformers |
|
||||
| **urban** | citySkyline, street, rooftop, neonDistrict, subway, park, mall, alley | energetic, gritty | Racing, Action |
|
||||
| **fantasy** | castle, dungeon, enchantedForest, floatingIslands, magicalLibrary, crystalCave, temple, tower | magical, wonder | RPG, Adventure |
|
||||
| **abstract** | geometricPatterns, gradients, particleFields, minimalist, waves, fractals, kaleidoscope, matrix | focused, trippy | Puzzle, Creative |
|
||||
| **retro** | pixelGrid, arcadeCabinet, crtEffects, vaporwave, scanlines, glitch, eightBit, synthwave | nostalgic, fun | Arcade, Classic |
|
||||
| **indoor** | laboratory, classroom, bedroom, kitchen, arcade, office, library, gym | cozy, focused | Puzzle, Educational |
|
||||
| **weather** | rain, snow, storm, sunset, sunrise, fog, lightning, aurora | atmospheric, dynamic | Adventure, Mood |
|
||||
| **sports** | stadium, raceTrack, court, field, arena, pool, gym, skatepark | energetic, competitive | Sports, Racing |
|
||||
| **seasonal** | springMeadow, autumnLeaves, winterWonderland, summerBeach, harvest, blossom, snowfall, tropical | nostalgic, themed | Casual, Seasonal |
|
||||
| **underwater** | coralReef, deepSea, kelpForest, submarine, shipwreck, abyss, iceCave, treasure | mysterious, serene | Adventure, Exploration |
|
||||
| **sky** | clouds, flyingHigh, hotAirBalloon, airplaneView, stratosphere, birdsEye, horizon, starfield | dreamy, free | Flying, Casual |
|
||||
| **mechanical** | gears, circuits, factory, robotFactory, conveyorBelts, pipes, steampunk, techLab | industrial, complex | Puzzle, Tech |
|
||||
| **spooky** | hauntedHouse, graveyard, darkForest, abandonedBuilding, crypt, manor, fog, shadows | eerie, tense | Horror-lite, Halloween |
|
||||
| **colorful** | rainbow, paintSplatter, candyWorld, disco, neon, tieDye, gradient, prism | vibrant, joyful | Kids, Casual |
|
||||
|
||||
---
|
||||
|
||||
## Avatar Context System
|
||||
|
||||
### Context Categories
|
||||
|
||||
#### Vehicles (12 contexts)
|
||||
Place your avatar inside vehicles with appropriate framing:
|
||||
|
||||
| Context | Avatar Mode | Description | Recommended For |
|
||||
|---------|-------------|-------------|-----------------|
|
||||
| spaceship-cockpit | HEAD_ONLY | Pilot view in spacecraft | Space shooters |
|
||||
| race-car | HEAD_AND_SHOULDERS | Racing car driver | Racing games |
|
||||
| airplane | HEAD_ONLY | Airplane pilot | Flying games |
|
||||
| flappy-style | HEAD_ONLY | Bird/flying creature | Flappy-type games |
|
||||
| tank | HEAD_ONLY | Tank commander | Action games |
|
||||
| pacman-style | FULL_BODY | Classic maze runner | Arcade games |
|
||||
| hoverboard | FULL_BODY | Futuristic board rider | Racing, Action |
|
||||
| jetpack | FULL_BODY | Jetpack flyer | Flying, Action |
|
||||
| mech-suit | HEAD_ONLY | Mech pilot | Action, Sci-Fi |
|
||||
| submarine | HEAD_AND_SHOULDERS | Sub commander | Underwater |
|
||||
| dragon-rider | FULL_BODY | Dragon mount | Fantasy, Adventure |
|
||||
| motorcycle | FULL_BODY | Motorcycle rider | Racing |
|
||||
|
||||
#### Costumes (10 contexts)
|
||||
Dress your avatar in themed outfits:
|
||||
|
||||
| Context | Avatar Mode | Description | Recommended For |
|
||||
|---------|-------------|-------------|-----------------|
|
||||
| knight-armor | FULL_BODY | Medieval knight | RPG, Adventure |
|
||||
| space-suit | FULL_BODY | Astronaut suit | Space, Sci-Fi |
|
||||
| ninja-outfit | FULL_BODY | Stealth ninja | Action, Stealth |
|
||||
| wizard-robes | FULL_BODY | Magic user | Fantasy, RPG |
|
||||
| superhero-cape | FULL_BODY | Superhero costume | Action |
|
||||
| athlete-uniform | FULL_BODY | Sports gear | Sports |
|
||||
| pirate-outfit | FULL_BODY | Pirate costume | Adventure |
|
||||
| scientist-labcoat | FULL_BODY | Lab scientist | Puzzle, Educational |
|
||||
| chef-outfit | FULL_BODY | Chef uniform | Cooking, Casual |
|
||||
| cowboy-gear | FULL_BODY | Western attire | Adventure |
|
||||
|
||||
#### Pure/Standard (4 contexts)
|
||||
Minimal modifications for classic gameplay:
|
||||
|
||||
| Context | Avatar Mode | Description | Recommended For |
|
||||
|---------|-------------|-------------|-----------------|
|
||||
| platformer-standard | FULL_BODY | Classic platformer | Platformers |
|
||||
| sports-player | FULL_BODY | Generic athlete | Sports |
|
||||
| adventure-hero | FULL_BODY | Generic adventurer | Adventure |
|
||||
| runner | FULL_BODY | Running character | Endless runners |
|
||||
|
||||
### Avatar Display Modes
|
||||
|
||||
```
|
||||
+----------------+ +-----------------------+ +-------------------+
|
||||
| HEAD_ONLY | | HEAD_AND_SHOULDERS | | FULL_BODY |
|
||||
| | | | | |
|
||||
| .---. | | .---. | | .---. |
|
||||
| ( o o ) | | ( o o ) | | ( o o ) |
|
||||
| '-.-' | | '-.-' | | '-.-' |
|
||||
| | | /| |\ | | /| |\ |
|
||||
| [Vehicle | | / | | \ | | / | | \ |
|
||||
| Cockpit] | | [Upper Body] | | / \ |
|
||||
| | | | | / \ |
|
||||
+----------------+ +-----------------------+ +-------------------+
|
||||
Used for: Used for: Used for:
|
||||
- Cockpits - Racing vehicles - Platformers
|
||||
- First-person - Seated contexts - Full character
|
||||
- Tight frames - Partial views - Action games
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Preset System
|
||||
|
||||
### Game Styles (11 total, 20 presets each)
|
||||
|
||||
| Style ID | Name | Description | Example Presets |
|
||||
|----------|------|-------------|-----------------|
|
||||
| action-arcade | Action/Arcade | Space shooters, platformers, fast action | Space Hero, Retro Runner, Tank Commander |
|
||||
| puzzle | Puzzle | Match-3, sliding, brain teasers | Zen Garden, Geometric Dreams, Candy Match |
|
||||
| story-adventure | Story Adventure | Visual novels, choose-your-adventure | Dragon's Quest, Enchanted Forest, Mystery Manor |
|
||||
| racing | Racing | Car racing, running, speed games | Speed Demon, Neon Racer, Desert Rally |
|
||||
| pet-simulator | Pet/Simulator | Virtual pets, farm games, life sim | Happy Farm, Pet Paradise, Garden Life |
|
||||
| trivia-quiz | Trivia/Quiz | Quiz shows, knowledge tests | Brain Challenge, Quiz Master, Fact Hunter |
|
||||
| music-rhythm | Music/Rhythm | Rhythm games, dance games | Disco Fever, Beat Drop, Neon Rhythm |
|
||||
| creative-drawing | Creative/Drawing | Drawing, design, art creation | Art Studio, Color Splash, Pixel Creator |
|
||||
| rpg-battle | RPG/Battle | Turn-based battles, dungeons | Dragon Slayer, Dark Dungeon, Hero's Quest |
|
||||
| sports | Sports | Ball games, athletics | Stadium Glory, Court King, Field Champion |
|
||||
| physics-pinball | Physics/Pinball | Pinball, physics puzzles | Pinball Wizard, Gravity Drop, Bounce Master |
|
||||
|
||||
### Preset Structure
|
||||
|
||||
Each preset defines a complete asset combination:
|
||||
|
||||
```javascript
|
||||
{
|
||||
id: "action-space-01",
|
||||
gameStyle: "action-arcade",
|
||||
name: "Space Hero",
|
||||
description: "Epic space battle with your avatar piloting a fighter",
|
||||
music: { mood: "Epic", energy: 9 },
|
||||
background: { theme: "space", variant: "nebula" },
|
||||
avatarContext: { mode: "HEAD_ONLY", context: "spaceship-cockpit" },
|
||||
colorPalette: "space-blue",
|
||||
tags: ["space", "shooter", "epic", "sci-fi"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Compatibility System
|
||||
|
||||
### Compatibility Levels
|
||||
|
||||
The system validates combinations across four levels:
|
||||
|
||||
| Level | Description |
|
||||
|-------|-------------|
|
||||
| **Excellent** | Perfect match, highly recommended |
|
||||
| **Good** | Works well together |
|
||||
| **Neutral** | Acceptable, no issues |
|
||||
| **Poor** | May feel disjointed, suggests alternatives |
|
||||
|
||||
### Mood-Background Compatibility Matrix
|
||||
|
||||
```
|
||||
| space | nature | urban | fantasy | spooky | colorful | retro |
|
||||
-------------|-------|--------|-------|---------|--------|----------|-------|
|
||||
Epic | E | G | G | E | N | N | N |
|
||||
Chill | N | E | P | N | P | G | N |
|
||||
Intense | G | N | E | N | G | P | G |
|
||||
Playful | N | E | P | N | P | E | E |
|
||||
Mysterious | N | G | G | E | E | P | P |
|
||||
Heroic | E | G | E | E | N | P | N |
|
||||
Quirky | P | G | N | N | P | E | E |
|
||||
Ambient | N | E | P | N | P | G | N |
|
||||
|
||||
E = Excellent, G = Good, N = Neutral, P = Poor
|
||||
```
|
||||
|
||||
### Validation API
|
||||
|
||||
```javascript
|
||||
// Validate a combination
|
||||
var result = AssetCompatibility.validate({
|
||||
music: { mood: 'Epic' },
|
||||
background: { theme: 'space' },
|
||||
avatarContext: { context: 'spaceship-cockpit' }
|
||||
});
|
||||
|
||||
// {
|
||||
// valid: true,
|
||||
// score: 95,
|
||||
// issues: []
|
||||
// }
|
||||
|
||||
// Get suggestions for improvement
|
||||
var suggestions = AssetCompatibility.suggestImprovements(config);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## System Files
|
||||
|
||||
### Complete File Listing
|
||||
|
||||
```
|
||||
/frontend/public/assets/
|
||||
|
|
||||
+-- assetManager.js ~45 KB Main coordinator, recommendations
|
||||
+-- assetCatalog.js ~12 KB Unified queries, game styles
|
||||
+-- compatibility.js ~35 KB Validation rules, suggestions
|
||||
+-- presets.js ~65 KB 220 preset definitions
|
||||
|
|
||||
+-- music/
|
||||
| +-- musicEngine.js ~25 KB Tone.js synthesis engine
|
||||
| +-- musicLibrary.js ~80 KB 160 song definitions
|
||||
| +-- moodCategories.js ~5 KB Mood metadata
|
||||
|
|
||||
+-- backgrounds/
|
||||
| +-- backgroundEngine.js ~15 KB Canvas 2D render engine
|
||||
| +-- backgroundCatalog.js ~8 KB Catalog queries
|
||||
| +-- effects.js ~10 KB Shared visual effects
|
||||
| +-- themes/
|
||||
| +-- space.js ~12 KB 8 space variants
|
||||
| +-- nature.js ~15 KB 8 nature variants
|
||||
| +-- urban.js ~12 KB 8 urban variants
|
||||
| +-- fantasy.js ~14 KB 8 fantasy variants
|
||||
| +-- abstract.js ~10 KB 8 abstract variants
|
||||
| +-- retro.js ~11 KB 8 retro variants
|
||||
| +-- indoor.js ~13 KB 8 indoor variants
|
||||
| +-- weather.js ~12 KB 8 weather variants
|
||||
| +-- sports.js ~11 KB 8 sports variants
|
||||
| +-- seasonal.js ~12 KB 8 seasonal variants
|
||||
| +-- underwater.js ~13 KB 8 underwater variants
|
||||
| +-- sky.js ~10 KB 8 sky variants
|
||||
| +-- mechanical.js ~11 KB 8 mechanical variants
|
||||
| +-- spooky.js ~12 KB 8 spooky variants
|
||||
| +-- colorful.js ~10 KB 8 colorful variants
|
||||
|
|
||||
+-- avatar/
|
||||
+-- avatarSystem.js ~20 KB Avatar management
|
||||
+-- avatarRenderer.js ~25 KB Canvas 2D avatar drawing
|
||||
+-- avatarData.js ~15 KB Customization options
|
||||
+-- accessories.js ~18 KB 45 accessory definitions
|
||||
+-- animations.js ~12 KB Animation system
|
||||
+-- accessoryRenderer.js ~10 KB Accessory drawing
|
||||
+-- contextCatalog.js ~8 KB Context queries
|
||||
+-- contextRenderer.js ~10 KB Context rendering
|
||||
+-- contexts/
|
||||
+-- vehicles.js ~45 KB 12 vehicle contexts
|
||||
+-- costumes.js ~50 KB 10 costume contexts
|
||||
+-- pure.js ~15 KB 4 standard contexts
|
||||
|
||||
Total: ~650 KB (uncompressed JavaScript)
|
||||
~150 KB (gzipped)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Music Catalog](MUSIC_CATALOG.md) - Complete song listing and synthesis details
|
||||
- [Background Catalog](BACKGROUND_CATALOG.md) - All themes and variants
|
||||
- [Avatar System](AVATAR_SYSTEM.md) - Customization options and rendering
|
||||
- [Context Catalog](CONTEXT_CATALOG.md) - Vehicle, costume, and pure contexts
|
||||
- [API Reference](API_REFERENCE.md) - Complete API documentation
|
||||
- [Preset Guide](PRESET_GUIDE.md) - Using and creating presets
|
||||
- [Game Generation Guide](GAME_GENERATION_GUIDE.md) - Integrating assets into games
|
||||
- [Adding New Assets](ADDING_NEW_ASSETS.md) - Extending the library
|
||||
|
||||
---
|
||||
|
||||
## Interactive Tools
|
||||
|
||||
- **[Asset Browser](/asset-browser.html)** - Visual exploration of all assets, preview combinations
|
||||
- **[Avatar Creator](/avatar-creator/index.html)** - Test avatar customization, try contexts
|
||||
|
||||
---
|
||||
|
||||
## API Quick Reference
|
||||
|
||||
### AssetManager
|
||||
|
||||
```javascript
|
||||
// Initialization
|
||||
AssetManager.initialize(options) // Promise - Initialize all systems
|
||||
AssetManager.isInitialized() // boolean - Check ready state
|
||||
|
||||
// Recommendations
|
||||
AssetManager.getRecommendations( // Array - Get top 3 recommendations
|
||||
gameStyle, keywords, mood
|
||||
)
|
||||
|
||||
// Detection Helpers
|
||||
AssetManager.detectTheme(keywords) // string - Detect theme from keywords
|
||||
AssetManager.detectMood(keywords) // string - Detect mood from keywords
|
||||
AssetManager.detectMechanics(keywords) // Object - Detect avatar mode/context
|
||||
|
||||
// Preset Lookup
|
||||
AssetManager.findPreset(gameStyle, index) // Object - Find preset by style
|
||||
AssetManager.presetToConfig(preset) // Object - Convert to config
|
||||
|
||||
// Asset Loading
|
||||
AssetManager.loadGameAssets(config) // Promise - Load assets
|
||||
AssetManager.getLoadedAssets() // Object - Get current assets
|
||||
|
||||
// Validation
|
||||
AssetManager.validateCombination(config) // Object - Validate compatibility
|
||||
|
||||
// Utilities
|
||||
AssetManager.describeAssets(config) // string - Human description
|
||||
AssetManager.getVariation(config, type) // Object - Get variation
|
||||
AssetManager.searchAssets(query) // Object - Search all assets
|
||||
AssetManager.getRandomCombination(style) // Object - Random combo
|
||||
|
||||
// Direct Subsystem Access
|
||||
AssetManager.music() // MusicEngine
|
||||
AssetManager.backgrounds() // BackgroundEngine
|
||||
AssetManager.avatars() // AvatarSystem
|
||||
AssetManager.contexts() // ContextRenderer
|
||||
AssetManager.catalog() // AssetCatalog
|
||||
AssetManager.presets() // AssetPresets
|
||||
AssetManager.compatibility() // AssetCompatibility
|
||||
```
|
||||
|
||||
### AssetCompatibility
|
||||
|
||||
```javascript
|
||||
// Validation
|
||||
validate(config) // Object - Full validation
|
||||
checkFullCompatibility(mood, theme, ctx) // Object - Quick check
|
||||
|
||||
// Compatibility Queries
|
||||
getMoodBackgroundCompat(mood, theme) // string - Compatibility level
|
||||
getThemeContextCompat(theme, context) // string - Compatibility level
|
||||
getContextAnimationCompat(context, anim) // string - Animation compat
|
||||
getPaletteHarmony(palette1, palette2) // string - Color harmony
|
||||
|
||||
// Suggestions
|
||||
getMusicForTheme(theme) // Array - Compatible moods
|
||||
getBackgroundsForMood(mood) // Array - Compatible themes
|
||||
getContextsForTheme(theme) // Array - Compatible contexts
|
||||
getContextsForMechanics(mechanics) // Array - Mechanics-based
|
||||
suggestImprovements(config) // Array - Improvement suggestions
|
||||
|
||||
// Animation Helpers
|
||||
getRequiredAnimations(context) // Array - Required anims
|
||||
getRecommendedAnimations(context) // Array - Recommended anims
|
||||
getValidAnimations(context) // Object - All animation info
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Version History
|
||||
|
||||
| Version | Date | Changes |
|
||||
|---------|------|---------|
|
||||
| 1.0.0 | 2026-02-05 | Initial release with full asset library |
|
||||
|
||||
---
|
||||
|
||||
*GamerComp Asset Library - Procedural Game Assets for Everyone*
|
||||
@@ -0,0 +1,734 @@
|
||||
# Avatar System
|
||||
|
||||
## Overview
|
||||
|
||||
Mii-style avatar system with full customization and level-based unlockable accessories. The system supports four rendering modes optimized for different game types, with smooth animations and real-time accessory rendering.
|
||||
|
||||
## Architecture
|
||||
|
||||
The avatar system consists of several modules:
|
||||
|
||||
| Module | File | Purpose |
|
||||
|--------|------|---------|
|
||||
| AvatarData | `avatarData.js` | Customization options and guest avatars |
|
||||
| AvatarSystem | `avatarSystem.js` | Main API for creation, rendering, accessories |
|
||||
| AvatarRenderer | `avatarRenderer.js` | Canvas 2D rendering engine |
|
||||
| AvatarAnimations | `animations.js` | Animation definitions per mode |
|
||||
| AvatarAccessories | `accessories.js` | Unlockable accessories catalog |
|
||||
| AccessoryRenderer | `accessoryRenderer.js` | Accessory rendering on avatars |
|
||||
|
||||
---
|
||||
|
||||
## Customization Options
|
||||
|
||||
### Face Shape (8 options)
|
||||
|
||||
| ID | Name | Description |
|
||||
|----|------|-------------|
|
||||
| `round` | Round | Circular face with soft jawline |
|
||||
| `oval` | Oval | Classic elongated oval shape |
|
||||
| `square` | Square | Strong angular jawline |
|
||||
| `heart` | Heart | Wide forehead, pointed chin |
|
||||
| `long` | Long | Narrow, elongated face |
|
||||
| `wide` | Wide | Broader face shape |
|
||||
| `angular` | Angular | Defined cheekbones, sharp features |
|
||||
| `soft` | Soft | Rounded features throughout |
|
||||
|
||||
### Skin Tone (20 options)
|
||||
|
||||
| ID | Name | Hex Code |
|
||||
|----|------|----------|
|
||||
| `fair1` | Porcelain | `#FFECD1` |
|
||||
| `fair2` | Ivory | `#FFE4C4` |
|
||||
| `fair3` | Peach | `#FFDAB9` |
|
||||
| `fair4` | Cream | `#FFD5B5` |
|
||||
| `light1` | Light Beige | `#F5D0A9` |
|
||||
| `light2` | Warm Beige | `#E8C49A` |
|
||||
| `light3` | Sand | `#DEB887` |
|
||||
| `medium1` | Golden | `#D4A373` |
|
||||
| `medium2` | Honey | `#C9A06A` |
|
||||
| `medium3` | Caramel | `#BC8F5F` |
|
||||
| `medium4` | Toffee | `#B07D4B` |
|
||||
| `tan1` | Tan | `#A67B5B` |
|
||||
| `tan2` | Bronze | `#996B4D` |
|
||||
| `tan3` | Cinnamon | `#8B6D4C` |
|
||||
| `brown1` | Chestnut | `#7D5A3C` |
|
||||
| `brown2` | Cocoa | `#6F4E37` |
|
||||
| `brown3` | Espresso | `#5D4532` |
|
||||
| `dark1` | Mocha | `#4E3B2D` |
|
||||
| `dark2` | Ebony | `#3D2B1F` |
|
||||
| `dark3` | Onyx | `#2C1F15` |
|
||||
|
||||
### Eye Shape (12 options)
|
||||
|
||||
| ID | Name | Description |
|
||||
|----|------|-------------|
|
||||
| `round` | Round | Large, circular eyes |
|
||||
| `almond` | Almond | Classic almond shape |
|
||||
| `oval` | Oval | Soft oval shape |
|
||||
| `narrow` | Narrow | Slim, elongated eyes |
|
||||
| `wide` | Wide | Broad, expressive eyes |
|
||||
| `droopy` | Droopy | Downturned outer corners |
|
||||
| `upturned` | Upturned | Lifted outer corners |
|
||||
| `cat` | Cat | Sharp upturned cat-eye |
|
||||
| `sleepy` | Sleepy | Heavy-lidded, relaxed look |
|
||||
| `surprised` | Surprised | Wide open, alert |
|
||||
| `angry` | Angry | Angled inward brow line |
|
||||
| `happy` | Happy | Slightly squinted, joyful |
|
||||
|
||||
### Eye Color (16 options)
|
||||
|
||||
| ID | Name | Hex Code |
|
||||
|----|------|----------|
|
||||
| `brown` | Brown | `#634E34` |
|
||||
| `darkBrown` | Dark Brown | `#3D2314` |
|
||||
| `hazel` | Hazel | `#8B7355` |
|
||||
| `green` | Green | `#3D7A3D` |
|
||||
| `blue` | Blue | `#4682B4` |
|
||||
| `lightBlue` | Light Blue | `#87CEEB` |
|
||||
| `gray` | Gray | `#708090` |
|
||||
| `amber` | Amber | `#B8860B` |
|
||||
| `violet` | Violet | `#8B008B` |
|
||||
| `emerald` | Emerald | `#50C878` |
|
||||
| `iceBlue` | Ice Blue | `#A5D8E6` |
|
||||
| `gold` | Gold | `#DAA520` |
|
||||
| `red` | Red | `#8B0000` |
|
||||
| `black` | Black | `#1A1A1A` |
|
||||
| `honey` | Honey | `#C9A06A` |
|
||||
| `turquoise` | Turquoise | `#40E0D0` |
|
||||
|
||||
**Total Eye Combinations**: 12 shapes x 16 colors = **192 unique eye options**
|
||||
|
||||
### Eyebrow Shape (10 options)
|
||||
|
||||
| ID | Name | Description |
|
||||
|----|------|-------------|
|
||||
| `natural` | Natural | Balanced, standard arch |
|
||||
| `arched` | Arched | High dramatic arch |
|
||||
| `straight` | Straight | Flat, horizontal brows |
|
||||
| `thick` | Thick | Full, bold brows |
|
||||
| `thin` | Thin | Delicate, fine brows |
|
||||
| `angry` | Angry | Angled down toward center |
|
||||
| `worried` | Worried | Angled up toward center |
|
||||
| `bushy` | Bushy | Wild, untamed look |
|
||||
| `sleek` | Sleek | Thin with elegant arch |
|
||||
| `curved` | Curved | Pronounced curved shape |
|
||||
|
||||
### Nose Shape (8 options)
|
||||
|
||||
| ID | Name | Description |
|
||||
|----|------|-------------|
|
||||
| `button` | Button | Small, rounded tip |
|
||||
| `pointed` | Pointed | Narrow with defined tip |
|
||||
| `roman` | Roman | Prominent bridge curve |
|
||||
| `snub` | Snub | Short with slight upturn |
|
||||
| `wide` | Wide | Broader nostril base |
|
||||
| `narrow` | Narrow | Thin, elongated bridge |
|
||||
| `aquiline` | Aquiline | Pronounced curved bridge |
|
||||
| `flat` | Flat | Low bridge, wide base |
|
||||
|
||||
### Mouth Shape (10 options)
|
||||
|
||||
| ID | Name | Description |
|
||||
|----|------|-------------|
|
||||
| `smile` | Smile | Gentle upward curve |
|
||||
| `neutral` | Neutral | Relaxed, straight line |
|
||||
| `grin` | Grin | Wide smile showing teeth |
|
||||
| `smirk` | Smirk | Asymmetric half-smile |
|
||||
| `pout` | Pout | Full lips, slight downturn |
|
||||
| `open` | Open | Slightly parted lips |
|
||||
| `small` | Small | Petite, compact mouth |
|
||||
| `wide` | Wide | Broader mouth width |
|
||||
| `thin` | Thin | Narrow lip fullness |
|
||||
| `full` | Full | Plump, pronounced lips |
|
||||
|
||||
### Ear Shape (6 options)
|
||||
|
||||
| ID | Name | Description |
|
||||
|----|------|-------------|
|
||||
| `normal` | Normal | Standard ear shape and size |
|
||||
| `small` | Small | Compact, closer to head |
|
||||
| `large` | Large | Prominent, larger ears |
|
||||
| `pointed` | Pointed | Elf-like pointed tips |
|
||||
| `round` | Round | Soft, rounded lobes |
|
||||
| `flat` | Flat | Close-set against head |
|
||||
|
||||
### Hair Style (30 options)
|
||||
|
||||
| ID | Name | Length | Coverage |
|
||||
|----|------|--------|----------|
|
||||
| `short-messy` | Short Messy | Short | 0.30 |
|
||||
| `short-neat` | Short Neat | Short | 0.25 |
|
||||
| `short-curly` | Short Curly | Short | 0.35 |
|
||||
| `medium-straight` | Medium Straight | Medium | 0.50 |
|
||||
| `medium-wavy` | Medium Wavy | Medium | 0.55 |
|
||||
| `long-straight` | Long Straight | Long | 0.70 |
|
||||
| `long-wavy` | Long Wavy | Long | 0.75 |
|
||||
| `ponytail` | Ponytail | Medium | 0.40 |
|
||||
| `pigtails` | Pigtails | Medium | 0.45 |
|
||||
| `bun` | Bun | Long | 0.35 |
|
||||
| `mohawk` | Mohawk | Short | 0.20 |
|
||||
| `afro` | Afro | Medium | 0.80 |
|
||||
| `buzz` | Buzz Cut | Short | 0.15 |
|
||||
| `bald` | Bald | None | 0.00 |
|
||||
| `sidepart` | Side Part | Short | 0.30 |
|
||||
| `spiky` | Spiky | Short | 0.35 |
|
||||
| `slicked` | Slicked Back | Short | 0.25 |
|
||||
| `bob` | Bob | Medium | 0.50 |
|
||||
| `pixie` | Pixie | Short | 0.35 |
|
||||
| `braids` | Braids | Long | 0.60 |
|
||||
| `dreads` | Dreads | Long | 0.70 |
|
||||
| `undercut` | Undercut | Short | 0.25 |
|
||||
| `fauxhawk` | Faux Hawk | Short | 0.30 |
|
||||
| `mullet` | Mullet | Medium | 0.45 |
|
||||
| `bowl` | Bowl Cut | Medium | 0.55 |
|
||||
| `combover` | Comb Over | Short | 0.20 |
|
||||
| `bangs` | Bangs | Medium | 0.50 |
|
||||
| `sidesweep` | Side Sweep | Medium | 0.45 |
|
||||
| `topknot` | Top Knot | Long | 0.30 |
|
||||
| `cornrows` | Cornrows | Medium | 0.40 |
|
||||
|
||||
### Hair Color (20 options)
|
||||
|
||||
| ID | Name | Hex Code | Type |
|
||||
|----|------|----------|------|
|
||||
| `black` | Black | `#1A1A1A` | Natural |
|
||||
| `darkBrown` | Dark Brown | `#2C1810` | Natural |
|
||||
| `brown` | Brown | `#4A3728` | Natural |
|
||||
| `lightBrown` | Light Brown | `#7A5A3A` | Natural |
|
||||
| `auburn` | Auburn | `#8B4513` | Natural |
|
||||
| `ginger` | Ginger | `#B5651D` | Natural |
|
||||
| `strawberry` | Strawberry | `#C67171` | Natural |
|
||||
| `blonde` | Blonde | `#D4B896` | Natural |
|
||||
| `platinum` | Platinum | `#E8E4C9` | Natural |
|
||||
| `white` | White | `#F0F0F0` | Natural |
|
||||
| `gray` | Gray | `#808080` | Natural |
|
||||
| `red` | Red | `#CC0000` | Fantasy |
|
||||
| `blue` | Blue | `#0066CC` | Fantasy |
|
||||
| `purple` | Purple | `#7B2D8E` | Fantasy |
|
||||
| `green` | Green | `#228B22` | Fantasy |
|
||||
| `pink` | Pink | `#FF69B4` | Fantasy |
|
||||
| `teal` | Teal | `#008B8B` | Fantasy |
|
||||
| `orange` | Orange | `#FF6600` | Fantasy |
|
||||
| `silver` | Silver | `#C0C0C0` | Fantasy |
|
||||
| `rainbow` | Rainbow | Gradient | Fantasy |
|
||||
|
||||
### Facial Hair (10 options)
|
||||
|
||||
| ID | Name | Coverage | Description |
|
||||
|----|------|----------|-------------|
|
||||
| `none` | None | - | Clean shaven |
|
||||
| `stubble` | Stubble | Light | 5 o'clock shadow |
|
||||
| `goatee` | Goatee | Chin | Chin beard only |
|
||||
| `mustache` | Mustache | Upper lip | Classic mustache |
|
||||
| `fullBeard` | Full Beard | Full face | Complete beard coverage |
|
||||
| `shortBeard` | Short Beard | Full face | Trimmed full beard |
|
||||
| `soulPatch` | Soul Patch | Chin center | Small chin patch |
|
||||
| `mutton` | Mutton Chops | Sides | Sideburn-connected style |
|
||||
| `handlebar` | Handlebar | Upper lip | Curled mustache tips |
|
||||
| `vandyke` | Van Dyke | Chin + mustache | Goatee with mustache |
|
||||
|
||||
### Body Type (6 options)
|
||||
|
||||
| ID | Name | Width Ratio | Height Ratio |
|
||||
|----|------|-------------|--------------|
|
||||
| `slim` | Slim | 0.80 | 1.00 |
|
||||
| `average` | Average | 1.00 | 1.00 |
|
||||
| `athletic` | Athletic | 1.10 | 1.00 |
|
||||
| `stocky` | Stocky | 1.20 | 0.95 |
|
||||
| `tall` | Tall | 0.95 | 1.15 |
|
||||
| `short` | Short | 1.00 | 0.85 |
|
||||
|
||||
### Clothing Style (4 options)
|
||||
|
||||
| ID | Name | Has Collar | Sleeve Length | Special |
|
||||
|----|------|------------|---------------|---------|
|
||||
| `casual` | Casual | No | Short | - |
|
||||
| `sporty` | Sporty | No | Short | Stripes |
|
||||
| `formal` | Formal | Yes | Long | Buttons |
|
||||
| `scifi` | Sci-Fi | Yes | Long | Glow effects |
|
||||
|
||||
### Clothing Color (20 preset colors)
|
||||
|
||||
```
|
||||
#E74C3C #E67E22 #F1C40F #2ECC71 #1ABC9C
|
||||
#3498DB #9B59B6 #34495E #95A5A6 #ECF0F1
|
||||
#C0392B #D35400 #F39C12 #27AE60 #16A085
|
||||
#2980B9 #8E44AD #2C3E50 #7F8C8D #BDC3C7
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Earned Accessories
|
||||
|
||||
### Rarity System
|
||||
|
||||
| Rarity | Color | Level Range | Hex Code |
|
||||
|--------|-------|-------------|----------|
|
||||
| Common | Gray | 1-15 | `#9D9D9D` |
|
||||
| Uncommon | Green | 16-30 | `#1EFF00` |
|
||||
| Rare | Blue | 31-50 | `#0070DD` |
|
||||
| Epic | Purple | 51-70 | `#A335EE` |
|
||||
| Legendary | Orange | 71-90 | `#FF8000` |
|
||||
| Mythic | Gold | 91-100 | `#E6CC80` |
|
||||
|
||||
### Eyewear (15 items)
|
||||
|
||||
| ID | Name | Unlock Level | Rarity | Has Effect | Description |
|
||||
|----|------|--------------|--------|------------|-------------|
|
||||
| `sunglasses-classic` | Classic Sunglasses | 5 | Common | No | Timeless shades for any occasion |
|
||||
| `aviator` | Aviator Glasses | 10 | Common | No | Top Gun approved eyewear |
|
||||
| `nerd-glasses` | Nerd Glasses | 15 | Common | No | Intelligence +100 (cosmetic only) |
|
||||
| `3d-glasses` | 3D Glasses | 20 | Uncommon | No | See the world in a whole new dimension |
|
||||
| `goggles` | Goggles | 25 | Uncommon | No | Ready for adventure or science experiments |
|
||||
| `monocle` | Monocle | 30 | Uncommon | No | Distinguished and sophisticated |
|
||||
| `star-glasses` | Star Glasses | 35 | Rare | No | You are a star! |
|
||||
| `heart-glasses` | Heart Glasses | 40 | Rare | No | Spread the love wherever you go |
|
||||
| `sport-visor` | Sport Visor | 45 | Rare | No | Professional gamer gear |
|
||||
| `vr-headset` | VR Headset | 50 | Epic | No | Immerse yourself in virtual worlds |
|
||||
| `cyber-visor` | Cyber Visor | 55 | Epic | No | Sleek futuristic eye protection |
|
||||
| `x-ray-specs` | X-Ray Specs | 60 | Epic | Yes | See through walls... probably |
|
||||
| `laser-eyes` | Laser Eyes | 70 | Legendary | Yes | Pew pew! Lasers shoot from your eyes |
|
||||
| `diamond-glasses` | Diamond Glasses | 80 | Legendary | No | Pure crystallized luxury |
|
||||
| `cosmic-lenses` | Cosmic Lenses | 90 | Mythic | Yes | Gaze upon the infinite universe |
|
||||
|
||||
### Headwear (20 items)
|
||||
|
||||
| ID | Name | Unlock Level | Rarity | Has Effect | Description |
|
||||
|----|------|--------------|--------|------------|-------------|
|
||||
| `baseball-cap` | Baseball Cap | 3 | Common | No | A classic casual cap |
|
||||
| `backwards-cap` | Backwards Cap | 8 | Common | No | Cool kids wear it backwards |
|
||||
| `beanie` | Beanie | 12 | Common | No | Cozy knitted headwear |
|
||||
| `party-hat` | Party Hat | 18 | Uncommon | No | Every day is a celebration! |
|
||||
| `chef-hat` | Chef Hat | 22 | Uncommon | No | Master of the kitchen |
|
||||
| `crown-bronze` | Bronze Crown | 25 | Uncommon | No | A humble crown for rising royalty |
|
||||
| `hard-hat` | Hard Hat | 26 | Uncommon | No | Safety first on the job site |
|
||||
| `wizard-hat` | Wizard Hat | 30 | Rare | No | Channel your inner sorcerer |
|
||||
| `pirate-hat` | Pirate Hat | 35 | Rare | No | Arrr! Set sail for adventure |
|
||||
| `santa-hat` | Santa Hat | 38 | Rare | No | Ho ho ho! Spread holiday cheer |
|
||||
| `crown-silver` | Silver Crown | 40 | Rare | No | A noble crown for dedicated players |
|
||||
| `graduation-cap` | Graduation Cap | 42 | Rare | No | Scholar of the gaming arts |
|
||||
| `bunny-ears` | Bunny Ears | 45 | Rare | No | Hop into the fun! |
|
||||
| `devil-horns` | Devil Horns | 48 | Rare | No | A little mischief never hurt anyone |
|
||||
| `halo` | Halo | 52 | Epic | Yes | An angelic golden ring of light |
|
||||
| `top-hat` | Top Hat | 56 | Epic | No | Dapper and distinguished |
|
||||
| `crown-gold` | Gold Crown | 60 | Epic | No | True royalty in golden splendor |
|
||||
| `viking-helmet` | Viking Helmet | 62 | Epic | No | Conquer games like a Norse warrior |
|
||||
| `crown-diamond` | Diamond Crown | 80 | Legendary | Yes | A magnificent crown of pure diamonds |
|
||||
| `crown-cosmic` | Cosmic Crown | 100 | Mythic | Yes | The ultimate crown, forged from stardust |
|
||||
|
||||
### Effects/Auras (10 items)
|
||||
|
||||
| ID | Name | Unlock Level | Rarity | Effect Type | Color | Description |
|
||||
|----|------|--------------|--------|-------------|-------|-------------|
|
||||
| `sparkle-trail` | Sparkle Trail | 15 | Uncommon | Particles | `#FFD700` | Leave a trail of golden sparkles |
|
||||
| `fire-aura` | Fire Aura | 25 | Rare | Glow | `#FF4500` | Surrounded by fierce flames |
|
||||
| `lightning-crackle` | Lightning Crackle | 35 | Rare | Electric | `#00BFFF` | Electricity crackles around you |
|
||||
| `rainbow-glow` | Rainbow Glow | 45 | Epic | Glow | Rainbow | Radiate all colors of the spectrum |
|
||||
| `star-particles` | Star Particles | 55 | Epic | Particles | `#FFFF00` | Tiny stars orbit around you |
|
||||
| `ice-crystals` | Ice Crystals | 65 | Legendary | Particles | `#87CEEB` | Frozen crystals shimmer around you |
|
||||
| `shadow-effect` | Shadow Effect | 70 | Legendary | Shadow | `#2F2F4F` | Darkness follows your every move |
|
||||
| `golden-glow` | Golden Glow | 75 | Legendary | Glow | `#FFD700` | Bathe in pure golden light |
|
||||
| `void-aura` | Void Aura | 85 | Mythic | Void | `#4B0082` | The void itself surrounds you |
|
||||
| `cosmic-trail` | Cosmic Trail | 95 | Mythic | Cosmic | Cosmic | Trail galaxies and nebulae in your wake |
|
||||
|
||||
**Total Accessories**: 15 + 20 + 10 = **45 unlockable items**
|
||||
|
||||
---
|
||||
|
||||
## Rendering Modes
|
||||
|
||||
### HEAD_ONLY (64x64 pixels)
|
||||
|
||||
**Best for**: Cockpit views, flying games (Flappy Bird style), maze games, puzzle games
|
||||
|
||||
**Shows**: Face, hair, ears, accessories (eyewear, headwear, effects)
|
||||
|
||||
**Animations** (5):
|
||||
| ID | Name | Frames | Duration | Loop | Description |
|
||||
|----|------|--------|----------|------|-------------|
|
||||
| `bob` | Bob | 3 | 150ms | Yes | Gentle up/down bobbing motion |
|
||||
| `flap` | Flap | 2 | 80ms | Yes | Flapping motion with head squash/stretch |
|
||||
| `blink` | Blink | 3 | 60ms | No | Eye blink animation |
|
||||
| `celebrate` | Celebrate | 4 | 100ms | No | Happy bouncing celebration |
|
||||
| `hurt` | Hurt | 2 | 80ms | No | Damage reaction shake |
|
||||
|
||||
### HEAD_AND_SHOULDERS (64x96 pixels)
|
||||
|
||||
**Best for**: Driving games, conversation scenes, submarine games, portrait views
|
||||
|
||||
**Shows**: Head, neck, shoulders, clothing collar
|
||||
|
||||
**Animations** (6):
|
||||
| ID | Name | Frames | Duration | Loop | Description |
|
||||
|----|------|--------|----------|------|-------------|
|
||||
| `idle` | Idle | 3 | 400ms | Yes | Subtle breathing motion |
|
||||
| `turn-left` | Turn Left | 2 | 100ms | No | Head turns to the left |
|
||||
| `turn-right` | Turn Right | 2 | 100ms | No | Head turns to the right |
|
||||
| `look-up` | Look Up | 2 | 100ms | No | Head tilts upward |
|
||||
| `celebrate` | Celebrate | 3 | 120ms | No | Bounce and smile celebration |
|
||||
| `hurt` | Hurt | 2 | 100ms | No | Recoil damage reaction |
|
||||
|
||||
### UPPER_BODY (64x128 pixels)
|
||||
|
||||
**Best for**: Racing games, shooting games, hoverboard games, action sequences
|
||||
|
||||
**Shows**: Head, neck, shoulders, torso, arms, hands
|
||||
|
||||
**Animations** (8):
|
||||
| ID | Name | Frames | Duration | Loop | Description |
|
||||
|----|------|--------|----------|------|-------------|
|
||||
| `idle` | Idle | 3 | 400ms | Yes | Breathing with subtle arm sway |
|
||||
| `wave` | Wave | 4 | 120ms | No | Friendly arm wave gesture |
|
||||
| `point` | Point | 3 | 100ms | No | Pointing forward gesture |
|
||||
| `steer-left` | Steer Left | 2 | 80ms | No | Leaning left for racing/steering |
|
||||
| `steer-right` | Steer Right | 2 | 80ms | No | Leaning right for racing/steering |
|
||||
| `shoot` | Shoot | 3 | 60ms | No | Arm extends forward shooting motion |
|
||||
| `celebrate` | Celebrate | 4 | 120ms | No | Arms up victory celebration |
|
||||
| `hurt` | Hurt | 2 | 100ms | No | Recoil backwards damage reaction |
|
||||
|
||||
### FULL_BODY (64x160 pixels)
|
||||
|
||||
**Best for**: Platformers, RPGs, sports games, adventure games, fighting games
|
||||
|
||||
**Shows**: Complete character with head, body, arms, legs, shoes
|
||||
|
||||
**Animations** (12):
|
||||
| ID | Name | Frames | Duration | Loop | Description |
|
||||
|----|------|--------|----------|------|-------------|
|
||||
| `idle` | Idle | 3 | 400ms | Yes | Standing with breathing motion |
|
||||
| `walk` | Walk Cycle | 4 | 100ms | Yes | Walking with arm/leg swing |
|
||||
| `run` | Run Cycle | 6 | 60ms | Yes | Running with full body movement |
|
||||
| `jump` | Jump | 3 | 100ms | No | Crouch, leap, stretch sequence |
|
||||
| `fall` | Fall | 2 | 150ms | Yes | Arms up, legs down falling pose |
|
||||
| `crouch` | Crouch | 2 | 80ms | No | Duck down into crouch position |
|
||||
| `celebrate` | Celebrate | 6 | 100ms | No | Jump and arm wave celebration |
|
||||
| `attack` | Attack | 4 | 60ms | No | Punch or swing attack motion |
|
||||
| `hurt` | Hurt | 3 | 80ms | No | Stagger backwards damage reaction |
|
||||
| `climb` | Climb | 4 | 120ms | Yes | Climbing ladder/wall motion |
|
||||
| `swim` | Swim | 4 | 150ms | Yes | Swimming stroke animation |
|
||||
| `fly` | Fly | 4 | 100ms | Yes | Superhero flying pose |
|
||||
|
||||
---
|
||||
|
||||
## API Reference
|
||||
|
||||
### Creating Avatars
|
||||
|
||||
```javascript
|
||||
// Create avatar with custom options
|
||||
const avatar = AvatarSystem.create({
|
||||
faceShape: 'round',
|
||||
skinTone: '#FFD5B8',
|
||||
eyes: { shape: 'round', color: '#4A90D9' },
|
||||
eyebrows: 'natural',
|
||||
nose: 'button',
|
||||
mouth: 'smile',
|
||||
ears: 'normal',
|
||||
hair: { style: 'short-messy', color: '#3D2314' },
|
||||
facialHair: 'none',
|
||||
body: { type: 'average' },
|
||||
clothing: { style: 'casual', shirtColor: '#3498DB', pantsColor: '#2C3E50' }
|
||||
});
|
||||
|
||||
// Create default avatar
|
||||
const defaultAvatar = AvatarSystem.createDefault();
|
||||
|
||||
// Get random guest avatar
|
||||
const guestAvatar = AvatarSystem.getGuestAvatar();
|
||||
```
|
||||
|
||||
### Loading and Saving
|
||||
|
||||
```javascript
|
||||
// Load user's saved avatar
|
||||
const avatar = await AvatarSystem.loadUserAvatar(userId);
|
||||
|
||||
// Save avatar
|
||||
AvatarSystem.saveAvatar(avatar);
|
||||
|
||||
// Clear cache
|
||||
AvatarSystem.clearCache(userId); // Clear specific user
|
||||
AvatarSystem.clearCache(); // Clear all
|
||||
```
|
||||
|
||||
### Rendering
|
||||
|
||||
```javascript
|
||||
// Render to canvas context
|
||||
AvatarSystem.render(avatar, 'FULL_BODY', ctx, x, y, {
|
||||
scale: 1,
|
||||
animation: 'walk',
|
||||
frame: 0
|
||||
});
|
||||
|
||||
// Render to offscreen canvas
|
||||
const canvas = AvatarSystem.renderToCanvas(avatar, 'HEAD_ONLY', { scale: 2 });
|
||||
|
||||
// Render to data URL (for images)
|
||||
const dataUrl = AvatarSystem.renderToDataURL(avatar, 'HEAD_AND_SHOULDERS');
|
||||
|
||||
// Get mode dimensions
|
||||
const size = AvatarSystem.getModeSize('FULL_BODY');
|
||||
// Returns: { width: 64, height: 160 }
|
||||
```
|
||||
|
||||
### Animation Control
|
||||
|
||||
```javascript
|
||||
// Start animation
|
||||
AvatarSystem.startAnimation(avatarId, 'walk', {
|
||||
loop: true,
|
||||
mode: 'FULL_BODY',
|
||||
onComplete: () => console.log('Animation finished')
|
||||
});
|
||||
|
||||
// Stop animation
|
||||
AvatarSystem.stopAnimation(avatarId);
|
||||
|
||||
// Get current animation state
|
||||
const state = AvatarSystem.getAnimationState(avatarId);
|
||||
// Returns: { animation: 'walk', frame: 2, complete: false, transforms: {...} }
|
||||
|
||||
// Check if animating
|
||||
const isAnimating = AvatarSystem.isAnimating(avatarId);
|
||||
|
||||
// Get animation frame transforms directly
|
||||
const transforms = AvatarSystem.animate(avatar, 'run', frameNumber);
|
||||
```
|
||||
|
||||
### Accessory Management
|
||||
|
||||
```javascript
|
||||
// Equip accessory
|
||||
AvatarSystem.equipAccessory(avatar, 'headwear', 'crown-gold');
|
||||
AvatarSystem.equipAccessory(avatar, 'eyewear', 'sunglasses-classic');
|
||||
AvatarSystem.equipAccessory(avatar, 'effect', 'sparkle-trail');
|
||||
|
||||
// Unequip accessory
|
||||
AvatarSystem.unequipAccessory(avatar, 'headwear');
|
||||
|
||||
// Unlock/award accessory
|
||||
const newlyUnlocked = AvatarSystem.unlockAccessory(avatar, 'vr-headset');
|
||||
// Returns: true if newly unlocked, false if already owned
|
||||
|
||||
// Check if avatar has accessory
|
||||
const hasItem = AvatarSystem.hasAccessory(avatar, 'crown-gold');
|
||||
|
||||
// Get earned accessories (full objects)
|
||||
const earned = AvatarSystem.getEarnedAccessories(avatar);
|
||||
// Returns: { eyewear: [...], headwear: [...], effects: [...] }
|
||||
|
||||
// Get equipped accessories (full objects)
|
||||
const equipped = AvatarSystem.getEquippedAccessories(avatar);
|
||||
// Returns: { eyewear: {...}, headwear: {...}, effect: {...} }
|
||||
|
||||
// Get full accessory catalog
|
||||
const catalog = AvatarSystem.getAccessoryCatalog();
|
||||
```
|
||||
|
||||
### Level Unlocks
|
||||
|
||||
```javascript
|
||||
// Check what unlocks at a specific level
|
||||
const newItems = AvatarSystem.checkLevelUnlocks(avatar, 50);
|
||||
// Returns: Array of newly unlocked accessory objects
|
||||
|
||||
// Add XP and check for level ups
|
||||
const result = AvatarSystem.addXP(avatar, 500);
|
||||
// Returns: { newLevel: 12, leveledUp: true, unlockedItems: [...] }
|
||||
|
||||
// Get XP progress info
|
||||
const xpInfo = AvatarSystem.getXPInfo(avatar);
|
||||
// Returns: { level, totalXP, currentLevelXP, xpNeededForLevel, progress }
|
||||
```
|
||||
|
||||
### Game Integration
|
||||
|
||||
```javascript
|
||||
// Export avatar for use in a game
|
||||
const gameAvatar = AvatarSystem.exportForGame(avatar, 'FULL_BODY');
|
||||
// Returns object with render() and animate() methods
|
||||
|
||||
// Use in game loop
|
||||
gameAvatar.render(ctx, x, y, { animation: 'run', frame: frameNum });
|
||||
const animInfo = gameAvatar.getAnimationInfo('run');
|
||||
|
||||
// Export minimal data for network transmission
|
||||
const minimal = AvatarSystem.exportMinimal(avatar);
|
||||
|
||||
// Import from minimal data
|
||||
const fullAvatar = AvatarSystem.importMinimal(minimalData, userId);
|
||||
|
||||
// Create sprite sheet for performance
|
||||
const spriteSheet = AvatarSystem.createSpriteSheet(avatar, 'FULL_BODY', ['idle', 'walk', 'run']);
|
||||
// Returns: { canvas, frameWidth, frameHeight, getFrameRect(animId, frame) }
|
||||
```
|
||||
|
||||
### Utility Functions
|
||||
|
||||
```javascript
|
||||
// Clone avatar
|
||||
const cloned = AvatarSystem.clone(avatar);
|
||||
|
||||
// Update base properties
|
||||
AvatarSystem.updateBase(avatar, { hair: { style: 'afro', color: '#000000' } });
|
||||
|
||||
// Validate avatar data
|
||||
const isValid = AvatarSystem.validate(avatarData);
|
||||
|
||||
// Compare avatars
|
||||
const areEqual = AvatarSystem.equals(avatar1, avatar2);
|
||||
|
||||
// Get all customization options
|
||||
const options = AvatarSystem.getCustomizationOptions();
|
||||
// Returns: { faceShapes, skinTones, eyeShapes, eyeColors, ... }
|
||||
|
||||
// Check if guest avatar
|
||||
const isGuest = AvatarSystem.isGuest(avatar);
|
||||
|
||||
// Convert guest to registered user
|
||||
const userAvatar = AvatarSystem.convertGuestToUser(guestAvatar, newUserId);
|
||||
|
||||
// Get version info
|
||||
const version = AvatarSystem.getVersion();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Guest Avatars
|
||||
|
||||
10 pre-defined guest avatars are available for non-logged-in users. Each has a unique appearance:
|
||||
|
||||
| ID | Name | Skin Tone | Hair Style | Eye Color | Clothing Color |
|
||||
|----|------|-----------|------------|-----------|----------------|
|
||||
| `guest_1` | Guest Blue | Medium | Short Messy | Blue | `#3498DB` |
|
||||
| `guest_2` | Guest Red | Light | Long Straight | Brown | `#E74C3C` |
|
||||
| `guest_3` | Guest Green | Tan | Buzz Cut | Dark Brown | `#2ECC71` |
|
||||
| `guest_4` | Guest Purple | Fair | Bob | Green | `#9B59B6` |
|
||||
| `guest_5` | Guest Orange | Brown | Afro | Amber | `#E67E22` |
|
||||
| `guest_6` | Guest Teal | Dark | Dreads | Dark Brown | `#1ABC9C` |
|
||||
| `guest_7` | Guest Gray | Light | Undercut | Gray | `#95A5A6` |
|
||||
| `guest_8` | Guest Yellow | Medium | Spiky | Hazel | `#F1C40F` |
|
||||
| `guest_9` | Guest Navy | Tan | Comb Over | Brown | `#2C3E50` |
|
||||
| `guest_10` | Guest Pink | Fair | Pigtails | Light Blue | `#FF69B4` |
|
||||
|
||||
```javascript
|
||||
// Get random guest avatar
|
||||
const guest = AvatarSystem.getGuestAvatar();
|
||||
|
||||
// Or use AvatarData directly
|
||||
const guestData = AvatarData.getRandomGuestAvatar();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## XP and Leveling System
|
||||
|
||||
### XP Per Level Formula
|
||||
|
||||
```
|
||||
XP needed for level N = 100 + (N - 1) * 50
|
||||
```
|
||||
|
||||
| Level | XP Needed | Cumulative XP |
|
||||
|-------|-----------|---------------|
|
||||
| 1 | 100 | 100 |
|
||||
| 2 | 150 | 250 |
|
||||
| 3 | 200 | 450 |
|
||||
| 5 | 300 | 1,000 |
|
||||
| 10 | 550 | 3,500 |
|
||||
| 25 | 1,300 | 18,250 |
|
||||
| 50 | 2,550 | 68,000 |
|
||||
| 75 | 3,800 | 148,500 |
|
||||
| 100 | 5,050 | 259,750 |
|
||||
|
||||
### Unlock Schedule
|
||||
|
||||
All accessories unlock by reaching specific levels:
|
||||
|
||||
- **Levels 3-15**: 6 Common items
|
||||
- **Levels 18-30**: 8 Uncommon items
|
||||
- **Levels 35-48**: 10 Rare items
|
||||
- **Levels 50-62**: 8 Epic items
|
||||
- **Levels 65-80**: 6 Legendary items
|
||||
- **Levels 85-100**: 4 Mythic items
|
||||
|
||||
---
|
||||
|
||||
## Accessory Animation Rules
|
||||
|
||||
Accessories follow specific animation behavior:
|
||||
|
||||
```javascript
|
||||
{
|
||||
headwear: {
|
||||
followHead: true, // Moves with head
|
||||
bounceMultiplier: 1.2, // Extra bounce on jumps
|
||||
rotationDamping: 0.8 // Slightly less rotation than head
|
||||
},
|
||||
eyewear: {
|
||||
followHead: true, // Moves with head
|
||||
bounceMultiplier: 1.0, // Same bounce as head
|
||||
rotationDamping: 1.0 // Matches head rotation exactly
|
||||
},
|
||||
effects: {
|
||||
independent: true, // Own animation cycle
|
||||
particleSpeed: 1.0 // Particle emission rate
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Performance Tips
|
||||
|
||||
### Sprite Caching
|
||||
|
||||
For games with many avatars or frequent redraws:
|
||||
|
||||
```javascript
|
||||
// Pre-render to sprite cache
|
||||
const cache = AvatarRenderer.createSpriteCache(avatars, 'HEAD_ONLY', 1);
|
||||
|
||||
// Render from cache (much faster)
|
||||
AvatarRenderer.renderFromCache(ctx, cache, avatarId, x, y);
|
||||
```
|
||||
|
||||
### Sprite Sheets
|
||||
|
||||
For animation-heavy games:
|
||||
|
||||
```javascript
|
||||
const sheet = AvatarSystem.createSpriteSheet(avatar, 'FULL_BODY', ['idle', 'walk', 'run', 'jump']);
|
||||
|
||||
// In game loop
|
||||
const rect = sheet.getFrameRect('walk', currentFrame);
|
||||
ctx.drawImage(sheet.image, rect.x, rect.y, rect.width, rect.height, destX, destY, rect.width, rect.height);
|
||||
```
|
||||
|
||||
### Batch Rendering
|
||||
|
||||
For many avatars on screen:
|
||||
|
||||
```javascript
|
||||
AvatarRenderer.renderBatch(ctx, avatars, 'HEAD_ONLY', positions);
|
||||
// Automatically skips off-screen avatars
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Dependencies
|
||||
|
||||
Load order matters. Include scripts in this order:
|
||||
|
||||
```html
|
||||
<script src="/assets/avatar/avatarData.js"></script>
|
||||
<script src="/assets/avatar/animations.js"></script>
|
||||
<script src="/assets/avatar/avatarRenderer.js"></script>
|
||||
<script src="/assets/avatar/accessories.js"></script>
|
||||
<script src="/assets/avatar/accessoryRenderer.js"></script>
|
||||
<script src="/assets/avatar/avatarSystem.js"></script>
|
||||
```
|
||||
|
||||
Or use the asset manager which handles loading automatically.
|
||||
@@ -0,0 +1,470 @@
|
||||
# Background Catalog
|
||||
|
||||
Complete catalog of all 120 procedural backgrounds available in the GamerComp game generation system.
|
||||
|
||||
**15 themes x 8 variants = 120 unique backgrounds**
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Overview](#overview)
|
||||
2. [Theme Categories](#theme-categories)
|
||||
- [Space](#space-theme)
|
||||
- [Nature](#nature-theme)
|
||||
- [Urban](#urban-theme)
|
||||
- [Fantasy](#fantasy-theme)
|
||||
- [Abstract](#abstract-theme)
|
||||
- [Retro](#retro-theme)
|
||||
- [Indoor](#indoor-theme)
|
||||
- [Weather](#weather-theme)
|
||||
- [Sports](#sports-theme)
|
||||
- [Seasonal](#seasonal-theme)
|
||||
- [Underwater](#underwater-theme)
|
||||
- [Sky](#sky-theme)
|
||||
- [Mechanical](#mechanical-theme)
|
||||
- [Spooky](#spooky-theme)
|
||||
- [Colorful](#colorful-theme)
|
||||
3. [Compatible Music Moods](#compatible-music-moods)
|
||||
4. [Compatible Avatar Contexts](#compatible-avatar-contexts)
|
||||
5. [API Usage](#api-usage)
|
||||
6. [Visual Preview Guide](#visual-preview-guide)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
All backgrounds are procedurally generated using Canvas 2D rendering. Each background features:
|
||||
|
||||
- **Animated elements** - Smooth animations driven by time parameter
|
||||
- **Layered rendering** - Base layer, mid layer, and particle effects
|
||||
- **Customizable colors** - 4-color palette per background
|
||||
- **Particle systems** - Optional ambient particles (stars, rain, sparkles, etc.)
|
||||
- **Mood-based filtering** - Find backgrounds by emotional tone
|
||||
- **Game genre recommendations** - Suggested game types for each background
|
||||
|
||||
### Particle Types Available
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| `stars` | Twinkling star field |
|
||||
| `rain` | Falling rain drops |
|
||||
| `snow` | Gentle snowfall |
|
||||
| `particles` | Generic floating particles |
|
||||
| `fog` | Drifting fog wisps |
|
||||
| `bubbles` | Rising bubbles |
|
||||
| `leaves` | Falling leaves |
|
||||
| `sparkles` | Glittering sparkles |
|
||||
| `fireflies` | Glowing fireflies |
|
||||
| `dust` | Floating dust motes |
|
||||
|
||||
---
|
||||
|
||||
## Theme Categories
|
||||
|
||||
### Space Theme
|
||||
|
||||
Cosmic environments featuring nebulas, planets, and interstellar phenomena.
|
||||
|
||||
| Variant | ID | Description | Mood | Colors | Particles | Recommended For |
|
||||
|---------|-----|-------------|------|--------|-----------|-----------------|
|
||||
| Nebula | `space_nebula` | Swirling nebula clouds with twinkling stars | wonder | `#0B0B2B` `#1A0A3E` `#3D1A78` `#7B2FBE` | sparkles | puzzle, story, creative |
|
||||
| Asteroid Field | `space_asteroidField` | Rocky asteroids drifting through dark space | tense | `#0A0A14` `#1C1C2E` `#4A3A2A` `#8B7355` | dust | action, racing, sports |
|
||||
| Deep Space | `space_deepSpace` | The void of deep space with distant starlight | serene | `#000005` `#050510` `#0A0A20` `#111133` | stars | puzzle, story, rpg |
|
||||
| Planets | `space_planets` | Colorful planets against a starry backdrop | wonder | `#0B0B2B` `#0F1640` `#CC5533` `#44BBAA` | sparkles | creative, rpg, story |
|
||||
| Space Station | `space_spaceStation` | Orbital station with geometric structures | focused | `#0A0A1E` `#151530` `#3A3A55` `#88AACC` | dust | puzzle, action, physics |
|
||||
| Warp Speed | `space_warpSpeed` | Light streaks from faster-than-light travel | energetic | `#000010` `#0A0A30` `#2244AA` `#66BBFF` | particles | racing, action, sports |
|
||||
| Satellites | `space_satellites` | Satellites orbiting above a dark Earth | calm | `#060615` `#101030` `#334466` `#AACCDD` | stars | puzzle, trivia, creative |
|
||||
| Black Hole | `space_blackHole` | A black hole bending light around its event horizon | intense | `#000000` `#0A0510` `#220A33` `#FF6622` | particles | action, rpg, physics |
|
||||
|
||||
---
|
||||
|
||||
### Nature Theme
|
||||
|
||||
Natural outdoor environments from forests to oceans.
|
||||
|
||||
| Variant | ID | Description | Mood | Colors | Particles | Recommended For |
|
||||
|---------|-----|-------------|------|--------|-----------|-----------------|
|
||||
| Forest | `nature_forest` | A dense forest with layered canopy and dappled light | peaceful | `#1A3320` `#2D5A27` `#4A7A3F` `#8FB86A` | fireflies | story, rpg, puzzle |
|
||||
| Jungle | `nature_jungle` | Thick tropical jungle with hanging vines and humid air | adventurous | `#0D2B0D` `#1A4D1A` `#2D7A2D` `#55AA33` | fireflies | action, rpg, pet |
|
||||
| Desert | `nature_desert` | Rolling sand dunes under a blazing sun | warm | `#F4A460` `#DAA06D` `#C2955A` `#8B6914` | dust | racing, action, rpg |
|
||||
| Mountains | `nature_mountains` | Snow-capped mountain peaks under sweeping skies | majestic | `#2C3E50` `#4A6B5A` `#7A9B6B` `#FFFFFF` | fog | rpg, sports, story |
|
||||
| Ocean | `nature_ocean` | Vast ocean stretching to the horizon at sunset | serene | `#1A5276` `#2E86C1` `#5DADE2` `#AED6F1` | fog | puzzle, story, creative |
|
||||
| Underwater | `nature_underwater` | Deep beneath the waves with shafts of sunlight | mystical | `#0A2342` `#1A4B6E` `#2E86C1` `#48D1CC` | bubbles | puzzle, pet, creative |
|
||||
| Waterfall | `nature_waterfall` | A cascading waterfall in a lush green cliff | refreshing | `#1B4332` `#2D6A4F` `#52B788` `#B7E4C7` | fog | puzzle, creative, story |
|
||||
| Meadow | `nature_meadow` | A sunny meadow with wildflowers and gentle breeze | joyful | `#4CAF50` `#81C784` `#A5D6A7` `#FFF59D` | leaves | pet, creative, story, puzzle |
|
||||
|
||||
---
|
||||
|
||||
### Urban Theme
|
||||
|
||||
City environments from skylines to subways.
|
||||
|
||||
| Variant | ID | Description | Mood | Colors | Particles | Recommended For |
|
||||
|---------|-----|-------------|------|--------|-----------|-----------------|
|
||||
| City Skyline | `urban_citySkyline` | City skyline silhouetted against a glowing sunset | inspiring | `#1A1A2E` `#2D2D44` `#4A4A66` `#FF8844` | dust | story, rpg, creative |
|
||||
| Street | `urban_street` | Busy city street with lamp posts and passing lights | busy | `#2C3E50` `#566573` `#808B96` `#FFD700` | dust | racing, action, sports |
|
||||
| Rooftop | `urban_rooftop` | Rooftop view over a twinkling nighttime city | reflective | `#1B2631` `#2C3E50` `#5D6D7E` `#F4D03F` | fireflies | story, puzzle, creative |
|
||||
| Neon District | `urban_neonDistrict` | Rain-slicked streets glowing with neon signs | electric | `#0D0D1A` `#1A0A2E` `#FF00FF` `#00FFCC` | rain | action, racing, music |
|
||||
| Subway | `urban_subway` | Underground subway platform with arriving train lights | gritty | `#1C1C1C` `#333333` `#555555` `#FFCC00` | dust | action, puzzle, rpg |
|
||||
| Park | `urban_park` | A peaceful city park with trees and walking paths | relaxed | `#2E7D32` `#4CAF50` `#81C784` `#795548` | leaves | pet, puzzle, story, creative |
|
||||
| Mall | `urban_mall` | Bright mall interior with shop windows and escalators | lively | `#E8E8E8` `#CCCCCC` `#888888` `#FF6B6B` | sparkles | trivia, creative, pet |
|
||||
| Alley | `urban_alley` | A narrow alley with a single warm light overhead | mysterious | `#111118` `#1E1E28` `#333340` `#BB8844` | fog | rpg, action, story |
|
||||
|
||||
---
|
||||
|
||||
### Fantasy Theme
|
||||
|
||||
Magical and fantastical environments.
|
||||
|
||||
| Variant | ID | Description | Mood | Colors | Particles | Recommended For |
|
||||
|---------|-----|-------------|------|--------|-----------|-----------------|
|
||||
| Castle | `fantasy_castle` | A grand castle silhouette against a twilight sky with golden banners | heroic | `#1a1040` `#2d1b69` `#8b7355` `#ffd700` | fireflies | rpg, action, story |
|
||||
| Dungeon | `fantasy_dungeon` | Dark stone corridors lit by flickering torches and glowing embers | dark | `#0a0a0f` `#1a1520` `#4a3728` `#ff6a00` | particles | rpg, action, puzzle |
|
||||
| Enchanted Forest | `fantasy_enchantedForest` | A mystical forest with glowing mushrooms and magical light | mystical | `#0a1a0f` `#0d2818` `#1a4a2a` `#44ff88` | fireflies | rpg, story, puzzle |
|
||||
| Floating Islands | `fantasy_floatingIslands` | Majestic islands suspended in a violet sky with waterfalls | wonder | `#1a0a3a` `#2d1b69` `#5a8a5a` `#88ccff` | sparkles | rpg, puzzle, creative |
|
||||
| Magical Library | `fantasy_magicalLibrary` | Towering bookshelves with floating magical tomes and arcane symbols | scholarly | `#1a0f0a` `#2d1a10` `#6b4423` `#cc88ff` | sparkles | puzzle, trivia, story |
|
||||
| Crystal Cave | `fantasy_crystalCave` | An underground cavern filled with luminous crystal formations | ethereal | `#0a0a1a` `#0f1a2d` `#225588` `#44ddff` | sparkles | puzzle, rpg, creative |
|
||||
| Temple | `fantasy_temple` | An ancient temple with towering marble pillars and sacred golden light | sacred | `#1a1025` `#2d1a3a` `#c9b77a` `#ffd700` | dust | rpg, story, trivia |
|
||||
| Tower | `fantasy_tower` | A tall wizard tower under a starlit sky with arcane energy | arcane | `#0a0a20` `#151540` `#554488` `#aa66ff` | sparkles | rpg, puzzle, trivia |
|
||||
|
||||
---
|
||||
|
||||
### Abstract Theme
|
||||
|
||||
Non-representational visual patterns and effects.
|
||||
|
||||
| Variant | ID | Description | Mood | Colors | Particles | Recommended For |
|
||||
|---------|-----|-------------|------|--------|-----------|-----------------|
|
||||
| Geometric Patterns | `abstract_geometricPatterns` | Interlocking geometric shapes in warm contrasting tones | focused | `#0d1b2a` `#1b2838` `#e07a5f` `#f2cc8f` | dust | puzzle, trivia, creative |
|
||||
| Gradients | `abstract_gradients` | Smoothly blending gradient orbs with ethereal color transitions | dreamy | `#0f0c29` `#302b63` `#24243e` `#ff6b6b` | sparkles | creative, story, music |
|
||||
| Particle Fields | `abstract_particleFields` | A dynamic network of connected particle nodes with pulsing energy | energetic | `#000000` `#111122` `#00ff88` `#0088ff` | particles | action, puzzle, physics |
|
||||
| Minimalist | `abstract_minimalist` | Clean open space with a single bold accent line | calm | `#f5f5f0` `#e8e4dd` `#2d2d2d` `#c44536` | none | puzzle, trivia, creative |
|
||||
| Waves | `abstract_waves` | Layered sinusoidal waves undulating in cool blue tones | flowing | `#0a192f` `#172a45` `#00b4d8` `#90e0ef` | bubbles | creative, music, physics |
|
||||
| Fractals | `abstract_fractals` | Recursive branching patterns that grow and pulse | complex | `#0a0a0a` `#1a1a2e` `#e94560` `#0f3460` | sparkles | puzzle, physics, creative |
|
||||
| Kaleidoscope | `abstract_kaleidoscope` | Symmetric radial patterns rotating like a living kaleidoscope | playful | `#1a1a2e` `#16213e` `#e94560` `#ffd166` | sparkles | music, creative, puzzle |
|
||||
| Matrix | `abstract_matrix` | Cascading columns of digital characters streaming down | digital | `#000000` `#001100` `#00ff41` `#008f11` | none | action, puzzle, trivia |
|
||||
|
||||
---
|
||||
|
||||
### Retro Theme
|
||||
|
||||
Nostalgic gaming aesthetics from past eras.
|
||||
|
||||
| Variant | ID | Description | Mood | Colors | Particles | Recommended For |
|
||||
|---------|-----|-------------|------|--------|-----------|-----------------|
|
||||
| Pixel Grid | `retro_pixelGrid` | A chunky pixel grid with classic 8-bit color blocks | nostalgic | `#1a1a2e` `#16213e` `#00ff88` `#ff6600` | sparkles | action, puzzle, creative |
|
||||
| Arcade Cabinet | `retro_arcadeCabinet` | Inside view of a dark arcade with neon-lit cabinet edges | fun | `#0a0a15` `#1a0a2e` `#ff2277` `#ffcc00` | dust | action, racing, sports |
|
||||
| CRT Effects | `retro_crtEffects` | Authentic CRT monitor with phosphor glow and scan line interference | vintage | `#0a0a0a` `#0f1a0f` `#33ff33` `#88ff88` | none | action, puzzle, trivia |
|
||||
| Vaporwave | `retro_vaporwave` | Aesthetic sunset horizon with perspective grid and palm silhouettes | aesthetic | `#0d0221` `#261447` `#ff71ce` `#01cdfe` | stars | creative, music, racing |
|
||||
| Scanlines | `retro_scanlines` | Dense horizontal scan lines over a shifting color field | technical | `#0a0a1a` `#141428` `#00aaff` `#ff4444` | none | action, puzzle, physics |
|
||||
| Glitch | `retro_glitch` | Fragmented display with chromatic aberration and corrupted data | chaotic | `#0a0a0a` `#1a0a1a` `#ff0055` `#00ffcc` | particles | action, racing, physics |
|
||||
| 8-Bit | `retro_eightBit` | Charming 8-bit scene with blocky pixel clouds and hills | cheerful | `#2b2b6e` `#3d3d94` `#5bc0eb` `#fde74c` | none | action, puzzle, creative |
|
||||
| Synthwave | `retro_synthwave` | Outrun-style neon horizon with receding road and mountain silhouettes | epic | `#0d0015` `#1a0033` `#ff2975` `#f222ff` | stars | racing, action, sports |
|
||||
|
||||
---
|
||||
|
||||
### Indoor Theme
|
||||
|
||||
Interior environments and spaces.
|
||||
|
||||
| Variant | ID | Description | Mood | Colors | Particles | Recommended For |
|
||||
|---------|-----|-------------|------|--------|-----------|-----------------|
|
||||
| Laboratory | `indoor_laboratory` | Dark science lab with glowing equipment and bubbling vials | mysterious | `#1a1e2e` `#2a3040` `#0f6b5e` `#44eebb` | bubbles | puzzle, trivia, rpg |
|
||||
| Classroom | `indoor_classroom` | Bright classroom with chalkboard, desks, and warm sunlight | cheerful | `#f5f0e0` `#d4c9a8` `#5b8c5a` `#8b5e3c` | dust | trivia, puzzle, story |
|
||||
| Bedroom | `indoor_bedroom` | Cozy bedroom at night with warm lamp glow and string lights | cozy | `#2a1f3d` `#3d2b5a` `#e8a87c` `#ffd166` | fireflies | story, creative, pet |
|
||||
| Kitchen | `indoor_kitchen` | Bright kitchen with checkered floor and warm appliance glow | warm | `#fff8e7` `#f0d9a0` `#c97b3a` `#8b4513` | dust | creative, pet, puzzle |
|
||||
| Arcade | `indoor_arcade` | Dark arcade with neon-lit cabinets and glowing screens | energetic | `#0d0d1a` `#1a0a2e` `#ff00ff` `#00ffff` | sparkles | action, racing, sports |
|
||||
| Office | `indoor_office` | Modern office with monitor glow and large windows | focused | `#e8e4dc` `#c5bfb2` `#4a6fa5` `#2c3e50` | dust | puzzle, trivia, creative |
|
||||
| Library | `indoor_library` | Grand library with towering bookshelves and reading lamps | serene | `#2c1810` `#4a3020` `#c4956a` `#f4e4c1` | dust | story, trivia, puzzle, rpg |
|
||||
| Gym | `indoor_gym` | Modern gym with equipment silhouettes and bright overhead lights | energetic | `#1a1a24` `#2a2a3a` `#ff4444` `#ff8800` | dust | action, sports, racing |
|
||||
|
||||
---
|
||||
|
||||
### Weather Theme
|
||||
|
||||
Atmospheric and meteorological conditions.
|
||||
|
||||
| Variant | ID | Description | Mood | Colors | Particles | Recommended For |
|
||||
|---------|-----|-------------|------|--------|-----------|-----------------|
|
||||
| Rain | `weather_rain` | Overcast sky with steady rainfall, puddles, and muted city outlines | melancholy | `#3a4a5a` `#2a3a4a` `#5a6a7a` `#8899aa` | rain | story, puzzle, rpg |
|
||||
| Snow | `weather_snow` | Gentle snowfall over a soft winter landscape with frosted trees | peaceful | `#c8d8e8` `#a0b8cc` `#e8eef4` `#FFFFFF` | snow | puzzle, pet, creative, story |
|
||||
| Storm | `weather_storm` | Dark storm clouds with heavy rain, wind-bent trees, and thunder | intense | `#1a1a25` `#252535` `#3a3a55` `#667788` | rain | action, rpg, racing |
|
||||
| Sunset | `weather_sunset` | Vibrant sunset with orange-purple gradient and silhouette landscape | warm | `#1a0a2e` `#cc4400` `#ff8833` `#ffd166` | sparkles | story, creative, pet, music |
|
||||
| Sunrise | `weather_sunrise` | Early morning sunrise with pink-orange sky, mist, and dewy fields | hopeful | `#2a1a40` `#884466` `#ee8855` `#ffe4a0` | dust | puzzle, pet, creative, sports |
|
||||
| Fog | `weather_fog` | Thick fog with barely visible shapes and dim lights | eerie | `#8a8a8a` `#666666` `#aaaaaa` `#cccccc` | fog | story, rpg, puzzle |
|
||||
| Lightning | `weather_lightning` | Pitch-dark sky lit by dramatic lightning bolts | dramatic | `#0a0a18` `#1a1a30` `#3344aa` `#eeeeff` | rain | action, rpg, racing |
|
||||
| Aurora | `weather_aurora` | Dark arctic sky with shimmering aurora borealis | magical | `#0a0a1a` `#0d1b2a` `#22cc88` `#8844dd` | stars | creative, rpg, story, music |
|
||||
|
||||
---
|
||||
|
||||
### Sports Theme
|
||||
|
||||
Athletic venues and environments.
|
||||
|
||||
| Variant | ID | Description | Mood | Colors | Particles | Recommended For |
|
||||
|---------|-----|-------------|------|--------|-----------|-----------------|
|
||||
| Stadium | `sports_stadium` | Large outdoor stadium with green pitch and bright floodlights | exciting | `#1a3a1a` `#2a5a2a` `#88cc44` `#ffffff` | sparkles | sports, action, trivia |
|
||||
| Race Track | `sports_raceTrack` | Asphalt race track with lane markings and grandstand | fast | `#333333` `#555555` `#cc0000` `#ffffff` | dust | racing, action, sports |
|
||||
| Court | `sports_court` | Indoor basketball court with polished hardwood and arena lighting | competitive | `#c47a34` `#e8944a` `#ffffff` `#2255aa` | sparkles | sports, action, trivia |
|
||||
| Field | `sports_field` | Open soccer field under blue sky with goals and corner flags | fresh | `#2a7a2a` `#3a9a3a` `#ffffff` `#88cc44` | leaves | sports, action, pet |
|
||||
| Arena | `sports_arena` | Dark fighting arena with dramatic spotlights and ropes | intense | `#1a1a2e` `#2a2a44` `#ff4444` `#ffaa00` | dust | action, sports, rpg |
|
||||
| Pool | `sports_pool` | Olympic swimming pool with lane dividers and rippling water | calm | `#1a6088` `#2288aa` `#44bbdd` `#88eeff` | sparkles | sports, racing, puzzle |
|
||||
| Gym | `sports_gym` | Gymnastics arena with spring floor and apparatus silhouettes | competitive | `#ddc8a0` `#c4a870` `#ffffff` `#cc3333` | dust | sports, action, creative |
|
||||
| Skatepark | `sports_skatepark` | Urban skatepark with concrete ramps and graffiti | cool | `#555566` `#777788` `#ff6600` `#ffcc00` | leaves | action, sports, racing, creative |
|
||||
|
||||
---
|
||||
|
||||
### Seasonal Theme
|
||||
|
||||
Time-of-year and holiday-themed environments.
|
||||
|
||||
| Variant | ID | Description | Mood | Colors | Particles | Recommended For |
|
||||
|---------|-----|-------------|------|--------|-----------|-----------------|
|
||||
| Spring Meadow | `seasonal_springMeadow` | A sunny spring meadow with wildflowers and gentle hills | cheerful | `#87CEEB` `#98FB98` `#FFD700` `#FF69B4` | leaves | puzzle, creative, pet |
|
||||
| Autumn Leaves | `seasonal_autumnLeaves` | A warm autumn landscape with falling leaves and golden light | warm | `#2C1810` `#CC5500` `#DD8833` `#FFD700` | leaves | puzzle, story, rpg |
|
||||
| Winter Wonderland | `seasonal_winterWonderland` | A serene winter landscape with snow-covered hills | calm | `#1A2744` `#4A7CB5` `#C8E0F4` `#FFFFFF` | snow | puzzle, story, creative |
|
||||
| Summer Beach | `seasonal_summerBeach` | A vibrant summer beach scene with rolling waves and warm sand | energetic | `#0077BE` `#00BFFF` `#F4D03F` `#FF6347` | sparkles | action, sports, racing |
|
||||
| Harvest | `seasonal_harvest` | Golden harvest fields with wheat rows and warm sunset | warm | `#5C3317` `#D4A017` `#8B4513` `#FFD700` | dust | puzzle, story, creative |
|
||||
| Blossom | `seasonal_blossom` | Gentle cherry blossom petals drifting under pink-tinted skies | peaceful | `#FFB7C5` `#FF69B4` `#FFF0F5` `#98FB98` | leaves | puzzle, story, creative, music |
|
||||
| Snowfall | `seasonal_snowfall` | Heavy snowfall over a dark winter night with distant lights | calm | `#0D1B2A` `#1B2838` `#415A77` `#E0E1DD` | snow | puzzle, story, rpg |
|
||||
| Tropical | `seasonal_tropical` | A lush tropical scene with dense foliage and vivid colors | energetic | `#00CED1` `#FF6347` `#228B22` `#FFD700` | fireflies | action, racing, sports, pet |
|
||||
|
||||
---
|
||||
|
||||
### Underwater Theme
|
||||
|
||||
Aquatic and marine environments.
|
||||
|
||||
| Variant | ID | Description | Mood | Colors | Particles | Recommended For |
|
||||
|---------|-----|-------------|------|--------|-----------|-----------------|
|
||||
| Coral Reef | `underwater_coralReef` | A vibrant coral reef teeming with colorful marine life | cheerful | `#006994` `#00A8CC` `#FF6F61` `#FFB347` | bubbles | puzzle, pet, creative |
|
||||
| Deep Sea | `underwater_deepSea` | The mysterious deep sea with bioluminescent creatures | mysterious | `#0A0A2E` `#0D1B3E` `#1A3A5C` `#00FFCC` | fireflies | rpg, story, puzzle |
|
||||
| Kelp Forest | `underwater_kelpForest` | A towering kelp forest with dappled light filtering through | peaceful | `#0B4F3A` `#1A7A5C` `#2FA87A` `#7EC8A0` | bubbles | puzzle, creative, story |
|
||||
| Submarine | `underwater_submarine` | A submarine expedition through dark ocean depths | adventurous | `#0A1628` `#1A3050` `#D4AA44` `#CC4444` | bubbles | action, rpg, story |
|
||||
| Shipwreck | `underwater_shipwreck` | A sunken ship resting on the ocean floor, overgrown with sea life | mysterious | `#0A1A2A` `#1A3344` `#8B7355` `#44AA88` | bubbles | rpg, story, puzzle |
|
||||
| Abyss | `underwater_abyss` | The abyssal zone with volcanic vents and glowing magma cracks | dark | `#020208` `#050515` `#0A0A30` `#FF2200` | particles | action, rpg, story |
|
||||
| Ice Cave | `underwater_iceCave` | An underwater ice cavern with crystalline formations | calm | `#0A2A4A` `#1A5A8A` `#88CCEE` `#E0F0FF` | sparkles | puzzle, story, creative |
|
||||
| Treasure | `underwater_treasure` | A hidden underwater treasure trove glowing with golden riches | adventurous | `#0D2B45` `#1A4A6A` `#FFD700` `#FF8C00` | sparkles | rpg, action, puzzle |
|
||||
|
||||
---
|
||||
|
||||
### Sky Theme
|
||||
|
||||
Aerial and atmospheric perspectives.
|
||||
|
||||
| Variant | ID | Description | Mood | Colors | Particles | Recommended For |
|
||||
|---------|-----|-------------|------|--------|-----------|-----------------|
|
||||
| Clouds | `sky_clouds` | A bright blue sky filled with drifting puffy white clouds | peaceful | `#4A90D9` `#87CEEB` `#FFFFFF` `#F0F8FF` | dust | puzzle, creative, pet |
|
||||
| Flying High | `sky_flyingHigh` | High altitude perspective with streaking wind lines and brilliant sun | energetic | `#1E3A6E` `#4682B4` `#FFD700` `#FFFFFF` | sparkles | action, racing, sports |
|
||||
| Hot Air Balloon | `sky_hotAirBalloon` | Colorful hot air balloons floating gently across a warm sky | cheerful | `#87CEEB` `#FF6347` `#FFD700` `#FFFFFF` | dust | puzzle, creative, pet, music |
|
||||
| Airplane View | `sky_airplaneView` | View from an airplane window looking down at a sea of clouds | calm | `#1A3366` `#336699` `#FFFFFF` `#AACCEE` | dust | puzzle, story, creative |
|
||||
| Stratosphere | `sky_stratosphere` | The edge of space where the atmosphere fades and Earth curves below | mysterious | `#0A0A2E` `#1A1A5E` `#4444AA` `#8888DD` | stars | story, rpg, puzzle |
|
||||
| Bird's Eye | `sky_birdsEye` | A bird's eye view looking down at patchwork fields and winding rivers | peaceful | `#5588BB` `#88BBDD` `#228B22` `#DEB887` | dust | puzzle, creative, story |
|
||||
| Horizon | `sky_horizon` | A dramatic sunset horizon with layers of warm orange, pink, and gold | warm | `#1A0533` `#CC4488` `#FF8844` `#FFD700` | dust | story, music, creative, rpg |
|
||||
| Starfield | `sky_starfield` | A clear night sky bursting with stars and a faint galactic band | calm | `#000011` `#0A0A2A` `#1A1A44` `#FFFFFF` | stars | puzzle, story, rpg, music |
|
||||
|
||||
---
|
||||
|
||||
### Mechanical Theme
|
||||
|
||||
Industrial and technological environments.
|
||||
|
||||
| Variant | ID | Description | Mood | Colors | Particles | Recommended For |
|
||||
|---------|-----|-------------|------|--------|-----------|-----------------|
|
||||
| Gears | `mechanical_gears` | Interlocking gears turning against a dark steel backdrop | focused | `#1A1A24` `#2A2A38` `#7A7A88` `#C08040` | dust | puzzle, physics, rpg |
|
||||
| Circuits | `mechanical_circuits` | Circuit board traces with glowing data paths | focused | `#0A0F14` `#112222` `#00CC88` `#33FFAA` | sparkles | puzzle, trivia, physics |
|
||||
| Factory | `mechanical_factory` | Factory floor with smokestacks and warning stripes | busy | `#1A1510` `#2A2520` `#8B7355` `#DDAA44` | dust | action, physics, puzzle |
|
||||
| Robot Factory | `mechanical_robotFactory` | Robot assembly line with mechanical arms and sparks | playful | `#151520` `#222238` `#5588CC` `#FFAA33` | sparkles | action, puzzle, creative |
|
||||
| Conveyor Belts | `mechanical_conveyorBelts` | Layered conveyor belts moving crates and parts | busy | `#18181F` `#28283A` `#666680` `#DD8822` | dust | puzzle, action, physics |
|
||||
| Pipes | `mechanical_pipes` | Interconnected pipe network with valves and joints | complex | `#121218` `#1E2A1E` `#558855` `#88BB44` | dust | puzzle, physics, rpg |
|
||||
| Steampunk | `mechanical_steamPunk` | Brass gears, gauges, and steam vents in warm tones | adventurous | `#1A1008` `#2A1A0A` `#C08040` `#E8C060` | dust | rpg, story, action |
|
||||
| Tech Lab | `mechanical_techLab` | Clean tech laboratory with holographic displays | curious | `#0E0E1A` `#1A1A30` `#4455AA` `#66DDFF` | sparkles | puzzle, trivia, creative |
|
||||
|
||||
---
|
||||
|
||||
### Spooky Theme
|
||||
|
||||
Eerie and horror-themed environments.
|
||||
|
||||
| Variant | ID | Description | Mood | Colors | Particles | Recommended For |
|
||||
|---------|-----|-------------|------|--------|-----------|-----------------|
|
||||
| Haunted House | `spooky_hauntedHouse` | A looming haunted house silhouette against a moonlit sky | eerie | `#0A0812` `#1A1025` `#3A2255` `#CCCC88` | fog | story, puzzle, rpg |
|
||||
| Graveyard | `spooky_graveyard` | Moonlit graveyard with crooked tombstones and mist | somber | `#080810` `#121828` `#2A3348` `#99AA77` | fog | rpg, story, puzzle |
|
||||
| Dark Forest | `spooky_darkForest` | Dense dark forest with twisted trees and glowing eyes | foreboding | `#050808` `#0A1510` `#1A2A18` `#3A5530` | fireflies | rpg, action, story |
|
||||
| Abandoned Building | `spooky_abandonedBuilding` | Crumbling abandoned building with broken windows and debris | desolate | `#0A0A0E` `#181820` `#3A3A48` `#667766` | dust | action, puzzle, rpg |
|
||||
| Crypt | `spooky_crypt` | Underground stone crypt with torchlight and coffins | dread | `#060608` `#101015` `#2A2A35` `#558855` | dust | rpg, action, story |
|
||||
| Manor | `spooky_manor` | Gothic manor interior with candlelight and portraits | gothic | `#0A080C` `#1A1020` `#3A2040` `#886644` | dust | story, rpg, puzzle |
|
||||
| Fog | `spooky_fog` | Thick rolling fog obscuring dark shapes and dim lights | mysterious | `#0A0E12` `#151E28` `#2A3844` `#556688` | fog | story, puzzle, rpg |
|
||||
| Shadows | `spooky_shadows` | Near-total darkness with shifting shadows and faint light | paranoid | `#050506` `#0E0E14` `#1C1C2A` `#332244` | dust | action, puzzle, rpg |
|
||||
|
||||
---
|
||||
|
||||
### Colorful Theme
|
||||
|
||||
Vibrant and visually striking environments.
|
||||
|
||||
| Variant | ID | Description | Mood | Colors | Particles | Recommended For |
|
||||
|---------|-----|-------------|------|--------|-----------|-----------------|
|
||||
| Rainbow | `colorful_rainbow` | Bold rainbow arcs and bands across a bright sky | joyful | `#FF4444` `#FFAA33` `#FFEE33` `#44DD55` | sparkles | creative, puzzle, music |
|
||||
| Paint Splatter | `colorful_paintSplatter` | Colorful paint splatters on a light canvas | creative | `#FAFAE8` `#FF3366` `#3388FF` `#FFCC00` | particles | creative, music, action |
|
||||
| Candy World | `colorful_candyWorld` | Candy landscape with lollipops, gumdrops, and sugar hills | sweet | `#FFE0F0` `#FF88BB` `#88DDFF` `#AAFFAA` | sparkles | pet, creative, puzzle |
|
||||
| Disco | `colorful_disco` | Disco floor with mirror ball and sweeping colored lights | energetic | `#1A0A2E` `#2A1A44` `#FF33AA` `#33FFCC` | sparkles | music, action, sports |
|
||||
| Neon | `colorful_neon` | Neon signs and glowing outlines against dark city night | electric | `#0A0A18` `#151530` `#FF0088` `#00FFCC` | particles | action, racing, music |
|
||||
| Tie-Dye | `colorful_tieDye` | Swirling tie-dye patterns with organic color blending | psychedelic | `#FF4488` `#FFAA22` `#44DDBB` `#8844FF` | particles | creative, music, story |
|
||||
| Gradient | `colorful_gradient` | Smooth shifting color gradients with geometric accents | peaceful | `#FF6B6B` `#FECA57` `#48DBFB` `#FF9FF3` | sparkles | puzzle, creative, trivia |
|
||||
| Prism | `colorful_prism` | Light splitting through prisms into rainbow beams | mystical | `#1A1A2E` `#0F3460` `#E94560` `#FFFFFF` | sparkles | puzzle, physics, creative |
|
||||
|
||||
---
|
||||
|
||||
## Compatible Music Moods
|
||||
|
||||
Backgrounds are tagged with compatible music moods for cohesive game experiences:
|
||||
|
||||
| Music Mood | Example Backgrounds |
|
||||
|------------|---------------------|
|
||||
| ambient | space_nebula, nature_ocean, weather_fog |
|
||||
| calm | nature_meadow, weather_snow, sky_clouds |
|
||||
| dreamy | abstract_gradients, seasonal_blossom, weather_aurora |
|
||||
| energetic | space_warpSpeed, sports_stadium, colorful_disco |
|
||||
| epic | fantasy_castle, weather_sunset, mechanical_steamPunk |
|
||||
| electronic | abstract_particleFields, retro_synthwave, colorful_neon |
|
||||
| playful | colorful_candyWorld, retro_pixelGrid, mechanical_robotFactory |
|
||||
| tense | space_asteroidField, spooky_crypt, weather_storm |
|
||||
| mysterious | underwater_deepSea, spooky_fog, sky_stratosphere |
|
||||
| happy | seasonal_springMeadow, sky_hotAirBalloon, underwater_treasure |
|
||||
|
||||
---
|
||||
|
||||
## Compatible Avatar Contexts
|
||||
|
||||
Recommended avatar context pairings for backgrounds:
|
||||
|
||||
| Background Theme | Recommended Avatar Contexts |
|
||||
|------------------|----------------------------|
|
||||
| space | astronaut, robot, alien, superhero |
|
||||
| nature | explorer, hiker, animal, fairy |
|
||||
| urban | cyclist, skater, runner, casual |
|
||||
| fantasy | knight, wizard, fairy, dragon |
|
||||
| abstract | geometric, minimal, gamer |
|
||||
| retro | pixel, arcade, classic |
|
||||
| indoor | student, worker, gamer, casual |
|
||||
| weather | raincoat, winter, summer |
|
||||
| sports | athlete, racer, swimmer |
|
||||
| seasonal | holiday, themed |
|
||||
| underwater | diver, mermaid, fish |
|
||||
| sky | pilot, bird, balloon |
|
||||
| mechanical | robot, engineer, steampunk |
|
||||
| spooky | ghost, monster, vampire |
|
||||
| colorful | party, disco, rainbow |
|
||||
|
||||
---
|
||||
|
||||
## API Usage
|
||||
|
||||
### Get All Themes
|
||||
|
||||
```javascript
|
||||
const summary = BackgroundEngine.getThemeSummary();
|
||||
// Returns: [{ theme: 'space', variants: [...], count: 8 }, ...]
|
||||
```
|
||||
|
||||
### Get Total Background Count
|
||||
|
||||
```javascript
|
||||
const total = BackgroundEngine.getTotalCount();
|
||||
// Returns: 120
|
||||
```
|
||||
|
||||
### Find Backgrounds by Game Genre
|
||||
|
||||
```javascript
|
||||
const puzzleBackgrounds = BackgroundEngine.findByGenre('puzzle');
|
||||
// Returns array of backgrounds recommended for puzzle games
|
||||
```
|
||||
|
||||
### Find by Music Mood
|
||||
|
||||
```javascript
|
||||
const calmBackgrounds = BackgroundEngine.findByMusicMood('calm');
|
||||
// Returns backgrounds compatible with calm music
|
||||
```
|
||||
|
||||
### Get Random Background from Theme
|
||||
|
||||
```javascript
|
||||
const bg = BackgroundEngine.getRandomFromTheme('space');
|
||||
// Returns: { theme: 'space', variant: 'nebula' } (random)
|
||||
```
|
||||
|
||||
### Get Random Matching Filters
|
||||
|
||||
```javascript
|
||||
const bg = BackgroundEngine.getRandomMatching({
|
||||
mood: 'energetic',
|
||||
tags: ['neon']
|
||||
});
|
||||
```
|
||||
|
||||
### Validate Catalog Integrity
|
||||
|
||||
```javascript
|
||||
const issues = BackgroundEngine.validateCatalog();
|
||||
// Returns array of any missing/invalid registrations
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Visual Preview Guide
|
||||
|
||||
Each background can be previewed using the BackgroundEngine:
|
||||
|
||||
```javascript
|
||||
// Initialize canvas
|
||||
const canvas = document.createElement('canvas');
|
||||
canvas.width = 800;
|
||||
canvas.height = 600;
|
||||
const ctx = canvas.getContext('2d');
|
||||
|
||||
// Render a specific background
|
||||
BackgroundEngine.set('space', 'nebula');
|
||||
|
||||
// In animation loop:
|
||||
function render(time) {
|
||||
BackgroundEngine.render(ctx, canvas.width, canvas.height, time / 1000);
|
||||
requestAnimationFrame(render);
|
||||
}
|
||||
render(0);
|
||||
```
|
||||
|
||||
### Color Palette Structure
|
||||
|
||||
Each background defines 4 colors:
|
||||
- **Color 1**: Primary/dominant background color
|
||||
- **Color 2**: Secondary background color
|
||||
- **Color 3**: Accent/highlight color
|
||||
- **Color 4**: Detail/contrast color
|
||||
|
||||
### Render Layers
|
||||
|
||||
1. **Base Layer** (`renderBase`) - Sky, ground, gradients
|
||||
2. **Mid Layer** (`renderMid`) - Objects, details, animations
|
||||
3. **Particle Layer** - Ambient particle effects (optional)
|
||||
|
||||
---
|
||||
|
||||
## Catalog Statistics
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Total Themes | 15 |
|
||||
| Variants Per Theme | 8 |
|
||||
| Total Backgrounds | 120 |
|
||||
| Particle Types | 10 |
|
||||
| Moods Available | 16 |
|
||||
| Game Genres Mapped | 10 |
|
||||
|
||||
---
|
||||
|
||||
*Last Updated: 2026-02-05*
|
||||
*Version: 1.0.0*
|
||||
@@ -0,0 +1,721 @@
|
||||
# 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)
|
||||
@@ -0,0 +1,170 @@
|
||||
# Game Generation Guide for AI
|
||||
|
||||
This guide helps Haiku (Claude AI) select appropriate assets when generating games.
|
||||
|
||||
## Decision Tree
|
||||
|
||||
### Step 1: Identify Game Style
|
||||
|
||||
Based on user's prompt, classify into one of 11 styles:
|
||||
|
||||
| Keywords | Game Style |
|
||||
|----------|------------|
|
||||
| shoot, space, action, fast, arcade | action-arcade |
|
||||
| puzzle, match, brain, logic | puzzle |
|
||||
| story, adventure, narrative, choice | story-adventure |
|
||||
| race, car, speed, run | racing |
|
||||
| pet, animal, care, farm | pet-simulator |
|
||||
| quiz, trivia, question, knowledge | trivia-quiz |
|
||||
| music, rhythm, dance, beat | music-rhythm |
|
||||
| draw, create, art, design | creative-drawing |
|
||||
| rpg, battle, quest, dungeon | rpg-battle |
|
||||
| sports, ball, soccer, basketball | sports |
|
||||
| physics, pinball, bounce, gravity | physics-pinball |
|
||||
|
||||
### Step 2: Detect Theme
|
||||
|
||||
| Theme Keywords | Background Theme |
|
||||
|----------------|-----------------|
|
||||
| space, alien, star, galaxy | space |
|
||||
| forest, nature, tree, outdoor | nature |
|
||||
| city, street, building, urban | urban |
|
||||
| magic, wizard, dragon, castle | fantasy |
|
||||
| ghost, haunted, scary, dark | spooky |
|
||||
| ocean, fish, underwater, sea | underwater |
|
||||
| retro, pixel, arcade, classic | retro |
|
||||
| sports, stadium, field, court | sports |
|
||||
| sky, flying, clouds, air | sky |
|
||||
| rainbow, colorful, bright, party | colorful |
|
||||
| robot, machine, factory, tech | mechanical |
|
||||
| home, room, kitchen, office | indoor |
|
||||
| rain, snow, storm, weather | weather |
|
||||
| spring, summer, autumn, winter | seasonal |
|
||||
| abstract, minimal, pattern | abstract |
|
||||
|
||||
### Step 3: Detect Mood
|
||||
|
||||
| Mood Keywords | Music Mood |
|
||||
|---------------|------------|
|
||||
| epic, battle, intense, boss | Epic |
|
||||
| calm, relax, peaceful, zen | Chill |
|
||||
| fast, action, rush, chase | Intense |
|
||||
| fun, happy, cute, silly | Playful |
|
||||
| mystery, scary, dark, creepy | Mysterious |
|
||||
| hero, adventure, brave | Heroic |
|
||||
| weird, unique, strange | Quirky |
|
||||
| background, ambient, subtle | Ambient |
|
||||
|
||||
### Step 4: Determine Avatar Mode
|
||||
|
||||
| Game Mechanic | Avatar Mode | Context |
|
||||
|---------------|-------------|---------|
|
||||
| Cockpit/driving view | HEAD_ONLY | spaceship-cockpit, tank, mech-suit |
|
||||
| Driving with body visible | HEAD_AND_SHOULDERS | race-car, airplane, submarine |
|
||||
| Upper body action | UPPER_BODY | hoverboard, jetpack |
|
||||
| Full character movement | FULL_BODY | platformer-standard, costumes |
|
||||
|
||||
### Step 5: Select Context
|
||||
|
||||
| Game Type | Recommended Context |
|
||||
|-----------|---------------------|
|
||||
| Space shooter | spaceship-cockpit |
|
||||
| Racing game | race-car, motorcycle |
|
||||
| Flappy clone | flappy-style |
|
||||
| Tank game | tank |
|
||||
| Maze game (pacman) | pacman-style |
|
||||
| Hoverboard/skateboard | hoverboard |
|
||||
| Jetpack game | jetpack |
|
||||
| Mech combat | mech-suit |
|
||||
| Underwater | submarine |
|
||||
| Dragon game | dragon-rider |
|
||||
| Platformer | platformer-standard |
|
||||
| RPG/Adventure | knight-armor, wizard-robes, ninja-outfit |
|
||||
| Sports | athlete-uniform, sports-player |
|
||||
| Cooking | chef-outfit |
|
||||
| Science | scientist-labcoat |
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Use Presets for Variety
|
||||
```javascript
|
||||
// DON'T: Always use the same combination
|
||||
background: { theme: 'space', variant: 'nebula' }
|
||||
|
||||
// DO: Use different presets or variations
|
||||
const preset = AssetPresets.getRandom('action-arcade');
|
||||
```
|
||||
|
||||
### 2. Match Mood and Theme
|
||||
```javascript
|
||||
// GOOD: Epic music + Space background
|
||||
{ music: { mood: 'Epic' }, background: { theme: 'space' } }
|
||||
|
||||
// BAD: Chill music + Intense action background
|
||||
{ music: { mood: 'Chill' }, background: { theme: 'mechanical' } }
|
||||
```
|
||||
|
||||
### 3. Match Context to Gameplay
|
||||
```javascript
|
||||
// GOOD: Flying game → HEAD_ONLY + flappy-style
|
||||
// GOOD: Platformer → FULL_BODY + platformer-standard
|
||||
// BAD: Racing game → FULL_BODY (should be HEAD_AND_SHOULDERS)
|
||||
```
|
||||
|
||||
### 4. Validate Combinations
|
||||
```javascript
|
||||
const score = AssetCompatibility.validate(config).score;
|
||||
// Aim for score > 70
|
||||
```
|
||||
|
||||
## Example Selections
|
||||
|
||||
### "space shooter with aliens"
|
||||
```javascript
|
||||
{
|
||||
music: { mood: 'Epic', energy: 8 },
|
||||
background: { theme: 'space', variant: 'nebula' },
|
||||
avatarContext: { mode: 'HEAD_ONLY', context: 'spaceship-cockpit' }
|
||||
}
|
||||
```
|
||||
|
||||
### "relaxing puzzle game with nature"
|
||||
```javascript
|
||||
{
|
||||
music: { mood: 'Chill', energy: 3 },
|
||||
background: { theme: 'nature', variant: 'meadow' },
|
||||
avatarContext: { mode: 'FULL_BODY', context: 'platformer-standard' }
|
||||
}
|
||||
```
|
||||
|
||||
### "medieval RPG with dragon battles"
|
||||
```javascript
|
||||
{
|
||||
music: { mood: 'Epic', energy: 9 },
|
||||
background: { theme: 'fantasy', variant: 'castle' },
|
||||
avatarContext: { mode: 'FULL_BODY', context: 'knight-armor' }
|
||||
}
|
||||
```
|
||||
|
||||
### "scary haunted house escape"
|
||||
```javascript
|
||||
{
|
||||
music: { mood: 'Mysterious', energy: 5 },
|
||||
background: { theme: 'spooky', variant: 'hauntedHouse' },
|
||||
avatarContext: { mode: 'FULL_BODY', context: 'adventure-hero' }
|
||||
}
|
||||
```
|
||||
|
||||
## Tracking Variety
|
||||
|
||||
To ensure games don't all look the same:
|
||||
|
||||
1. Rotate through presets (don't always pick index 0)
|
||||
2. Use different background variants within same theme
|
||||
3. Mix costumes even for similar game types
|
||||
4. Vary music energy levels
|
||||
|
||||
## Template Selection
|
||||
|
||||
- Use `gameTemplateAssets.html` when avatar matters
|
||||
- Use `gameTemplateSimple.html` for abstract/puzzle games without avatars
|
||||
@@ -0,0 +1,406 @@
|
||||
# Music Catalog
|
||||
|
||||
## Overview
|
||||
|
||||
160 procedural songs generated using Tone.js.
|
||||
8 moods x 20 songs each.
|
||||
|
||||
All songs are synthesized in real-time using the MusicEngine, which reads song definitions from MusicLibrary and generates audio procedurally using Tone.js synths, effects, and chord progressions.
|
||||
|
||||
---
|
||||
|
||||
## Mood Categories
|
||||
|
||||
### Epic (20 songs)
|
||||
|
||||
Energy range: 7-10
|
||||
Best for: Boss battles, climactic moments, action sequences
|
||||
|
||||
| ID | Name | Energy | Tempo | Key | Tags | Description |
|
||||
|----|------|--------|-------|-----|------|-------------|
|
||||
| epic_001 | Siege of Thunder | 9 | 150 | C minor | action, siege, storm | Thunderous orchestral assault with relentless percussion and soaring brass lines |
|
||||
| epic_002 | Dragon's Wrath | 10 | 160 | D harmonic minor | dragon, boss-fight, powerful | Ferocious harmonic minor shred with explosive drum fills and scorching lead |
|
||||
| epic_003 | Kingdom's Fall | 8 | 135 | E dorian | kingdom, dramatic, war | Brooding dorian march that builds from sorrowful strings to a devastating climax |
|
||||
| epic_004 | Titan Ascendant | 9 | 145 | F minor | titan, heroic, climax | Ascending power theme with massive layered synths and triumphant resolution |
|
||||
| epic_005 | Forge of Legends | 8 | 130 | G melodic minor | forge, battle, powerful | Heavy melodic minor groove with hammering rhythms and a blazing lead melody |
|
||||
| epic_006 | Storm Legion | 9 | 155 | A harmonic minor | storm, legion, fierce | Rapid harmonic minor fury with militant snare rolls and piercing lead runs |
|
||||
| epic_007 | Conquest of Dawn | 8 | 140 | B minor | conquest, heroic, victory | Majestic dawn-rise theme with layered pads building to a grand fanfare |
|
||||
| epic_008 | Blood of the Arena | 10 | 165 | C# phrygian | battle, fierce, combat | Phrygian gladiator anthem with thundering kicks and savage melodic hooks |
|
||||
| epic_009 | Throne Eternal | 7 | 125 | D# dorian | throne, dramatic, kingdom | Stately dorian processional with regal brass swells and ceremonial percussion |
|
||||
| epic_010 | Wings of Valkyrie | 9 | 152 | F# harmonic minor | heroic, action, victory | Soaring harmonic minor flight with rapid arpeggios and a euphoric peak |
|
||||
| epic_011 | The Iron March | 8 | 132 | G# minor | war, legion, march | Crushing military march with iron-clad percussion and a resolute melodic theme |
|
||||
| epic_012 | Celestial Siege | 9 | 148 | A# melodic minor | siege, climax, powerful | Heavenly melodic minor ascent colliding with earth-shaking low end and choir-like pads |
|
||||
| epic_013 | Oathbreaker | 10 | 170 | E harmonic minor | boss-fight, aggressive, dramatic | Blistering boss battle anthem with relentless double-kicks and a searing harmonic minor riff |
|
||||
| epic_014 | Pillars of Eternity | 7 | 120 | F dorian | dramatic, kingdom, throne | Grand dorian hymn with towering pad layers and a slow-building, inevitable crescendo |
|
||||
| epic_015 | The Last Bastion | 9 | 142 | A minor | siege, heroic, battle | Desperate last-stand theme with urgent strings and a defiant, rising chorus |
|
||||
| epic_016 | Warcry of the North | 10 | 158 | B harmonic minor | war, fierce, conquest | Nordic war chant with thunderous toms, harsh harmonic minor runs, and tribal energy |
|
||||
| epic_017 | Shattered Crown | 8 | 138 | C# dorian | dramatic, throne, powerful | Regal dorian tragedy with broken chord progressions that rebuild into glory |
|
||||
| epic_018 | Dragonfire Overture | 9 | 162 | D melodic minor | dragon, action, climax | Scorching melodic minor overture with blazing fast arpeggios and massive drops |
|
||||
| epic_019 | Echoes of Valhalla | 8 | 128 | G minor | victory, heroic, legend | Heroic afterglow theme with echoing delays, reverent pads, and a noble melody |
|
||||
| epic_020 | Apex Predator | 10 | 168 | D# phrygian | boss-fight, titan, aggressive | Phrygian apex boss theme with crushing low end, frantic leads, and zero mercy |
|
||||
|
||||
---
|
||||
|
||||
### Chill (20 songs)
|
||||
|
||||
Energy range: 1-4
|
||||
Best for: Puzzle games, menus, relaxation
|
||||
|
||||
| ID | Name | Energy | Tempo | Key | Tags | Description |
|
||||
|----|------|--------|-------|-----|------|-------------|
|
||||
| chill_001 | Sunset Horizon | 2 | 80 | C major | sunset, calm, peaceful | Warm golden-hour pads with gentle plucked melodies drifting over a soft beat |
|
||||
| chill_002 | Cloud Nine | 2 | 85 | D lydian | cloud, zen, soft | Floating lydian dreamscape with airy pads and a delicate crystalline lead |
|
||||
| chill_003 | Gentle Stream | 1 | 72 | F major | stream, peaceful, meditation | Babbling brook ambience with minimal plucked notes and vast reverb spaces |
|
||||
| chill_004 | Amber Dusk | 3 | 90 | G mixolydian | sunset, smooth, lounge | Laid-back mixolydian groove with a silky lead line and soft shuffled percussion |
|
||||
| chill_005 | Velvet Rain | 2 | 78 | A dorian | rain, calm, soft | Tender dorian rainfall with muted plucks and warm sub-bass undertones |
|
||||
| chill_006 | Morning Dew | 3 | 95 | E pentatonic major | breeze, garden, easy | Fresh pentatonic morning with sparkling plucks and a gentle rhythmic pulse |
|
||||
| chill_007 | Sapphire Coast | 3 | 92 | B major | shore, smooth, relax | Coastal shimmer with wave-like pad swells and a melodic bass walk |
|
||||
| chill_008 | Paper Lanterns | 2 | 76 | D# lydian | zen, peaceful, meditation | Floating lydian lantern-light with shimmering overtones and barely-there percussion |
|
||||
| chill_009 | Lavender Fields | 2 | 82 | F# major | garden, calm, soft | Pastoral meadow soundscape with singing pads and tiny melodic blossoms |
|
||||
| chill_010 | Moonlit Canopy | 1 | 70 | C# dorian | zen, meditation, soft | Deep forest night ambience with owl-like calls and a hypnotic dorian drone |
|
||||
| chill_011 | Drifting Kites | 3 | 100 | G# pentatonic major | breeze, cheerful, easy | Breezy pentatonic float with a playful pluck melody and airy pad washes |
|
||||
| chill_012 | Still Waters | 1 | 74 | A# major | calm, peaceful, meditation | Mirror-flat lake ambience with slow reverb tails and barely audible melodic whispers |
|
||||
| chill_013 | Silken Thread | 3 | 96 | D mixolydian | smooth, lounge, easy | Sophisticated mixolydian lounge with buttery chords and a cool walking bass |
|
||||
| chill_014 | Porcelain Sky | 2 | 84 | E lydian | cloud, zen, peaceful | Delicate lydian sky with bell-like plucks floating over an endless pad horizon |
|
||||
| chill_015 | Terracotta Noon | 4 | 105 | A dorian | smooth, lounge, relax | Sun-baked dorian groove with a loose beat, mellow keys, and an easy bass line |
|
||||
| chill_016 | Snowfall Waltz | 2 | 88 | F major | soft, calm, peaceful | Gentle snowfall waltz with twinkling bells and a feather-light three-beat feel |
|
||||
| chill_017 | Jasmine Tea | 2 | 78 | G pentatonic major | zen, meditation, soft | Meditative pentatonic ritual with ceramic-toned plucks and warm bass hum |
|
||||
| chill_018 | Indigo Hour | 3 | 98 | B dorian | smooth, lounge, sunset | Deep dorian twilight groove with a muted lead, lush pads, and subtle swing |
|
||||
| chill_019 | Floating Feather | 1 | 70 | C lydian | cloud, peaceful, meditation | Weightless lydian drift with overtone-rich pads and the faintest melodic outline |
|
||||
| chill_020 | Harbor Lights | 4 | 110 | F# mixolydian | shore, smooth, relax | Warm harbor-side mixolydian jam with a steady pulse and reflective melodic phrases |
|
||||
|
||||
---
|
||||
|
||||
### Intense (20 songs)
|
||||
|
||||
Energy range: 8-10
|
||||
Best for: Racing, action, time pressure
|
||||
|
||||
| ID | Name | Energy | Tempo | Key | Tags | Description |
|
||||
|----|------|--------|-------|-----|------|-------------|
|
||||
| intense_001 | Midnight Chase | 9 | 160 | C minor | chase, urgent, adrenaline | Heart-pounding minor key pursuit with relentless four-on-floor and staccato stabs |
|
||||
| intense_002 | Fury Unleashed | 10 | 175 | D phrygian | fury, aggressive, rampage | Phrygian berserker rage with distorted bass, frantic leads, and pummeling kicks |
|
||||
| intense_003 | Overdrive | 9 | 155 | E minor | overdrive, fast, thrilling | Redlined engine energy with screaming synths and a breakneck tempo that never lets up |
|
||||
| intense_004 | Razor Edge | 10 | 170 | F harmonic minor | danger, aggressive, combat | Razor-sharp harmonic minor slashes with searing leads and machine-gun percussion |
|
||||
| intense_005 | Panic Protocol | 9 | 165 | G minor | panic, urgent, pursuit | Emergency klaxon energy with alarm-like leads and a propulsive bass engine |
|
||||
| intense_006 | Blitz Reaper | 10 | 180 | A phrygian | blitz, fierce, frenzy | Maximum-speed phrygian onslaught with unrelenting double-time drums and savage riffs |
|
||||
| intense_007 | Neon Inferno | 9 | 150 | B blues | adrenaline, thrilling, fast | Blues-infused neon hellscape with gritty lead bends and a stomping groove |
|
||||
| intense_008 | Shockwave | 10 | 172 | C# harmonic minor | combat, aggressive, fierce | Explosive harmonic minor shockblast with staccato stabs and obliterating drops |
|
||||
| intense_009 | Terminal Velocity | 9 | 162 | D# minor | fast, pursuit, adrenaline | Free-falling velocity rush with whipping arpeggios and an unstoppable beat |
|
||||
| intense_010 | Venom Strike | 10 | 168 | F# phrygian | danger, combat, rampage | Venomous phrygian attack with serpentine lead phrases and toxic bass drops |
|
||||
| intense_011 | Wraith Runner | 9 | 156 | G# harmonic minor | chase, thrilling, urgent | Ghostly harmonic minor sprint with phasing leads and a thundering rhythmic foundation |
|
||||
| intense_012 | Meltdown | 10 | 176 | A# chromatic | frenzy, aggressive, panic | Nuclear meltdown chaos with chromatic madness and total percussive devastation |
|
||||
| intense_013 | Iron Lung | 8 | 148 | C blues | fierce, thrilling, overdrive | Breathless blues-scale assault with a heavy swing and gritty overdriven bass |
|
||||
| intense_014 | Voltage Surge | 9 | 158 | D minor | adrenaline, fast, urgent | Electric voltage spike with buzzing FM leads and an unstoppable rhythmic charge |
|
||||
| intense_015 | Reckless Descent | 9 | 152 | E harmonic minor | danger, thrilling, pursuit | Spiraling harmonic minor descent with cascading leads and hammering kicks |
|
||||
| intense_016 | Firestorm Protocol | 10 | 174 | F phrygian | combat, aggressive, blitz | Scorched-earth phrygian devastation with relentless snare rolls and wall-of-sound bass |
|
||||
| intense_017 | Cascade Fury | 8 | 145 | G minor | fierce, pursuit, thrilling | Cascading minor fury with tumbling melodic runs and a rock-solid groove foundation |
|
||||
| intense_018 | Deathline Express | 10 | 178 | A harmonic minor | frenzy, rampage, aggressive | Runaway-train harmonic minor express with breakneck speed and zero stopping power |
|
||||
| intense_019 | Concrete Jungle | 8 | 142 | B blues | urgent, adrenaline, thrilling | Gritty urban blues assault with dirty bass growls and relentless breakbeat energy |
|
||||
| intense_020 | Event Horizon | 9 | 164 | D# chromatic | danger, panic, fast | Reality-warping chromatic vortex pulling everything into a relentless rhythmic singularity |
|
||||
|
||||
---
|
||||
|
||||
### Playful (20 songs)
|
||||
|
||||
Energy range: 4-7
|
||||
Best for: Kids games, casual games, fun moments
|
||||
|
||||
| ID | Name | Energy | Tempo | Key | Tags | Description |
|
||||
|----|------|--------|-------|-----|------|-------------|
|
||||
| playful_001 | Bubble Pop | 6 | 130 | C major | fun, bouncy, bubble | Bouncy pop confection with fizzy pluck melodies and a toe-tapping beat |
|
||||
| playful_002 | Candy Rush | 7 | 140 | D mixolydian | candy, happy, party | Sugar-coated mixolydian romp with rapid-fire melodies and a party-floor beat |
|
||||
| playful_003 | Skip & Jump | 5 | 120 | F major | skip, cheerful, lighthearted | Carefree skip-along with a lilting melody, simple chords, and a playful shuffle |
|
||||
| playful_004 | Sunshine Express | 6 | 135 | G lydian | sunshine, happy, dance | Bright lydian sunshine ride with sparkling chords and an infectious rhythmic hook |
|
||||
| playful_005 | Frog Hop | 5 | 118 | A pentatonic major | jump, silly, cartoon | Quirky pentatonic hop with bouncing bass notes and a whimsical plucked melody |
|
||||
| playful_006 | Pixel Parade | 6 | 132 | E major | fun, cheerful, party | Retro pixel-art parade with chiptuney leads and a marching festival vibe |
|
||||
| playful_007 | Jellybean Bounce | 7 | 142 | B mixolydian | bouncy, candy, dance | Maximum-bounce mixolydian groove with rubbery bass and a sugary melodic hook |
|
||||
| playful_008 | Rainbow Sprinkles | 5 | 125 | C# lydian | rainbow, happy, lighthearted | Colorful lydian celebration with chiming leads and a gentle, flowing groove |
|
||||
| playful_009 | Trampoline | 7 | 145 | D# major | jump, bouncy, fun | Sky-high trampoline energy with elastic bass and soaring staccato rebounds |
|
||||
| playful_010 | Whirlwind Waltz | 4 | 115 | F# major | dance, cheerful, lighthearted | Gentle whirlwind waltz with graceful plucks and a charming three-beat lilt |
|
||||
| playful_011 | Firefly Festival | 5 | 122 | G# pentatonic major | cheerful, fun, frolic | Twinkling firefly night with dancing pentatonic melodies and a warm, steady pulse |
|
||||
| playful_012 | Lollipop Lane | 6 | 128 | A# major | candy, silly, cartoon | Sweet lollipop stroll with cartoon-like sound effects and a skip-worthy rhythm |
|
||||
| playful_013 | Dizzy Spin | 7 | 148 | E dorian | fun, dance, party | Dizzying dorian spin cycle with whirling arpeggios and a head-bobbing groove |
|
||||
| playful_014 | Cotton Candy Clouds | 4 | 112 | F lydian | cloud, happy, lighthearted | Fluffy lydian cotton-candy float with soft plucks and dreamy pad wisps |
|
||||
| playful_015 | Pinball Wizard | 7 | 150 | A mixolydian | fun, bouncy, party | Rapid-fire pinball ricochet with dinging FM leads and a hyperactive bassline |
|
||||
| playful_016 | Confetti Cannon | 6 | 138 | B major | party, cheerful, dance | Explosive confetti burst with bright staccato hits and a celebratory chorus |
|
||||
| playful_017 | Rubber Duck | 5 | 116 | D pentatonic major | silly, cartoon, fun | Squeaky-clean pentatonic ditty with rubbery bass plucks and a goofy swing |
|
||||
| playful_018 | Kite Runner | 5 | 124 | G dorian | frolic, lighthearted, breeze | Breezy dorian kite flight with soaring lead phrases and a playful rhythmic tug |
|
||||
| playful_019 | Pancake Flip | 6 | 134 | C mixolydian | silly, fun, bouncy | Morning-kitchen mixolydian jam with flippy rhythms and a warm, buttery tone |
|
||||
| playful_020 | Starlight Carousel | 4 | 110 | F# lydian | dance, happy, lighthearted | Enchanted carousel spin with twinkling lydian bells and a gentle, revolving rhythm |
|
||||
|
||||
---
|
||||
|
||||
### Mysterious (20 songs)
|
||||
|
||||
Energy range: 2-5
|
||||
Best for: Horror, exploration, puzzles
|
||||
|
||||
| ID | Name | Energy | Tempo | Key | Tags | Description |
|
||||
|----|------|--------|-------|-----|------|-------------|
|
||||
| mysterious_001 | Shadow Waltz | 3 | 95 | D phrygian | mystery, dark, suspense | Eerie waltz with unsettling chromatic turns and ghostly reverberations |
|
||||
| mysterious_002 | Phantom's Riddle | 4 | 105 | A harmonic minor | phantom, riddle, enigma | Brooding harmonic minor theme with restless melodic questions |
|
||||
| mysterious_003 | Twilight Labyrinth | 3 | 88 | F# minor | twilight, labyrinth, shadow | Winding minor key passages through dim corridors of sound |
|
||||
| mysterious_004 | Crypt Whispers | 2 | 82 | B phrygian | crypt, whisper, eerie | Hushed phrygian murmurs echoing through ancient stone chambers |
|
||||
| mysterious_005 | Fog of Enigma | 3 | 100 | E whole tone | fog, enigma, mystery | Drifting whole-tone haze obscuring all sense of harmonic direction |
|
||||
| mysterious_006 | Spell Unraveled | 5 | 115 | G harmonic minor | spell, dark, haunt | Urgent harmonic minor incantation building to a feverish climax |
|
||||
| mysterious_007 | Void Gazer | 2 | 84 | C chromatic | void, dark, eerie | Staring into the abyss with atonal fragments dissolving into silence |
|
||||
| mysterious_008 | Detective Noir | 4 | 108 | C# minor | detective, suspense, shadow | Smoky noir investigation theme with sly chromatic bass lines |
|
||||
| mysterious_009 | Haunted Carousel | 4 | 112 | F phrygian | haunt, eerie, puzzle | A broken carousel spinning in phrygian darkness with warped melodies |
|
||||
| mysterious_010 | Riddle of Echoes | 3 | 92 | D# harmonic minor | riddle, enigma, whisper | Haunting call-and-response between shadowy melodic fragments |
|
||||
| mysterious_011 | Obsidian Mirror | 3 | 98 | G# minor | dark, mystery, shadow | Dark reflections shimmer in minor key with glassy sustained tones |
|
||||
| mysterious_012 | Serpent Passage | 5 | 118 | A# phrygian | suspense, dark, labyrinth | Slithering phrygian riff coiling through an underground labyrinth |
|
||||
| mysterious_013 | Moonless Night | 2 | 80 | E whole tone | eerie, void, twilight | Formless whole-tone drifts under a starless sky with no resolution |
|
||||
| mysterious_014 | Specter's Descent | 4 | 104 | B harmonic minor | phantom, dark, haunt | Descending harmonic minor spiral pulling deeper into spectral depths |
|
||||
| mysterious_015 | Puzzle Chamber | 4 | 110 | F minor | puzzle, mystery, riddle | Interlocking melodic puzzles clicking into place within stone walls |
|
||||
| mysterious_016 | Veiled Threshold | 3 | 90 | C phrygian | mystery, fog, twilight | Standing at the boundary between worlds in thick phrygian fog |
|
||||
| mysterious_017 | Waning Sigil | 3 | 96 | D harmonic minor | spell, enigma, crypt | A fading magical sigil pulsing with diminishing harmonic minor energy |
|
||||
| mysterious_018 | Forgotten Archive | 3 | 94 | G# chromatic | mystery, puzzle, shadow | Dusty chromatic fragments unearthed from a lost archive of secrets |
|
||||
| mysterious_019 | Oracle's Warning | 5 | 120 | A minor | suspense, dark, whisper | An urgent prophetic warning delivered in frantic minor key passages |
|
||||
| mysterious_020 | Abyssal Lullaby | 2 | 85 | F# whole tone | void, eerie, twilight | A gentle yet deeply unsettling lullaby drifting over an endless abyss |
|
||||
|
||||
---
|
||||
|
||||
### Heroic (20 songs)
|
||||
|
||||
Energy range: 6-9
|
||||
Best for: Adventure, achievements, victories
|
||||
|
||||
| ID | Name | Energy | Tempo | Key | Tags | Description |
|
||||
|----|------|--------|-------|-----|------|-------------|
|
||||
| heroic_001 | Champion's Anthem | 8 | 145 | C major | hero, triumph, anthem | A soaring major key anthem celebrating the ultimate champion |
|
||||
| heroic_002 | Dawn of Valor | 7 | 138 | G lydian | dawn, valor, courage | Radiant lydian sunrise heralding a new era of bravery and valor |
|
||||
| heroic_003 | Shield Bearer | 7 | 132 | D mixolydian | shield, brave, quest | Sturdy mixolydian march of a steadfast shield bearer on a noble quest |
|
||||
| heroic_004 | Glory Unchained | 9 | 155 | A major | glory, triumph, champion | Explosive high-energy celebration of total victory and unchained glory |
|
||||
| heroic_005 | Oath of the Paladin | 7 | 128 | F dorian | oath, paladin, courage | Solemn yet powerful dorian oath sworn by a noble paladin |
|
||||
| heroic_006 | Crusader's March | 8 | 142 | E major | crusade, hero, sword | Relentless marching rhythm driving a crusade forward to victory |
|
||||
| heroic_007 | Beacon of Hope | 6 | 125 | B lydian | beacon, hero, legend | A luminous lydian melody shining as a beacon through the darkness |
|
||||
| heroic_008 | Thunder Vanguard | 9 | 158 | D# minor | brave, quest, sword | Thunderous minor key charge of the vanguard into the heart of battle |
|
||||
| heroic_009 | Skyward Bound | 7 | 135 | F# major | adventure, glory, dawn | An uplifting ascent into the clouds with boundless major key optimism |
|
||||
| heroic_010 | Iron Resolve | 8 | 148 | C# dorian | champion, shield, valor | Unbreakable dorian determination with a hammering rhythmic backbone |
|
||||
| heroic_011 | Wingspan | 6 | 122 | G# lydian | adventure, hero, dawn | Soaring lydian theme evoking the spread of mighty wings at first light |
|
||||
| heroic_012 | Legend's Forge | 8 | 150 | A# minor | legend, sword, crusade | White-hot minor key intensity of a legendary weapon being forged |
|
||||
| heroic_013 | Rally Cry | 9 | 160 | D mixolydian | triumph, anthem, glory | A deafening mixolydian rally cry uniting an army before the final charge |
|
||||
| heroic_014 | Valor Rising | 7 | 130 | F major | valor, brave, quest | A steadily rising major key theme embodying growing courage |
|
||||
| heroic_015 | Fortress Eternal | 7 | 136 | B dorian | shield, paladin, oath | Impenetrable dorian fortress theme with layered harmonic defenses |
|
||||
| heroic_016 | Phoenix's Flight | 8 | 146 | E lydian | hero, legend, dawn | Blazing lydian ascent of a reborn phoenix soaring above the flames |
|
||||
| heroic_017 | Banner Unfurled | 7 | 134 | G major | glory, courage, champion | Majestic unfurling of a victorious banner in crisp major key splendor |
|
||||
| heroic_018 | Dragonslayer | 9 | 156 | C# minor | sword, brave, quest | Ferocious minor key battle theme of a legendary dragonslayer |
|
||||
| heroic_019 | Crowning Moment | 6 | 120 | A# major | triumph, anthem, glory | A stately coronation theme building to an emotional crowning climax |
|
||||
| heroic_020 | Eternal Vow | 6 | 126 | F# mixolydian | oath, paladin, beacon | A profound mixolydian pledge of eternal service and unwavering loyalty |
|
||||
|
||||
---
|
||||
|
||||
### Quirky (20 songs)
|
||||
|
||||
Energy range: 5-8
|
||||
Best for: Comedy, unique games, surprises
|
||||
|
||||
| ID | Name | Energy | Tempo | Key | Tags | Description |
|
||||
|----|------|--------|-------|-----|------|-------------|
|
||||
| quirky_001 | Wobble Walk | 6 | 118 | C mixolydian | wobble, funny, offbeat | A tipsy mixolydian stroll with syncopated bass and bouncy staccato hits |
|
||||
| quirky_002 | Glitch Parade | 7 | 128 | F blues | glitch, weird, surprise | A malfunctioning parade of blues riffs and unexpected rhythmic hiccups |
|
||||
| quirky_003 | Mischief Maker | 6 | 112 | D dorian | mischief, prank, eccentric | Sneaky dorian theme of a trickster plotting delightful chaos |
|
||||
| quirky_004 | Rubber Duck Boogie | 7 | 132 | A pentatonic minor | funny, bounce, comedy | Absurd pentatonic boogie with squeaky lead lines and rubber bass |
|
||||
| quirky_005 | Clockwork Confusion | 5 | 108 | G whole tone | odd, twist, eccentric | Malfunctioning clockwork mechanism ticking in whole-tone disorientation |
|
||||
| quirky_006 | Prankster Polka | 7 | 135 | E mixolydian | prank, wacky, clown | A manic polka-inspired romp driven by wacky syncopation and flat-seven swagger |
|
||||
| quirky_007 | Jellybean Jamboree | 8 | 140 | B lydian | bounce, zany, comedy | Sugary lydian explosion of color and bouncing melodic candy |
|
||||
| quirky_008 | Sneaky Squirrel | 5 | 105 | D# dorian | mischief, trick, offbeat | Furtive dorian scurrying with darting staccato leads and syncopated bass |
|
||||
| quirky_009 | Topsy Turvy | 6 | 120 | F# blues | chaos, twist, wacky | Everything flipped upside down in a chaotic blues-scale adventure |
|
||||
| quirky_010 | Noodle Soup | 5 | 102 | C# pentatonic minor | weird, odd, eccentric | A winding noodly pentatonic melody sloshing around in rhythmic broth |
|
||||
| quirky_011 | Pixel Pandemonium | 8 | 138 | G# mixolydian | glitch, chaos, surprise | Hyper 8-bit style mixolydian mayhem with frantic arpeggio bursts |
|
||||
| quirky_012 | Banana Peel Slide | 6 | 116 | A# blues | funny, clown, comedy | Slippery blues-scale comedy with pratfall rhythms and slide-whistle leads |
|
||||
| quirky_013 | Funhouse Mirror | 5 | 110 | E whole tone | twist, odd, eccentric | Distorted whole-tone reflections warping reality in a carnival funhouse |
|
||||
| quirky_014 | Hiccup Hop | 7 | 126 | D dorian | bounce, wacky, zany | Jerky dorian hop interrupted by melodic hiccups and rhythmic stumbles |
|
||||
| quirky_015 | Zigzag Zephyr | 6 | 122 | B lydian | surprise, offbeat, mischief | Unpredictable lydian wind gusts pushing melodies in zigzag directions |
|
||||
| quirky_016 | Rubber Band Riff | 6 | 114 | F pentatonic minor | wobble, trick, comedy | Stretchy pentatonic riffs snapping back and forth with elastic energy |
|
||||
| quirky_017 | Carousel Malfunction | 7 | 130 | G mixolydian | chaos, glitch, wacky | A malfunctioning fairground ride spinning at odd intervals in mixolydian frenzy |
|
||||
| quirky_018 | Jester Jig | 7 | 136 | A dorian | clown, prank, zany | A flamboyant dorian jig performed by a mischievous court jester |
|
||||
| quirky_019 | Slapstick Serenade | 5 | 100 | C# blues | funny, comedy, twist | A tender serenade gone hilariously wrong with slapstick timing and blue notes |
|
||||
| quirky_020 | Kaleidoscope Caper | 6 | 124 | D# lydian | surprise, eccentric, wobble | Shifting lydian patterns like a kaleidoscope of musical fragments |
|
||||
|
||||
---
|
||||
|
||||
### Ambient (20 songs)
|
||||
|
||||
Energy range: 1-3
|
||||
Best for: Background, meditation, creative tools
|
||||
|
||||
| ID | Name | Energy | Tempo | Key | Tags | Description |
|
||||
|----|------|--------|-------|-----|------|-------------|
|
||||
| ambient_001 | Nebula Drift | 2 | 68 | C major | space, cosmic, floating | Weightless major key pads drifting through a colorful cosmic nebula |
|
||||
| ambient_002 | Crystal Meadow | 2 | 72 | G pentatonic major | crystal, meadow, tranquil | Sparkling pentatonic chimes scattered across a sunlit meadow |
|
||||
| ambient_003 | Glacial Horizon | 1 | 62 | D lydian | glacier, vast, ethereal | Immense glacial soundscape stretching to an infinite lydian horizon |
|
||||
| ambient_004 | Aurora Veil | 2 | 75 | A pentatonic major | aurora, ethereal, dream | Shimmering aurora borealis painted in pentatonic washes of light |
|
||||
| ambient_005 | Tidal Murmur | 2 | 66 | F minor | tide, mist, tranquil | Gentle minor key tides lapping rhythmically in a misty coastal haze |
|
||||
| ambient_006 | Stardust Canopy | 1 | 60 | B major | stardust, cosmic, vast | An endless canopy of stars rendered in slow-moving major key pads |
|
||||
| ambient_007 | Silk River | 2 | 70 | E pentatonic minor | floating, dream, tranquil | Smooth pentatonic minor currents flowing like liquid silk through space |
|
||||
| ambient_008 | Morning Dew | 2 | 76 | D# lydian | meadow, crystal, atmosphere | Dewdrops catching first light in shimmering lydian bell tones |
|
||||
| ambient_009 | Deep Cavern Echo | 1 | 64 | F# minor | void, vast, atmosphere | Cavernous minor key echoes bouncing endlessly through underground spaces |
|
||||
| ambient_010 | Velvet Cosmos | 2 | 74 | C# whole tone | cosmic, nebula, floating | Luxurious whole-tone textures unfolding across a velvet cosmic canvas |
|
||||
| ambient_011 | Feather Fall | 1 | 63 | G# pentatonic major | ethereal, dream, floating | Weightless pentatonic notes falling like feathers through still air |
|
||||
| ambient_012 | Horizon Glow | 3 | 82 | A# major | horizon, aurora, tranquil | Warm major key glow spreading across a peaceful distant horizon |
|
||||
| ambient_013 | Moss Garden | 2 | 69 | D pentatonic minor | meadow, mist, tranquil | A damp moss garden where pentatonic tones grow like delicate plants |
|
||||
| ambient_014 | Solar Wind | 2 | 78 | F lydian | space, cosmic, vast | Streams of lydian particles carried by an invisible solar wind |
|
||||
| ambient_015 | Moonpool Reflection | 1 | 61 | B minor | dream, mist, ethereal | Perfectly still moonlit pool reflecting minor key pads in mirrored silence |
|
||||
| ambient_016 | Ember Glow | 3 | 85 | E pentatonic major | atmosphere, tranquil, meadow | Warm dying embers casting a pentatonic glow across a quiet room |
|
||||
| ambient_017 | Cloud Temple | 2 | 71 | A lydian | floating, ethereal, vast | An ancient temple floating among the clouds in shimmering lydian suspension |
|
||||
| ambient_018 | Frozen Bloom | 1 | 65 | G whole tone | glacier, crystal, void | Ice crystals blooming in slow motion with directionless whole-tone shimmer |
|
||||
| ambient_019 | Whispering Sands | 2 | 73 | C# pentatonic minor | tide, mist, atmosphere | Desert sands whispering pentatonic secrets carried on a warm breeze |
|
||||
| ambient_020 | Infinite Stillness | 1 | 60 | F# major | void, stardust, vast | Absolute stillness at the edge of the universe where sound barely exists |
|
||||
|
||||
---
|
||||
|
||||
## Compatibility Matrix
|
||||
|
||||
### Mood to Background Theme
|
||||
|
||||
| Mood | Excellent Themes | Good Themes | Avoid |
|
||||
|------|-----------------|-------------|-------|
|
||||
| Epic | space, fantasy, dungeon, volcanic | urban, stadium, castle | pastel, garden, beach |
|
||||
| Chill | garden, beach, sunset, meadow | forest, sky, underwater | dungeon, volcanic, industrial |
|
||||
| Intense | urban, industrial, volcanic, stadium | space, dungeon, desert | garden, beach, meadow |
|
||||
| Playful | candy, circus, playground, cartoon | beach, forest, sky | dungeon, volcanic, horror |
|
||||
| Mysterious | dungeon, forest-night, underwater-deep, ancient-ruins | castle, space-dark, swamp | candy, playground, beach |
|
||||
| Heroic | castle, stadium, mountain-peak, sky | fantasy, forest, space | dungeon, horror, swamp |
|
||||
| Quirky | circus, cartoon, laboratory, toy-room | urban, candy, beach | dungeon, horror, volcanic |
|
||||
| Ambient | space, underwater, forest, sky | desert, beach, meadow | urban, stadium, industrial |
|
||||
|
||||
### Mood to Avatar Context
|
||||
|
||||
| Mood | Recommended Contexts |
|
||||
|------|---------------------|
|
||||
| Epic | knight-armor, spaceship-cockpit, dragon-rider, warrior-arena, commander-bridge |
|
||||
| Chill | beach-chair, hammock, cafe-window, meditation-cushion, garden-bench |
|
||||
| Intense | race-car, fighter-jet, motorcycle, battle-station, control-room |
|
||||
| Playful | playground, trampoline, carnival-booth, ball-pit, treehouse |
|
||||
| Mysterious | detective-office, ancient-library, foggy-alley, crystal-cave, haunted-mansion |
|
||||
| Heroic | throne-room, mountain-summit, victory-podium, ship-helm, castle-balcony |
|
||||
| Quirky | mad-scientist-lab, upside-down-room, funhouse, time-machine, cartoon-world |
|
||||
| Ambient | starship-window, underwater-dome, cloud-platform, zen-garden, space-station |
|
||||
|
||||
---
|
||||
|
||||
## API Usage
|
||||
|
||||
```javascript
|
||||
// Initialize (called automatically on first play)
|
||||
await MusicEngine.init();
|
||||
|
||||
// Play random song from mood
|
||||
const song = await MusicEngine.playRandomSong('Epic');
|
||||
console.log(song.name); // e.g., "Siege of Thunder"
|
||||
|
||||
// Play specific song by ID
|
||||
const song = await MusicEngine.playSong('epic_001');
|
||||
|
||||
// Find songs by criteria
|
||||
const songs = MusicEngine.findSongs({
|
||||
mood: 'Epic',
|
||||
minEnergy: 8,
|
||||
maxEnergy: 10,
|
||||
minTempo: 150,
|
||||
maxTempo: 180,
|
||||
tags: ['battle']
|
||||
});
|
||||
|
||||
// Get full catalog with metadata
|
||||
const allSongs = MusicEngine.getCatalog();
|
||||
// Returns: [{ id, name, mood, energy, tempo, key, scale, tags, desc }, ...]
|
||||
|
||||
// Volume control (0.0 to 1.0)
|
||||
MusicEngine.setVolume(0.7);
|
||||
|
||||
// Fade out current song (duration in seconds)
|
||||
MusicEngine.fadeOut(2);
|
||||
|
||||
// Stop music immediately
|
||||
MusicEngine.stopMusic();
|
||||
|
||||
// Check current state
|
||||
const isPlaying = MusicEngine.isPlaying();
|
||||
const currentSong = MusicEngine.getCurrentSong();
|
||||
|
||||
// Get all available moods
|
||||
const moods = MusicLibrary.getMoods();
|
||||
// Returns: ['Epic', 'Chill', 'Intense', 'Playful', 'Mysterious', 'Heroic', 'Quirky', 'Ambient']
|
||||
|
||||
// Get songs for a specific mood
|
||||
const epicSongs = MusicLibrary.getSongsByMood('Epic');
|
||||
|
||||
// Get a specific song definition
|
||||
const song = MusicLibrary.getSong('epic_001');
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Technical Details
|
||||
|
||||
### Synthesis
|
||||
|
||||
- **Engine**: Tone.js (loaded from CDN)
|
||||
- **Duration**: 60+ seconds per song (loops seamlessly)
|
||||
- **Sample Rate**: 44.1 kHz (browser default)
|
||||
|
||||
### Synth Types Used
|
||||
|
||||
| Type | Tone.js Class | Typical Use |
|
||||
|------|---------------|-------------|
|
||||
| FM | FMSynth | Bright leads, stabs, bells |
|
||||
| AM | AMSynth | Warm pads, subtle leads |
|
||||
| Mono | MonoSynth | Bass, monophonic leads |
|
||||
| Poly | PolySynth | Pads, chords |
|
||||
| Membrane | MembraneSynth | Drums, percussive bass |
|
||||
| Metal | MetalSynth | Metallic percussion |
|
||||
| Pluck | PluckSynth | Plucked strings, mallets |
|
||||
| Duo | DuoSynth | Rich leads, doubled tones |
|
||||
| Noise | NoiseSynth | Effects, ambience |
|
||||
|
||||
### Effects Chain
|
||||
|
||||
| Effect | Parameter | Range | Purpose |
|
||||
|--------|-----------|-------|---------|
|
||||
| Reverb | reverb | 0.1-0.8 | Room size/tail |
|
||||
| Delay | delay | 0.05-0.5 | Echo amount |
|
||||
| Filter | filter | 500-8000 | Low-pass cutoff (Hz) |
|
||||
|
||||
### Song Structure
|
||||
|
||||
Each song defines:
|
||||
- **Sections**: intro, verse, chorus, bridge, break, outro
|
||||
- **Per Section**: bars, chord progression, melody style, bass style, drum pattern, intensity
|
||||
|
||||
### Scales Available
|
||||
|
||||
| Scale | Intervals | Typical Mood |
|
||||
|-------|-----------|--------------|
|
||||
| major | 0,2,4,5,7,9,11 | Happy, triumphant |
|
||||
| minor | 0,2,3,5,7,8,10 | Sad, dramatic |
|
||||
| dorian | 0,2,3,5,7,9,10 | Jazzy, mysterious |
|
||||
| phrygian | 0,1,3,5,7,8,10 | Dark, exotic |
|
||||
| lydian | 0,2,4,6,7,9,11 | Dreamy, bright |
|
||||
| mixolydian | 0,2,4,5,7,9,10 | Bluesy, groovy |
|
||||
| harmonicMinor | 0,2,3,5,7,8,11 | Dramatic, Eastern |
|
||||
| melodicMinor | 0,2,3,5,7,9,11 | Jazz, sophisticated |
|
||||
| pentatonicMajor | 0,2,4,7,9 | Simple, folk |
|
||||
| pentatonicMinor | 0,3,5,7,10 | Blues, rock |
|
||||
| blues | 0,3,5,6,7,10 | Blues, funky |
|
||||
| wholeTone | 0,2,4,6,8,10 | Dreamy, unsettling |
|
||||
| chromatic | all 12 | Atonal, chaotic |
|
||||
|
||||
---
|
||||
|
||||
## Statistics Summary
|
||||
|
||||
| Mood | Songs | Energy Range | Tempo Range | Top Tags |
|
||||
|------|-------|--------------|-------------|----------|
|
||||
| Epic | 20 | 7-10 | 120-170 | battle, heroic, powerful |
|
||||
| Chill | 20 | 1-4 | 70-110 | peaceful, calm, soft |
|
||||
| Intense | 20 | 8-10 | 142-180 | aggressive, fast, urgent |
|
||||
| Playful | 20 | 4-7 | 110-150 | fun, bouncy, happy |
|
||||
| Mysterious | 20 | 2-5 | 80-120 | dark, enigma, eerie |
|
||||
| Heroic | 20 | 6-9 | 120-160 | triumph, courage, glory |
|
||||
| Quirky | 20 | 5-8 | 100-140 | funny, wacky, eccentric |
|
||||
| Ambient | 20 | 1-3 | 60-85 | floating, tranquil, vast |
|
||||
|
||||
**Total: 160 songs**
|
||||
@@ -0,0 +1,546 @@
|
||||
# Preset Guide
|
||||
|
||||
## Overview
|
||||
|
||||
220 curated asset combinations providing instant variety for 11 game styles.
|
||||
Each preset includes coordinated music, background, and avatar context.
|
||||
|
||||
**Total Presets:** 220
|
||||
**Presets per Style:** 20
|
||||
**Game Styles:** 11
|
||||
|
||||
---
|
||||
|
||||
## Game Styles
|
||||
|
||||
### Action/Arcade (20 presets)
|
||||
|
||||
Fast-paced action games with intense gameplay and dynamic visuals.
|
||||
|
||||
| ID | Name | Music | Background | Context | Best For |
|
||||
|----|------|-------|------------|---------|----------|
|
||||
| action-space-01 | Space Hero | Epic, 9 | space/nebula | spaceship-cockpit | Space shooters |
|
||||
| action-space-02 | Asteroid Runner | Intense, 8 | space/asteroidField | spaceship-cockpit | Dodging games |
|
||||
| action-platform-01 | Retro Runner | Playful, 7 | retro/pixelGrid | platformer-standard | Platformers |
|
||||
| action-platform-02 | Jungle Dash | Heroic, 8 | nature/jungle | adventure-hero | Jungle runners |
|
||||
| action-tank-01 | Tank Commander | Heroic, 9 | urban/citySkyline | tank | Military games |
|
||||
| action-tank-02 | Desert Storm | Epic, 8 | nature/desert | tank | Desert warfare |
|
||||
| action-mech-01 | Mech Warrior | Epic, 10 | mechanical/robotFactory | mech-suit | Robot battles |
|
||||
| action-mech-02 | Titan Fall | Intense, 9 | space/planets | mech-suit | Sci-fi combat |
|
||||
| action-jetpack-01 | Jetpack Joyride | Playful, 7 | sky/clouds | jetpack | Flying games |
|
||||
| action-jetpack-02 | Volcano Escape | Intense, 9 | nature/mountains | jetpack | Escape games |
|
||||
| action-ninja-01 | Shadow Strike | Mysterious, 7 | fantasy/temple | ninja-outfit | Stealth action |
|
||||
| action-ninja-02 | Rooftop Runner | Intense, 8 | urban/rooftop | ninja-outfit | Parkour games |
|
||||
| action-shooter-01 | Alien Blaster | Epic, 9 | space/deepSpace | spaceship-cockpit | Shoot-em-ups |
|
||||
| action-shooter-02 | Robot Rampage | Intense, 8 | mechanical/factory | superhero-cape | Wave shooters |
|
||||
| action-flying-01 | Sky Ace | Heroic, 8 | sky/flyingHigh | airplane | Dogfight games |
|
||||
| action-flying-02 | Storm Chaser | Intense, 9 | weather/storm | airplane | Weather dodging |
|
||||
| action-underwater-01 | Deep Sea Diver | Mysterious, 6 | underwater/deepSea | submarine | Ocean exploration |
|
||||
| action-underwater-02 | Submarine Command | Heroic, 7 | underwater/submarine | submarine | Naval combat |
|
||||
| action-superhero-01 | Cape Crusader | Heroic, 9 | urban/citySkyline | superhero-cape | Superhero games |
|
||||
| action-arcade-classic | Arcade Classic | Playful, 8 | retro/arcadeCabinet | platformer-standard | Retro arcade |
|
||||
|
||||
---
|
||||
|
||||
### Puzzle (20 presets)
|
||||
|
||||
Brain-teasing puzzle games with calm, focused atmospheres.
|
||||
|
||||
| ID | Name | Music | Background | Context | Best For |
|
||||
|----|------|-------|------------|---------|----------|
|
||||
| puzzle-zen-01 | Zen Garden | Chill, 2 | nature/meadow | platformer-standard | Matching games |
|
||||
| puzzle-zen-02 | Bamboo Sanctuary | Ambient, 2 | nature/forest | platformer-standard | Tile puzzles |
|
||||
| puzzle-abstract-01 | Geometric Dreams | Ambient, 3 | abstract/geometricPatterns | platformer-standard | Pattern games |
|
||||
| puzzle-abstract-02 | Color Flow | Chill, 3 | abstract/gradients | platformer-standard | Color matching |
|
||||
| puzzle-lab-01 | Science Lab | Quirky, 4 | indoor/laboratory | scientist-labcoat | Chemistry puzzles |
|
||||
| puzzle-lab-02 | Brain Teasers | Quirky, 4 | indoor/library | scientist-labcoat | Logic puzzles |
|
||||
| puzzle-colorful-01 | Candy Crush | Playful, 5 | colorful/candyWorld | platformer-standard | Match-3 games |
|
||||
| puzzle-colorful-02 | Rainbow Bridge | Playful, 4 | colorful/rainbow | platformer-standard | Color puzzles |
|
||||
| puzzle-space-01 | Cosmic Puzzle | Ambient, 3 | space/nebula | space-suit | Space puzzles |
|
||||
| puzzle-space-02 | Starlight Logic | Mysterious, 3 | space/deepSpace | space-suit | Constellation puzzles |
|
||||
| puzzle-library-01 | Ancient Library | Mysterious, 4 | fantasy/magicalLibrary | wizard-robes | Word puzzles |
|
||||
| puzzle-library-02 | Scholar's Study | Chill, 3 | indoor/library | wizard-robes | Book puzzles |
|
||||
| puzzle-ocean-01 | Ocean Depths | Ambient, 2 | underwater/coralReef | platformer-standard | Marine puzzles |
|
||||
| puzzle-ocean-02 | Bubble Pop | Playful, 4 | underwater/kelpForest | platformer-standard | Bubble games |
|
||||
| puzzle-crystal-01 | Crystal Cave | Mysterious, 4 | fantasy/crystalCave | platformer-standard | Gem puzzles |
|
||||
| puzzle-crystal-02 | Jewel Quest | Playful, 5 | fantasy/crystalCave | adventure-hero | Gem matching |
|
||||
| puzzle-cloud-01 | Cloud Kingdom | Ambient, 2 | sky/clouds | platformer-standard | Sky puzzles |
|
||||
| puzzle-cloud-02 | Dream Weaver | Chill, 2 | sky/horizon | platformer-standard | Dream puzzles |
|
||||
| puzzle-minimalist-01 | Minimal Mind | Ambient, 2 | abstract/minimalist | platformer-standard | Minimal puzzles |
|
||||
| puzzle-garden-01 | Garden Puzzle | Chill, 3 | seasonal/springMeadow | platformer-standard | Nature puzzles |
|
||||
|
||||
---
|
||||
|
||||
### Story Adventure (20 presets)
|
||||
|
||||
Narrative-driven adventures with immersive world-building.
|
||||
|
||||
| ID | Name | Music | Background | Context | Best For |
|
||||
|----|------|-------|------------|---------|----------|
|
||||
| story-fantasy-01 | Dragon Quest | Heroic, 8 | fantasy/castle | knight-armor | Fantasy RPGs |
|
||||
| story-fantasy-02 | Enchanted Forest | Mysterious, 6 | fantasy/enchantedForest | adventure-hero | Fairy tales |
|
||||
| story-wizard-01 | Wizard Academy | Quirky, 6 | fantasy/magicalLibrary | wizard-robes | Magic schools |
|
||||
| story-wizard-02 | Spell Caster | Epic, 7 | fantasy/tower | wizard-robes | Magic adventures |
|
||||
| story-pirate-01 | Pirate's Treasure | Heroic, 7 | nature/ocean | pirate-outfit | Pirate adventures |
|
||||
| story-pirate-02 | Shipwreck Island | Mysterious, 6 | underwater/shipwreck | pirate-outfit | Island mysteries |
|
||||
| story-nature-01 | Forest Journey | Chill, 5 | nature/forest | adventure-hero | Nature quests |
|
||||
| story-nature-02 | Mountain Expedition | Heroic, 6 | nature/mountains | adventure-hero | Climbing adventures |
|
||||
| story-urban-01 | City Detective | Mysterious, 5 | urban/street | platformer-standard | Mystery solving |
|
||||
| story-urban-02 | Night City | Mysterious, 6 | urban/neonDistrict | ninja-outfit | Noir adventures |
|
||||
| story-spooky-01 | Haunted Manor | Mysterious, 5 | spooky/hauntedHouse | platformer-standard | Ghost stories |
|
||||
| story-spooky-02 | Graveyard Shift | Mysterious, 6 | spooky/graveyard | ninja-outfit | Horror adventures |
|
||||
| story-medieval-01 | Knight's Honor | Heroic, 7 | fantasy/castle | knight-armor | Medieval quests |
|
||||
| story-medieval-02 | Village Hero | Playful, 6 | fantasy/castle | adventure-hero | Village adventures |
|
||||
| story-scifi-01 | Space Explorer | Ambient, 5 | space/spaceStation | space-suit | Sci-fi exploration |
|
||||
| story-scifi-02 | Alien Contact | Mysterious, 6 | space/planets | space-suit | First contact stories |
|
||||
| story-fairy-01 | Fairy Tale | Playful, 4 | fantasy/enchantedForest | wizard-robes | Classic fairy tales |
|
||||
| story-fairy-02 | Magic Kingdom | Heroic, 5 | fantasy/floatingIslands | adventure-hero | Fantasy kingdoms |
|
||||
| story-desert-01 | Desert Wanderer | Ambient, 5 | nature/desert | cowboy-gear | Desert adventures |
|
||||
| story-desert-02 | Oasis Quest | Heroic, 6 | nature/desert | adventure-hero | Desert exploration |
|
||||
|
||||
---
|
||||
|
||||
### Racing (20 presets)
|
||||
|
||||
High-speed racing games with adrenaline-pumping action.
|
||||
|
||||
| ID | Name | Music | Background | Context | Best For |
|
||||
|----|------|-------|------------|---------|----------|
|
||||
| racing-street-01 | Street Racer | Intense, 9 | urban/street | race-car | Street racing |
|
||||
| racing-street-02 | Midnight Run | Intense, 8 | urban/neonDistrict | race-car | Night racing |
|
||||
| racing-track-01 | Grand Prix | Epic, 9 | sports/raceTrack | race-car | Track racing |
|
||||
| racing-track-02 | Speed Champion | Heroic, 9 | sports/stadium | race-car | Championship races |
|
||||
| racing-motorcycle-01 | Moto Mayhem | Intense, 9 | urban/street | motorcycle | Motorcycle racing |
|
||||
| racing-motorcycle-02 | Highway Rider | Heroic, 8 | nature/mountains | motorcycle | Highway racing |
|
||||
| racing-hover-01 | Hover Rush | Epic, 9 | abstract/waves | hoverboard | Futuristic racing |
|
||||
| racing-hover-02 | Neon Glide | Intense, 8 | retro/synthwave | hoverboard | Cyberpunk racing |
|
||||
| racing-runner-01 | Endless Runner | Playful, 7 | urban/street | runner | Endless runners |
|
||||
| racing-runner-02 | Temple Sprint | Heroic, 8 | fantasy/temple | runner | Temple runs |
|
||||
| racing-offroad-01 | Offroad Rally | Intense, 8 | nature/mountains | race-car | Rally racing |
|
||||
| racing-offroad-02 | Mud Madness | Heroic, 7 | nature/forest | race-car | Offroad racing |
|
||||
| racing-boat-01 | Wave Rider | Heroic, 8 | nature/ocean | platformer-standard | Boat racing |
|
||||
| racing-boat-02 | River Rush | Intense, 7 | nature/waterfall | platformer-standard | River racing |
|
||||
| racing-sky-01 | Sky Race | Epic, 9 | sky/flyingHigh | airplane | Air racing |
|
||||
| racing-sky-02 | Cloud Dash | Playful, 7 | sky/clouds | flappy-style | Sky dodging |
|
||||
| racing-kart-01 | Kart Kingdom | Playful, 7 | colorful/rainbow | race-car | Kart racing |
|
||||
| racing-kart-02 | Turbo Toons | Playful, 8 | colorful/candyWorld | race-car | Cartoon racing |
|
||||
| racing-winter-01 | Snow Drift | Heroic, 7 | seasonal/winterWonderland | race-car | Winter racing |
|
||||
| racing-winter-02 | Ice Racer | Intense, 8 | weather/snow | race-car | Ice track racing |
|
||||
|
||||
---
|
||||
|
||||
### Pet/Simulator (20 presets)
|
||||
|
||||
Relaxing pet care and life simulation games.
|
||||
|
||||
| ID | Name | Music | Background | Context | Best For |
|
||||
|----|------|-------|------------|---------|----------|
|
||||
| pet-home-01 | Cozy Home | Chill, 3 | indoor/bedroom | platformer-standard | Virtual pets |
|
||||
| pet-home-02 | Pet Palace | Playful, 4 | indoor/bedroom | platformer-standard | Pet mansions |
|
||||
| pet-garden-01 | Garden Friends | Chill, 3 | nature/meadow | platformer-standard | Outdoor pets |
|
||||
| pet-garden-02 | Butterfly Garden | Ambient, 2 | seasonal/springMeadow | platformer-standard | Insect pets |
|
||||
| pet-farm-01 | Farm Life | Playful, 4 | nature/meadow | platformer-standard | Farm animals |
|
||||
| pet-farm-02 | Barn Buddies | Playful, 5 | nature/forest | platformer-standard | Farm simulation |
|
||||
| pet-aquarium-01 | Aqua World | Ambient, 2 | underwater/coralReef | platformer-standard | Fish tanks |
|
||||
| pet-aquarium-02 | Deep Sea Friends | Chill, 3 | underwater/kelpForest | platformer-standard | Ocean pets |
|
||||
| pet-park-01 | Pet Park | Playful, 4 | urban/park | platformer-standard | Dog walking |
|
||||
| pet-park-02 | Playground Pals | Playful, 5 | urban/park | platformer-standard | Pet playgrounds |
|
||||
| pet-cafe-01 | Pet Cafe | Chill, 3 | indoor/kitchen | chef-outfit | Cat cafes |
|
||||
| pet-cafe-02 | Treat Shop | Playful, 4 | colorful/candyWorld | chef-outfit | Pet treats |
|
||||
| pet-exotic-01 | Exotic Sanctuary | Mysterious, 4 | nature/jungle | adventure-hero | Exotic pets |
|
||||
| pet-exotic-02 | Rainforest Refuge | Ambient, 3 | nature/jungle | adventure-hero | Jungle animals |
|
||||
| pet-wildlife-01 | Wildlife Rescue | Heroic, 5 | nature/forest | adventure-hero | Animal rescue |
|
||||
| pet-wildlife-02 | Safari Friends | Playful, 4 | nature/desert | adventure-hero | Safari animals |
|
||||
| pet-virtual-01 | Cyber Pet | Quirky, 4 | retro/pixelGrid | platformer-standard | Digital pets |
|
||||
| pet-virtual-02 | Pixel Pals | Playful, 5 | retro/eightBit | platformer-standard | Retro virtual pets |
|
||||
| pet-clinic-01 | Vet Clinic | Chill, 4 | indoor/laboratory | scientist-labcoat | Vet games |
|
||||
| pet-grooming-01 | Grooming Salon | Playful, 3 | colorful/paintSplatter | platformer-standard | Pet grooming |
|
||||
|
||||
---
|
||||
|
||||
### Trivia/Quiz (20 presets)
|
||||
|
||||
Educational quiz games with engaging visual themes.
|
||||
|
||||
| ID | Name | Music | Background | Context | Best For |
|
||||
|----|------|-------|------------|---------|----------|
|
||||
| trivia-gameshow-01 | Game Show Star | Playful, 6 | colorful/disco | platformer-standard | TV quiz shows |
|
||||
| trivia-gameshow-02 | Quiz Champion | Epic, 7 | colorful/neon | platformer-standard | Championship quizzes |
|
||||
| trivia-classroom-01 | Classroom Quiz | Quirky, 4 | indoor/classroom | scientist-labcoat | School quizzes |
|
||||
| trivia-classroom-02 | Study Session | Chill, 3 | indoor/library | wizard-robes | Study games |
|
||||
| trivia-space-01 | Space Academy | Mysterious, 5 | space/nebula | space-suit | Astronomy quizzes |
|
||||
| trivia-space-02 | Cosmic Quiz | Ambient, 4 | space/deepSpace | space-suit | Space trivia |
|
||||
| trivia-history-01 | Time Traveler | Heroic, 5 | fantasy/castle | knight-armor | History quizzes |
|
||||
| trivia-history-02 | Ancient Wisdom | Mysterious, 4 | fantasy/temple | wizard-robes | Ancient history |
|
||||
| trivia-nature-01 | Nature Explorer | Chill, 4 | nature/forest | adventure-hero | Nature quizzes |
|
||||
| trivia-nature-02 | Wildlife Quiz | Playful, 4 | nature/jungle | adventure-hero | Animal trivia |
|
||||
| trivia-pop-01 | Pop Culture | Playful, 6 | colorful/neon | platformer-standard | Pop culture quizzes |
|
||||
| trivia-pop-02 | Music Mania | Playful, 7 | colorful/disco | platformer-standard | Music trivia |
|
||||
| trivia-sports-01 | Sports Fanatic | Heroic, 6 | sports/stadium | sports-player | Sports quizzes |
|
||||
| trivia-sports-02 | Champion Trivia | Epic, 7 | sports/arena | sports-player | Sports history |
|
||||
| trivia-geography-01 | World Explorer | Heroic, 5 | sky/flyingHigh | adventure-hero | Geography quizzes |
|
||||
| trivia-geography-02 | Map Master | Chill, 4 | sky/horizon | adventure-hero | Map quizzes |
|
||||
| trivia-food-01 | Foodie Quiz | Playful, 5 | indoor/kitchen | chef-outfit | Food trivia |
|
||||
| trivia-food-02 | Chef Challenge | Quirky, 6 | colorful/candyWorld | chef-outfit | Cooking quizzes |
|
||||
| trivia-math-01 | Math Genius | Quirky, 5 | abstract/geometricPatterns | scientist-labcoat | Math quizzes |
|
||||
| trivia-general-01 | Know It All | Playful, 5 | colorful/rainbow | platformer-standard | General knowledge |
|
||||
|
||||
---
|
||||
|
||||
### Music/Rhythm (20 presets)
|
||||
|
||||
Beat-matching and rhythm games with vibrant audio-visual experiences.
|
||||
|
||||
| ID | Name | Music | Background | Context | Best For |
|
||||
|----|------|-------|------------|---------|----------|
|
||||
| rhythm-disco-01 | Disco Fever | Playful, 8 | colorful/disco | platformer-standard | Disco rhythm |
|
||||
| rhythm-disco-02 | Dance Floor | Intense, 8 | colorful/neon | platformer-standard | Dancing games |
|
||||
| rhythm-retro-01 | Arcade Beats | Playful, 7 | retro/arcadeCabinet | platformer-standard | Retro rhythm |
|
||||
| rhythm-retro-02 | Pixel Grooves | Quirky, 6 | retro/pixelGrid | platformer-standard | 8-bit music |
|
||||
| rhythm-concert-01 | Rock Concert | Epic, 9 | colorful/neon | superhero-cape | Rock rhythm |
|
||||
| rhythm-concert-02 | Stage Star | Heroic, 8 | colorful/disco | platformer-standard | Concert games |
|
||||
| rhythm-space-01 | Cosmic Beats | Ambient, 6 | space/nebula | space-suit | Space rhythm |
|
||||
| rhythm-space-02 | Stellar Symphony | Mysterious, 5 | space/deepSpace | space-suit | Ambient music |
|
||||
| rhythm-street-01 | Street Beat | Intense, 8 | urban/street | ninja-outfit | Hip-hop rhythm |
|
||||
| rhythm-street-02 | Urban Flow | Heroic, 7 | urban/neonDistrict | platformer-standard | Street dancing |
|
||||
| rhythm-tropical-01 | Island Vibes | Playful, 6 | seasonal/tropical | platformer-standard | Tropical rhythm |
|
||||
| rhythm-tropical-02 | Beach Party | Playful, 7 | seasonal/summerBeach | platformer-standard | Beach music |
|
||||
| rhythm-abstract-01 | Visual Beats | Ambient, 5 | abstract/waves | platformer-standard | Abstract rhythm |
|
||||
| rhythm-abstract-02 | Synth Wave | Quirky, 6 | abstract/kaleidoscope | platformer-standard | Synth music |
|
||||
| rhythm-classical-01 | Symphony Hall | Chill, 4 | indoor/library | wizard-robes | Classical music |
|
||||
| rhythm-classical-02 | Piano Master | Ambient, 3 | indoor/arcade | platformer-standard | Piano rhythm |
|
||||
| rhythm-festival-01 | Festival Fever | Epic, 9 | colorful/tieDye | platformer-standard | Festival music |
|
||||
| rhythm-festival-02 | Rave Night | Intense, 10 | colorful/neon | ninja-outfit | Rave games |
|
||||
| rhythm-jazz-01 | Jazz Lounge | Chill, 4 | urban/alley | platformer-standard | Jazz rhythm |
|
||||
| rhythm-drums-01 | Drum Circle | Heroic, 7 | nature/jungle | adventure-hero | Drum games |
|
||||
|
||||
---
|
||||
|
||||
### Creative/Drawing (20 presets)
|
||||
|
||||
Art and creativity games encouraging self-expression.
|
||||
|
||||
| ID | Name | Music | Background | Context | Best For |
|
||||
|----|------|-------|------------|---------|----------|
|
||||
| creative-studio-01 | Art Studio | Chill, 3 | indoor/classroom | platformer-standard | Drawing games |
|
||||
| creative-studio-02 | Paint Paradise | Playful, 4 | colorful/paintSplatter | platformer-standard | Painting games |
|
||||
| creative-nature-01 | Nature Sketch | Ambient, 3 | nature/meadow | adventure-hero | Nature drawing |
|
||||
| creative-nature-02 | Forest Canvas | Chill, 2 | nature/forest | adventure-hero | Landscape art |
|
||||
| creative-colorful-01 | Color Splash | Playful, 5 | colorful/rainbow | platformer-standard | Coloring games |
|
||||
| creative-colorful-02 | Neon Art | Quirky, 6 | colorful/neon | platformer-standard | Glow art |
|
||||
| creative-abstract-01 | Abstract Express | Ambient, 4 | abstract/gradients | platformer-standard | Abstract art |
|
||||
| creative-abstract-02 | Shape Maker | Chill, 3 | abstract/geometricPatterns | platformer-standard | Geometric art |
|
||||
| creative-kids-01 | Crayon World | Playful, 5 | colorful/candyWorld | platformer-standard | Kids drawing |
|
||||
| creative-kids-02 | Doodle Town | Playful, 6 | colorful/paintSplatter | platformer-standard | Doodling games |
|
||||
| creative-fantasy-01 | Dragon Painter | Heroic, 5 | fantasy/enchantedForest | wizard-robes | Fantasy art |
|
||||
| creative-fantasy-02 | Magic Canvas | Mysterious, 4 | fantasy/magicalLibrary | wizard-robes | Magical drawing |
|
||||
| creative-space-01 | Galaxy Art | Ambient, 3 | space/nebula | space-suit | Space art |
|
||||
| creative-space-02 | Cosmic Creator | Mysterious, 4 | space/deepSpace | space-suit | Universe creation |
|
||||
| creative-beach-01 | Beach Doodles | Chill, 3 | seasonal/summerBeach | platformer-standard | Beach art |
|
||||
| creative-beach-02 | Sand Art | Ambient, 2 | nature/desert | platformer-standard | Sand drawing |
|
||||
| creative-city-01 | City Sketch | Quirky, 4 | urban/citySkyline | platformer-standard | Urban art |
|
||||
| creative-city-02 | Street Art | Playful, 5 | urban/alley | ninja-outfit | Graffiti games |
|
||||
| creative-pixel-01 | Pixel Art | Quirky, 5 | retro/pixelGrid | platformer-standard | Pixel drawing |
|
||||
| creative-food-01 | Food Art | Playful, 4 | indoor/kitchen | chef-outfit | Food decoration |
|
||||
|
||||
---
|
||||
|
||||
### RPG/Battle (20 presets)
|
||||
|
||||
Role-playing and combat games with epic adventures.
|
||||
|
||||
| ID | Name | Music | Background | Context | Best For |
|
||||
|----|------|-------|------------|---------|----------|
|
||||
| rpg-fantasy-01 | Kingdom Quest | Epic, 8 | fantasy/castle | knight-armor | Fantasy RPGs |
|
||||
| rpg-fantasy-02 | Hero's Journey | Heroic, 7 | fantasy/enchantedForest | adventure-hero | Adventure RPGs |
|
||||
| rpg-wizard-01 | Arcane Academy | Mysterious, 6 | fantasy/magicalLibrary | wizard-robes | Magic RPGs |
|
||||
| rpg-wizard-02 | Sorcerer Supreme | Epic, 8 | fantasy/tower | wizard-robes | Wizard battles |
|
||||
| rpg-ninja-01 | Ninja Chronicles | Intense, 7 | fantasy/temple | ninja-outfit | Ninja RPGs |
|
||||
| rpg-ninja-02 | Shadow Warrior | Mysterious, 8 | spooky/darkForest | ninja-outfit | Stealth RPGs |
|
||||
| rpg-dragon-01 | Dragon Rider | Epic, 9 | sky/flyingHigh | dragon-rider | Dragon games |
|
||||
| rpg-dragon-02 | Dragon Slayer | Heroic, 9 | fantasy/floatingIslands | knight-armor | Dragon battles |
|
||||
| rpg-dungeon-01 | Dungeon Crawler | Mysterious, 7 | fantasy/dungeon | knight-armor | Dungeon games |
|
||||
| rpg-dungeon-02 | Crypt Explorer | Mysterious, 6 | spooky/crypt | adventure-hero | Crypt exploration |
|
||||
| rpg-spooky-01 | Ghost Hunter | Mysterious, 6 | spooky/hauntedHouse | adventure-hero | Ghost hunting |
|
||||
| rpg-spooky-02 | Vampire Slayer | Intense, 8 | spooky/manor | knight-armor | Monster hunting |
|
||||
| rpg-nature-01 | Forest Guardian | Heroic, 6 | nature/forest | adventure-hero | Nature RPGs |
|
||||
| rpg-nature-02 | Wilderness Hero | Playful, 5 | nature/meadow | adventure-hero | Exploration RPGs |
|
||||
| rpg-arena-01 | Battle Arena | Epic, 9 | sports/arena | knight-armor | Arena battles |
|
||||
| rpg-arena-02 | Gladiator Glory | Intense, 9 | sports/stadium | superhero-cape | Gladiator games |
|
||||
| rpg-ice-01 | Frost Warrior | Heroic, 7 | seasonal/winterWonderland | knight-armor | Ice RPGs |
|
||||
| rpg-ice-02 | Blizzard Quest | Intense, 8 | weather/snow | adventure-hero | Winter quests |
|
||||
| rpg-volcano-01 | Lava Lord | Epic, 9 | nature/mountains | knight-armor | Volcano adventures |
|
||||
| rpg-boss-01 | Boss Battle | Epic, 10 | fantasy/dungeon | superhero-cape | Boss fights |
|
||||
|
||||
---
|
||||
|
||||
### Sports (20 presets)
|
||||
|
||||
Athletic competition games across various sports.
|
||||
|
||||
| ID | Name | Music | Background | Context | Best For |
|
||||
|----|------|-------|------------|---------|----------|
|
||||
| sports-soccer-01 | Soccer Star | Heroic, 8 | sports/field | sports-player | Soccer games |
|
||||
| sports-soccer-02 | World Cup | Epic, 9 | sports/stadium | sports-player | Soccer tournaments |
|
||||
| sports-basketball-01 | Court Kings | Heroic, 8 | sports/court | sports-player | Basketball games |
|
||||
| sports-basketball-02 | Slam Dunk | Epic, 9 | sports/arena | sports-player | Basketball action |
|
||||
| sports-baseball-01 | Home Run Hero | Heroic, 7 | sports/field | sports-player | Baseball games |
|
||||
| sports-baseball-02 | World Series | Epic, 8 | sports/stadium | sports-player | Baseball tournaments |
|
||||
| sports-tennis-01 | Tennis Ace | Playful, 6 | sports/court | sports-player | Tennis games |
|
||||
| sports-tennis-02 | Grand Slam | Heroic, 7 | sports/stadium | sports-player | Tennis tournaments |
|
||||
| sports-golf-01 | Golf Master | Chill, 4 | nature/meadow | sports-player | Golf games |
|
||||
| sports-golf-02 | Championship Green | Ambient, 5 | sports/field | sports-player | Golf tournaments |
|
||||
| sports-swimming-01 | Pool Champion | Heroic, 6 | sports/pool | sports-player | Swimming races |
|
||||
| sports-swimming-02 | Dive Star | Playful, 5 | underwater/coralReef | sports-player | Diving games |
|
||||
| sports-football-01 | Touchdown Hero | Epic, 8 | sports/field | sports-player | Football games |
|
||||
| sports-football-02 | Super Bowl | Epic, 9 | sports/stadium | sports-player | Football tournaments |
|
||||
| sports-hockey-01 | Ice Champion | Intense, 8 | sports/arena | sports-player | Hockey games |
|
||||
| sports-hockey-02 | Puck Master | Heroic, 7 | seasonal/winterWonderland | sports-player | Ice hockey |
|
||||
| sports-boxing-01 | Ring Champion | Intense, 9 | sports/arena | superhero-cape | Boxing games |
|
||||
| sports-boxing-02 | Knockout King | Epic, 9 | sports/gym | superhero-cape | Fighting games |
|
||||
| sports-extreme-01 | Extreme Games | Intense, 8 | nature/mountains | adventure-hero | Extreme sports |
|
||||
| sports-extreme-02 | X-Games Hero | Heroic, 9 | sports/skatepark | adventure-hero | Skateboarding |
|
||||
|
||||
---
|
||||
|
||||
### Physics/Pinball (20 presets)
|
||||
|
||||
Physics-based puzzle games and pinball simulations.
|
||||
|
||||
| ID | Name | Music | Background | Context | Best For |
|
||||
|----|------|-------|------------|---------|----------|
|
||||
| physics-pinball-01 | Classic Pinball | Playful, 7 | retro/arcadeCabinet | platformer-standard | Classic pinball |
|
||||
| physics-pinball-02 | Neon Pinball | Intense, 8 | colorful/neon | platformer-standard | Modern pinball |
|
||||
| physics-retro-01 | Retro Physics | Quirky, 6 | retro/pixelGrid | platformer-standard | Retro physics |
|
||||
| physics-retro-02 | Arcade Physics | Playful, 7 | retro/arcadeCabinet | platformer-standard | Arcade physics |
|
||||
| physics-mechanical-01 | Gear Works | Quirky, 5 | mechanical/gears | scientist-labcoat | Gear puzzles |
|
||||
| physics-mechanical-02 | Factory Fun | Quirky, 6 | mechanical/factory | scientist-labcoat | Factory games |
|
||||
| physics-colorful-01 | Bouncy World | Playful, 6 | colorful/rainbow | platformer-standard | Bouncing games |
|
||||
| physics-colorful-02 | Candy Physics | Playful, 5 | colorful/candyWorld | platformer-standard | Candy physics |
|
||||
| physics-gravity-01 | Zero Gravity | Ambient, 4 | space/deepSpace | space-suit | Gravity puzzles |
|
||||
| physics-gravity-02 | Orbital Mechanics | Mysterious, 5 | space/planets | space-suit | Space physics |
|
||||
| physics-destruction-01 | Demolition Derby | Intense, 8 | urban/citySkyline | superhero-cape | Destruction games |
|
||||
| physics-destruction-02 | Crash Test | Heroic, 7 | mechanical/factory | platformer-standard | Crash physics |
|
||||
| physics-water-01 | Water Works | Chill, 4 | underwater/coralReef | platformer-standard | Water physics |
|
||||
| physics-water-02 | Fluid Dynamics | Ambient, 3 | abstract/waves | scientist-labcoat | Fluid games |
|
||||
| physics-balance-01 | Stack Master | Quirky, 5 | abstract/minimalist | platformer-standard | Stacking games |
|
||||
| physics-balance-02 | Tower Builder | Playful, 6 | urban/citySkyline | platformer-standard | Building games |
|
||||
| physics-launch-01 | Launcher Pro | Heroic, 7 | sky/clouds | platformer-standard | Launch games |
|
||||
| physics-launch-02 | Catapult King | Epic, 8 | fantasy/castle | knight-armor | Siege games |
|
||||
| physics-pendulum-01 | Pendulum Puzzle | Chill, 4 | abstract/geometricPatterns | scientist-labcoat | Pendulum games |
|
||||
| physics-rube-01 | Rube Goldberg | Quirky, 6 | mechanical/conveyorBelts | scientist-labcoat | Chain reaction |
|
||||
|
||||
---
|
||||
|
||||
## Using Presets
|
||||
|
||||
### Get Preset by ID
|
||||
|
||||
```javascript
|
||||
const preset = AssetPresets.getById('action-space-01');
|
||||
// Returns: { id, name, music, background, avatarContext, ... }
|
||||
```
|
||||
|
||||
### Get All for Game Style
|
||||
|
||||
```javascript
|
||||
const actionPresets = AssetPresets.getByGameStyle('action-arcade');
|
||||
// Returns array of 20 presets
|
||||
```
|
||||
|
||||
### Get Random Preset
|
||||
|
||||
```javascript
|
||||
const random = AssetPresets.getRandom('racing');
|
||||
// Returns single random preset from racing category
|
||||
```
|
||||
|
||||
### Search Presets
|
||||
|
||||
```javascript
|
||||
const matches = AssetPresets.search('dragon');
|
||||
// Returns all presets with "dragon" in name, description, or tags
|
||||
```
|
||||
|
||||
### Load Preset
|
||||
|
||||
```javascript
|
||||
const preset = AssetPresets.getById('action-space-01');
|
||||
const config = {
|
||||
music: preset.music,
|
||||
background: preset.background,
|
||||
avatarContext: preset.avatarContext
|
||||
};
|
||||
await AssetManager.loadGameAssets(config);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Customizing Presets
|
||||
|
||||
### Override Music
|
||||
|
||||
Keep the visual theme but change the music mood:
|
||||
|
||||
```javascript
|
||||
const preset = AssetPresets.getById('action-space-01');
|
||||
const custom = {
|
||||
...preset,
|
||||
music: { mood: 'Mysterious', energy: 5 } // Different mood
|
||||
};
|
||||
```
|
||||
|
||||
### Keep Music, Change Background
|
||||
|
||||
Swap the background while maintaining audio coherence:
|
||||
|
||||
```javascript
|
||||
const preset = AssetPresets.getById('puzzle-zen-01');
|
||||
const custom = {
|
||||
music: preset.music,
|
||||
background: { theme: 'underwater', variant: 'coralReef' },
|
||||
avatarContext: preset.avatarContext
|
||||
};
|
||||
```
|
||||
|
||||
### Change Avatar Context Only
|
||||
|
||||
Different character presentation with same environment:
|
||||
|
||||
```javascript
|
||||
const preset = AssetPresets.getById('racing-street-01');
|
||||
const custom = {
|
||||
...preset,
|
||||
avatarContext: { mode: 'FULL_BODY', context: 'motorcycle' }
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Preset Variety Strategy
|
||||
|
||||
For maximum variety in generated games:
|
||||
|
||||
### 1. Track Recently Used Presets
|
||||
|
||||
```javascript
|
||||
const usedPresets = new Set();
|
||||
|
||||
function getUnusedPreset(gameStyle) {
|
||||
const presets = AssetPresets.getByGameStyle(gameStyle);
|
||||
const unused = presets.filter(p => !usedPresets.has(p.id));
|
||||
|
||||
if (unused.length === 0) {
|
||||
usedPresets.clear(); // Reset when all used
|
||||
return presets[0];
|
||||
}
|
||||
|
||||
const selected = unused[Math.floor(Math.random() * unused.length)];
|
||||
usedPresets.add(selected.id);
|
||||
return selected;
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Cycle Through All 20 Presets
|
||||
|
||||
```javascript
|
||||
const presetIndex = {};
|
||||
|
||||
function getNextPreset(gameStyle) {
|
||||
if (!presetIndex[gameStyle]) presetIndex[gameStyle] = 0;
|
||||
|
||||
const presets = AssetPresets.getByGameStyle(gameStyle);
|
||||
const preset = presets[presetIndex[gameStyle]];
|
||||
|
||||
presetIndex[gameStyle] = (presetIndex[gameStyle] + 1) % presets.length;
|
||||
return preset;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Use Variation Functions
|
||||
|
||||
```javascript
|
||||
// Get variation of a preset
|
||||
const variation = AssetManager.getVariation(preset, 'background');
|
||||
// Same music and context, different background variant
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation
|
||||
|
||||
All presets are pre-validated for compatibility. To check custom modifications:
|
||||
|
||||
```javascript
|
||||
const result = AssetCompatibility.validate(customConfig);
|
||||
|
||||
if (result.score < 70) {
|
||||
console.warn('Low compatibility score:', result.score);
|
||||
console.warn('Issues:', result.issues);
|
||||
}
|
||||
|
||||
// result.score: 0-100 compatibility score
|
||||
// result.issues: array of compatibility warnings
|
||||
```
|
||||
|
||||
### Compatibility Criteria
|
||||
|
||||
| Score Range | Quality |
|
||||
|-------------|---------|
|
||||
| 90-100 | Excellent - perfect harmony |
|
||||
| 70-89 | Good - works well |
|
||||
| 50-69 | Fair - noticeable mismatch |
|
||||
| 0-49 | Poor - significant issues |
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Music Moods
|
||||
|
||||
| Mood | Energy Range | Best For |
|
||||
|------|--------------|----------|
|
||||
| Epic | 7-10 | Boss fights, climactic moments |
|
||||
| Heroic | 6-9 | Adventures, triumphs |
|
||||
| Intense | 8-10 | Chases, action sequences |
|
||||
| Playful | 4-7 | Fun, lighthearted games |
|
||||
| Mysterious | 2-5 | Puzzles, suspense |
|
||||
| Ambient | 1-3 | Calm, atmospheric |
|
||||
| Chill | 1-4 | Relaxation, menus |
|
||||
| Quirky | 4-8 | Comedy, eccentric |
|
||||
|
||||
### Background Themes
|
||||
|
||||
15 themes with 8 variants each (120 total):
|
||||
|
||||
- **space**: nebula, asteroidField, deepSpace, planets, spaceStation, warpSpeed, satellites, blackHole
|
||||
- **nature**: forest, jungle, desert, mountains, ocean, underwater, waterfall, meadow
|
||||
- **urban**: citySkyline, street, rooftop, neonDistrict, subway, park, mall, alley
|
||||
- **fantasy**: castle, dungeon, enchantedForest, floatingIslands, magicalLibrary, crystalCave, temple, tower
|
||||
- **abstract**: geometricPatterns, gradients, particleFields, minimalist, waves, fractals, kaleidoscope, matrix
|
||||
- **retro**: pixelGrid, arcadeCabinet, crtEffects, vaporwave, scanlines, glitch, eightBit, synthwave
|
||||
- **indoor**: laboratory, classroom, bedroom, kitchen, arcade, office, library, gym
|
||||
- **weather**: rain, snow, storm, sunset, sunrise, fog, lightning, aurora
|
||||
- **sports**: stadium, raceTrack, court, field, arena, pool, gym, skatepark
|
||||
- **seasonal**: springMeadow, autumnLeaves, winterWonderland, summerBeach, harvest, blossom, snowfall, tropical
|
||||
- **underwater**: coralReef, deepSea, kelpForest, submarine, shipwreck, abyss, iceCave, treasure
|
||||
- **sky**: clouds, flyingHigh, hotAirBalloon, airplaneView, stratosphere, birdsEye, horizon, starfield
|
||||
- **mechanical**: gears, circuits, factory, robotFactory, conveyorBelts, pipes, steampunk, techLab
|
||||
- **spooky**: hauntedHouse, graveyard, darkForest, abandonedBuilding, crypt, manor, fog, shadows
|
||||
- **colorful**: rainbow, paintSplatter, candyWorld, disco, neon, tieDye, gradient, prism
|
||||
|
||||
### Avatar Contexts
|
||||
|
||||
| Category | Contexts |
|
||||
|----------|----------|
|
||||
| **Vehicles** | spaceship-cockpit, race-car, airplane, flappy-style, tank, pacman-style, hoverboard, jetpack, mech-suit, submarine, dragon-rider, motorcycle |
|
||||
| **Costumes** | knight-armor, space-suit, ninja-outfit, wizard-robes, pirate-outfit, superhero-cape, adventure-hero, scientist-labcoat, chef-outfit, sports-player, cowboy-gear |
|
||||
| **Pure** | platformer-standard, runner |
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Asset Library Overview](./ASSET_LIBRARY_OVERVIEW.md) - Complete asset system documentation
|
||||
- [Adding New Assets](./ADDING_NEW_ASSETS.md) - How to create new assets
|
||||
- [Game Generation Guide](./GAME_GENERATION_GUIDE.md) - How assets are used in generation
|
||||
Reference in New Issue
Block a user