User Manual

Getting Started

1. Launch TextureAtlas Toolbox.
2. On first launch a setup wizard guides you through language, update preferences, and theme selection.
3. Choose your workflow:
   • Extract tab (default) — Convert existing atlases into animations (GIF/WebP/APNG) and individual frames.
   • Generate tab — Build new atlases from loose frame images.
   • Editor tab — Manually align sprites and apply offset fixes.
4. Configure your settings and enjoy!

First Launch Wizard

The first time you open the app (or after a major upgrade) a three-step wizard appears:

1. Language — Choose your UI language. A quality indicator shows whether the translation is native, reviewed, or machine-generated.
2. What's New — Overview of the latest changes and an option to enable automatic update checks.
3. Theme — Pick a theme family, light/dark/AMOLED variant, and accent colour. A live preview panel shows sample widgets that update in real-time as you change options.

Fresh installs default to the Clean family with Light or Dark automatically detected from your operating system colour scheme.

Themes and Appearance

TextureAtlas Toolbox ships with five theme families, each available in Light, Dark, and AMOLED variants (15 combinations):

You can also choose from eight accent colour presets (Default, Blue, Purple, Green, Red, Orange, Pink, Teal). All theme settings are available in Options → Theme and persist between sessions.

Extract Tab

The Extract tab handles batch processing of existing texture atlases into animations and frames.

Main Components

• Atlas List (left panel) — Shows all queued texture atlas files with context menus for file management.
• Animation List (second panel) — Displays animations detected in the selected texture atlas.
• Input/Output Directories — Select source folder and destination for exports.
• Animation Export Group — Configure animated output settings (GIF, WebP, APNG).
• Frame Export Group — Configure individual frame output settings.

Animation Export Settings

Frame Export Settings

Additional Settings

Control Buttons

• Start Process — Begin extraction with current settings.
• Reset — Clear all loaded files from the queue.
• Advanced Filename — Open find/replace rules for output naming.
• Override Settings — Per-texture atlas or per-animation overrides.

Generate Tab

The Generate tab creates new texture atlases from individual frame images or from existing texture atlases.

Main Components

• Animation Tree — Hierarchical view of animation groups and their frames. Supports drag-and-drop reordering.
• Frame Input Buttons — Add individual files, directories, or import from existing atlases.
• Packing Options — Algorithm selection, padding, power-of-two sizing.
• Output Settings — Metadata format and image compression.

Input Buttons

Packing Algorithms

It's recommended to use Automatic (Best Fit) for the algorithm and Auto (Best Result) for the heuristic; the app will test all combinations and pick the most efficient result for your specific atlas.

Atlas Options

GPU Texture Compression

When a game-engine metadata format is selected, additional GPU compression controls appear:

Editor Tab

The Editor tab provides an interactive alignment workspace for manual sprite adjustments.

Main Components

• Animation Tree — Lists loaded animations and their individual frames.
• Alignment Canvas — Interactive preview with zoom, pan, and drag support.
• Offset Controls — Manual X/Y offset entry with apply-all functionality.
• Canvas Size — Adjustable virtual canvas dimensions (multiples of 256).
• Ghost Overlay — Semi-transparent reference frame for alignment comparison.

Canvas Controls

Features

• Ghost Overlays — Show a semi-transparent reference frame for alignment.
• Snap to Grid — Enable snapping with configurable step size.
• Origin Mode — Choose between Center or Top-Left origin for offset calculations.
• Detachable Canvas — Pop out the canvas to a separate window for more space.
• Batch Offset Application — Apply the current offset to all frames in an animation.
• Save Overrides — Store alignment data for use in the Extract tab.
• Export Composite — Create combined animations from multiple sources.

Loading Texture Atlases

Image File Support

The application supports all common image formats:

• PNG (recommended for sprites with transparency)
• AVIF, BMP, DDS, JPEG/JPG, KTX2, TGA, TIFF, WebP

Metadata Formats

TextureAtlas Toolbox automatically detects and parses many texture atlas formats. For detailed technical specifications, see the Format Reference.

Metadata-Free Images

For texture atlases without metadata files, the application can extract sprites using:

• Color keying — Remove solid background colors automatically
• Grid-based slicing — Divide the image into equal-sized cells

Loading Process

1. Click Select input directory or drag files directly onto the texture atlas list.
2. The application scans for matching metadata files automatically.
3. Select a texture atlas from the left list to view its animations.
4. Choose animations to export or select all.

Basic Animation Export

1. Load your texture atlas(es) using Select input directory or drag-and-drop.
2. Choose an output directory for the exported files.
3. Select the texture atlas from the left panel.
4. Review detected animations in the second panel.
5. Configure export settings:
   • Enable/disable Animation export and Frame export groups as needed.
   • Set your desired format, frame rate, and scale.
6. Click Start Process to begin.

Output Structure

output_directory/
├── texture_atlas_name/
│   ├── animation_name.gif
│   ├── animation_name_frames/
│   │   ├── frame_001.png
│   │   ├── frame_002.png
│   │   └── ...
│   └── ...

Generating New Atlases

1. Switch to the Generate tab.
2. Add your frame images using one of the input methods:
   • Add Files — Select individual images.
   • Add Directory — Import entire folder (subfolders become separate animations).
   • Add Existing Atlas — Import and re-pack an existing atlas.
3. Organize frames in the animation tree (drag to reorder).
4. Select a packing algorithm (or use Automatic).
5. Configure atlas options:
   • Padding: Space between frames (2px recommended to prevent bleeding).
   • Power of Two: Enable for older GPU compatibility.
   • Allow Rotation: Enable for tighter packing (format-dependent).
6. Choose your output metadata format.
7. Click Generate and specify the output location.

Rotation and Flip Support

Advanced Settings

Cropping Options

Resampling Methods

Filename Formatting

Add custom Prefix and Suffix text to output names. Use the Advanced filename button for find/replace rules with regex support.

Override Settings

Apply custom settings to specific texture atlases or animations:

• Override texture atlas Settings — Right-click a texture atlas or use the button.
• Override Animation Settings — Right-click an animation for per-animation overrides.

Overrides persist across sessions and take precedence over global settings.

Output Formats

Animation Formats

Frame Export Formats

Frame Selection Options

Generated Atlas Metadata Formats

Tips and Best Practices

File Organization

• Keep atlas and metadata together — Store the image and its metadata file in the same directory for automatic detection.
• Use consistent naming — The app matches files by base name (e.g., player.png + player.xml).
• Organize by project — Create separate input folders for different projects or game states.

Performance

• Close other applications when processing Adobe Animate spritemaps (memory-intensive).
• Use fewer worker threads if you encounter memory issues on systems with limited RAM.
• SSD storage significantly speeds up batch processing.

Quality Tips

• Use Nearest resampling for pixel art to preserve sharp edges.
• Use Lanczos for photographic or anti-aliased content.
• Scale in the atlas generator rather than at runtime for better quality.
• Use 2px padding minimum to prevent texture bleeding; increase to 4px if applying filters.
• Power-of-two dimensions improve GPU performance on older hardware.

Common Issues