sprite-gen: How to Set It Up and Make Game Sprites From One Image

By Shah Rukh, software developer · October 2, 2026 · 8 min read

sprite-gen is an open-source Python tool that turns one character drawing into game-ready sprites: a transparent sprite sheet with a data file, or short transparent animation loops. This guide covers what it needs, what it costs, how to install it, the first commands to run, and the precautions to take before you start.

Read this first. The sprite-gen code is free, but it does not include an AI image model. To generate anything you must bring your own paid account: a ChatGPT subscription (through the Codex tool), a SuperGrok subscription, or an API key that is billed per use. The project also documents its install commands for a Mac or Linux style terminal only. It does not give Windows steps.

What sprite-gen is

A sprite is a small picture of a game character. A sprite sheet or atlas is one image file that holds many poses of that character, so a game engine can play them as animation.

If you ask an AI image model for a sprite sheet directly, the project says you usually get a character whose face changes in every frame, a background that will not come off cleanly, and poses that are not lined up. sprite-gen is built to fix that. You give it one base image. It asks the AI model for one row of poses at a time, removes the coloured background, cuts each pose into a clean transparent frame, and builds the final atlas.

It works in two ways: as a command-line program (the command is sprite-gen), and as a “skill” that a coding assistant such as Codex or Claude can run for you when you ask for sprites in plain words.

What you need

• Python 3.11 or newer. Python 3.10 is no longer supported. The project’s own automated tests run only on Python 3.14.
• Git, to download the repository.
• One base image of your character, for example base.png.
• An AI account for generation (see the table below).
• For the video route only: the programs ffmpeg and img2webp, plus a Grok login or an XAI_API_KEY.

The install itself only adds two Python packages, Pillow and NumPy. You do not need a graphics card, because the AI work happens on the provider’s servers.

The repository does not list prices. Check each provider’s own pricing page before you start. The tools in groups C, D and E work on images you already have, so they do not need an AI account.

Precautions before you install

1. Use the real repository. Download only from github.com/aldegad/sprite-gen. It is an independent project by one developer, not made by OpenAI, xAI or Anthropic.
2. Your images leave your computer. The base image and prompts are uploaded to the provider you choose. Don’t upload artwork you are not allowed to share.
3. Only use art you have the rights to. Start from your own drawing or one you are licensed to use. Don’t feed in another game’s characters. Also read your provider’s terms on using generated images in a commercial game.
4. Watch your quota and credit. The gen-set command generates every state row, four at a time, so one run makes many requests. The project describes the Grok Imagine quota as a weekly allowance. If you set an API key, usage is charged to that key.
5. Keep keys and logins private. The Grok login is stored in ~/.grok/auth.json. sprite-gen only reads it. Your saved choices go in preferences.json inside ~/.config/sprite-gen/; the project says no keys or tokens are saved there. Never put an API key in a file you upload to GitHub.
6. Use a separate output folder. Point each run at its own folder and keep a copy of your original image. If a coding assistant runs the tool for you, read what it plans to do before you approve it.

How to install sprite-gen on Mac

These are the project’s own quickstart commands. They also work on Linux.

1. Press Cmd + Space, type Terminal and press Enter.
2. Download the repository and go into its folder:

   git clone https://github.com/aldegad/sprite-gen
   cd sprite-gen

3. Create a virtual environment (a private Python folder for this project), switch it on, and install:

   python3 -m venv .venv && source .venv/bin/activate
   pip install -e .

4. Check that it works. This prints the list of commands, grouped by the pipelines above:

   sprite-gen --help

The project says this virtual environment is the only supported way to run it. Each time you open a new Terminal window, go to the folder and run source .venv/bin/activate again before using sprite-gen.

How to install sprite-gen on Windows

The project does not document Windows steps. Its quickstart is written for a Mac or Linux shell, and its automated tests run on Linux only. The code does contain Windows-specific fixes contributed by users, so it may work, but you are on your own if it does not.

The safest route is to run the Mac commands above inside a Linux environment on Windows, such as WSL. If you try plain Windows instead, note that the source .venv/bin/activate line is a Mac and Linux command and will not work as written.

Install it as a skill for Codex

If you use the Codex coding assistant, the project gives this one command to add sprite-gen as a skill:

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo aldegad/sprite-gen --path . --name sprite-gen

After that you can simply ask for sprites or an image. The project says the assistant checks your access, asks only for the missing choices (which provider, which motion method), runs the pipeline and delivers the files.

Make your first sprite atlas

Replace <run> with a new folder name and <id> with a short name for your character.

sprite-gen prepare --out-dir <run> --character-id <id> --base-image base.png
sprite-gen gen-set --run-dir <run> --provider codex
sprite-gen extract --run-dir <run>
sprite-gen compose-atlas --run-dir <run>

1. prepare sets up the run folder with the request, guides and prompts.
2. gen-set asks the AI provider for every state row. This is the step that uses your subscription.
3. extract removes the coloured background and saves transparent frames.
4. compose-atlas writes sprite-sheet-alpha.png and manifest.json.

An optional fifth command opens a review page in your browser, where you can compare frames, reject bad ones, nudge positions and watch the loop before you build the final sheet:

sprite-gen curation --run-dir <run>

This page is served from your own computer at 127.0.0.1 on a free port chosen at each launch, so it is not open to other devices by default.

Useful features

• Animation loops from video. This needs ffmpeg, img2webp and Grok access:

  sprite-gen video-set --base side=still.png --states idle,walk,run,jump,attack --out-dir set/

  The file set/table.md lists every result.
• Cut out an existing image. No AI account needed:

  sprite-gen cutout icon.png --white-check

• Colour variants. sprite-gen recolor makes recoloured copies of a finished sheet from a palette map, without generating again.
• Engine export. sprite-gen export-aseprite --run-dir <run> writes Aseprite JSON for Phaser and Flame.
• Change the default provider. Set SPRITE_GEN_DEFAULT_PROVIDER to codex or grok. If Codex is the default but is not available, the tool switches to Grok and prints a notice.

Be realistic about results. The project itself says walk and run cycles stay experimental unless they pass its motion check, and that its left or right facing detector can be wrong even when it reports high confidence. Review the frames yourself.

Update and uninstall

The project does not document an update or uninstall command. One thing it does say: changing the project files does not upgrade a virtual environment that is already installed, and running pip install -e . again refreshes the sprite-gen command in an older one.

Common problems

Some of the project’s documentation pages are written in Korean, so you may need a translator for the deeper guides. The README is available in English.

This guide is based on the project’s repository as it was on October 2, 2026 (version 2.17.0, Apache-2.0 licence). The project changes often, so if a step looks different, follow the README on GitHub. ToolsCloset is not connected to the project, or to OpenAI, xAI or Anthropic.

More AI tips

Related tools