gamercomp/frontend/public/assets/backgrounds/backgroundCatalog.js

// backgroundCatalog.js — Metadata catalog for all 120 procedural backgrounds
// Loaded after all theme files; provides queryable catalog of backgrounds
// 15 themes × 8 variants = 120 unique backgrounds

(function(engine) {
  if (!engine) return;

  // ─── Catalog Metadata ──────────────────────────────────────
  //
  // The catalog is auto-generated from theme registrations.
  // Each background has:
  //   id                   - Unique identifier (theme_variant)
  //   theme                - Parent theme name
  //   variant              - Variant name within theme
  //   mood                 - Emotional tone (wonder, tense, serene, energetic, etc.)
  //   colors               - Default color palette [4 hex colors]
  //   tags                 - Descriptive tags for filtering
  //   description          - Human-readable description
  //   compatibleMusicMoods - Array of music moods that pair well
  //   recommendedFor       - Array of game genres this works for

  // ─── Theme → Variant Listing ───────────────────────────────

  var THEME_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'],
  };

  // ─── Mood Categories ───────────────────────────────────────

  var MOOD_DESCRIPTIONS = {
    wonder:    'Awe-inspiring and magical',
    tense:     'Suspenseful and gripping',
    serene:    'Calm and peaceful',
    energetic: 'Fast-paced and exciting',
    focused:   'Clear and concentrated',
    playful:   'Fun and lighthearted',
    mysterious:'Dark and intriguing',
    nostalgic: 'Retro and reminiscent',
    cozy:      'Warm and comfortable',
    spooky:    'Eerie and unsettling',
    epic:      'Grand and dramatic',
    dreamy:    'Soft and ethereal',
    vibrant:   'Bright and colorful',
    industrial:'Mechanical and gritty',
    tropical:  'Warm and exotic',
    festive:   'Celebratory and joyful',
  };

  // ─── Game Genre Mappings ───────────────────────────────────

  var GENRE_TAGS = {
    action:  ['fast', 'intense', 'danger', 'combat'],
    puzzle:  ['calm', 'focused', 'minimal', 'clean'],
    racing:  ['fast', 'streaks', 'motion', 'speed'],
    rpg:     ['epic', 'magical', 'adventure', 'story'],
    sports:  ['stadium', 'field', 'arena', 'competitive'],
    creative:['colorful', 'playful', 'artistic', 'open'],
    story:   ['atmospheric', 'immersive', 'cinematic'],
    physics: ['tech', 'mechanical', 'industrial', 'scientific'],
    trivia:  ['clean', 'simple', 'focused', 'bright'],
    music:   ['rhythmic', 'neon', 'disco', 'vibrant'],
  };

  // ─── Public API Extensions ─────────────────────────────────

  /**
   * Get all themes with their variant counts
   */
  engine.getThemeSummary = function() {
    var summary = [];
    for (var theme in THEME_VARIANTS) {
      summary.push({
        theme: theme,
        variants: THEME_VARIANTS[theme],
        count: THEME_VARIANTS[theme].length
      });
    }
    return summary;
  };

  /**
   * Get total background count
   */
  engine.getTotalCount = function() {
    var count = 0;
    for (var theme in THEME_VARIANTS) {
      count += THEME_VARIANTS[theme].length;
    }
    return count;
  };

  /**
   * Get all available moods
   */
  engine.getMoods = function() {
    return Object.keys(MOOD_DESCRIPTIONS);
  };

  /**
   * Get mood description
   */
  engine.getMoodDescription = function(mood) {
    return MOOD_DESCRIPTIONS[mood] || null;
  };

  /**
   * Find backgrounds by game genre
   */
  engine.findByGenre = function(genre) {
    var tags = GENRE_TAGS[genre] || [];
    if (!tags.length) return [];
    return engine.find({ tags: tags });
  };

  /**
   * Get a random background from a specific theme
   */
  engine.getRandomFromTheme = function(theme) {
    var variants = THEME_VARIANTS[theme];
    if (!variants || !variants.length) return null;
    var variant = variants[Math.floor(Math.random() * variants.length)];
    return { theme: theme, variant: variant };
  };

  /**
   * Get a random background matching filters
   */
  engine.getRandomMatching = function(filters) {
    var matches = engine.find(filters);
    if (!matches.length) return null;
    return matches[Math.floor(Math.random() * matches.length)];
  };

  /**
   * Find backgrounds compatible with a music mood
   */
  engine.findByMusicMood = function(musicMood) {
    return engine.getCatalog().filter(function(bg) {
      return bg.compatibleMusicMoods && bg.compatibleMusicMoods.includes(musicMood);
    });
  };

  /**
   * Get backgrounds recommended for a game type
   */
  engine.getRecommendedFor = function(gameType) {
    return engine.getCatalog().filter(function(bg) {
      return bg.recommendedFor && bg.recommendedFor.includes(gameType);
    });
  };

  /**
   * Preload/validate all registered themes
   * Returns array of any themes with missing variants
   */
  engine.validateCatalog = function() {
    var issues = [];
    for (var theme in THEME_VARIANTS) {
      var variants = THEME_VARIANTS[theme];
      variants.forEach(function(variant) {
        var catalog = engine.getCatalog();
        var found = catalog.find(function(bg) {
          return bg.theme === theme && bg.variant === variant;
        });
        if (!found) {
          issues.push({ theme: theme, variant: variant, issue: 'missing registration' });
        }
      });
    }
    return issues;
  };

  // ─── Catalog Statistics ────────────────────────────────────

  engine.catalogStats = {
    themes: Object.keys(THEME_VARIANTS).length,
    variantsPerTheme: 8,
    totalBackgrounds: 120,
    version: '1.0.0',
    lastUpdated: '2026-02-05'
  };

})(window.BackgroundEngine);