SpriteTool - Game Developer Tool Suite

A powerful suite of game development tools providing a complete solution for Sprite and image editing.

🎯 Feature Overview

SpriteTool is an integrated web application that combines multiple professional-grade tools into one:

📏 Grid Tool

Used to define regular grid areas on an image and perform batch selections.

Key Features:

• Automatically generate grids based on rows and columns (e.g., 64x95 cells).
• Supports drag-to-pan and scroll-to-zoom.
• Cmd+Click to select any rectangular area.
• Real-time calculation of total selected cells.
• Export or edit area definitions in JSON format.
• Supports undo and clear operations.
• Batch export as a single PNG image.

Use Cases: Tilemap creation, Sprite Sheet splitting, map editing.

---

🎯 Sprite Picker

Quickly select and extract individual sprites from complex Sprite Sheets.

Key Features:

• Free-hand selection box (supports any size and position).
• Unified Sprite dimension settings (width/height).
• Set column count for export with automatic layout.
• Real-time preview of selected Sprites.
• Click preview images to remove unwanted Sprites.
• Export as optimized PNG images.

Use Cases: Character animation decomposition, prop extraction, UI asset organization.

---

✨ Shiny Monster Maker

Professional-grade "shiny" variant adjustment using HSV color space.

Key Features:

• Hue Shift - 0~180° color wheel rotation.
• Saturation - 0~2x multiplier adjustment.
• Brightness - 0~2x multiplier adjustment.
• Saturation Mask - Protects gray/black pixels.
• Real-time effect preview.
• Supports multiple image input formats.
• One-click download of the result.

Use Cases: Shiny variant creation, character skin adjustment, thematic color swapping.

---

🔄 Sprite Flipper

Quickly perform horizontal flipping (mirroring) for each animation cell in a Sprite Sheet.

Key Features:

• Precisely split cells based on configured row and column counts.
• Batch horizontal flip for all cells.
• Real-time preview of both original and result images.
• Preserves Alpha transparency channel.
• One-click download of the complete flipped Sprite Sheet.

Use Cases: Creating mirrored animations, symmetrical Tilemap variants, character action adjustments.

---

🧩 Sprite Merger

Precisely merge source Sprite into the target cell of a main Sprite Sheet.

Key Features:

• Upload main image and source sprite.
• Set main image row/column counts with automatic cell size calculation.
• Specify target cell coordinates (Column / Row).
• Automatic alignment and merge of source sprite to target position.
• Preserves transparency and color information.
• Real-time preview of merge result.
• One-click download of completed image.

Use Cases: Character variant assembly, Tilemap element composition, Sprite Sheet content updates.

---

✂️ Inset Crop Tool

Remove Chroma Key background and perform intelligent inset cropping and enlargement on Sprite Sheets.

Key Features:

• Color Removal - Custom chroma key (default #ff00ff pink) and threshold adjustment.
• Real-time Preview - Instantly view background removal effects while adjusting threshold.
• Preview Background Customization - Change preview background color to check edge precision (inspection only, does not affect export).
• Inset Guide Lines - Display dashed lines showing each cell's inset boundary (pink dashed outline) for visual verification of inset effects.
• Coordinate Offset - Support for X/Y axis offset adjustment to handle misaligned grids.
• Smart Cropping - Precisely divide cells based on rows/columns and inset distance.
• Enlarge After Crop - Automatically enlarge back to original cell size after inset cropping.
• Batch Export - Export individual cell PNGs + combined full image.
• ZIP Archive - Download all results in a single ZIP package.

Use Cases: Sprite Sheet background removal, pixel art standardization, animation frame sequence optimization.

---

📦 Sprite Splitter

The simplest tool to split a Sprite Sheet into grid cells and package them into a ZIP file.

Key Features:

• Automatically calculates cell size based on row and column counts.
• Real-time preview of grid split lines.
• One-click packaging of all cells into a ZIP archive for download.
• Pixel-art optimized rendering (maintains sharpness).

Use Cases: Quick decomposition of asset packs, animation sequence export.

---

🗂️ Folder Sprite Builder

Select a folder, then auto-scale and merge images into a sprite sheet with filename-based ordering.

Key Features:

• Load all images from a selected folder at once.
• Input Columns and total output width to auto-calculate cell width.
• Keep aspect ratio while scaling images and center them in each cell.
• Automatic row wrapping (including incomplete last row).
• Output order uses natural filename sort (e.g., 1, 2, 10).
• Files with identical names are stabilized using relative-path tie-break sorting.
• One-click PNG export and download.

Use Cases: Batch asset organization, folder-to-sprite-sheet pipelines, animation atlas packing.

---

🚀 Quick Start

Prerequisites

• Python 3.8+
• FastAPI
• Pillow (PIL)
• OpenCV (cv2)
• Uvicorn
• Starlette

Install Dependencies

pip install fastapi uvicorn pillow opencv-python starlette

Run Application

python tool.py

The application will start at http://localhost:8000

Visit the home page to see all available tools, or access them directly:

• Grid Tool: http://localhost:8000/grid/
• Sprite Picker: http://localhost:8000/picker/
• Shiny Maker: http://localhost:8000/shiny/
• Sprite Flipper: http://localhost:8000/flipper/
• Sprite Merger: http://localhost:8000/merger/
• Folder Sprite Builder: http://localhost:8000/folder-builder/
• Inset Crop Tool: http://localhost:8000/inset/
• Sprite Splitter: http://localhost:8000/splitter/

📂 Project Structure

SpriteTool/
├── tool.py                          # Main entry point (FastAPI aggregation)
├── sprite_tool_fullstack.py         # Grid Tool sub-app
├── sprite_webtool.py                # Sprite Picker sub-app
├── shiny_maker.py                   # Shiny Monster Maker sub-app
├── rotate_webtool.py                # Sprite Flipper sub-app
├── rotate.py                        # Flipper core processing logic
├── sprite_merger.py                 # Sprite Merger sub-app
├── folder_sprite_builder.py         # Folder Sprite Builder sub-app
├── inset_crop_tool.py               # Inset Crop Tool sub-app
├── sprite_splitter.py               # Sprite Splitter sub-app
├── remove_pink_background.py        # Color removal tool (standalone use)
├── output/                          # Grid Tool export directory
├── shiny_output/                    # Shiny Maker export directory
└── README.md                        # This file

---

🎮 User Guide

Grid Tool Workflow

1. Upload Image - Select the Sprite Sheet to cut.
2. Set Grid - Enter row and column counts (e.g., 64x95).
3. Select Areas
   • Drag to pan the image.
   • Cmd+Click to select rectangular areas.
   • Or modify coordinates directly in the JSON editor below.
4. Export - Set output columns and name, then click Export.

Sprite Picker Workflow

1. Upload Sheet - Select an image containing multiple Sprites.
2. Adjust Settings
   • Set uniform Sprite width and height.
   • Set the number of columns for the exported row.
3. Select Sprites - Draw boxes on the canvas to select Sprites to extract.
4. Check Preview - View thumbnail previews on the left.
5. Remove Errors - Click a preview image to remove unwanted Sprites.
6. Export - Enter a filename and click Export Image.

Shiny Maker Workflow

1. Upload Original Image - Select the image to recolor.
2. Adjust Parameters
   • Drag Hue Shift slider to change tone.
   • Adjust Saturation multiplier.
   • Adjust Brightness multiplier.
   • Set Saturation Mask to protect neutral colors.
3. Real-time Preview - View the effect instantly on the right.
4. Download - Click "Download" once satisfied.

Sprite Flipper Workflow

1. Upload Image - Select the Sprite Sheet to flip.
2. Set Partition - Enter the row and column counts (Cols/Rows).
3. Execute Flip - Click the button to process each cell automatically.
4. Check Result - View the flipped preview image below.
5. Download - Click the download button to get the result.

Sprite Merger Workflow

1. Upload Images - Select the main Sprite Sheet and source sprite.
2. Set Main Grid - Enter the row and column counts for the main image.
3. Specify Target Position - Enter the target column and row indices (starting from 0).
4. Preview Merge - View the merge result preview.
5. Download - Click the download button to get the merged image.

Inset Crop Tool Workflow

1. Upload Sprite Sheet - Select an image with chroma key background.
2. Adjust Background Removal Settings
   • Choose or input the background color (e.g., #ff00ff).
   • Adjust Threshold slider and observe real-time preview on the right.
   • Confirm the background removal result.
3. Configure Crop Parameters
   • Enter grid row and column counts (Cols/Rows).
   • Adjust X/Y Offset to align the grid correctly.
   • Set inset distance (px) for all edges.
   • View calculated cell size and output count.
4. Confirm and Download
   • Click "Confirm and Download ZIP" button.
   • System executes: Remove background → Inset crop → Enlarge back → Package.
   • Download ZIP containing all individual cell PNGs + combined image.

Sprite Splitter Workflow

1. Upload Image - Select the Sprite Sheet to split.
2. Set Grid - Enter row and column counts; the preview will show blue split lines instantly.
3. Download - Click "Download ZIP" to get all individual cell files.

Folder Sprite Builder Workflow

1. Select Folder - Load all image files from a folder.
2. Set Output - Enter Columns and total width (px).
3. Confirm Ordering - Images are merged in natural filename order (path tie-break if duplicate names exist).
4. Export - Click "Export and Download" to get the merged PNG.

---

🛠️ Technical Architecture

Core Tech Stack

• Backend Framework: FastAPI (High-performance asynchronous web framework)
• Frontend Framework: Tailwind CSS (Utility-first CSS framework)
• Image Processing: Pillow + OpenCV
• Color Space: HSV color conversion and processing

System Design

Tool Entry (tool.py)

• Unified navigation bar middleware.
• Sub-app mounting mechanism.
• Home page information display.

Image Processing Pipeline

• Frontend drag/click interaction → Coordinate transmission.
• Backend Python image calculation → Binary output.
• Real-time preview + batch export.

---

📝 API Endpoints

Grid Tool

• GET /grid/ - Home page.
• POST /grid/upload - Upload image and generate preview.

Sprite Picker

• GET /picker/ - Home page.
• POST /picker/upload - Upload image.
• POST /picker/export - Export selected Sprites.

Shiny Maker

• GET /shiny/ - Home page.
• POST /shiny/process - Process shiny adjustment.
• GET /shiny/download - Download result.

Sprite Flipper

• GET /flipper/ - Home page.
• POST /flipper/flip - Execute sprite flipping process.

Sprite Merger

• GET /merger/ - Home page.
• POST /merger/merge - Execute sprite merge process.

Inset Crop Tool

• GET /inset/ - Home page.
• POST /inset/preview - Real-time background removal preview.
• POST /inset/process - Execute background removal + cropping + packaging.

Sprite Splitter

• GET /splitter/ - Home page.
• POST /splitter/process - Execute grid splitting and packaging.

---

🎨 UI/UX Features

• Dark Theme - Eye-friendly dark gray color scheme.
• Unified Navigation - Navigation bar is automatically injected into all tool pages via FastAPI middleware.
• Standardized Layout - Consistent wide-screen layout (Max-width 7xl) and header styling across all tools.
• Responsive Design - Optimized for desktop and tablets.
• Instant Preview - Lag-free visual feedback.
• Drag-and-Drop Interaction - Intuitive image manipulation.
• Touch-Friendly - Precise pixel-level selection.

---

📊 Common Use Cases

Indie Game Development

• Sprite Sheet cutting and optimization.
• Monster/character shiny variant creation.
• Animation frame sequence organization.

Art Workflow

• Tilemap asset preparation.
• UI atlas organization.
• Character skin variant production.

Resource Optimization

• Batch Sprite extraction.
• Unified size normalization.
• Reduction of resource file counts.

---

🔧 Troubleshooting

Problem: Image fails to upload

• Check image format (Supports PNG, JPG, GIF).
• Ensure file size is reasonable.

Problem: Exported image is blurry

• Confirm original image is in pixel art format.
• Check browser zoom level.

Problem: Color adjustment effect is suboptimal

• Adjust Saturation Mask value.
• Try different Hue Shift angles.

---

📄 License

Open-source project, free to use and modify.

---

👤 Contribution

Issues and Pull Requests are welcome!

---

Last Updated: May 2026
Version: 1.3.0