Sprite Sheet Slicing Off — Fix Margin, Spacing and Drift
When slices start right and drift a little further with every column, the sheet has spacing between its cells that the grid ignores; when the first row or column is clipped, it has a margin around the edge. Irregular sheets without a grid and coloured backgrounds cause most of the other slicing trouble.
Slices that are off come from one of five causes: the wrong cell size (sprites split or two per frame), spacing between cells that the grid ignores (the error grows by the gap every column), a margin around the sheet (every cut off by the same amount), a sheet with no regular grid, or a packed atlas that never had one. Measure before re-cutting: where the cut first goes wrong and how fast the error grows tell you which number is wrong. Nerulio's import measures cell, margin and spacing from the transparent gaps and previews the cut first; it cannot rebuild a trimmed atlas without its data file.
- 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
Five causes, each with its own pattern
Wrong cell size shows at once: the frame count is double or half, or cuts land inside sprites from the second column on. The width of the sheet divided by the number of frames is only the cell when there are no gaps and no margin.
Spacing ignored makes the error grow: with a gap of g pixels, column n is off by n × g, so the first column is right and the last one can be off by half a frame. A margin ignored makes the error constant: every cut is early by the margin, and the last column or row shows extra pixels. Unity's Sprite Editor calls the same two numbers Offset and Padding; Nerulio calls them Offset X / Y and Gap X / Y.
Some sheets have no single grid: sprites of different sizes packed side by side, or cells whose content sticks out. Any grid then either cuts sprites or leaves pixels outside every cell, so the right cut is along the transparent gaps (islands). A packed atlas from TexturePacker, Aseprite's packed layout or another packer is worse: frames are trimmed to different sizes, sometimes rotated, and placed wherever they fit, so only the JSON or XML that came with it knows where each frame is.
- Cell
- Width × height of one frame's box.
- Offset / margin
- Blank pixels before the first cell.
- Gap / spacing / padding
- Blank pixels between cells (Unity calls it Padding).
- Packed atlas
- Frames placed wherever they fit, described by a data file instead of a grid.
The numbers behind each symptom
A strip of 8 frames of 32 × 32 with 2 px gaps and no margin: 8 × 32 + 7 × 2 = 270 px wide.
right W 32, Gap 2 → x = 34n → 0, 34, 68 … 238; 8 whole cells, 0 px left over
gap ignored W 32 → x = 32n; frame n is off by 2n → 0, 2, 4 … 14 px at frame 8
cell = 270 ÷ 8 ≈ 34 → (270 + 0) ÷ 34 = 7.9 → 7 whole cells, 32 px left over: frame 8 is lost
margin 4 px ignored → every cut 4 px early in every column (constant, not growing)
real case: tank.png 288 × 26 read as 32 × 24 leaves 2 px rows outside every cell;
32 × 26 covers it exactly → 288 ÷ 32 = 9 framesThe general rule the importer uses: whole cells per row = floor((width − 2 × margin + gap) ÷ (cell + gap)). If that is not your frame count, one of the three numbers is wrong.
What it does
- The import measures cell size, margin and spacing from the transparent gaps in the art and ranks several grids, each with a confidence and the reasons behind it.
- A grid that splits sprites, cuts through them or leaves pixels outside its cells loses to one that does not; the first reading stays in the list as an alternative.
- Custom grid: type the cell width and height, Offset X/Y (the margin) and Gap X/Y (the spacing), or drag the first cell in Sheet view. The count of whole cells that fit, and the pixels left over, update as you go.
- Islands (irregular sheet) cuts each sprite by its own transparent border; small effect pieces stay attached, and pieces that fit no frame turn red.
- A magenta or flat background is keyed to transparency with the original kept for undo, and cells without pixels are skipped instead of becoming blank frames.
How to do it
- Drop the sheet into the Sprite workspace; nothing is cut yet.
- Look at the preview: if slices drift, choose another grid or open Custom grid and set the gap.
- If the first row or column is clipped, set the offset; for sprites of mixed sizes switch to Islands.
- Press Apply (one undo step), then drag any frame region that is still off in Sheet view (`).
Check the result
- In Nerulio's Custom grid the fit line must read your frame count as whole cells, with the pixels left over no larger than the right and bottom margins.
- In Sheet view (`) every region outline runs through the gaps from the first column to the last, not only at the start.
- Play one row: nothing jumps by a gap width between frames.
Slicing symptoms and what to set
| Symptom | Cause | What to set |
|---|---|---|
| Each column is further off than the one before | Spacing between cells | Gap X (and Gap Y for rows) |
| First row or column clipped, the last one shows extra pixels | A margin around the sheet | Offset X / Offset Y |
| An empty frame at the end of a row | A partly filled last row | Nothing: cells without pixels are skipped |
| Sprites cut in half, frames of different sizes | No regular grid | Islands (irregular sheet) |
| A coloured box around every frame | Magenta or flat background | Key colour to transparent |
| Sparks or dust left outside the frames | Pieces too far from any sprite | Shown in red; drag the frame region to include them |
| Cut right, but the sprite jumps when played | Art placed unevenly inside the cells | Align frames after Apply |
Troubleshooting
| Symptom | Likely cause | How to check | Fix |
|---|---|---|---|
| The first column is right and each later one is further off | Spacing between cells is not set | Measure the error at the last column and divide by its index: that is the gap | Set Gap X (and Gap Y if rows drift too) |
| Every column is off by the same amount; the last one shows extra pixels | A margin around the sheet | Count the blank pixels before the first opaque column and row | Set Offset X / Y to that margin |
| The last frame of each row disappears | The cell was rounded up from width ÷ frames, so the last cell no longer fits | The fit line shows fewer whole cells and many pixels left over | Use the real cell plus the gap instead of the rounded size |
| Sprites are cut in half, or two share a frame | The cell is half or double the real one | The frame count is double or half of what you see | Pick the other size from the list, or type the real cell |
| Some sprites fit, others are cut, whatever the grid | The sheet has no regular grid (mixed sprite sizes) | Different sprites need different cells | Switch to Islands (cut along transparent gaps) |
| Frames are scattered, of different sizes, some sideways | It is a packed atlas, not a grid | A .json, .xml or .atlas file came with the PNG | Open the PNG with its data in the atlas viewer; without the data file no tool can recover the frames |
Other ways to do it
| Option | When it is the better choice |
|---|---|
| Ask for, or re-export, the data file | The sheet came from a packer or from Aseprite: its JSON describes every frame exactly and removes all guessing. |
| Slice in the engine with the corrected numbers | Unity's Sprite Editor takes Pixel Size, Offset and Padding; In Godot's SpriteFrames panel, Add frames from a Sprite Sheet starts from the number of horizontal and vertical frames. |
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
- Automatic detection searches margins up to 64 px and gaps up to 16 px (a quarter of the cell for small cells); wider layouts need the Custom grid.
- Sprites whose boxes overlap on the sheet cannot be separated by islands.
- A trimmed or rotated atlas cannot be rebuilt from the PNG alone.
- 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
The detector and the fit line follow src/game/grid-detect.js and src/studio/sprite/import-plan.js; the tank.png case is one of the real sheets the grid re-ranking was built on. Unity and Godot slicer settings are quoted from the Unity 6 manual and the Godot 4.7 documentation.
Official documentation used
Questions
Why is each column a few pixels further off than the last?
The sheet has spacing between cells. Every cell adds that gap, so the error grows across the row. Set Gap X (and Gap Y if rows drift too); the preview moves before anything is cut.
Why do I get an empty frame at the end?
Usually the last row is only partly filled. Cells without pixels are skipped, so they never become frames. If pixels are left over at the right or bottom, the grid panel says how many.
The frames are cut right, but the character bobs when played.
That is the art, not the slicing: each frame sits at a slightly different spot inside its cell. After Apply, Align frames measures the wobble in pixels and fixes it with whole-pixel moves.
Why is there a pink box around every frame?
The background colour was not keyed. The import normally proposes it for magenta or flat backgrounds; if it did not, pick the key-colour alternative in the import panel. The original stays in the project for undo.
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).