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

{
  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

MusicEngine.playSong('epic-21');

---

Adding New Background Theme

1. Create Theme File

Create themes/newtheme.js:

(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:

<script src="/assets/backgrounds/themes/newtheme.js"></script>

3. Update Catalog

Add to THEME_VARIANTS in backgroundCatalog.js.

4. Test

BackgroundEngine.render(ctx, 'newtheme', 'variant1', w, h, 0);

---

Adding New Avatar Accessory

1. Add to accessories.js

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

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

AvatarSystem.equipAccessory(avatar, 'headwear', 'new-item');

---

Adding New Avatar Context

1. Add to Appropriate File

For vehicles, add to contexts/vehicles.js:

{
  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

const awc = ContextRenderer.apply(avatar, 'new-vehicle');
ContextRenderer.render(awc, ctx, x, y);

---

Adding New Preset

1. Add to presets.js

{
  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

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)