Sprite Sheet to Aseprite — Cut, Tag and Save .aseprite
To rework a downloaded or old sprite sheet in Aseprite you want frames and tags, not one big picture. Drop the PNG here: the Studio measures the grid (margin and spacing included) or finds each sprite as an island, removes a flat background colour, makes each row a tag, and writes one .aseprite file with the timing, the pivot and the hitboxes as slices.
A PNG sprite sheet is one picture: it has no frame boundaries, timing, animation names or pivot. To make an .aseprite file, Nerulio measures the grid (or finds each sprite as an island), keys out a flat background, starts one tag per row at 100 ms per frame, lets you fix tags, timing, pivot and hitboxes, and then Sprite › Export .aseprite… writes frames, tags, durations and slices. The same writer produced 231 of 231 files that Aseprite 1.3.18.6 opened without a warning.
- .asepriteVerified· Aseprite 1.3.18
- 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
- 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 a sheet has, and what an .aseprite file needs
A sheet only holds pixels. Cell size, margin (the empty border around the sheet) and spacing (the gap between cells) are implied by the layout, and the animations by the rows, if the artist was consistent. Frame timing, animation names, loop settings and the pivot are not in the file at all; they live in a game's code or in the artist's notes.
An .aseprite file needs each of those explicitly: a canvas size, frames with a duration in milliseconds, tags with from–to, a direction and a repeat count, and slices for points and boxes. Nerulio fills in what can be measured (grid, islands, key colour, one tag per row), shows each guess with a confidence, and uses 100 ms per frame (Aseprite's default) until you set the real timing.
Aseprite tags are ranges, so a tag must be a run of consecutive frames. Nerulio writes a run in timeline order as it is, writes a backwards run as a reverse tag, and names any tag whose frames are scattered instead of bending it into a wrong range.
- Cell
- One frame's rectangle in the grid.
- Margin / spacing
- Empty pixels around the whole sheet / between neighbouring cells.
- Islands
- Separate groups of opaque pixels, used to cut a sheet that has no regular grid.
- Slice
- Aseprite's named rectangle; Nerulio writes the pivot and each rectangle box as one.
Example: an 8 × 4 sheet with margin and spacing
sheet 267 × 135 px, magenta background
grid 32 × 32 cells, margin 2 px, spacing 1 px
check width 2 + 8 × 32 + 7 × 1 + 2 = 267 px
check height 2 + 4 × 32 + 3 × 1 + 2 = 135 px
frames 8 × 4 = 32 → tags row_1 … row_4, 8 frames each
timing row_2 at 12 fps: 1000 / 12 = 83.33 ms → written as 83 ms
.aseprite 32 × 32 canvas, 32 frames, 1 layer, 4 tags, magenta → transparentRename row_1 … row_4 on the Timeline (idle, walk, jump, hurt) before export: Aseprite shows the tag names exactly as written.
What maps to what
| From the sheet / Studio | Written into the .aseprite | What to know |
|---|---|---|
| Frames cut by grid or islands | One frame each on a canvas as large as the largest frame | Each frame keeps its offset from the top left; frames of different sizes do not share a pivot |
| Tag over consecutive frames | Tag with from, to, direction and repeat | A backwards run becomes reverse; ping-pong stays ping-pong |
| Tag over scattered frames | Not written | Named in the export message; drag the frames together and export again |
| Frame duration | Whole milliseconds, at least 1 | 83.33 ms → 83 ms; untouched frames stay at 100 ms |
| Pivot | A slice named pivot with a pivot point, keyed where it changes | Left out while every frame keeps the default bottom centre |
| Rectangle boxes | One slice per type and slot (hit, hit2, hurt …) | An empty key where a box stops, so it does not carry on |
| Circle and polygon boxes, collision polygons | Not written | Aseprite slices are rectangles; the export message lists skipped boxes |
| Key colour | Transparent pixels, RGBA colour mode | The untouched sheet stays in the Studio for undo |
| Layers | The Studio's layers (a cut sheet has one) | Identical cels on a layer are stored as linked cels |
What it does
- Grid measured from the pixels with cell size, margin, spacing and a confidence; islands mode for irregular sheets keeps small effect pieces with their sprite and marks pieces it cannot place in red.
- Magenta or any flat background colour keyed to transparency; the untouched original is kept so the change can be undone.
- One animation per row to start with; rename, resize or drag out new tags on the Timeline, each with direction (forward, reverse, ping-pong) and repeat.
- Durations per frame or for a whole tag at once (Set all to fps), a pivot (P) and rectangle boxes (B) typed hit, hurt, interact or your own word.
- Sprite › Export .aseprite… writes the frames, tags, durations in whole milliseconds, a pivot slice and one slice per box.
How to do it
- Drop the sprite sheet PNG.
- Check the grid or islands guess and the background colour, choose an alternative if one is wrong, then press Apply (one undo step).
- On the Timeline, make one tag per animation and set its direction and repeat.
- Add timing, a pivot and hitboxes where you need them.
- Choose Sprite › Export .aseprite… and open the file in Aseprite.
Files you get
| File | What it is for |
|---|---|
hero.aseprite | Sprite › Export .aseprite…: frames at their own offsets, the Studio's layers, tags, durations, and pivot and box slices. |
hero_aseprite.zip › hero_aseprite/hero.aseprite | Pack & Export › .aseprite file: every frame on one pivot-aligned canvas, and a frame used by two tags repeated so each tag stays one range. The Aseprite 1.3.18 command line opened it and rendered every frame in our checks. |
Continue in Aseprite
- Open
hero.asepritein Aseprite. The canvas is the frame size (32 × 32 in the example), not the sheet size. - Check the tags above the frames: names, ranges and direction as set in Nerulio. A tag the export message listed as skipped is missing; fix its frame order in Nerulio and export again.
- Choose the Slice tool to see the
pivotslice and the box slices; each keeps its keys per frame. - Work on the animation. To get a sheet back for an engine, use File > Export Sprite Sheet, or bring the
.asepriteback to Nerulio for Godot, Unity or Phaser.
Check the result
aseprite -b hero.aseprite --list-tagsprints the tag names from first to last; compare them with the Timeline.- Play each tag in Aseprite:
row_2at 83 ms per frame loops every 8 × 83 = 664 ms. - Show a checkered background: areas that were magenta must be transparent, not pink.
What goes into the .aseprite file
| From the Studio | Written in the .aseprite as | Notes |
|---|---|---|
| Frames cut from the sheet | one frame each on a canvas the size of the largest frame | each frame keeps its own offset |
| Tags | tags with from..to, direction and repeat | a backwards run is written as reverse |
| Frame durations | a duration per frame in whole milliseconds | untouched frames stay at 100 ms, Aseprite's own default |
| Pivot | a slice named pivot with its pivot point | left out while every frame keeps the default bottom-centre pivot |
| Rectangle boxes | one slice per box type (hit, hurt, hit2 …), keyed where the box changes | circles and polygons are skipped |
| Layers | the asset's layers with opacity and blend mode | a cut sheet has one layer |
Troubleshooting
| Symptom | Likely cause | How to check | Fix |
|---|---|---|---|
| A tag is missing in Aseprite | Its frames are not consecutive on the Timeline | The export message names the skipped tag | Drag its frames next to each other (duplicate shared frames with Alt+N) and export again |
| Frames jump or drift when played in Aseprite | Frames were cut as islands of different sizes and sit at different offsets on the shared canvas | Step through the frames and compare their sizes in the Frame panel | Use Align › one canvas size with an anchor before export, or export the pivot-aligned file from Pack & Export; see jitter after trimming |
| Circle or polygon hitboxes are gone | Aseprite slices are rectangles only | The export message lists every skipped box | Redraw them as rectangles (B), or keep them in the Godot or generic JSON export |
| Pink or green pixels remain around the art | The key colour was not applied (confidence below high), or the art was anti-aliased against it | Import panel: the Background colour decision | Apply the detected colour; blended edge pixels need retouching, see removing a sprite background |
| Every frame is 100 ms | A PNG stores no timing, so the import starts at 100 ms | Frame panel: duration | Set all to fps per tag, or type milliseconds per frame, before export |
Other ways to do it
| Option | When it is the better choice |
|---|---|
| Aseprite's File > Import Sprite Sheet | The grid is regular and you prefer to work in Aseprite: it asks for the offset (x, y), the sprite width and height and the padding, then takes the frames in the order of the sheet type. Tags, timing and slices you add by hand. |
| Pack & Export › .aseprite file | You want every frame already aligned on its pivot, for example after cutting islands of different sizes. |
| The sprite slicer | You only need the frames as separate PNGs, not an Aseprite document. |
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
- Scattered tags and non-rectangular boxes are reported, not written.
- A sheet with semi-transparent edges against a key colour keeps those blended pixels.
- 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
Sprite › Export .aseprite… uses the writer that was checked on 231 real files: imported, written back and opened in Aseprite 1.3.18.6 without a warning, with tags, durations and pixels identical on all 231. The Pack & Export .aseprite target was opened and rendered frame by frame by the Aseprite 1.3.18 command line. The Aseprite steps above follow the Aseprite documentation.
Official documentation used
Questions
Will Aseprite open the file without complaints?
The writer was checked on 231 real .aseprite files imported into the Studio and written back: real Aseprite 1.3.18.6 opened all of them without a warning, with the same tags, durations and pixels. A sheet you cut here goes through that same writer.
What happens to circle and polygon hitboxes?
Aseprite slices are rectangles, so only rectangle boxes are written; circles and polygons are skipped, and the export message names them. Collision polygons stay in the project and in the Godot and Generic JSON exports.
Can a tag skip frames?
An Aseprite tag is a from..to range. A tag whose frames are consecutive on the Timeline, forwards or backwards, is written; one with gaps is left out and named rather than bent into a wrong range. Drag the frames into order and export again.
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).