pixel-asset-master

name	pixel-asset-master
description	AI-driven 2D pixel game asset generation system. Converts game design descriptions into pixel art sprites, tilesets, animations, and UI elements through multi-role collaboration. Exports as sprite sheets and individual PNGs. Use when user asks to "create pixel art", "generate game sprites", "make tileset", "生成像素素材", "做游戏瓦片", "制作精灵图", or mentions "pixel-asset-master".
license	Apache-2.0
metadata	{"author":424431185,"version":"0.2.0","created":"2025-01-01T00:00:00.000Z","last_reviewed":"2026-08-17T00:00:00.000Z","review_interval_days":90,"dependencies":[{"url":"https://pypi.org/project/Pillow/","name":"Pillow (Python image library)","type":"library"}]}

/pixel-asset-master — AI-Driven 2D Pixel Game Asset Generation

AI-driven 2D pixel game asset generation system. Converts game design descriptions into pixel art sprites, tilesets, animations, and UI elements through multi-role collaboration and exports as sprite sheets / individual PNGs.

Core Pipeline: Game Description → Create Project → Style Confirmation → Strategist → [Image_Generator] → Executor → Post-processing → Export

[!NOTE]

📂 Path Resolution

${SKILL_DIR} refers to the directory containing this SKILL.md file, i.e. the pixel-asset-master/ folder. When executing scripts, resolve it to the actual absolute path on your system. For example:

• If the repo is at /home/user/mk-pixel-asset-master-skills, then ${SKILL_DIR} = /home/user/mk-pixel-asset-master-skills/skills/pixel-asset-master
• All script paths in this document use ${SKILL_DIR}/scripts/ as the prefix

[!CAUTION]

🚨 Global Execution Discipline (MANDATORY)

This workflow is a strict serial pipeline. The following rules have the highest priority — violating any one of them constitutes execution failure:

1. SERIAL EXECUTION — Steps MUST be executed in order; the output of each step is the input for the next. Non-BLOCKING adjacent steps may proceed continuously once prerequisites are met
2. BLOCKING = HARD STOP — Steps marked ⛔ BLOCKING require a full stop; the AI MUST wait for an explicit user response before proceeding
3. NO CROSS-PHASE BUNDLING — Cross-phase bundling is FORBIDDEN
4. GATE BEFORE ENTRY — Each Step has prerequisites (🚧 GATE) listed at the top; these MUST be verified before starting that Step
5. NO SPECULATIVE EXECUTION — "Pre-preparing" content for subsequent Steps is FORBIDDEN
6. NO SUB-AGENT GENERATION — Executor Step 6 pixel art generation is context-dependent and MUST be completed by the current main agent end-to-end
7. SEQUENTIAL ASSET GENERATION — Assets MUST be generated sequentially in one continuous pass
8. SPEC_LOCK RE-READ PER ASSET — Before generating each asset, Executor MUST re-read spec_lock.md. All colors / sizes / palettes MUST come from this file

[!IMPORTANT]

🌐 Language & Communication Rule

• Response language: match the user's input. Explicit user override takes precedence.
• Template format: design_spec.md MUST follow its original English template structure regardless of conversation language. Content values may be in the user's language.

[!IMPORTANT]

🔌 Compatibility With Generic Coding Skills

• pixel-asset-master is a repository-specific workflow, not a general application scaffold
• Do NOT create .worktrees/, tests/, branch workflows, or generic engineering structure by default
• On conflict with a generic coding skill, follow this skill unless the user explicitly says otherwise

Trigger

User invokes /pixel-asset-master or mentions pixel art asset generation:

/pixel-asset-master Create a 64x64 RPG character sprite sheet with idle and walk animations
/pixel-asset-master 帮我生成一套水墨风像素游戏瓦片，包括草地、泥土、石板路
/pixel-asset-master Make a 32x32 tileset for a dungeon, NES classic style, 4 colors per tile

The skill also activates naturally when the user asks to "create pixel art", "generate game sprites", "make tileset", or mentions pixel game assets.

Main Pipeline Scripts

Script	Purpose
${SKILL_DIR}/scripts/project_manager.py	Project init / validate / manage
${SKILL_DIR}/scripts/palette_analyzer.py	Palette extraction and validation
${SKILL_DIR}/scripts/asset_validator.py	Pixel art asset quality check
${SKILL_DIR}/scripts/sprite_sheet.py	Sprite sheet packing and export
${SKILL_DIR}/scripts/image_gen.py	AI image generation (multi-provider)
${SKILL_DIR}/scripts/finalize_assets.py	Asset post-processing (quantize, clean, index)
${SKILL_DIR}/scripts/gen_tiles_reference.py	Tile generation reference implementation
${SKILL_DIR}/scripts/run_pipeline.py	One-command pipeline orchestrator (Step 7)
${SKILL_DIR}/scripts/check_pipeline.py	Skill structure validator

For complete tool documentation, see ${SKILL_DIR}/scripts/README.md.

Template Index

Index	Path	Purpose
Palette library	${SKILL_DIR}/templates/palettes/palettes_index.json	Query available pixel art color palettes
Size presets	${SKILL_DIR}/templates/sizes/sizes_index.json	Query standard pixel art dimensions
Sprite templates	${SKILL_DIR}/templates/sprites/sprites_index.json	Query sprite layout templates (character, tile, item, UI)

Standalone Workflows

Workflow	Path	Purpose
create-palette	workflows/create-palette.md	Standalone palette creation workflow
batch-animate	workflows/batch-animate.md	Batch animation frame generation

---

Pipeline Steps

Step 1: Source Content Processing

🚧 GATE: User provides game design description (text/image/reference)

Input Type	Processing
Text description	Direct use as design brief
Reference images	Analyze style, palette, size via palette_analyzer.py
Game design doc	Extract asset requirements list
Existing sprites	Analyze and extend existing style

Output: Structured asset requirements list

---

Step 2: Project Initialization

🚧 GATE: Step 1 complete

python ${SKILL_DIR}/scripts/project_manager.py init <project_name> --size 32x32 --palette default

Project structure:

projects/<name>_<size>_<date>/
├── design_spec.md          # Human-readable design narrative
├── spec_lock.md            # Machine-readable execution contract
├── images/                 # User-provided reference images
├── assets/                 # Generated pixel art assets (PNG)
│   ├── characters/
│   ├── tiles/
│   ├── items/
│   ├── ui/
│   ├── effects/
│   └── backgrounds/
├── animations/             # Animation frame sequences
├── sheets/                 # Packed sprite sheets
├── notes/                  # Design notes per asset
└── exports/                # Final export directory

If user provides reference images:

python ${SKILL_DIR}/scripts/project_manager.py import-sources <project_path> <files...> --move

---

Step 3: Style Confirmation

🚧 GATE: Step 2 complete

Select pixel art style direction:

Style	Description	Typical Size	Palette
NES Classic	8-bit console style, hard edges	16x16 / 32x32	4-8 colors per sprite
SNES Retro	16-bit console, more detail	32x32 / 64x64	8-16 colors per sprite
Modern Pixel	Clean, contemporary indie	32x32 / 64x64	16-32 colors per sprite
Minimalist	Ultra-simple, few pixels	8x8 / 16x16	2-4 colors per sprite
Dense Detail	Rich detail, large sprites	64x64 / 128x128	24-48 colors per sprite
High-Res Pixel	Ultra-detailed, illustration-grade	256x256 / 512x512	64-96 colors per sprite
Cinematic Pixel	Print/billboard quality	1024x1024 / 2048x2048	128-256 colors per sprite

⛔ BLOCKING — Present style options to user, wait for confirmation.

---

Step 4: Strategist — Six Confirmations

🚧 GATE: Step 3 confirmed

The Strategist formulates Six Confirmations for the pixel art project:

#	Confirmation	Description
1	Canvas Size	Base sprite size per frame. Available presets: 8x8 / 16x16 / 24x24 / 32x32 / 48x48 / 64x64 / 128x128 / 256x256 / 512x512 / 1024x1024 / 2048x2048. Custom sizes allowed (max 2048x2048). For character sprite sheets, prefer ≥ 64x64 for sufficient detail.
2	Asset Count	Total number of assets to generate
3	Target Platform	Game engine / runtime (Unity, Godot, RPG Maker, web, etc.)
4	Color Palette	Specific palette or auto-derived from references
5	Art Style	Pixel art sub-style (outlined / outlineless / dithered / cel-shaded)
6	Animation Needs	For each character asset, confirm the following:

Animation detail breakdown (for character assets):

Item	Options	Notes
Facing direction	4-dir (up/down/left/right) / 8-dir / side-only (left+right) / single (front-facing only)	Determines how many directional rows the sprite sheet needs
Action list	Select from common actions below, or specify custom	Each action = one row in the sprite sheet
Frames per action	Typical 4-8 frames per action; idle can be 2-4, run 6-8, attack 4-6	More frames = smoother but larger sheet

Common character actions:

Action	Typical Frames	Description
idle	2-4	Standing breathing / subtle motion
walk	4-6	Slow-paced walking cycle
run	6-8	Fast running cycle
jump	4-6	Jump ascent + peak
fall	2-4	Falling / descent
attack	4-6	Melee / ranged attack
hurt	2-3	Taking damage reaction
die	4-6	Death animation
cast	4-6	Magic / skill casting
interact	2-4	Opening chest / pushing / pulling
climb	4-6	Ladder / wall climbing
crouch	2-3	Crouching / sneaking
roll	4-6	Dodge roll
swim	4-6	Swimming cycle

⛔ BLOCKING — Present Six Confirmations to user, wait for explicit confirmation.

After confirmation, generate:

• design_spec.md — Human-readable design narrative
• spec_lock.md — Machine-readable execution contract

---

Step 5: Image Acquisition

🚧 GATE: Step 4 confirmed

Scenario	Action
User provided references	Already in images/, skip
Need additional references	Use image_gen.py or web search
No references needed	Generate from description only

---

Step 6: Executor — Generate Pixel Art Assets

🚧 GATE: Step 5 complete, spec_lock.md exists

Role-specific rules: see references/executor-pixel.md

Generation phases:

1. Visual Construction Phase: Generate all pixel art PNG assets sequentially
2. Quality Check Gate: Run asset_validator.py on all assets
3. Logic Construction Phase: Generate design notes per asset

Per-asset generation:

• Re-read spec_lock.md before each asset
• Generate at declared canvas size
• Apply declared palette (quantize if needed)
• Save to appropriate assets/ subdirectory

Asset categories:

Category	Subdirectory	Typical Assets
Characters	assets/characters/	Player, NPCs, enemies, bosses
Tiles	assets/tiles/	Ground, walls, decorations, transitions
Items	assets/items/	Weapons, potions, keys, collectibles
UI	assets/ui/	Buttons, frames, icons, bars, panels
Effects	assets/effects/	Explosions, particles, magic, weather
Backgrounds	assets/backgrounds/	Parallax layers, sky, terrain

---

🧱 Tile Generation Standards (MANDATORY)

Tiles are the most common asset type and easiest to make look "fake". The following 9 rules must ALL be satisfied for every tile.

1. Canvas & Format

• Default size: 64×64 RGB (no transparency for ground tiles)
• Palette: Strict quantization to declared palette in spec_lock.md
• Anti-pattern: Anti-aliasing, semi-transparent edges, gradients with > palette colors

2. NO Obvious Geometric Patterns ⛔

The #1 cause of "fake-looking" tiles. Forbidden in repeatable terrain:

❌ Anti-pattern	✅ Replace with
Centered cross / star / plus	Random off-center features
4 equal quadrants	Voronoi 8-15 irregular cells
Regular sine waves	Low-frequency value noise
Horizontal stripe layers	Diagonal/random color blobs
Symmetric corner motifs	Single asymmetric accent
Straight diagonal cracks	Random walk segments

Decorative tiles (e.g., tile_brick) may use geometric patterns, but only when explicitly designed as architecture, not as terrain.

3. Multi-Tier Color Distribution

Each pixel sampled by probability bucket:

• 70% main color (palette base)
• 15% dark accent (-1 palette step)
• 10% light accent (+1 palette step)
• 5% emphasis color (rare highlight/feature)

4. Low-Frequency Value Noise (Required)

For natural color variation, use value noise + cosine interpolation:

nodes = [[rng.uniform(-1, 1) for _ in range(gw)] for _ in range(gh)]
# CRITICAL: wrap edges for seamless tiling
for row in nodes: row[gw-1] = row[0]
nodes[gh-1] = list(nodes[0])
# Then cosine-lerp at each pixel

Recommended scales:

• Main blob: 8~16 px per node (large irregular regions)
• Detail: 3~6 px per node (subtle variation)
• Combine 2 octaves for richer texture

5. Seamless Tiling (4-Edge Wrap) ⛔

Tile must repeat without visible seams. Two enforcement methods:

• Modulo coordinates: img.putpixel((x % W, y % H), color)
• Wrap noise nodes: last row/col equals first
• Test: Place 2×2 instances side-by-side; no visible borders

6. Sparse Feature Points (≤ 1% of pixels)

Cracks, mineral veins, moss spots, water droplets, etc:

• Random-walk paths for cracks (short, intermittent, never straight)
• Scattered points (not clustered, not aligned)
• Total feature pixels ≤ 1% of canvas area
• Forbidden: Continuous straight lines crossing the tile

7. Low-Noise Visual Coherence

Terrain tiles must feel calm and continuous when shown full-screen:

• Noise rule: Avoid salt-and-pepper noise, snow-like white speckles, or evenly scattered bright dots.
• Highlight rule: White / near-white pixels are forbidden for ground and underground tiles unless explicitly requested; use warm ochre, muted gray, or one-step lighter palette colors instead.
• Continuity rule: Prefer broad, low-frequency color regions and short soft bands over per-pixel randomness.
• Pixel style rule: Keep hard pixel edges and readable clusters; do not blur, smear, or use anti-aliased gradients.
• Ink-gongbi rule: For this project, terrain should stay in restrained ink-and-gongbi tones: muted earth, sand, jade, water, gray ink; no neon colors or high-contrast glitter.

8. Edge Color Continuity

Edges within ±1 palette step of interior. Avoid:

• ❌ Black border line around the tile (creates grid effect when tiled)
• ❌ Drastically different color in 1-pixel border
• ✅ Same color distribution on edges as interior

9. Mandatory Validation

Before declaring done, verify:

• Place 4 copies in 2×2 grid → no seams visible
• Compare with adjacent tiles (e.g., grass + dirt) → color transition feels natural
• No symmetric features (rotate 90° / flip → looks different)
• Quantized to exact palette (palette_analyzer.py)
• Feature density ≤ 1%
• No visible white speckle noise when viewed at game fullscreen scale

Reference Implementation

See ${SKILL_DIR}/scripts/gen_tiles_reference.py for working examples of:

• Voronoi stone path with wrap-distance metric
• Two-octave noise jade with cosine interpolation
• Random-walk cracks for clay/bedrock
• Probability-bucketed multi-tier color distribution

---

Step 7: Post-processing & Export

🚧 GATE: Step 6 complete, all assets pass quality check

One-command pipeline (recommended):

python ${SKILL_DIR}/scripts/run_pipeline.py <project_path>

Step-by-step (manual control):

# 1. Post-process assets (quantize, clean borders, index colors)
python ${SKILL_DIR}/scripts/finalize_assets.py <project_path> --all
# 2. Pack sprite sheets
python ${SKILL_DIR}/scripts/sprite_sheet.py <project_path>
# 3. Export final package
# Output:
#   exports/<project_name>_<timestamp>.zip
#   ├── sprites/           ← Individual PNGs
#   ├── sheets/            ← Packed sprite sheets
#   ├── palettes/          ← Palette files (GPL/PAL/ACT)
#   └── manifest.json      ← Asset manifest with metadata

Export formats:

Format	Description
Individual PNGs	One file per asset/animation frame
Sprite sheets	Packed grid with manifest
Palette files	GPL / PAL / ACT format
Asset manifest	JSON with size, palette, animation metadata

---

Role Switching Rules

Phase	Active Role	Reference File
Step 1-3	Coordinator	This file
Step 4	Strategist	references/strategist.md
Step 5	Image_Generator (optional)	references/image-generator.md
Step 6	Executor	references/executor-pixel.md
Step 7	Post-processor	This file + references/shared-standards.md

Switching protocol: Announce role switch with [Role Switch: <Role>] before starting the phase.