# GamerComp Asset Library

A comprehensive procedural asset library for generating HTML5 canvas games. All assets are rendered in real-time using Canvas 2D API and Web Audio API.

## Quick Stats

| Asset Type | Count | Description |
|------------|-------|-------------|
| Backgrounds | 120 | 15 themes × 8 variants |
| Music | 160 | 8 moods × 20 songs |
| Avatar Modes | 4 | HEAD_ONLY, HEAD_AND_SHOULDERS, UPPER_BODY, FULL_BODY |
| Game Contexts | 26 | 12 vehicles, 10 costumes, 4 pure |
| Presets | 220 | 11 game styles × 20 presets |

## Directory Structure

```
/assets/
├── backgrounds/           # Procedural background system
│   ├── backgroundEngine.js    # Core rendering engine
│   ├── effects.js             # Particle/animation effects
│   ├── backgroundCatalog.js   # Metadata catalog
│   └── themes/                # 15 theme files
│       ├── space.js
│       ├── nature.js
│       ├── urban.js
│       └── ... (12 more)
│
├── music/                 # Procedural music system
│   ├── moodCategories.js      # Mood definitions
│   ├── musicEngine.js         # Tone.js synthesis engine
│   └── library/
│       ├── songs1-80.js       # Songs 1-80
│       └── songs81-160.js     # Songs 81-160
│
├── avatar/                # Mii-style avatar system
│   ├── avatarData.js          # Face shapes, hair, colors
│   ├── accessories.js         # 45 unlockable accessories
│   ├── animations.js          # 31 animations
│   ├── avatarRenderer.js      # Core avatar rendering
│   ├── accessoryRenderer.js   # Accessory rendering
│   ├── avatarSystem.js        # Main avatar API
│   ├── contextRenderer.js     # Context rendering
│   ├── contextCatalog.js      # Context metadata
│   └── contexts/
│       ├── vehicles.js        # 12 vehicle contexts
│       ├── costumes.js        # 10 costume contexts
│       └── pure.js            # 4 pure contexts
│
├── assetManager.js        # Unified asset coordination
├── assetCatalog.js        # Combined metadata catalog
├── presets.js             # 220 preset combinations
├── compatibility.js       # Asset compatibility rules
└── README.md              # This file
```

## Usage

### Basic Setup

Include the required scripts in your HTML:

```html
<!-- Backgrounds -->
<script src="/assets/backgrounds/backgroundEngine.js"></script>
<script src="/assets/backgrounds/effects.js"></script>
<script src="/assets/backgrounds/themes/space.js"></script>
<script src="/assets/backgrounds/backgroundCatalog.js"></script>

<!-- Music -->
<script src="/assets/music/moodCategories.js"></script>
<script src="/assets/music/musicEngine.js"></script>
<script src="/assets/music/library/songs1-80.js"></script>

<!-- Avatar -->
<script src="/assets/avatar/avatarData.js"></script>
<script src="/assets/avatar/avatarRenderer.js"></script>
<script src="/assets/avatar/avatarSystem.js"></script>

<!-- Asset Manager -->
<script src="/assets/assetManager.js"></script>
<script src="/assets/presets.js"></script>
```

### Rendering a Background

```javascript
// Get canvas context
const ctx = canvas.getContext('2d');

// Render background (animated)
function render(time) {
    BackgroundEngine.render(ctx, 'space', 'nebula', canvas.width, canvas.height, time);
    requestAnimationFrame(render);
}
render(0);
```

### Playing Music

```javascript
// Play by mood
MusicEngine.playByMood('Epic', 8);  // mood, energy (1-10)

// Play specific song
MusicEngine.play('epic_001');

// Stop music
MusicEngine.stop();

// Set volume
MusicEngine.setVolume(0.7);  // 0-1
```

### Rendering an Avatar

```javascript
// Define avatar configuration
const avatar = {
    faceShape: 'round',
    skinTone: 'medium',
    hairStyle: 'short',
    hairColor: '#3d2314',
    eyeShape: 'round',
    eyeColor: '#4a7c59'
};

// Render avatar
AvatarSystem.render(ctx, avatar, 'FULL_BODY', 'idle', animationTime);

// With context (vehicle/costume)
ContextRenderer.render(ctx, 'spaceship-cockpit', avatar, x, y, 'idle', time);
```

### Using Presets

```javascript
// Get a preset for a game style
const preset = AssetPresets.getByStyle('action')[0];

// Apply preset
const config = {
    music: preset.music,
    background: preset.background,
    avatarContext: preset.context
};
```

### Using the Recommendation Engine

```javascript
// Get recommendations based on game description
const recommendations = AssetManager.recommend(
    "A fast-paced space shooter with epic battles",
    "action"
);

// Returns: { background, music, context, preset }
```

## Game Templates

Two HTML templates are provided:

### gameTemplateAssets.html
Full-featured template with:
- Asset library integration
- Loading screen
- Pause menu
- Input handling (keyboard + touch)
- Score/health tracking

Best for: Games using avatars, procedural backgrounds, and music.

### gameTemplateSimple.html
Minimal template with:
- Basic Canvas setup
- Simple game loop
- No external dependencies

Best for: Puzzle games, simple arcade games, creative tools.

## Examples

See `/examples/` for complete working games:

- **platformer-example.html** - FULL_BODY avatar, nature background
- **flappy-example.html** - HEAD_ONLY avatar, sky background
- **racer-example.html** - Vehicle context, urban background
- **comparison-demo.html** - Same game with 4 different asset sets

## Interactive Browser

Visit `/asset-browser.html` for an interactive tool to:
- Browse all 120 backgrounds with live previews
- Preview all 160 music tracks
- Test avatar configurations
- Explore all 26 game contexts
- Browse 220 presets
- Generate random combinations

## Avatar Modes

| Mode | Dimensions | Use Case |
|------|------------|----------|
| HEAD_ONLY | 64×64 | Cockpit views, maze games |
| HEAD_AND_SHOULDERS | 64×96 | Driving, seated vehicles |
| UPPER_BODY | 64×128 | Hoverboard, jetpack games |
| FULL_BODY | 64×160 | Platformers, RPGs, sports |

## Music Moods

| Mood | Energy Range | Best For |
|------|--------------|----------|
| Epic | 7-10 | Boss battles, action |
| Chill | 2-4 | Puzzle, casual |
| Intense | 8-10 | Racing, shooters |
| Playful | 5-7 | Kids games, casual |
| Mysterious | 3-6 | Horror, exploration |
| Heroic | 6-8 | Adventure, platformers |
| Quirky | 4-7 | Puzzle, comedy |
| Ambient | 1-3 | Meditation, creative |

## Background Themes

15 themes, each with 8 variants:

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

## Game Contexts (26)

### Vehicles (12)
spaceship-cockpit, race-car, airplane, flappy-style, tank, pacman-style, hoverboard, jetpack, mech-suit, submarine, dragon-rider, motorcycle

### Costumes (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

## Documentation

See `/docs/` for detailed documentation:

- **ASSET_LIBRARY_OVERVIEW.md** - Complete system overview
- **GAME_GENERATION_GUIDE.md** - AI generation instructions
- **ADDING_NEW_ASSETS.md** - How to extend the library
- **API_REFERENCE.md** - Full API documentation

## Browser Support

- Chrome 80+
- Firefox 78+
- Safari 14+
- Edge 80+

Requires Canvas 2D and Web Audio API support.

## Performance Notes

- All assets are procedurally generated (no image loading)
- Backgrounds animate at 60fps
- Music uses Web Audio synthesis (low memory)
- Avatar rendering is optimized for multiple instances
- Use `requestAnimationFrame` for smooth animation

## License

Proprietary - GamerComp.com