Traditional Chinese README: README.zh-TW.md

Turn natural-language prompts into game-ready 2D sprites with Codex.

Plan with an agent. Render with built-in image generation. Export clean transparent sheets and GIFs.

Showcase

Text To Sprite

Spell Bundle / Cast, Projectile, Impact

Prompt:

Use  $generate2dsprite to create a fire mage cast animation with projectile and impact.

Game Sprite / Four-Direction Walk

Prompt:

Use Generate 2D Sprite to create a top-down 4x4 player_sheet for a wandering young samurai with a red scarf and short katana.
Make a four-direction walk sprite sheet with 4 frames per direction.
Row order: down, left, right, up.
Same character, same outfit, same proportions, same pixel scale in every frame.
Solid #FF00FF background.
Each frame must fit fully inside its cell, with clear margin on all sides.
Retro JRPG pixel-art style.

Reference To Sprite

Codex-first 2D sprite generation skill for game-ready pixel assets.

This repository currently ships one generic skill: skills/generate2dsprite.

Codex is the primary target because Codex already has built-in image generation. That lets one agent handle the full loop:

1. Plan the asset.
2. Generate the raw sprite sheet.
3. Run deterministic local post-processing for chroma-key cleanup, frame extraction, alignment, QC, and transparent PNG/GIF export.

The current focus is self-contained 2D assets, not full game packs.

What It Can Generate

• Creatures
• Characters
• Players and NPCs
• Spell casts
• Projectiles
• Impacts and explosions
• FX sheets
• Small bundles such as unit_bundle, spell_bundle, and combat_bundle

Why Codex First

This repo is intentionally Codex-first because Codex can generate images directly inside the same workflow.

That gives you a much cleaner pipeline:

• No separate image API wiring
• No external sprite backend
• No extra prompt-builder service
• One agent decides the asset plan
• One local processor handles deterministic cleanup and export

The script is not the creative brain. The agent decides:

• Asset type
• Action type
• Bundle shape
• Sheet layout
• Frame count
• Alignment strategy
• Whether detached effects should be kept or filtered

The Python script only performs deterministic pixel operations.

Repository Layout

agent-sprite-forge/
  README.md
  README.zh-TW.md
  requirements.txt
  src/
  skills/
    generate2dsprite/
      SKILL.md
      agents/
        openai.yaml
      references/
        modes.md
        prompt-rules.md
      scripts/
        generate2dsprite.py

Install

Option 1: Windows PowerShell

Clone the repo, install the local processor dependencies, then copy the skill into your Codex skills directory:

git clone https://github.com/0x0funky/agent-sprite-forge.git
cd .\agent-sprite-forge
python -m pip install -r .\requirements.txt
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex\skills" | Out-Null
Copy-Item -Recurse -Force `
  ".\skills\generate2dsprite" `
  "$env:USERPROFILE\.codex\skills\generate2dsprite"

Option 2: macOS / Linux

git clone https://github.com/0x0funky/agent-sprite-forge.git
cd ./agent-sprite-forge
python3 -m pip install -r ./requirements.txt
mkdir -p ~/.codex/skills
cp -R ./skills/generate2dsprite ~/.codex/skills/generate2dsprite

Start a new Codex session after installation so the skill is loaded cleanly.

Python Requirements

The local post-processor depends on:

• Pillow
• numpy

They are listed in requirements.txt. Codex handles image generation itself, but these Python packages are still needed for:

• Magenta background removal
• Frame splitting
• Bounding-box extraction
• Alignment and rescaling
• Transparent GIF and PNG export

Suggested Prompts

Basic

Use  $generate2dsprite to create a 3x3 idle for an ultimate earth titan.

Use  $generate2dsprite to create a side-view lightning knight attack animation.

Use  $generate2dsprite to create a late-Sengoku player_sheet for a wandering fire swordsman.

Spell / FX

Use  $generate2dsprite to create a wizard spell bundle with cast, projectile, and impact sprites.

Use  $generate2dsprite to create a fireball projectile loop and a matching explosion impact.

Use  $generate2dsprite to create a side-view summon entrance effect for a thunder wolf spirit.

Character / Monster Examples

Use  $generate2dsprite to create Omegamon attack and right-move animation assets.

Use  $generate2dsprite to create a golden divine boar 2x2 idle animation.

Use  $generate2dsprite to create a Naruto-style rasengan cast sheet in 2x3.

What You Get

For a typical sheet output:

• raw-sheet.png
• raw-sheet-clean.png
• sheet-transparent.png
• Frame PNGs
• animation.gif
• prompt-used.txt
• pipeline-meta.json

For player walk sheets, you also get direction strips and per-direction GIFs.

Notes

• Best results come from prompts that clearly specify view, action, and the desired motion style.
• Large creatures often work better as 3x3 idle.
• Small spells and projectiles often work better as 1x4, 2x2, or 2x3.
• For commercial projects, prefer original characters or IP that you control.

License

MIT. See LICENSE.