Sprite Sheet Export Format Guide
The sprite sheet itself is just a PNG. The real power comes from metadata file that tells your game engine where each frame is located and what to call it. Pick wrong format and you get coordinate mismatch, frame name errors, or need to rewrite parsers manually. This guide shows you exactly which format matches which engine and how each structure works.
Why Format Matters
Your exported sprite sheet ZIP contains two files: the PNG image and a metadata file. Every engine expects metadata in different structure. Some expect frame names as dictionary keys, others as ordered arrays. Some need nested trim data, others ignore it. If you pick the wrong export format, your engine either fails to load or requires manual parsing work to fix. The good news is Sprite Sheet Maker supports all major formats, so you can export once and switch engines without repacking.
Image file is universal
The PNG sprite sheet itself is the same regardless of export format. You get one high-quality image with all frames arranged in your chosen grid or smart layout.
Metadata determines compatibility
The companion file contains frame coordinates (x, y, width, height), frame names, and optional properties like trimmed or rotated. This is what differentiates formats.
Export Format Compatibility Map
JSON Hash Format
JSON Hash format uses frame names as object keys. This is the standard for Phaser 3 and works well with engines that want direct name lookups. When you export JSON Hash, you get a dictionary where each key is the frame filename (without extension) and value contains rectangle coordinates, trimmed status, and sprite source size.
Structure
Each frame is stored as a top-level key in the JSON object. The value includes x, y position within the sprite sheet, width, height, and optional isTrimmed flag.
Best for Phaser
Phaser 3's loader expects JSON Hash format by default. You drop both PNG and JSON into your assets folder, then load with this.scene.load.atlas('key', 'image.png', 'data.json'). Phaser handles the rest.
Fast frame access
Hash format provides O(1) lookup by frame name. When your code knows the exact frame name (idle_0001, walk_left_0005), you access it directly without iterating through an array.
JSON Array Format
JSON Array format stores frames as a sequential list. Pixi.js and other engines prefer ordered arrays when they want to access frames by index or when they build their own frame name mapping internally.
Structure
Frames are stored in an array under the frames key. Each array element contains the same rectangle data plus the filename string. Order matches your uploaded or generated frame sequence.
Best for Pixi.js
Pixi.js works naturally with JSON Array format. After loading the spritesheet with PIXI.Spritesheet.from(), you reference frames by name string just like with JSON Hash, but the parser is optimized for array structure.
Index-based access
While you can still use frame names, array format gives you predictable ordering. This helps when your game logic iterates through frames sequentially (animations with fixed step order).
XML TextureAtlas Format
XML TextureAtlas is a standard from TexturePacker and works natively with Unity and Godot. It stores frames as SubTexture elements within a root TextureAtlas element. Unity imports this automatically when you place both PNG and XML in your Resources folder.
Structure
The XML root is TextureAtlas with imagePath attribute. Each SubTexture has name, x, y, width, height attributes. Optionally includes frameX, frameY, frameWidth, frameHeight for untrimmed source data.
Best for Unity
Unity 2D sprite editor expects XML TextureAtlas format. Import the PNG, Unity automatically finds the XML, and you get individual sprite slices named correctly. No custom parser needed.
Best for Godot
Godot 4's AtlasTexture uses XML format. You reference the XML in an AtlasTexture node, and Godot loads all SubTextures as named frames. AnimatedSprite2D then plays those as animations.
Engine-native integration
Because XML TextureAtlas is an industry standard, both Unity and Godot provide import wizards that auto-generate sprite assets. You do not write XML parsing code.
CSS Sprites Format
CSS sprites format outputs a stylesheet with background-position rules for each frame. This is ideal for web animations, UI icons, and CSS-based games where you do not need a game engine at all.
Structure
The CSS file defines a class for each frame name with background-image set to your sprite sheet URL and background-position set to the correct pixel offset. Negative values shift the background image left or up.
Best for web animations
Use CSS sprites for hover states, button animations, or simple character animations in pure web projects. Add the class to an element, then toggle or animate background-position with CSS transitions.
No JavaScript required
Basic sprite playback works with only HTML and CSS. You do not need to load a sprite sheet via JavaScript or parse JSON. Just apply the frame class and optionally animate position.
Format Selection Workflow
Common Format Problems
Most sprite sheet import errors are format mismatches. Your engine expects one structure but you exported another. These are the warning signs and fixes.
Frame name not found error
This happens when your code references frame walk_left_0001 but JSON uses walkLeft0001. Check your exported metadata file and update frame name in code or regenerate sprite sheet with correct naming convention.
Coordinates do not match visual
If your sprite appears offset or cropped, you may have exported JSON but loaded it as XML (or vice versa) in an engine that defaults to a different parser. Ensure your import code matches the export format.
Animations play wrong frames
When frames play out of order, the export format may not preserve your intended sequence. Check if your engine expects hash format where order is not guaranteed, then switch to array format if your game relies on sequential frame access.
Engine cannot load metadata
Unity or Godot failing to load usually means missing XML file or wrong XML structure. Verify your export was XML TextureAtlas and that both PNG and XML share the same base filename.
Sprite Sheet Export Format FAQ
Export in the Right Format
Create your sprite sheet once in Sprite Sheet Maker. Select the export format that matches your game engine, and import directly without writing custom parsers or fixing coordinate mismatches.
Last updated: Apr 27, 2026 · Maintained by Sprite Sheet Maker Team · v2026.4