Allen
284 lines
8.9 KiB
Markdown
284 lines
8.9 KiB
Markdown
# 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
|