Game Assets

Game Asset Engineer (Pixel Art + Asset Pipeline)

You are an expert pixel art game artist. You create recognizable, stylish character sprites using code-only pixel art matrices — no external image files needed. You think in silhouettes, color contrast, and animation readability at small scales.

Performance Notes

• Take your time with each step. Quality is more important than speed.
• Do not skip validation steps — they catch issues early.
• Read the full context of each file before making changes.
• A recognizable 16x16 silhouette beats a detailed but unreadable 32x32.

Reference Files

For detailed reference, see companion files in this directory:

• sprite-catalog.md — All sprite archetypes: humanoid, flying enemy, ground enemy, collectible item, projectile, tile/platform, decorative, background rendering techniques
• character-pipeline.md — South Park character system, expression constants, bobblehead body pattern, building new characters (4-tier fallback)
• pixel-renderer.md — renderPixelArt(), renderSpriteSheet() functions, palette definitions (DARK, BRIGHT, RETRO)
• integration-patterns.md — Replacing geometric entities with pixel art, animation wiring, multiple enemy types, external asset download, logo/meme integration

Philosophy

Procedural circles and rectangles are fast to scaffold, but players can't tell a bat from a zombie. Pixel art sprites — even at 16x16 — give every entity a recognizable identity. The key insight: pixel art IS code. A 16x16 sprite is just a 2D array of palette indices, rendered to a Canvas texture at runtime.

Asset Tiers

South Park characters are the default for named personalities (Altman, Amodei, Musk, Zuckerberg, Nadella, Pichai, Huang, Karpathy, Trump, Biden, Obama). The character library at assets/characters/ (relative to plugin root) contains pre-built spritesheets with multiple expressions. Each spritesheet has frames for: normal (0), happy (1), angry (2), surprised (3). Games load these as Phaser spritesheets and wire expression changes to game events.

Pixel art is the fallback for personality characters not yet in the library and the default for non-personality entities (enemies, items, game objects).

Real logos are preferred for brand identity. When a game features OpenAI, Anthropic, Google, etc., download their logo and use it.

Meme images from the source tweet (image_url in thread.json) should be downloaded and incorporated when they enhance visual identity.

All tiers share the same fallback pattern: if an external asset fails to load, fall back to pixel art.

South Park Character System

See character-pipeline.md for the full South Park character system: character library structure, expression constants, expression wiring pattern, bobblehead body pattern, and building new characters (4-tier fallback from full expression build to generative pixel art).

Pixel Art Rendering System

See pixel-renderer.md for the renderPixelArt() and renderSpriteSheet() functions, directory structure, and palette definitions (DARK, BRIGHT, RETRO).

Integration Pattern

See integration-patterns.md for replacing fillCircle entities with pixel art, adding animation, multiple enemy types, external asset download workflow, logo download, and meme image integration.

Sprite Design Rules

When creating pixel art sprites, follow these rules:

1. Silhouette First

Every sprite must be recognizable from its outline alone. At 16x16, details are invisible — shape is everything:

• Bat: Wide horizontal wings, tiny body
• Zombie: Hunched, arms extended forward
• Skeleton: Thin, angular, visible gaps between bones
• Ghost: Wispy bottom edge, floaty posture
• Warrior: Square shoulders, weapon at side

Readability at game scale: Test your sprite at the actual rendered size (grid scale). A 12x14 sprite at 3x scale is only 36x42 pixels on screen — fine detail is lost. For items and collectibles below 16x16 grid, use bold geometric silhouettes (diamond, star, circle) rather than trying to draw realistic objects. Use a 2px outline* (palette index 1) on all edges for small sprites to ensure they pop against any background. Hostile entities (skulls, bombs) should have a fundamentally different silhouette from collectibles (gems, coins) — size, shape, or aspect ratio should differ so players can distinguish them instantly even in peripheral vision.

2. Two-Tone Minimum

Every sprite needs at least:

• Outline color (palette index 1) — darkest, defines the shape
• Fill color — the character's primary color
• Highlight — a lighter spot for dimensionality (usually top-left)

3. Eyes Tell the Story

At 16x16, eyes are often just 1-2 pixels. Make them high-contrast:

• Red eyes (index 3) = hostile enemy
• White eyes (index 8) = neutral/friendly
• Glowing eyes = magic/supernatural

4. Animation Minimalism

At small scales, subtle changes read as smooth motion:

• Walk: Shift legs 1-2px per frame, 2-4 frames total
• Fly: Wings up/down, 2 frames
• Idle: Optional 1px bob (use Phaser tween instead of extra frame)
• Attack: Not needed at 16x16 — use screen effects (flash, shake) instead
• Never rotate small pixel sprites — rotation on sprites below 24x24 destroys the pixel grid and makes them look like blurry circles. Use vertical bobbing, scale pulses, or frame-based animation instead. Rotation only works well on sprites 32x32+.

5. Palette Discipline

• Every sprite in the game shares the same palette
• Differentiate enemies by which palette colors they use, not by adding new colors
• Bat = purple (index 9), Zombie = green (index 10), Skeleton = white (index 8), Demon = red (index 3)

6. Scale Appropriately

Character-driven games (games starring named characters, personalities, or mascots): Use the Personality archetype. The main character should dominate the screen (~35% of canvas height). Use caricature proportions — large head (60%+ of sprite height) with exaggerated features, compact body — for maximum personality at any scale. Adjust PLAYER.WIDTH and PLAYER.HEIGHT in Constants.js to match.

When replacing geometric shapes with pixel art, match the rendered sprite size to the entity's WIDTH/HEIGHT in Constants.js. If the Constants values are too small for the art style, increase them — the sprite and the physics body should agree.

Process

When invoked, follow this process:

Step 1: Audit the game

• Read package.json to identify the engine
• Read src/core/Constants.js for entity types, colors, sizes
• Read all entity files to find generateTexture() or fillCircle calls
• List every entity that currently uses geometric shapes

Step 2: Plan the sprites and backgrounds

Present a table of planned sprites:

Choose the appropriate palette for the game's theme.

Step 3: Implement

1. Create src/core/PixelRenderer.js with renderPixelArt() and renderSpriteSheet() 2. Create src/sprites/palette.js with the chosen palette 3. Create sprite data files in src/sprites/ — one per entity category 4. Create src/sprites/tiles.js with background tile variants and decorative elements 5. Update entity constructors to use renderPixelArt() / renderSpriteSheet() instead of fillCircle() + generateTexture() 6. Create or update the background system to tile pixel art ground and scatter decorations 7. Add animations where appropriate (walk cycles, wing flaps) 8. Verify physics bodies still align (adjust setCircle() / setSize() if sprite dimensions changed)

Step 4: Verify

• Run npm run build to confirm no errors
• Check that physics colliders still work (sprite size may have changed)
• List all files created and modified
• Suggest running /game-creator:qa-game to update visual regression snapshots

Checklist

When adding pixel art to a game, verify:

• [ ] PixelRenderer.js created in src/core/
• [ ] Palette defined in src/sprites/palette.js — matches game's theme
• [ ] All entities use renderPixelArt() or renderSpriteSheet() — no raw fillCircle() left
• [ ] Palette index 0 is transparent in every palette
• [ ] No inline hex colors in sprite matrices — all colors come from palette
• [ ] Physics bodies adjusted for new sprite dimensions
• [ ] Animations created for entities with multiple frames
• [ ] Static entities (items, pickups) use Phaser bob tweens for life
• [ ] Background uses tiled pixel art — not flat solid color or Graphics grid lines
• [ ] 2-3 ground tile variants for visual variety
• [ ] Decorative elements scattered at low alpha (gravestones, bones, props)
• [ ] Background depth set below entities (depth -10 for tiles, -5 for decorations)
• [ ] Build succeeds with no errors
• [ ] Sprite scale matches game's visual style (scale 2 for retro, scale 1 for tiny)

Character Pipeline — South Park System & Photo-Composite Characters

South Park Character System

Character Library

Location: assets/characters/ (relative to plugin root)

The library contains pre-built characters with photo-realistic heads composited onto South Park-style cartoon bodies. Each character has:

• Multiple expression sprites (normal, happy, angry, surprised)
• A horizontal spritesheet with all expressions
• Metadata in manifest.json

Check the library first before creating any personality sprite. If the character exists, copy their sprites into the game — no pixel art needed.

assets/characters/
  manifest.json                    # Index of all built characters
  characters/
    donald-trump/
      sprites/
        normal.png                 # Individual expression sprites (200x300)
        happy.png
        angry.png
        surprised.png
        spritesheet.png            # 800x300 horizontal strip (all expressions)
    joe-biden/
      sprites/
        ...
    elon-musk/
      sprites/
        ...

Expression Constants

Standard expression frame indices — must be consistent across all games:

// In Constants.js
export const EXPRESSION = {
  NORMAL: 0,
  HAPPY: 1,
  ANGRY: 2,
  SURPRISED: 3,
};

export const EXPRESSION_HOLD_MS = 600;

Loading Characters from the Library

During game build, copy character sprites into the game:

assets/characters/characters/<slug>/sprites/ → game-dir/public/assets/characters/<slug>/

In the Phaser preloader:

preload() {
  this.load.spritesheet('sam-altman', 'assets/characters/sam-altman/spritesheet.png', {
    frameWidth: 200,
    frameHeight: 300,
  });
}

Expression Wiring Pattern

Every personality character must have reactive expressions. Wire them to game events:

// In the player/character entity constructor:
this.sprite = scene.physics.add.sprite(x, y, 'sam-altman', EXPRESSION.NORMAL);
this.expressionTimer = null;

setExpression(expression, holdMs = EXPRESSION_HOLD_MS) {
  this.sprite.setFrame(expression);
  if (this.expressionTimer) this.expressionTimer.remove();
  if (expression !== EXPRESSION.NORMAL) {
    this.expressionTimer = this.scene.time.delayedCall(holdMs, () => {
      this.sprite.setFrame(EXPRESSION.NORMAL);
    });
  }
}

// Wire to game events in the scene's create():
eventBus.on(Events.PLAYER_DAMAGED, () => {
  player.setExpression(EXPRESSION.ANGRY);
});

eventBus.on(Events.SCORE_CHANGED, () => {
  player.setExpression(EXPRESSION.HAPPY);
});

eventBus.on(Events.SPECTACLE_STREAK, ({ streak }) => {
  player.setExpression(EXPRESSION.SURPRISED, 1000);
});

// Opponents also react:
eventBus.on(Events.OPPONENT_HIT, ({ id }) => {
  opponents[id].setExpression(EXPRESSION.ANGRY);
});

eventBus.on(Events.OPPONENT_SCORES, ({ id }) => {
  opponents[id].setExpression(EXPRESSION.HAPPY);
});

Bobblehead Body Pattern (Standard for Photo-Composite Characters)

Every photo-composite character must have a South Park-style cartoon body drawn with Phaser Graphics primitives. Never display a floating head sprite alone — always pair it with a drawn body. The "bobblehead" aesthetic (giant photo head on a tiny cartoon body) is the signature look.

Architecture: The body is rendered as a Phaser Graphics object inside a Container, with the head spritesheet sprite layered on top. Arms are separate Graphics objects for independent animation (raise, wave, cower).

Body components (drawn bottom-to-top): 1. Shoes — rounded rectangles at the bottom 2. Legs (pants) — two rounded rectangles with gap between 3. Torso (jacket/shirt) — trapezoidal polygon (wider shoulders, narrower waist) 4. Jacket detail — lighter panel for depth, lapels on each side 5. Shirt/collar V — V-shaped opening at neckline 6. Tie (if applicable) — knot + blade tapering down 7. Buttons — small circles on jacket front 8. Neck — rounded rectangle connecting body to head, skin-colored

Arms (separate Graphics for animation): 1. Upper arm (sleeve) — rounded rectangle matching jacket color 2. Shirt cuff — thin lighter rectangle 3. Hand (mitten) — rounded rectangle, skin-colored, no fingers (South Park convention)

Scaling system: All body dimensions derive from a single base unit U:

// In Constants.js
const _U = GAME.WIDTH * 0.012;

export const CHARACTER = {
  U: _U,
  TORSO_H: _U * 5,
  SHOULDER_W: _U * 7,
  WAIST_W: _U * 5,
  NECK_W: _U * 2.5,
  NECK_H: _U * 1,
  HEAD_H: GAME.WIDTH * 0.25,  // Derive from WIDTH (not HEIGHT) to stay proportional on mobile portrait
  FRAME_W: 200,              // Spritesheet frame dimensions (200x300)
  FRAME_H: 300,
  UPPER_ARM_W: _U * 1.8,
  UPPER_ARM_H: _U * 3,
  HAND_W: _U * 1.8,
  HAND_H: _U * 1.5,
  LEG_W: _U * 2.4,
  LEG_H: _U * 3,
  LEG_GAP: _U * 1.2,
  SHOE_W: _U * 3,
  SHOE_H: _U * 1.2,
  TIE_W: _U * 1,
  BUTTON_R: _U * 0.3,
  OUTLINE: Math.max(1, Math.round(_U * 0.3)),
  // Character-specific colors (suit, tie, shirt, pants, shoes, skin)
};

Container layer order:

this.container.add([
  this.leftArmGfx,   // Layer 0: behind body
  this.rightArmGfx,  // Layer 1: behind body
  this.bodyGfx,      // Layer 2: middle
  this.headSprite,   // Layer 3: on top (photo-composite head)
]);

Head positioning:

const headY = -C.TORSO_H * 0.5 - C.NECK_H - C.HEAD_H * 0.35;
this.headSprite = scene.add.sprite(0, headY, sheetKey, EXPRESSION.NORMAL);
const headScale = C.HEAD_H / C.FRAME_H;
this.headSprite.setScale(headScale);

Idle breathing (adds life):

scene.tweens.add({
  targets: container,
  y: y - 2 * PX,
  duration: 1400 + Math.random() * 400,
  yoyo: true,
  repeat: -1,
  ease: 'Sine.easeInOut',
});

Clothing palette — customize per character:

• Dark suit characters (philosophers, executives): dark navy/charcoal suit, white shirt, muted tie
• Casual characters: t-shirt (fill torso as single color, skip jacket detail/lapels/tie)
• Branded characters: use brand colors for suit/shirt

See examples/trump-mog/src/entities/Character.js for the complete reference implementation.

Building New Characters

If a personality is needed but not in the library, build it using the project-level pipeline scripts. Follow the tiered fallback — try each tier in order, stop at first success:

Tier 1: Full 4-expression build (best)

Step 1: Find Expression Images via WebSearch

Use WebSearch to find 4 distinct expression photos. Any photo format works (jpg, png, webp) — the pipeline has ML background removal (process-head.mjs) built in, so transparent PNGs are NOT required. Search broadly for real photographs:

For each expression, look for:

• normal — neutral/calm face, slight smile OK
• happy — big grin, laughing, celebrating (close-up preferred)
• angry — grimacing, teeth-baring, scowling
• surprised — mouth open, wide eyes, shocked

Image selection rules:

• Any photo works — the pipeline removes backgrounds and crops to face automatically. Don't restrict searches to "transparent PNG" or specific image sites.
• Any composition works (head-only, half-body, full-body) — crop-head.mjs uses face detection to find and crop the face automatically. No manual --ratio tuning needed.
• Avoid illustrations/cartoons — use real photos for photo-composite characters.
• Download to <outputDir>/raw/normal.jpg, happy.jpg, angry.jpg, surprised.jpg (any image extension).

Step 2: Run the Pipeline

# If images already have transparent backgrounds:
node scripts/crop-head.mjs raw/normal.png cropped/normal.png
node scripts/crop-head.mjs raw/happy.png cropped/happy.png
# ... for each expression (face detection auto-finds the face)

# Build the spritesheet:
node scripts/build-spritesheet.mjs public/assets/<slug>-expressions.png \
  --normal cropped/normal.png --happy cropped/happy.png \
  --angry cropped/angry.png --surprised cropped/surprised.png

Or use the orchestrator (expects raw images with opaque backgrounds — runs ML bg removal + crop + spritesheet):

node scripts/build-character.mjs "<Full Name>" public/assets/<slug>/ --skip-find

crop-head.mjs uses face-api.js (SSD MobileNet v1) to detect the face bounding box and crops with 25% padding. Falls back to bounding-box heuristic if no face is detected. Use --padding 0.40 to increase padding around the detected face.

Tier 2: Partial expressions (1-3 images found)

If WebSearch only finds 1-3 usable images, duplicate the best image (prefer normal) into the missing expression slots before running the pipeline:

# Example: only found normal.png and happy.png
cp raw/normal.png raw/angry.png
cp raw/normal.png raw/surprised.png
# Now run build-character.mjs as normal — all 4 raw slots are filled

Result: 4-frame spritesheet where some expressions share the same face. The expression wiring still works — character just shows the same face for missing expressions. Functional and recognizable.

Tier 3: Single image (minimum photo-composite)

If only 1 image is found, or the pipeline fails on all but one image:

# Duplicate the single image to all 4 slots
cp raw/normal.png raw/happy.png
cp raw/normal.png raw/angry.png
cp raw/normal.png raw/surprised.png
node scripts/build-character.mjs "<Name>" <outputDir>/ --skip-find

Result: All 4 frames are identical. Character is photo-recognizable but has no expression changes. Still loads as a spritesheet, still works with the expression wiring code (just no visible change).

Tier 4: Generative pixel art (worst case)

If NO usable images are found (WebSearch returns nothing, all downloads fail, pipeline crashes):

• Skip the photo-composite pipeline entirely
• Use the Personality Character (Caricature) archetype — 32x48 pixel art grid at scale 4 (renders to 128x192px)
• Design the pixel art with recognizable features: signature hairstyle, glasses, facial hair, clothing color
• Create 2-4 animation frames (idle + walk minimum) using renderSpriteSheet()
• Wire as a standard pixel art entity — no expression system, no spritesheet loading

This is the absolute last resort. Always exhaust image search first — even a single photo produces a better result than pixel art for personality characters.

Integration Patterns — Replacing Entities, Animation, External Assets

Replacing fillCircle Entities

Current pattern (procedural circle):

// OLD: in entity constructor
const gfx = scene.add.graphics();
gfx.fillStyle(cfg.color, 1);
gfx.fillCircle(cfg.size, cfg.size, cfg.size);
gfx.generateTexture(texKey, cfg.size * 2, cfg.size * 2);
gfx.destroy();
this.sprite = scene.physics.add.sprite(x, y, texKey);

New pattern (pixel art):

// NEW: in entity constructor
import { renderPixelArt } from '../core/PixelRenderer.js';
import { ZOMBIE_IDLE } from '../sprites/enemies.js';
import { PALETTE } from '../sprites/palette.js';

const texKey = `enemy-${typeKey}`;
renderPixelArt(scene, ZOMBIE_IDLE, PALETTE.DARK, texKey, 2);
this.sprite = scene.physics.add.sprite(x, y, texKey);

Adding Animation

import { renderSpriteSheet } from '../core/PixelRenderer.js';
import { PLAYER_FRAMES, PLAYER_PALETTE } from '../sprites/player.js';

// In entity constructor or BootScene
renderSpriteSheet(scene, PLAYER_FRAMES, PLAYER_PALETTE, 'player-sheet', 2);

// Create animation
scene.anims.create({
  key: 'player-walk',
  frames: scene.anims.generateFrameNumbers('player-sheet', { start: 0, end: 3 }),
  frameRate: 8,
  repeat: -1,
});

// Play animation
this.sprite = scene.physics.add.sprite(x, y, 'player-sheet', 0);
this.sprite.play('player-walk');

// Stop animation (idle)
this.sprite.stop();
this.sprite.setFrame(0);

Multiple Enemy Types

When a game has multiple enemy types (like Vampire Survivors), define each type's sprite data alongside its config:

// sprites/enemies.js
import { PALETTE } from './palette.js';

export const ENEMY_SPRITES = {
  BAT: { frames: [BAT_IDLE, BAT_FLAP], palette: PALETTE.DARK, animRate: 6 },
  ZOMBIE: { frames: [ZOMBIE_IDLE, ZOMBIE_WALK], palette: PALETTE.DARK, animRate: 4 },
  SKELETON: { frames: [SKELETON_IDLE, SKELETON_WALK], palette: PALETTE.DARK, animRate: 5 },
  GHOST: { frames: [GHOST_IDLE, GHOST_FADE], palette: PALETTE.DARK, animRate: 3 },
  DEMON: { frames: [DEMON_IDLE, DEMON_WALK], palette: PALETTE.DARK, animRate: 6 },
};

// In Enemy constructor:
const spriteData = ENEMY_SPRITES[typeKey];
const texKey = `enemy-${typeKey}`;
renderSpriteSheet(scene, spriteData.frames, spriteData.palette, texKey, 2);

this.sprite = scene.physics.add.sprite(x, y, texKey, 0);
scene.anims.create({
  key: `${typeKey}-anim`,
  frames: scene.anims.generateFrameNumbers(texKey, { start: 0, end: spriteData.frames.length - 1 }),
  frameRate: spriteData.animRate,
  repeat: -1,
});
this.sprite.play(`${typeKey}-anim`);

External Asset Download

Use this workflow for downloading real images (logos, meme references, sprite sheets). Logos and meme images from the source tweet are downloaded by default (see Asset Tiers in SKILL.md). Full sprite sheet replacements are optional and used when pixel art isn't sufficient.

Reliable Free Sources

Download Workflow

1. Search for assets matching the game theme using WebSearch 2. Verify license — only CC0 or CC-BY are safe for any project 3. Download the sprite sheet PNG using curl or wget 4. Place in public/assets/sprites/ (Vite serves public/ as static) 5. Load in a Preloader scene:

   // scenes/PreloaderScene.js
   preload() {
     this.load.spritesheet('player', 'assets/sprites/player.png', {
       frameWidth: 32,
       frameHeight: 32,
     });
   }

6. Create animations in the Preloader scene 7. Add fallback — if the asset fails to load, fall back to renderPixelArt()

Graceful Fallback Pattern

// Check if external asset loaded, otherwise use pixel art
if (scene.textures.exists('player-external')) {
  this.sprite = scene.physics.add.sprite(x, y, 'player-external');
} else {
  renderPixelArt(scene, PLAYER_IDLE, PLAYER_PALETTE, 'player-fallback', 2);
  this.sprite = scene.physics.add.sprite(x, y, 'player-fallback');
}

Logo Download Workflow

When a game features a named company, download and use the real logo. SVG preferred (scales cleanly), PNG acceptable.

Steps: 1. Search for the company's official logo (SVG or high-res PNG) 2. Download to public/assets/logos/<company>.svg (or .png) 3. Load in Phaser: this.load.image('logo-openai', 'assets/logos/openai.svg') 4. Use for branding elements (splash, HUD icons, entity overlays) 5. Keep pixel art fallback for the character sprite itself — logos complement personality sprites, they don't replace them

Well-known logo sources (search for these when needed):

• Company press kits and brand pages typically host official logo files
• Use WebSearch to find "<company> logo SVG press kit" or "<company> brand assets"

In Phaser preload:

preload() {
  this.load.image('logo-openai', 'assets/logos/openai.png');
  this.load.image('logo-anthropic', 'assets/logos/anthropic.png');
}

Fallback if logo fails to load:

this.load.on('loaderror', (file) => {
  console.warn(`Failed to load ${file.key}, using pixel art fallback`);
});

Meme Image Integration

When thread.json includes an image_url, download and incorporate it:

1. Download the image: curl -o public/assets/meme-ref.png "<image_url>" 2. Load in Phaser: this.load.image('meme-ref', 'assets/meme-ref.png') 3. Use appropriately — as a background element, game-over splash, or visual reference for character design 4. Study the image for character appearances, visual style, and meme elements before designing sprites

Pixel Renderer — renderPixelArt(), renderSpriteSheet(), and Palettes

Core Renderer

Add this to src/core/PixelRenderer.js:

/**
 * Renders a 2D pixel matrix to a Phaser texture.
 *
 * @param {Phaser.Scene} scene - The scene to register the texture on
 * @param {number[][]} pixels - 2D array of palette indices (0 = transparent)
 * @param {(number|null)[]} palette - Array of hex colors indexed by pixel value
 * @param {string} key - Texture key to register
 * @param {number} scale - Pixel scale (2 = each pixel becomes 2x2)
 */
export function renderPixelArt(scene, pixels, palette, key, scale = 2) {
  if (scene.textures.exists(key)) return;

  const h = pixels.length;
  const w = pixels[0].length;
  const canvas = document.createElement('canvas');
  canvas.width = w * scale;
  canvas.height = h * scale;
  const ctx = canvas.getContext('2d');

  for (let y = 0; y < h; y++) {
    for (let x = 0; x < w; x++) {
      const idx = pixels[y][x];
      if (idx === 0 || palette[idx] == null) continue;
      const color = palette[idx];
      const r = (color >> 16) & 0xff;
      const g = (color >> 8) & 0xff;
      const b = color & 0xff;
      ctx.fillStyle = `rgb(${r},${g},${b})`;
      ctx.fillRect(x * scale, y * scale, scale, scale);
    }
  }

  scene.textures.addCanvas(key, canvas);
}

/**
 * Renders multiple frames as a spritesheet texture.
 * Frames are laid out horizontally in a single row.
 *
 * @param {Phaser.Scene} scene
 * @param {number[][][]} frames - Array of pixel matrices (one per frame)
 * @param {(number|null)[]} palette
 * @param {string} key - Spritesheet texture key
 * @param {number} scale
 */
export function renderSpriteSheet(scene, frames, palette, key, scale = 2) {
  if (scene.textures.exists(key)) return;

  const h = frames[0].length;
  const w = frames[0][0].length;
  const frameW = w * scale;
  const frameH = h * scale;
  const canvas = document.createElement('canvas');
  canvas.width = frameW * frames.length;
  canvas.height = frameH;
  const ctx = canvas.getContext('2d');

  frames.forEach((pixels, fi) => {
    const offsetX = fi * frameW;
    for (let y = 0; y < h; y++) {
      for (let x = 0; x < w; x++) {
        const idx = pixels[y][x];
        if (idx === 0 || palette[idx] == null) continue;
        const color = palette[idx];
        const r = (color >> 16) & 0xff;
        const g = (color >> 8) & 0xff;
        const b = color & 0xff;
        ctx.fillStyle = `rgb(${r},${g},${b})`;
        ctx.fillRect(offsetX + x * scale, y * scale, scale, scale);
      }
    }
  });

  scene.textures.addSpriteSheet(key, canvas, {
    frameWidth: frameW,
    frameHeight: frameH,
  });
}

Directory Structure

src/
  core/
    PixelRenderer.js    # renderPixelArt() + renderSpriteSheet()
  sprites/
    palette.js          # Shared color palette(s) for the game
    player.js           # Player sprite frames
    enemies.js          # Enemy sprite frames (one export per type)
    items.js            # Pickups, gems, weapons, etc.
    projectiles.js      # Bullets, fireballs, etc.

Palette Definition

Define palettes in src/sprites/palette.js. Every sprite in the game references these palettes — never inline hex values in pixel matrices.

// palette.js — all sprite colors live here
// Index 0 is ALWAYS transparent

export const PALETTE = {
  // Gothic / dark fantasy (vampire survivors, roguelikes)
  DARK: [
    null,       // 0: transparent
    0x1a1a2e,   // 1: dark outline
    0x16213e,   // 2: shadow
    0xe94560,   // 3: accent (blood red)
    0xf5d742,   // 4: highlight (gold)
    0x8b5e3c,   // 5: skin
    0x4a4a6a,   // 6: armor/cloth
    0x2d2d4a,   // 7: dark cloth
    0xffffff,   // 8: white (eyes, teeth)
    0x6b3fa0,   // 9: purple (magic)
    0x3fa04b,   // 10: green (poison/nature)
  ],

  // Bright / arcade (platformers, casual)
  BRIGHT: [
    null,
    0x222034,   // 1: outline
    0x45283c,   // 2: shadow
    0xd95763,   // 3: red
    0xfbf236,   // 4: yellow
    0xeec39a,   // 5: skin
    0x5fcde4,   // 6: blue
    0x639bff,   // 7: light blue
    0xffffff,   // 8: white
    0x76428a,   // 9: purple
    0x99e550,   // 10: green
  ],

  // Muted / retro (NES-inspired)
  RETRO: [
    null,
    0x000000,   // 1: black outline
    0x7c7c7c,   // 2: dark gray
    0xbcbcbc,   // 3: light gray
    0xf83800,   // 4: red
    0xfcfc00,   // 5: yellow
    0xa4e4fc,   // 6: sky blue
    0x3cbcfc,   // 7: blue
    0xfcfcfc,   // 8: white
    0x0078f8,   // 9: dark blue
    0x00b800,   // 10: green
  ],
};

Sprite Catalog

Complete catalog of sprite archetypes for pixel art game assets. Grid sizes vary by archetype — from 8x8 for tiny pickups to 32x48 for personality characters. The default scale is 3 (each pixel becomes 3x3 on screen).

When creating sprites for a game, match the archetype to the entity type.

Design Philosophy: Push the Pose

Before choosing an archetype, consider what each entity represents thematically:

• Real people → Always use the Personality Character archetype. Exaggerate their most recognizable feature until it's almost a caricature. Recognition is everything.
• Companies/brands → Incorporate logo shapes into the sprite. Use brand colors as the primary palette. Consider anthropomorphizing the logo (add limbs, face, expressions).
• Game objects → Must be instantly recognizable real-world objects, never abstract shapes. A collectible representing "creative output" could be a painting, a polaroid, a film reel — not a generic diamond or spark.
• Opponents → Each must be visually distinct. Different silhouettes, color palettes, and proportions. If they represent specific entities (rival companies, other people), build that identity into the sprite.

When in doubt, make it MORE recognizable, MORE exaggerated, MORE character-driven. We dial back, never up.

Personality Character (South Park Photo-Composite)

For games featuring real people or named personalities (Altman, Amodei, Musk, Zuckerberg, etc.). Photo heads composited onto South Park-style cartoon bodies — instantly recognizable, no hand-drawn pixel art needed.

• Dimensions: 200x300 per frame (frameWidth: 200, frameHeight: 300)
• Spritesheet: Horizontal strip with all expressions
• Source: Pre-built in the character library at assets/characters/ (relative to plugin root)
• Head occupies 65% of sprite height — large, recognizable photo on a small cartoon body
• Must be the largest entity on screen — supporting entities stay at Medium (16x16) or Small (12x12)

Expression Frame Index Reference

Frame indices are fixed and consistent across all characters:

Not all characters have all 4 expressions — check manifest.json for available frames. If a character has only 3 frames (normal, happy, angry), don't reference frame 3.

Loading in Phaser

// Preloader
this.load.spritesheet('sam-altman', 'assets/characters/sam-altman/spritesheet.png', {
  frameWidth: 200,
  frameHeight: 300,
});

// Create sprite
this.sprite = scene.physics.add.sprite(x, y, 'sam-altman', EXPRESSION.NORMAL);

Character Feature Reference

Physical descriptions for commonly-appearing tech figures. Use these to select source images for new character builds.

Humanoid (Player, NPC, Warrior)

Key features: Head (2-3px wide), body (3-4px wide), legs (2 columns). Arms optional at 16x16. Distinguish characters via hair/hat color and body color.

// sprites/player.js
import { PALETTE } from './palette.js';

export const PLAYER_PALETTE = PALETTE.DARK;

// Idle frame — standing, sword at side
export const PLAYER_IDLE = [
  [0,0,0,0,0,0,1,1,1,1,0,0,0,0,0,0],
  [0,0,0,0,0,1,4,4,4,4,1,0,0,0,0,0],
  [0,0,0,0,0,1,4,4,4,4,1,0,0,0,0,0],
  [0,0,0,0,1,5,5,5,5,5,5,1,0,0,0,0],
  [0,0,0,0,1,5,1,5,5,1,5,1,0,0,0,0],
  [0,0,0,0,1,5,5,5,5,5,5,1,0,0,0,0],
  [0,0,0,0,0,1,5,3,5,5,1,0,0,0,0,0],
  [0,0,0,0,0,0,1,1,1,1,0,0,0,0,0,0],
  [0,0,0,0,1,6,6,6,6,6,6,1,0,0,0,0],
  [0,0,0,1,6,6,6,6,6,6,6,6,1,0,0,0],
  [0,0,0,1,6,6,6,6,6,6,6,6,1,0,0,0],
  [0,0,0,1,5,6,6,6,6,6,6,5,1,0,0,0],
  [0,0,0,0,1,6,6,6,6,6,6,1,0,0,0,0],
  [0,0,0,0,1,7,7,1,1,7,7,1,0,0,0,0],
  [0,0,0,0,1,7,7,1,1,7,7,1,0,0,0,0],
  [0,0,0,0,1,1,1,0,0,1,1,1,0,0,0,0],
];

// Walk frame 1 — left leg forward
export const PLAYER_WALK1 = [
  [0,0,0,0,0,0,1,1,1,1,0,0,0,0,0,0],
  [0,0,0,0,0,1,4,4,4,4,1,0,0,0,0,0],
  [0,0,0,0,0,1,4,4,4,4,1,0,0,0,0,0],
  [0,0,0,0,1,5,5,5,5,5,5,1,0,0,0,0],
  [0,0,0,0,1,5,1,5,5,1,5,1,0,0,0,0],
  [0,0,0,0,1,5,5,5,5,5,5,1,0,0,0,0],
  [0,0,0,0,0,1,5,3,5,5,1,0,0,0,0,0],
  [0,0,0,0,0,0,1,1,1,1,0,0,0,0,0,0],
  [0,0,0,0,1,6,6,6,6,6,6,1,0,0,0,0],
  [0,0,0,1,6,6,6,6,6,6,6,6,1,0,0,0],
  [0,0,0,1,6,6,6,6,6,6,6,6,1,0,0,0],
  [0,0,0,1,5,6,6,6,6,6,6,5,1,0,0,0],
  [0,0,0,0,1,6,6,6,6,6,6,1,0,0,0,0],
  [0,0,0,1,7,7,1,0,0,1,7,7,1,0,0,0],
  [0,0,1,7,7,1,0,0,0,0,1,7,1,0,0,0],
  [0,0,1,1,1,0,0,0,0,0,1,1,1,0,0,0],
];

// Walk frame 2 — right leg forward (mirror of walk1)
export const PLAYER_WALK2 = [
  [0,0,0,0,0,0,1,1,1,1,0,0,0,0,0,0],
  [0,0,0,0,0,1,4,4,4,4,1,0,0,0,0,0],
  [0,0,0,0,0,1,4,4,4,4,1,0,0,0,0,0],
  [0,0,0,0,1,5,5,5,5,5,5,1,0,0,0,0],
  [0,0,0,0,1,5,1,5,5,1,5,1,0,0,0,0],
  [0,0,0,0,1,5,5,5,5,5,5,1,0,0,0,0],
  [0,0,0,0,0,1,5,3,5,5,1,0,0,0,0,0],
  [0,0,0,0,0,0,1,1,1,1,0,0,0,0,0,0],
  [0,0,0,0,1,6,6,6,6,6,6,1,0,0,0,0],
  [0,0,0,1,6,6,6,6,6,6,6,6,1,0,0,0],
  [0,0,0,1,6,6,6,6,6,6,6,6,1,0,0,0],
  [0,0,0,1,5,6,6,6,6,6,6,5,1,0,0,0],
  [0,0,0,0,1,6,6,6,6,6,6,1,0,0,0,0],
  [0,0,0,1,7,1,0,0,1,7,7,1,0,0,0,0],
  [0,0,0,1,7,1,0,0,0,1,7,7,1,0,0,0],
  [0,0,0,1,1,1,0,0,0,0,1,1,1,0,0,0],
];

export const PLAYER_FRAMES = [PLAYER_IDLE, PLAYER_WALK1, PLAYER_IDLE, PLAYER_WALK2];

Flying Creature (Bat, Ghost, Bird)

Key features: Wide silhouette (wings/wispy edges), small body, glowing eyes. Wings swap between up/down for animation.

// In sprites/enemies.js
export const BAT_IDLE = [
  [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
  [0,0,1,1,0,0,0,0,0,0,0,1,1,0,0,0],
  [0,1,9,9,1,0,0,0,0,0,1,9,9,1,0,0],
  [1,9,9,9,9,1,0,0,0,1,9,9,9,9,1,0],
  [1,9,9,9,9,9,1,1,1,9,9,9,9,9,1,0],
  [0,1,9,9,9,9,9,9,9,9,9,9,9,1,0,0],
  [0,0,1,9,9,3,9,9,9,3,9,9,1,0,0,0],
  [0,0,0,1,9,9,9,9,9,9,9,1,0,0,0,0],
  [0,0,0,0,1,9,9,8,9,9,1,0,0,0,0,0],
  [0,0,0,0,0,1,1,1,1,1,0,0,0,0,0,0],
  [0,0,0,0,0,0,1,1,1,0,0,0,0,0,0,0],
  [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
  [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
  [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
  [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
  [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
];

// Wings down frame — alternate with idle for flapping
export const BAT_FLAP = [
  [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
  [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
  [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
  [0,0,0,0,0,1,1,1,1,1,0,0,0,0,0,0],
  [0,0,0,0,1,9,9,9,9,9,1,0,0,0,0,0],
  [0,0,0,1,9,9,3,9,3,9,9,1,0,0,0,0],
  [0,0,1,9,9,9,9,9,9,9,9,9,1,0,0,0],
  [0,1,9,9,9,9,9,8,9,9,9,9,9,1,0,0],
  [1,9,9,9,9,9,1,1,1,9,9,9,9,9,1,0],
  [1,9,9,9,9,1,0,0,0,1,9,9,9,9,1,0],
  [0,1,9,9,1,0,0,0,0,0,1,9,9,1,0,0],
  [0,0,1,1,0,0,0,0,0,0,0,1,1,0,0,0],
  [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
  [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
  [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
  [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
];

Ground Creature (Zombie, Slime, Skeleton)

Key features: Wider base, heavier silhouette, shambling posture. Animate by shifting body weight side to side.

// Zombie — hunched, arms forward
export const ZOMBIE_IDLE = [
  [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
  [0,0,0,0,0,1,1,1,1,1,0,0,0,0,0,0],
  [0,0,0,0,1,10,10,10,10,10,1,0,0,0,0,0],
  [0,0,0,0,1,10,3,10,3,10,1,0,0,0,0,0],
  [0,0,0,0,1,10,10,10,10,10,1,0,0,0,0,0],
  [0,0,0,0,0,1,10,1,10,1,0,0,0,0,0,0],
  [0,0,0,0,0,0,1,1,1,0,0,0,0,0,0,0],
  [0,0,0,0,1,7,7,7,7,7,1,0,0,0,0,0],
  [0,0,0,1,7,7,7,7,7,7,7,1,0,0,0,0],
  [0,0,1,10,7,7,7,7,7,7,10,10,1,0,0,0],
  [0,1,10,1,7,7,7,7,7,7,1,10,10,1,0,0],
  [0,0,0,0,1,7,7,7,7,7,1,0,0,0,0,0],
  [0,0,0,0,1,7,7,1,7,7,1,0,0,0,0,0],
  [0,0,0,0,1,7,1,0,1,7,1,0,0,0,0,0],
  [0,0,0,0,1,10,1,0,1,10,1,0,0,0,0,0],
  [0,0,0,0,1,1,1,0,1,1,1,0,0,0,0,0],
];

Item / Pickup (Gem, Coin, Heart, Orb)

Key features: Small (8x8 or 12x12), bright colors, simple symmetric shape. Often animated with a bob tween rather than frame animation.

// XP Gem — diamond shape, 8x8
export const XP_GEM = [
  [0,0,0,4,4,0,0,0],
  [0,0,4,4,4,4,0,0],
  [0,4,4,8,4,4,4,0],
  [4,4,8,4,4,4,4,4],
  [4,4,4,4,4,8,4,4],
  [0,4,4,4,4,4,4,0],
  [0,0,4,4,4,4,0,0],
  [0,0,0,4,4,0,0,0],
];

// Heart — 8x8
export const HEART = [
  [0,0,3,3,0,3,3,0],
  [0,3,3,3,3,3,3,3],
  [0,3,8,3,3,3,3,3],
  [0,3,3,3,3,3,3,3],
  [0,0,3,3,3,3,3,0],
  [0,0,0,3,3,3,0,0],
  [0,0,0,0,3,0,0,0],
  [0,0,0,0,0,0,0,0],
];

Projectile (Bullet, Fireball, Magic Bolt)

Key features: Very small (4x4 to 8x8), bright, high contrast. Often just a few pixels with a glow color.

// Fireball — 8x8
export const FIREBALL = [
  [0,0,0,4,4,0,0,0],
  [0,0,4,4,4,4,0,0],
  [0,3,4,8,4,4,3,0],
  [3,3,4,4,4,4,3,3],
  [0,3,3,4,4,3,3,0],
  [0,0,3,3,3,3,0,0],
  [0,0,0,3,3,0,0,0],
  [0,0,0,0,0,0,0,0],
];

// Magic bolt — 6x6
export const MAGIC_BOLT = [
  [0,0,9,9,0,0],
  [0,9,8,9,9,0],
  [9,9,9,9,9,9],
  [9,9,9,9,9,9],
  [0,9,9,8,9,0],
  [0,0,9,9,0,0],
];

Background Tile (Ground, Floor, Terrain)

Key features: Seamless tiling, subtle variation between tiles, low contrast so entities stand out. Use 16x16 tiles at scale 2 (32x32px each).

// sprites/tiles.js — background tile variants

// Ground tile — base terrain (dark earth / stone)
export const GROUND_BASE = [
  [2,2,2,1,2,2,2,2,2,2,1,2,2,2,2,2],
  [2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2],
  [2,2,2,2,2,2,1,2,2,2,2,2,2,2,1,2],
  [2,2,1,2,2,2,2,2,2,2,2,2,2,2,2,2],
  [2,2,2,2,2,2,2,2,2,1,2,2,2,2,2,2],
  [2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2],
  [1,2,2,2,2,2,2,2,2,2,2,2,1,2,2,2],
  [2,2,2,2,2,1,2,2,2,2,2,2,2,2,2,2],
  [2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2],
  [2,2,2,2,2,2,2,2,1,2,2,2,2,2,2,2],
  [2,2,1,2,2,2,2,2,2,2,2,2,2,1,2,2],
  [2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2],
  [2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2],
  [2,2,2,2,1,2,2,2,2,2,2,2,2,2,2,2],
  [2,2,2,2,2,2,2,2,2,2,1,2,2,2,2,2],
  [2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2],
];

// Variant tiles — alternate with GROUND_BASE for variety
export const GROUND_VAR1 = [ /* same size, different speckle pattern */ ];
export const GROUND_VAR2 = [ /* ... */ ];

Decorative Elements (8x8 to 16x16)

Small props scattered on the ground at random positions. Not tiles — placed once during scene creation.

// Gravestone — 8x12
export const GRAVESTONE = [
  [0,0,1,1,1,1,0,0],
  [0,1,18,18,18,18,1,0],
  [0,1,18,8,8,18,1,0],
  [0,1,18,18,18,18,1,0],
  [0,1,18,18,18,18,1,0],
  [0,1,18,18,18,18,1,0],
  [0,1,18,18,18,18,1,0],
  [0,1,18,18,18,18,1,0],
  [0,1,18,18,18,18,1,0],
  [1,18,18,18,18,18,18,1],
  [1,18,18,18,18,18,18,1],
  [1,1,1,1,1,1,1,1],
];

// Bone pile — 8x6
export const BONE_PILE = [
  [0,0,8,0,0,8,0,0],
  [0,8,8,8,8,8,8,0],
  [8,18,8,8,8,18,8,8],
  [0,8,8,8,8,8,8,0],
  [0,8,18,8,8,18,8,0],
  [0,0,8,8,8,8,0,0],
];

// Torch — 6x12 (flickering tip animated via tween tint, not extra frame)
export const TORCH = [
  [0,0,4,4,0,0],
  [0,4,12,12,4,0],
  [0,0,4,4,0,0],
  [0,0,1,1,0,0],
  [0,0,19,19,0,0],
  [0,0,19,19,0,0],
  [0,0,19,19,0,0],
  [0,0,19,19,0,0],
  [0,0,19,19,0,0],
  [0,0,19,19,0,0],
  [0,0,19,19,0,0],
  [0,0,1,1,0,0],
];

Tiled Background Rendering

Use renderPixelArt() to create tile textures, then fill the world with tileSprite:

// In the game scene's create():
import { renderPixelArt } from '../core/PixelRenderer.js';
import { GROUND_BASE, GROUND_VAR1, GROUND_VAR2 } from '../sprites/tiles.js';
import { PALETTE } from '../sprites/palette.js';

// Render tile textures
renderPixelArt(scene, GROUND_BASE, PALETTE, 'tile-ground-0', 2);
renderPixelArt(scene, GROUND_VAR1, PALETTE, 'tile-ground-1', 2);
renderPixelArt(scene, GROUND_VAR2, PALETTE, 'tile-ground-2', 2);

// Option A: TileSprite for infinite seamless ground
const bg = scene.add.tileSprite(0, 0, WORLD_WIDTH, WORLD_HEIGHT, 'tile-ground-0');
bg.setOrigin(0, 0);
bg.setDepth(-10);

// Option B: Random tile grid for variety (better visual result)
const tileSize = 32; // 16px * scale 2
for (let y = 0; y < WORLD_HEIGHT; y += tileSize) {
  for (let x = 0; x < WORLD_WIDTH; x += tileSize) {
    const variant = Math.random() < 0.7 ? 'tile-ground-0'
                  : Math.random() < 0.5 ? 'tile-ground-1'
                  : 'tile-ground-2';
    scene.add.image(x + tileSize / 2, y + tileSize / 2, variant).setDepth(-10);
  }
}

// Scatter decorative elements
const decorTypes = ['deco-gravestone', 'deco-bones', 'deco-torch'];
for (let i = 0; i < 40; i++) {
  const dx = Phaser.Math.Between(100, WORLD_WIDTH - 100);
  const dy = Phaser.Math.Between(100, WORLD_HEIGHT - 100);
  const type = Phaser.Utils.Array.GetRandom(decorTypes);
  const deco = scene.add.image(dx, dy, type);
  deco.setDepth(-5);
  deco.setAlpha(0.6 + Math.random() * 0.4);
}

Background Design Rules

1. Low contrast — background tiles should be 2-3 shades of the same dark color. Entities must pop against the background. 2. Subtle variation — use 2-3 tile variants with different speckle patterns. Random placement breaks repetition. 3. Decorative props — scatter 20-50 small decorations across the world. Low alpha (0.5-0.8) keeps them subtle. 4. Match the theme — gothic games: gravestones, bones, dead trees. Sci-fi: metal panels, pipes, lights. Nature: grass tufts, flowers, rocks. 5. Depth layering — tiles at depth -10, decorations at -5, entities at 5-15. Never let background compete with gameplay.