gamercomp/frontend/public/docs/ADDING_NEW_ASSETS.md

# 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)