Match’n Gacha Admin Guide 🔧⚙️

“With great power comes great responsibility… to make cool themes” - Admin Spider-Man, probably

Welcome to the admin side of Match’n Gacha! This guide covers everything you need to know about managing themes, collectible assets, and system configuration. Perfect for when you want to add that kawaii cat theme or introduce limited-edition collectibles.

🎨 Theme Management System

Theme File Structure

Themes are stored as JSON manifests in /public/data/themes/. Each theme defines colors, visual styles, and asset mappings.

/public/data/themes/
├── default.json          # Base theme (always required)
├── neon.json             # Optional: Cyberpunk theme  
├── kawaii.json           # Optional: Cute anime theme
└── seasonal/             # Optional: Event themes
    ├── halloween.json
    ├── christmas.json
    └── summer.json

Theme JSON Structure

{
    "name": "Theme Display Name",
    "version": "1.0.0",
    "description": "Brief theme description",
    "colors": {
        "primary": "#4a148c",
        "secondary": "#7b1fa2", 
        "accent": "#ffc107",
        "background": "#1a0033",
        "surface": "rgba(255, 255, 255, 0.1)",
        "text": "#ffffff",
        "textSecondary": "rgba(255, 255, 255, 0.7)"
    },
    "blocks": {
        "red": { "color": "#e53935", "glow": "#ff5722" },
        "blue": { "color": "#1e88e5", "glow": "#2196f3" },
        "green": { "color": "#43a047", "glow": "#4caf50" },
        "yellow": { "color": "#fdd835", "glow": "#ffeb3b" },
        "purple": { "color": "#8e24aa", "glow": "#9c27b0" },
        "orange": { "color": "#fb8c00", "glow": "#ff9800" }
    },
    "collectibles": {
        "common": { "color": "#9e9e9e", "border": "#757575" },
        "uncommon": { "color": "#4caf50", "border": "#388e3c" },
        "rare": { "color": "#2196f3", "border": "#1976d2" },
        "epic": { "color": "#9c27b0", "border": "#7b1fa2" },
        "legendary": { "color": "#ffc107", "border": "#f57f17" },
        "mythic": { "color": "#e91e63", "border": "#c2185b" }
    },
    "effects": {
        "particles": {
            "match": "#ffffff",
            "combo": "#ffc107",
            "powerup": "#e91e63"
        },
        "animations": {
            "speed": 1.0,
            "easing": "Back.easeOut"
        }
    },
    "audio": {
        "volume": 0.7,
        "variants": ["default", "8bit", "orchestral"]
    }
}

Adding New Themes

Create Theme File: Add new JSON file in /public/data/themes/
Follow Naming Convention: Use kebab-case (e.g., cyberpunk-neon.json)
Test Colors: Ensure sufficient contrast for accessibility
Update Theme Manager: No code changes needed - themes auto-load!

Theme Hot-Swapping

The ThemeManager system supports real-time theme switching:

// Load theme programmatically
await window.themeManager.loadTheme('neon');

// Get available themes
const themes = await window.themeManager.getAvailableThemes();

// Apply theme to running game
window.themeManager.applyTheme(gameScene);

🖼️ Asset Management System

Asset Directory Structure

/public/assets/
├── sprites/
│   ├── blocks/           # Block graphics
│   │   ├── red.png
│   │   ├── blue.png
│   │   └── [color].png
│   ├── collectibles/     # Collectible card art
│   │   ├── common/
│   │   ├── rare/
│   │   └── mythic/
│   ├── ui/              # Interface elements
│   │   ├── buttons/
│   │   ├── icons/
│   │   └── backgrounds/
│   └── effects/         # Particle and effect sprites
│       ├── sparkles/
│       └── explosions/
├── audio/
│   ├── sfx/             # Sound effects
│   │   ├── match.ogg
│   │   ├── combo.ogg
│   │   └── powerup.ogg
│   ├── music/           # Background music
│   │   ├── menu.ogg
│   │   └── gameplay.ogg
│   └── voice/           # Character voices (optional)
└── themes/              # Theme-specific assets
    ├── default/
    ├── neon/
    └── kawaii/

Asset Loading with Fallbacks

The AssetManager automatically handles missing assets:

Try theme-specific asset (/assets/themes/neon/blocks/red.png)
Fall back to default (/assets/sprites/blocks/red.png)
Generate placeholder (procedural graphics if nothing found)

Adding New Assets

For Block Graphics:

# Add to default set
/public/assets/sprites/blocks/[color].png     # 64x64 px, PNG format

# Add theme variant
/public/assets/themes/[theme]/blocks/[color].png

For Collectibles:

# Rarity-based organization
/public/assets/sprites/collectibles/[rarity]/[name].png   # 100x140 px

# Examples:
/public/assets/sprites/collectibles/mythic/dragon-card.png
/public/assets/sprites/collectibles/legendary/phoenix-gem.png

For UI Elements:

/public/assets/sprites/ui/buttons/[name].png              # Variable size
/public/assets/sprites/ui/icons/[name].png                # 32x32 px

Audio Asset Guidelines

Format: OGG Vorbis (web-optimized)
Sample Rate: 44.1kHz for music, 22kHz for SFX
Bit Rate: 128kbps for music, 96kbps for SFX
Duration: Keep SFX under 2 seconds, music loops 30-120 seconds

💎 Collectibles System

Collectible Data Structure

Collectibles are defined in /public/data/collectibles/ with JSON manifests:

{
    "id": "dragon_card_001",
    "name": "Ancient Dragon Card",
    "type": "card",
    "rarity": "mythic", 
    "description": "A legendary card depicting the first dragon",
    "value": 10000,
    "tradeable": true,
    "category": "fantasy",
    "series": "ancient_legends",
    "attributes": {
        "power": 95,
        "luck": 85,
        "special": "combo_bonus"
    },
    "drop_conditions": {
        "min_level": 10,
        "combo_threshold": 5,
        "chance": 0.001
    },
    "visual": {
        "sprite": "dragon_card_001.png",
        "animation": "mythic_glow",
        "particles": true
    }
}

Rarity Distribution System

Default drop rates (configurable in CollectibleSystem.js):

const rarityWeights = {
    common: 60,      // 60% drop rate
    uncommon: 25,    // 25% drop rate  
    rare: 10,        // 10% drop rate
    epic: 3,         // 3% drop rate
    legendary: 1.5,  // 1.5% drop rate
    mythic: 0.5      // 0.5% drop rate (ultra rare!)
};

Adding New Collectibles

Create Asset: Add sprite to /public/assets/sprites/collectibles/[rarity]/
Define Metadata: Create JSON file in /public/data/collectibles/
Configure Drops: Set conditions and rarity in the JSON
Test Generation: Use browser console to test drops

Limited Edition Events

For special events (holidays, anniversaries):

{
    "event": "halloween_2025",
    "duration": {
        "start": "2025-10-01T00:00:00Z",
        "end": "2025-11-01T00:00:00Z"
    },
    "collectibles": [
        "pumpkin_king_card",
        "ghost_gem", 
        "witch_artifact"
    ],
    "bonus_rates": {
        "legendary": 2.0,  // 2x legendary drop rate
        "mythic": 1.5      // 1.5x mythic drop rate
    }
}

🛠️ Development Workflow

Local Testing

# Navigate to project directory
cd /home/thrax/unified-services/match-n-gacha

# Edit theme files
vim public/data/themes/your-theme.json

# Test theme loading in browser console
window.themeManager.loadTheme('your-theme')

# Rebuild and deploy
docker compose build match-n-gacha && docker compose up -d match-n-gacha

Asset Optimization

Images:

# Optimize PNG files
optipng -o7 public/assets/sprites/**/*.png

# Convert to WebP for better compression
cwebp -q 80 input.png -o output.webp

Audio:

# Convert to OGG
ffmpeg -i input.wav -c:a libvorbis -q:a 4 output.ogg

# Normalize audio levels
ffmpeg -i input.ogg -filter:a "dynaudnorm" output_normalized.ogg

Version Control

Theme and asset files should be versioned:

{
    "name": "Neon Theme",
    "version": "1.2.0",
    "changelog": [
        "1.2.0: Added Halloween collectibles",
        "1.1.0: Improved block animations", 
        "1.0.0: Initial release"
    ]
}

🔧 Configuration Files

Game Constants (`/public/js/config/constants.js`)

const GAME_CONFIG = {
    GRID_SIZE: { cols: 8, rows: 10 },
    BLOCK_SIZE: 60,
    BLOCK_TYPES: ['red', 'blue', 'green', 'yellow', 'purple', 'orange'],
    MATCH_THRESHOLD: 3,
    MAX_THEMES: 10,
    COLLECTIBLE_DROP_BASE_CHANCE: 0.1
};

Feature Flags (`/public/js/config/features.js`)

const FEATURES = {
    MARKETPLACE_ENABLED: true,
    DAILY_CHALLENGES: true,
    SOCIAL_FEATURES: false,
    BETA_THEMES: false,
    DEBUG_MODE: false
};

📊 Analytics & Monitoring

Theme Usage Tracking

// Track theme switches
window.themeManager.on('themeChanged', (oldTheme, newTheme) => {
    analytics.track('theme_changed', {
        from: oldTheme,
        to: newTheme,
        timestamp: Date.now()
    });
});

Asset Loading Performance

// Monitor asset load times
window.assetManager.on('assetLoaded', (asset, loadTime) => {
    console.log(`${asset.name} loaded in ${loadTime}ms`);
});

🚨 Troubleshooting

Common Issues

Theme Not Loading:

Check JSON syntax with jsonlint
Verify file permissions
Clear browser cache
Check browser console for errors

Assets Missing:

Confirm file paths match manifest
Check asset dimensions match spec
Verify supported formats (PNG, WebP, OGG)

Performance Issues:

Optimize large images
Reduce audio file sizes
Limit simultaneous theme loading
Use sprite atlases for small assets

Debug Commands

Browser console commands for testing:

// Reload all themes
await window.themeManager.reloadThemes();

// Force collectible drop
window.collectibleSystem.awardCollectible('mythic');

// Clear all cached assets
window.assetManager.clearCache();

// Show performance stats
window.game.debug.showStats = true;

📝 Best Practices

Theme Design

Maintain 4.5:1 contrast ratio for accessibility
Test on multiple devices and screen sizes
Keep file sizes under 2MB total per theme
Use consistent naming conventions

Asset Management

Version control all assets
Maintain backup copies of source files
Document asset sources and licenses
Regular cleanup of unused assets

Testing Protocol

Test each new theme on mobile and desktop
Verify all collectibles display correctly
Check performance impact of new assets
User acceptance testing for major changes

🎮 Quick Reference

File Paths

Themes: /public/data/themes/[name].json
Collectibles: /public/data/collectibles/[name].json
Sprites: /public/assets/sprites/[category]/[name].png
Audio: /public/assets/audio/[category]/[name].ogg

Key Classes

ThemeManager: window.themeManager
AssetManager: window.assetManager
CollectibleSystem: window.collectibleSystem

Useful Commands

# Rebuild game
docker compose build match-n-gacha && docker compose up -d match-n-gacha

# View logs  
docker logs match-n-gacha

# Access container
docker exec -it match-n-gacha sh

🔧 Admin powers activated! Remember: with great theme comes great responsibility to make it look awesome.

📅 Last updated: August 2025 | For Match’n Gacha v1.0.0