Game Asset & VFX — Visual Quality Standards

When to Use

• Creating new game sprites or textures procedurally
• Reviewing existing visuals for quality (audit)
• Designing VFX systems (particles, screen effects, transitions)
• Adding "game juice" — making actions feel satisfying
• Setting up backgrounds, UI elements, or menu screens
• Integrating audio feedback with visual effects
• Building consistent UI using shared design tokens
• Any time a game looks "too simple" or "prototype-ish"

Part 1 — Sprite & Asset Quality Standards

The Quality Ladder

Every visual element in a game lands on this quality ladder. The minimum bar for shipping is Level 3.

Procedural Sprite Standards (generateTexture)

When generating sprites via Phaser's generateTexture(), every sprite should include at least 4 visual layers because flat shapes read as placeholder art, while layered shapes feel like intentional design:

Layer 1: Base shape + fill (gradient if possible)
Layer 2: Shadow / dark edge (bottom, right)
Layer 3: Highlight / specular (top-left, center)
Layer 4: Detail / accent (pattern, icon, glow, outline)

Concrete Example — A Gem Sprite

// ❌ BAD — Level 1 placeholder
const g = this.make.graphics();
g.fillStyle(0xff0000);
g.fillRect(0, 0, 32, 32);
g.generateTexture('gem', 32, 32);

// ✅ GOOD — Level 3 polished
const g = this.make.graphics();
const size = 32;

// Layer 1: Base with gradient-like fill (darker at bottom)
g.fillStyle(0xcc2244);
g.fillTriangle(size/2, 2, 4, size*0.4, size-4, size*0.4); // top facet
g.fillStyle(0xaa1133);
g.fillTriangle(4, size*0.4, size-4, size*0.4, size/2, size-2); // bottom facet

// Layer 2: Shadow (darker edge)
g.fillStyle(0x660022, 0.4);
g.fillTriangle(size*0.6, size*0.4, size-4, size*0.4, size/2, size-2);

// Layer 3: Highlight (bright specular)
g.fillStyle(0xffffff, 0.5);
g.fillTriangle(size/2, 4, size*0.35, size*0.35, size*0.55, size*0.25);

// Layer 4: Center glow
g.fillStyle(0xff88aa, 0.6);
g.fillCircle(size/2, size*0.38, 3);

g.generateTexture('gem', size, size);

Sprite Sheet Loading Standards

For games using pre-made assets (external art, AI-generated sprites), follow these standards:

// ✅ Sprite sheet loading with error fallback
preload() {
    this.load.spritesheet('spr_player_idle', 'assets/player-idle.png', {
        frameWidth: 64, frameHeight: 64,
    });
    this.load.on('loaderror', (file) => {
        console.warn(`Asset failed: ${file.key}, generating fallback`);
        this.generateFallbackTexture(file.key);
    });
}

Asset Naming Convention

Consistent naming reduces confusion and enables automation:

tx_[category]_[name]_[variant]

Categories:
  player    — player character sprites
  enemy     — enemy/obstacle sprites
  item      — collectibles, power-ups
  tile      — environment/level tiles
  ui        — buttons, icons, frames
  bg        — background elements
  fx        — VFX textures (particles, trails)

Examples:
  tx_player_idle
  tx_enemy_slime_red
  tx_item_gem_blue
  tx_tile_ground_grass
  tx_ui_btn_primary
  tx_fx_particle_circle

Color Palette Rules

Random or "pure" colors (0xff0000, 0x00ff00, 0x0000ff) look amateurish because they're oversaturated and clash with each other. Use curated palettes:

Rule of thumb: Pick 1-2 background colors (dark, desaturated), 1 primary accent, 1 secondary accent, 1 highlight color.

generateTexture Performance Guidelines

Procedural generation is preload-time cost, zero-runtime cost because the texture lives in GPU memory after generation. This makes it ideal for web games, but there are pitfalls:

• Generate textures in preload() or create(), never in update()
• Keep texture dimensions power-of-2 when possible (32, 64, 128) for GPU optimization
• Limit total generated textures to < 100 per scene to avoid VRAM pressure on mobile
• Reuse textures — don't generate the same sprite multiple times
• Destroy the temporary Graphics object after generateTexture() — it won't be collected otherwise

Part 2 — Design Token System (THEME)

All games should use the shared design token system from @shared/lib/ui-helpers.js. This ensures visual consistency across the entire game portfolio.

Design Tokens Reference

import { THEME } from '@shared/lib/ui-helpers.js';

const THEME = {
    // Colors
    primary:     0x00d4ff,   // Cyan — primary accent
    primaryDark: 0x0099cc,   // Dark cyan — hover states
    secondary:   0xff6b6b,   // Coral — secondary accent
    accent:      0xffd93d,   // Gold — highlights, achievements
    success:     0x51cf66,   // Green — positive feedback
    danger:      0xff6b6b,   // Red — warnings, damage

    // Backgrounds
    bg:          0x0a0e27,   // Deep navy — main background
    bgCard:      0x141834,   // Card/panel background
    bgOverlay:   0x000000,   // Overlay (with alpha)

    // Text
    text:        0xffffff,   // Primary text
    textMuted:   0x8899aa,   // Secondary/muted text

    // Structure
    border:      0x2a2f55,   // Borders and dividers

    // Typography
    fontFamily: '"Outfit", "Segoe UI", system-ui, sans-serif',

    // Border Radius
    radiusSm:  8,    // Small elements (tags, chips)
    radiusMd:  12,   // Medium elements (buttons, inputs)
    radiusLg:  16,   // Large elements (cards, panels)
    radiusXl:  24,   // Extra large (modals, sheets)
};

When to Use THEME Tokens

Custom Per-Game Color Overrides

When a game needs its own palette (nature theme, fire theme), create a local override that preserves the token structure:

// ✅ GOOD — Override tokens, keep structure
const GAME_THEME = {
    ...THEME,
    primary:     0x44ff88,   // Green for nature game
    primaryDark: 0x33cc66,
    bg:          0x0a1a0a,   // Dark green bg
    bgCard:      0x142814,
};

Part 3 — UI Component Library Reference

All games should use @shared/lib/ui-helpers.js for consistent, polished UI components.

Available UI Components

Button Styles

createButton supports 4 styles via opts.style:

Button Quality Standard

Every interactive button needs these properties because static buttons feel dead:

Note: UI.createButton() already implements hover/press animations, highlight shine, and hand cursor automatically. Use it instead of building buttons from scratch.

Part 4 — VFX Quality Standards

The VFX Hierarchy

Every game needs VFX at three tiers. Missing any tier makes the game feel incomplete:

Required VFX Per Game Type

Shared VFX Library Reference

All games should use @shared/lib/vfx-helpers.js which provides these production-ready effects:

Inline VFX Patterns (When Shared Lib Isn't Appropriate)

Some VFX are too game-specific for the shared library. In these cases, use inline patterns that follow the same quality standards. Always ensure:

1. Self-destruction — every particle/tween has onComplete: () => obj.destroy()
2. Depth layering — follows the standard depth map
3. Performance limits — respects particle/tween budgets

// ✅ GOOD — Inline wall-bounce VFX (game-specific, not reusable)
this.physics.world.on('worldbounds', (body) => {
    const ball = body.gameObject;
    if (!ball || !ball.active) return;

    // Expanding ring
    const ring = this.add.circle(ball.x, ball.y, 8, 0x00ccff, 0)
        .setStrokeStyle(2, 0x00ccff, 0.6).setDepth(5);
    this.tweens.add({
        targets: ring, scaleX: 2.5, scaleY: 2.5, alpha: 0,
        duration: 300, onComplete: () => ring.destroy(),
    });

    // Directional sparks
    for (let i = 0; i < 6; i++) {
        const angle = Phaser.Math.FloatBetween(0, Math.PI * 2);
        const spark = this.add.circle(ball.x, ball.y, 2, 0x00ccff, 0.7).setDepth(5);
        this.tweens.add({
            targets: spark,
            x: ball.x + Math.cos(angle) * 25,
            y: ball.y + Math.sin(angle) * 25,
            alpha: 0, scaleX: 0.2, scaleY: 0.2,
            duration: Phaser.Math.Between(180, 350),
            onComplete: () => spark.destroy(),
        });
    }
});

VFX Performance Budget

Web games run in the browser — performance matters more than native because you're sharing resources with the OS, browser tabs, and extensions:

Cleanup rule: Every visual effect MUST self-destruct. Use onComplete: () => obj.destroy() in tweens. A particle system that doesn't clean up will eventually crash the browser tab.

VFX Depth Layering

Consistent depth values prevent visual glitches where effects appear behind game objects:

Depth Map:
  -100    Background grid / gradient
  -50     Ambient particles
  -10     Dot backgrounds
  -3      Trail glow particles
  -2      Trail core particles
  -1      Ball halos, game object auras
  0-100   Game world objects (tiles, environment)
  100-500 Entities (player, enemies, NPCs)
  500-1K  Entity effects (trails, auras)
  1K-5K   Projectiles
  5K      Overlays (game over background)
  5K-7K   Glow rings, ripples
  7K-8K   Sparkles, particle bursts
  8K-9K   Floating text, score popups
  9K-9.5K Combo text, toast notifications
  9.5K    Screen flash, vignette
  10K     Scene transition wipe

Part 5 — Audio-Visual Integration

The Golden Rule

Every visual effect should have a corresponding audio event. Silent VFX feel hollow; audio without visual feels invisible. The combination creates the "juice" that makes games feel satisfying.

AudioManager Integration

All games use @shared/lib/audio-manager.js:

import { AudioManager } from '@shared/lib/audio-manager';

create() {
    this.audio = new AudioManager(this);
    this.audio.playMusic('action-loop');  // Background music
}

// On player action:
this.audio.playSFX('click');     // UI interaction
this.audio.playSFX('match');     // Destruction/success
this.audio.playSFX('drop');      // Hit/impact
this.audio.playSFX('select');    // Menu selection, pickup

Audio-VFX Sync Table

For every VFX effect, pair it with the correct SFX:

SFX Not-Too-Frequent Rule

Playing too many SFX simultaneously or in rapid succession creates audio mud. Throttle:

// ✅ GOOD — Throttled SFX for rapid events
if (this.time.now - this.lastHitSfxTime > 80) {   // 80ms cooldown
    this.audio.playSFX('drop');
    this.lastHitSfxTime = this.time.now;
}

Sound Toggle Standard

Every game MUST include a sound toggle:

• Position: Top-right corner of all scenes
• Default state: Sound ON
• Persistence: Save to localStorage
• Visual: Icon changes between 🔊/🔇 states
• Implementation: AudioManager.toggleMute()

Part 6 — Background & Scene Design

Background Quality Standards

Flat solid-color backgrounds are the #1 indicator of a prototype. Every scene needs layered backgrounds:

Premium Background Recipe (Inline)

When games need custom backgrounds beyond what the shared lib provides:

// Multi-layer premium background (from Bounce Breaker)
create() {
    const W = this.cameras.main.width, H = this.cameras.main.height;

    // Layer 1: Gradient
    const bgG = this.add.graphics().setDepth(-100);
    for (let i = 0; i < 48; i++) {
        const t = i / 47;
        const r = Phaser.Math.Linear(0x08, 0x0a, t);
        const g = Phaser.Math.Linear(0x08, 0x06, t);
        const b = Phaser.Math.Linear(0x1a, 0x2e, t);
        bgG.fillStyle((r << 16) | (g << 8) | b, 1);
        bgG.fillRect(0, Math.floor(t * H), W, Math.ceil(H / 48) + 1);
    }

    // Layer 2: Subtle grid
    const grid = this.add.graphics().setDepth(-50);
    grid.lineStyle(1, 0x00ccff, 0.02);
    for (let x = 0; x < W; x += 48) grid.lineBetween(x, 0, x, H);
    for (let y = 0; y < H; y += 48) grid.lineBetween(0, y, W, y);

    // Layer 3: Ambient particles (sparse for gameplay scenes)
    for (let i = 0; i < 12; i++) {
        const x = Phaser.Math.Between(10, W - 10);
        const y = Phaser.Math.Between(30, H - 30);
        const dot = this.add.circle(x, y,
            Phaser.Math.FloatBetween(0.5, 1.5),
            0x00ccff,
            Phaser.Math.FloatBetween(0.01, 0.05)
        ).setDepth(-40);
        this.tweens.add({
            targets: dot, y: y - 30, alpha: 0,
            duration: Phaser.Math.Between(4000, 8000),
            yoyo: true, repeat: -1,
        });
    }
}

Menu Screen Checklist

Game Over Screen Checklist

HUD (Heads-Up Display) Standards

Part 7 — Mobile & Responsive Standards

Touch Target Requirements

Viewport Handling

// Standard game dimensions for web/mobile
const config = {
    width: 480,     // Portrait mobile width
    height: 800,    // Portrait mobile height (16:10 safe)
    scale: {
        mode: Phaser.Scale.FIT,
        autoCenter: Phaser.Scale.CENTER_BOTH,
    },
};

Mobile-Specific VFX Adjustments

Detect mobile at initialization:

const isMobile = !this.sys.game.device.os.desktop;
const particleCount = isMobile ? 15 : 30;
const trailInterval = isMobile ? 50 : 35;

Part 8 — Typography & Font Standards

Font Loading

Browser default fonts (Times New Roman, Arial) immediately signal "not a real game." Always specify custom fonts:

<!-- In index.html <head>: -->
<link href="https://fonts.googleapis.com/css2?family=Outfit:wght@400;600;700&display=swap" rel="stylesheet">

// In code:
const FONT = THEME.fontFamily; // '"Outfit", "Segoe UI", system-ui, sans-serif'

Typography Hierarchy

Part 9 — Boot/Loading Screen Standards

First impressions matter — a loading screen sets the quality expectation:

// Boot scene pattern
export default class Boot extends Phaser.Scene {
    constructor() { super('Boot'); }

    preload() {
        // Show loading UI
        const bar = UI.createProgressBar(this, 240, 450, 200, 12, { showText: true });

        this.load.on('progress', (p) => bar.setProgress(p));
        this.load.on('complete', () => {
            this.time.delayedCall(1500, () => {  // Minimum display time
                this.cameras.main.fadeOut(300);
                this.time.delayedCall(300, () => this.scene.start('Menu'));
            });
        });

        // Load game assets here...
    }
}

Part 10 — Visual Feedback Specification Template

Every game must include a Visual Feedback Table in its GDD. This table maps every player action to its visual and audio response:

## Visual Feedback Table

| Player Action | Visual Effect | Sound | Screen Effect | Priority |
|---------------|--------------|-------|---------------|----------|
| [action name] | [VFX method + params] | [sfx key] | [shake/flash/none] | P0/P1/P2 |

Priority guide:

• P0 — Required: Without this, the action feels broken (hit feedback, basic destruction)
• P1 — Expected: Players notice if missing (combo indicators, score popups)
• P2 — Polish: Elevates from good to great (ambient particles, subtle pulses)

Common Mistakes

Quality Audit Checklist

Score each item 0 (missing) or 1 (present). Minimum passing score: 16/22.

Assets & Sprites (4 points)

Backgrounds & Scenes (4 points)

VFX & Feedback (5 points)

UI Components (4 points)

Audio Integration (2 points)

Technical (3 points)

Grade:

• 20-22: A — Premium quality, ship-ready
• 16-19: B — Good, minor polish needed
• 12-15: C — Needs improvement, specific items missing
• 0-11: D — Major visual rework needed

Handoff Protocol

Execution Checklist

• All sprites at Level 3+ quality (4-layer minimum)
• Curated color palette defined (using THEME tokens or custom overrides)
• Gradient backgrounds + ambient particles in every scene
• Custom font (Outfit) loaded via THEME.fontFamily
• Boot/loading screen with animated progress
• All buttons use UI.createButton() or meet hover/press standard
• Scene transitions (wipe or fade) between all scenes
• Visual Feedback Table complete for all player actions
• Shared VFX library (vfx-helpers.js) integrated where appropriate
• Shared UI library (ui-helpers.js) used for standard components
• AudioManager integrated — SFX paired with all T1 VFX
• Sound toggle present and persistent
• All particle effects self-destruct
• Depth layering follows standard depth map
• Performance within budget (particles, tweens, trails)
• Mobile detection with reduced VFX
• Menu screen meets full checklist
• Game Over screen meets full checklist
• HUD uses premium frosted glass + animated score
• Quality audit score ≥ 16/22