# 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 ` ``` ### 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*