| 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:
- 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
- BLOCKING = HARD STOP — Steps marked ⛔ BLOCKING require a full stop; the AI MUST wait for an explicit user response before proceeding
- NO CROSS-PHASE BUNDLING — Cross-phase bundling is FORBIDDEN
- GATE BEFORE ENTRY — Each Step has prerequisites (🚧 GATE) listed at the top; these MUST be verified before starting that Step
- NO SPECULATIVE EXECUTION — "Pre-preparing" content for subsequent Steps is FORBIDDEN
- 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
- SEQUENTIAL ASSET GENERATION — Assets MUST be generated sequentially in one continuous pass
- 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 narrativespec_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:
- Visual Construction Phase: Generate all pixel art PNG assets sequentially
- Quality Check Gate: Run
asset_validator.py on all assets
- 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)]
for row in nodes: row[gw-1] = row[0]
nodes[gh-1] = list(nodes[0])
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:
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):
python ${SKILL_DIR}/scripts/finalize_assets.py <project_path> --all
python ${SKILL_DIR}/scripts/sprite_sheet.py <project_path>
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.
