TexturePacker to Godot 4 — JSON Atlas to SpriteFrames
You have a sheet packed by TexturePacker, or by another packer that writes its JSON, and a Godot 4 project. Drop the PNG and the JSON together: every frame is read with its trim, frames are grouped into animations by name, and the export is a SpriteFrames .tres with an AnimatedSprite2D scene, the bundle format Godot 4.7.2 loaded and drew frame by frame in the verification runs. No editor plugin is involved.
A TexturePacker JSON data file (hash or array) lists every sprite by name with its rectangle on the PNG, its trim (spriteSourceSize, sourceSize), a rotated flag and optionally a pivot, but no animations and no timing. Drop the PNG and the JSON into Nerulio: frames are read with their trim, grouped into animations by name (walk_01, walk_02 → walk), and exported as a Godot 4 SpriteFrames .tres, an AnimatedSprite2D .tscn and a .png.import, with no editor plugin. Godot 4 only; that bundle format was loaded by Godot 4.7.2.
- Godot 4Verified· Godot 4.7.2
- Unity 6Verified· Unity 6000.5.3f1
- Phaser 3 / 4Verified· Phaser 3.90 + 4.2
- PixiJS 8Verified· PixiJS 8.21
- Aseprite JSONVerified· Phaser load.aseprite · PixiJS 8.21
- .asepriteVerified· Aseprite 1.3.18
- Spine / libGDXVerified· spine-canvas 4.2
- Starling / Sparrow XMLVerified· Phaser 4.2
- LÖVEVerified· LÖVE 11.5
- DefoldBuilt· Defold bob.jar 1.13.1
- GameMakerUNVERIFIED
- CSS spritesVerified· Chromium
- GIF / APNGDecoded· Pillow
What the TexturePacker file holds, and what Godot needs
TexturePacker's JSON is a list of sprites. For each one: frame (where the stored pixels are on the PNG), spriteSourceSize (where those pixels sat in the original image), sourceSize (the original size), rotated (the piece lies turned by 90°) and, if you set pivot points, a pivot from 0 to 1. meta.image names the PNG and meta.size gives its size. There is no frame duration and no animation list: animations exist only as a naming convention.
Godot 4 plays frame animation from a SpriteFrames resource on an AnimatedSprite2D. Each frame there is an AtlasTexture: region is the rectangle on the atlas and margin adds the trimmed border back, so a trimmed frame keeps its full size. AtlasTexture has atlas, region, margin and filter_clip but no rotation property, which is why rotated sprites have to be repacked.
Nerulio does not reuse TexturePacker's PNG as it is. It cuts every frame out with its trim, lets you name tags and set durations on the timeline, and packs a new page for Godot without rotation. The page layout may differ from TexturePacker's; the frame names stay.
- spriteSourceSize
- x, y, w, h of the stored pixels inside the original image.
- sourceSize
- Width and height of the original, untrimmed image.
- AtlasTexture margin
Rect2(left, top, width to add, height to add)that restores a trimmed frame.- Relative duration
- Godot's per-frame multiplier: 1.0 lasts 1 ÷ the animation speed.
Example: one trimmed frame from JSON to SpriteFrames
TexturePacker JSON Godot 4 SpriteFrames (.tres)
"run_0": { [sub_resource type="AtlasTexture" …]
"frame": {"x":…,"y":…,"w":18,"h":15}, region = Rect2(x, y, 18, 15) on the new page
"spriteSourceSize": {"x":10,"y":10,"w":18,"h":15},
"sourceSize": {"w":40,"h":29} } margin = Rect2(10, 10, 22, 14)
22 = 40 − 18, 14 = 29 − 15
filter_clip = true
names run_0 … run_5 → animation "run", 6 frames, 100 ms each (the JSON has no timing)
"speed": 10.0 (1000 / 100 ms) every frame "duration": 1.0
set run_5 to 250 ms in the Studio → run_5 "duration": 2.5 (250 / 100)The margin puts the 18 × 15 piece back 10 px from the left and top of a 40 × 29 frame, so Godot draws and measures the frame at its original size.
TexturePacker publish settings and what reaches Godot
| Setting in TexturePacker | What the JSON then contains | Result in the Godot 4 bundle |
|---|---|---|
| Data format JSON (Hash) or JSON (Array) | frames as an object keyed by name, or as a list with filename | Both are read; names are kept without the file extension |
| Trim mode Trim | trimmed: true, spriteSourceSize, sourceSize | AtlasTexture margin restores the full size |
| Trim mode Crop, flush position | A sourceSize equal to the cropped size | Frames arrive at the cropped size; the original canvas cannot be recovered |
| Allow rotation on | rotated: true for the turned sprites | Imported still turned and exported UNVERIFIED; repack with rotation off |
| Detect identical sprites | Several names point at one rectangle | Every name stays a frame; identical AtlasTextures are shared in the .tres |
| Pivot points | pivot {x, y} from 0 to 1 | Frame pivot; the node offset uses the first frame's pivot |
| Sprite names walk_01, walk_02 … | Names only | Animation walk, frames in natural order (2 before 10) |
What it does
- Hash and array JSON, trimmed frames included: spriteSourceSize and sourceSize become each frame's full canvas and offset.
- Animations from frame names: walk_01, walk_02 … become "walk", in natural order (2 before 10); the names themselves are kept.
- A pivot stored in the JSON is used; otherwise frames start with a bottom-centre pivot that you move with the pivot tool (P).
- TexturePacker JSON carries no timing, so every frame starts at 100 ms; set real durations per frame or per tag before exporting.
- The bundle: SpriteFrames .tres (AtlasTexture region + margin), an AnimatedSprite2D .tscn with Nearest filtering and the pivot as offset, and a .png.import with fix_alpha_border off.
How to do it
- Drop the PNG and its .json together (the JSON names its image in meta.image).
- Read the Import panel: frame count, how the animations were grouped, frames lying outside the image.
- Fix names, tags and timing on the Timeline and preview with Enter.
- Open Pack & Export, choose Godot 4 and export; this target never rotates frames.
- Copy the folder anywhere under res:// and drag the .tscn into a scene, or give the .tres to your own AnimatedSprite2D.
Files you get
| File | What it is for |
|---|---|
run.tres | SpriteFrames: one animation per tag with speed, loop and relative durations; AtlasTexture region, margin and filter_clip; metadata nerulio with pivots and boxes. |
run.tscn | An AnimatedSprite2D that uses the resource, with Nearest texture filter and the first frame's pivot as offset. |
run.png, run.png.import | The new page and its import settings: lossless, no mipmaps, Fix Alpha Border off. |
README-GODOT.md | The steps for this bundle. |
Import it into Godot 4
- Unzip and copy the whole folder under
res://, for exampleres://characters/run/; the.tresfinds the new PNG by a relative path. - Let the FileSystem dock import it. The shipped
.png.importkeeps faint pixels exact; Godot's default import would recolour pixels under alpha 20. - Drag
run.tscninto your scene, or loadrun.tresinto the Sprite Frames property of your own AnimatedSprite2D. - Play from a script with
$Hero.play("run"); connectanimation_finishedfor animations that do not loop. - Remove the old TexturePacker PNG and JSON from the project if nothing else uses them, so the same art is not imported twice.
Check the result
- SpriteFrames panel: one animation per name group, with the frame count of the JSON (6 for run_0 … run_5).
- Zoom to 400 % and compare a trimmed frame with its original: same size and position, because the margin restored the trim.
print($Hero.sprite_frames.get_frame_texture("run", 0).margin)prints the frame's margin Rect2.
TexturePacker JSON fields and where they land in Godot
| TexturePacker JSON | In the Studio | In the Godot 4 bundle |
|---|---|---|
| frames key or filename | frame name, extension dropped | animation name from its prefix; frame entry in metadata |
| frame {x, y, w, h} | the frame's region on your sheet | AtlasTexture region on the newly packed page |
| spriteSourceSize, sourceSize | full frame canvas and offset | AtlasTexture margin restores the full size |
| pivot | frame pivot (default bottom centre) | AnimatedSprite2D offset; every pivot kept in metadata |
| rotated: true | imported still turned | UNVERIFIED; repack without rotation |
| meta.image | pairs the JSON with its PNG | PNG page plus .png.import (lossless, no mipmaps) |
| no timing field | 100 ms per frame until you change it | animation speed plus relative frame durations |
Troubleshooting
| Symptom | Likely cause | How to check | Fix |
|---|---|---|---|
| Frames were grouped into the wrong animations | Names do not follow name + number, or two groups share a prefix | The Import panel shows how the animations were grouped | Rename frames or fix the tags on the timeline before exporting |
| Some frames are sideways | Those sprites were packed with rotation | Search the JSON for "rotated": true | Repack in TexturePacker with Allow rotation off and drop the new pair of files |
| Every animation plays at the same speed | The JSON has no timing, so every frame starts at 100 ms | Timeline durations before exporting | Set the real durations per frame or per tag, then export again |
| The Import panel says frames lie outside the image | The JSON belongs to another PNG, or the PNG was resized after packing | Compare meta.size with the PNG's size | Drop the PNG named in meta.image together with its JSON |
| Faint pixels (glow, smoke) change colour | The PNG was imported with Godot's default Fix Alpha Border instead of the shipped .png.import | Import dock of the PNG | Keep the shipped .png.import, or turn Fix Alpha Border off and reimport |
Other ways to do it
| Option | When it is the better choice |
|---|---|
TexturePacker's own Godot importer (Godot SpriteSheet .tpsheet + plugin) | You keep publishing from TexturePacker and want automatic reimport. According to CodeAndWeb it creates one AtlasTexture per sprite in a .sprites folder and an AnimationLibrary with looping animations at 10 fps. In our Godot 4.7.2 test it drew correctly, but under Godot's default PNG import faint pixels changed in 2 of 10 archer frames. |
| Add Frames from Sprite Sheet in Godot | Only for sheets on an even grid; a packed atlas has frames of different sizes. See sprite sheets in Godot. |
| Start from the source instead | If you still have the .aseprite file, Aseprite to Godot keeps tags and durations that a TexturePacker JSON never had. |
Engine exports and how each was checked
"Verified" means the exported files were loaded by the real engine or tool on real CC0 assets and the result was compared with the source. Anything that was not loaded is labelled as such.
| Target | Files | Check |
|---|---|---|
| Godot 4 | .tres SpriteFrames · .tscn AnimatedSprite2D · .png.import | Verified Godot 4.7.2Loaded by Godot; every animation frame drawn and compared with the source file. The scene uses Nearest filtering; rotation is never used. |
| Unity 6 | .unity.json · Editor/NerulioSpriteImporter.cs · AnimationClip | Verified Unity 6000.5.3f1Batch mode: sprite rects, pivots, pixels, clip keys and durations checked. |
| Phaser 3 / 4 | atlas JSON (multiatlas) · .anims.json | Verified Phaser 3.90 + 4.2Frames and animations drawn by both versions. |
| PixiJS 8 | spritesheet JSON · animations · anchor · meta.scale | Verified PixiJS 8.21Rotated and multi-page atlases included. |
| Aseprite JSON | hash / array · frameTags · slices | Verified Phaser load.aseprite · PixiJS 8.21Tags keep their direction and repeat count. |
| .aseprite | layers · tags · durations · slices | Verified Aseprite 1.3.18Opened and rendered by the Aseprite command line. |
| Spine / libGDX | .atlas | Verified spine-canvas 4.2Every region drawn by the Spine runtime, rotated and trimmed; libGDX itself was not run. |
| Starling / Sparrow XML | XML per page | Verified Phaser 4.2Phaser 3.90 draws trimmed XML frames wrongly (its own bug); the "Sparrow XML (Phaser 3)" preset turns trim off and passes in 3.90 and 4.2. |
| LÖVE | Lua quads · nerulio_atlas.lua · main.lua | Verified LÖVE 11.5Every frame drawn and every animation stepped through the shipped helper. |
| Defold | .atlas · .tilesource | Built Defold bob.jar 1.13.1Built by Defold's command-line builder; the built texture's UVs were read back. |
| GameMaker | spr_<name>_stripN.png · gamemaker.json | UNVERIFIEDNot loaded in GameMaker (no headless GameMaker). The strips are cut the way its strip importer cuts them. |
| CSS sprites | .css · preview .html | Verified ChromiumEvery class drawn from the shipped stylesheet. |
| GIF / APNG | one file per animation | Decoded PillowEvery frame and delay decoded again after export; APNG is exact. |
Evidence
GIF decoder: 408 of 408 frames identical to Pillow on 29 real GIFs; APNG 132 of 132 on 16 files. .aseprite: 231 corpus files imported, re-written and reopened in Aseprite 1.3.18 with the same tags, durations and pixels (231/231). Exports: 49 runs in the real engines on real CC0 assets, 47 pass — the 2 failures are Phaser 3.90's trimmed-XML bug, which the Phaser 3 preset avoids.
Limits
- Rotated sprites in the JSON are imported still turned, and exporting them is UNVERIFIED.
- TexturePacker's
.tpsheetformat is not read; publish the sheet as JSON (Hash or Array). - Polygon-packed sheets are read as rectangles; the polygon meshes are ignored.
- A grid or island guess is a preview with a confidence; nothing is cut until you press Apply, and every choice has one-click alternatives.
- .aseprite files whose layers do not compose exactly (e.g. group opacity) are imported flattened, and the Import panel says why.
- Rotated frames in an imported atlas stay rotated; their export is UNVERIFIED.
- Images up to 32,768 px per side (268 million pixels), subject to your browser's memory.
Versions and sources
Nerulio's Godot 4 bundle (SpriteFrames .tres, .tscn, .png.import) was loaded by Godot 4.7.2, and every frame was drawn at 1× and 4× and compared with its source; the TexturePacker JSON reader is src/studio/sprite/atlas-data.js. TexturePacker 8.3.0 and its Godot plugin v4.3.0 were run in the 2026-09-25 comparison. Godot behaviour follows the Godot 4.7 docs; the plugin's behaviour is quoted from CodeAndWeb.
Official documentation used
Questions
What about frames TexturePacker stored rotated?
They are imported as they lie on the sheet, still turned, and exporting them is UNVERIFIED. Repack in TexturePacker with rotation off and drop the new files; Godot's AtlasTexture cannot rotate a region, which is why the Godot target never packs rotated.
Does Godot keep the frame timing?
Yes, in Godot's own terms: each animation's speed is its fps and every frame's duration is relative to it, so 250 ms at 12 fps is written as 3.0. Reverse and ping-pong are written out as frame order. Godot 3.x cannot read this resource.
Where do my hitboxes end up?
Boxes and collision polygons drawn in the Studio are stored in the SpriteFrames metadata under "nerulio" (sprite_frames.get_meta("nerulio")), not created as nodes.
Is it free, and do I need an account?
Everything on these pages is free and works without an account. There is no watermark and no export that is held back.
Are my sprites uploaded?
No. The Studio decodes, packs and exports in this browser tab. Projects are autosaved in the browser (IndexedDB) and can be saved as a .nerulio file.
Does it need Aseprite or an engine plugin installed?
No. .aseprite files are read and written in the browser, and each engine bundle carries what that engine needs (for Godot, the import settings and scene; for Unity and the Godot TileSet, a small editor script).