Godot Sprite Sheet Importer (Free Add-on)
A free add-on for Godot 4 that turns a sprite sheet and its JSON into a ready SpriteFrames resource for AnimatedSprite2D. Right click the JSON, pick Create SpriteFrames, done. It reads the JSON SpritePilot exports and the TexturePacker and Aseprite formats other tools write.
Download
- Download the add-on (version 1.0.0, ZIP, 9 KB)
- Source code on GitHub, MIT licence
- Needs Godot 4.4 or newer. We test it on Godot 4.7.
Why we made it
Setting up an AnimatedSprite2D by hand gets old fast. You make a SpriteFrames, slice the sheet, drag frames into each animation, then fix the timing. If the sheet already comes with a JSON file that says where every frame is and which frames belong to which animation, all of that is busywork.
SpritePilot could already export a SpriteFrames file, but it only works with the sheet in the root of your project, and it can’t carry a tag’s reverse or ping-pong direction. The add-on reads the JSON inside Godot instead, so neither limit applies.
Installing
Unzip the download and copy the addons/spritepilot_importer folder into your project’s addons folder. Then open Project, Project Settings, Plugins and turn on SpritePilot Importer.
Using it
Keep the sheet and its JSON in the same folder, for example res://characters/hero.png and res://characters/hero.json. In the FileSystem dock, right click hero.json and choose Create SpriteFrames (SpritePilot). A hero.tres file appears next to it. Drag it onto your AnimatedSprite2D’s Sprite Frames property and press play.
To do several sheets at once, select their JSON files and run Project, Tools, Create SpriteFrames from selected JSON.
Formats it reads
- SpritePilot Godot JSON (sprite-sheet.godot.json)
- TexturePacker JSON, hash or array, which is also what SpritePilot’s TexturePacker and Phaser options write
- Aseprite JSON, hash or array, the only one of these that stores how long each frame lasts
What ends up in the file
Every frame points at your sheet as an AtlasTexture, so the sheet stays one image with its own import settings. Nothing is copied or cut up.
If transparent edges were trimmed off the frames, each one gets back the margin it lost, so it keeps its original size and the sprite doesn’t wobble from frame to frame.
Each animation tag becomes an animation with the same name. Reverse tags play backwards, and ping-pong tags go there and back without doubling up the end frames. With no tags you get one animation called default with every frame in it.
Aseprite JSON keeps its frame times: a frame held for 300 ms stays three times longer than a 100 ms one. The other formats have no timing, so every frame gets the same length, which you can change in the SpriteFrames panel.
Re-export the sheet and convert again whenever the art changes. The loop and speed you set on each animation in the SpriteFrames panel are kept.
Making the sheet in SpritePilot
Cut an existing sheet into frames with the Sprite Sheet Cutter, pack loose images with the Sprite Sheet Maker, or turn a GIF into frames with GIF to Sprite Sheet. Then open Export & Download, pick Aseprite JSON or Godot JSON, and add an Animation Tag for each animation. The Godot export guide walks through those settings.
Limits
Rotated frames, a TexturePacker packing option, aren’t supported, so export without rotation. Multi page atlases aren’t supported either: it’s one sheet per JSON.
Found a bug, or a sprite sheet format it should read? Tell us on the contact page or open an issue on GitHub.