Skip to content
Nerulio.
Studio

Aseprite to Phaser 3 / 4 — Atlas and Animations JSON

Two routes from one .aseprite file: an atlas plus an animations file you load with anims.fromJSON, or Aseprite JSON that Phaser's own load.aseprite / createFromAseprite reads — both drawn by Phaser 3.90 and 4.2.

Phaser 3 and 4 do not read .aseprite files; they read a PNG plus JSON. Nerulio turns the file into either of the two JSON routes Phaser supports: a TexturePacker atlas with an .anims.json for this.anims.fromJSON() (loop, ping-pong and per-frame milliseconds written in), or Aseprite JSON for this.load.aseprite() and this.anims.createFromAseprite(). Both were loaded and drawn by Phaser 3.90 and 4.2. Set pixelArt: true in the game config so the frames stay sharp.

Drop a sprite sheet, numbered frames, a GIF / APNG or an .aseprite file
Open the empty Studio
Runs in your browser. Files are not uploaded.
Studio Pack & Export: the packed atlas page with every frame outlined, the used area and the export targets
The real Studio with a CC0 asset (OpenGameArt).
Exports to
  • Phaser 3 / 4Verified· Phaser 3.90 + 4.2
  • Aseprite JSONVerified· Phaser load.aseprite · PixiJS 8.21
  • Starling / Sparrow XMLVerified· Phaser 4.2
  • Godot 4Verified· Godot 4.7.2
  • Unity 6Verified· Unity 6000.5.3f1
  • PixiJS 8Verified· PixiJS 8.21
  • .asepriteVerified· Aseprite 1.3.18
  • Spine / libGDXVerified· spine-canvas 4.2
  • LÖVEVerified· LÖVE 11.5
  • DefoldBuilt· Defold bob.jar 1.13.1
  • GameMakerUNVERIFIED
  • CSS spritesVerified· Chromium
  • GIF / APNGDecoded· Pillow

Two ways Phaser builds animations from JSON

Phaser draws frames from a texture atlas: a PNG plus JSON listing each frame's rectangle, trim and pivot. Animations are separate objects with a key, a list of frames, a frame rate, a repeat count (−1 = forever) and an optional yoyo that plays back down to the start. Each animation frame may carry its own duration in milliseconds, which Phaser uses as that frame's time as long as you do not override the frame rate when you play it.

Route 1, atlas + animations file: load.atlas (or load.multiatlas for several pages) reads the TexturePacker-style JSON, and anims.fromJSON creates the animations from a JSON file that already holds every setting. Route 2, Aseprite JSON: load.aseprite reads the JSON Aseprite writes with File › Export Sprite Sheet, and createFromAseprite makes one animation per tag, reading each frame's duration and the tag direction (reverse, ping-pong as yoyo). In the Phaser 3.90 and 4.2 source it does not read the tag's repeat count, so those animations play once unless you ask for a repeat when you play them.

Nerulio reads the .aseprite file in the browser, composites the visible layers per frame and packs the frames. For route 1 it writes each tag as an animation with repeat: -1 for ∞ or n − 1 for a count, reverse written out, ping-pong as yoyo, and every frame's milliseconds. For route 2 it writes frame keys "0" … "n" (what createFromAseprite expects), frameTags with direction and repeat, and slices for the pivot and boxes; this route needs all frames on one page. Rotation stays off because both Phaser versions drew rotated TexturePacker frames mirrored in the verification runs.

Atlas JSON
TexturePacker-style frame list (hash, or multiatlas for several pages) with rects, trim and pivot.
anims.fromJSON
Creates animations from a JSON file of animation configs.
createFromAseprite
Creates one animation per frameTag of a loaded Aseprite JSON.
repeat
Extra plays after the first; −1 repeats forever.
yoyo
Plays the frames forward, then back to the start.

Example: three tags, both routes

Aseprite tag                          hero.anims.json (route 1)
idle    4 × 125 ms, ∞                 frameRate 10, repeat -1, durations 125 ×4
attack  100, 100, 150, 250 ms, ×1     repeat 0 (plays once), durations 100, 100, 150, 250
jump    3 × 80 ms, ping-pong, ∞       frames 0, 1, 2 + yoyo: true, repeat -1

Aseprite JSON (route 2): frameTags  idle 0–3, attack 4–7 (repeat "1"), jump 8–10 pingpong
  createFromAseprite → idle, attack, jump, each with repeat 0
  sprite.play({ key: 'idle', repeat: -1 })   ← needed for looping tags

The attack animation lasts 100 + 100 + 150 + 250 = 600 ms in both routes, because Phaser takes each frame's duration as that frame's time.

What survives the conversion

In AsepriteIn NerulioIn Phaser 3 / 4
Frame pixels (visible layers)Composited frame, packed into the PNGAtlas frame with trim offsets
Frame duration (ms)Kept per frameAnimationFrame duration in ms, the frame's own time
TagOne animation of the same nameAnimation key (anims.json) or frameTag (Aseprite JSON)
Direction reverseFrame order written reversedFrames in reverse order
Direction ping-pongFrames listed forwardyoyo: true
Repeat ∞ / repeat nLoop / play n timesRoute 1: repeat: -1 / n − 1. Route 2: set repeat yourself when playing
Pivot slice or P pivotFrame pivotRoute 1: frame pivot, which Phaser reads as the frame's custom pivot. Route 2: a pivot slice Phaser does not use
Hit / hurt slicesBoxesRoute 2 only, as slices in meta for your own code

What it does

  • Atlas JSON hash (multiatlas when there are several pages) and .anims.json with each frame's duration.
  • Aseprite JSON hash or array with frameTags (direction, repeat) and slices; frame keys "0".."n" as createFromAseprite needs.
  • Rotation stays off for Phaser: both versions drew rotated TexturePacker frames wrongly (not turned back) in our runs.
  • PixiJS 8 gets its own spritesheet JSON with animations and anchors.

How to do it

  1. Drop the .aseprite file.
  2. Check the tags on the timeline.
  3. Open Pack & Export; choose Phaser 3 / 4 or Aseprite JSON.
  4. Load it with this.load.atlas / multiatlas + anims.fromJSON, or this.load.aseprite.

Files you get

Route 1 (Pack & Export › Phaser 3 / 4) and route 2 (Aseprite JSON hash or array):

FileWhat it is for
hero.pngThe packed frames (trimmed, 2 px apart, never rotated).
hero.jsonRoute 1: atlas JSON hash (hero.multiatlas.json when there are several pages). Route 2: Aseprite JSON with frames "0"…"n", meta.frameTags and meta.slices.
hero.anims.jsonRoute 1 only: every tag as an animation config for anims.fromJSON.
README-PHASER.md / README-ASEPRITE-JSON.mdThe loading code for this bundle.

Load it in Phaser

  1. Copy the PNG and JSON files into your game's assets folder.
  2. Create the game with pixelArt: true in the config; it turns antialiasing off and rounds positions.
  3. Route 1, in preload(): this.load.atlas('hero', 'hero.png', 'hero.json') and this.load.json('hero-anims', 'hero.anims.json').
  4. Route 1, in create(): this.anims.fromJSON(this.cache.json.get('hero-anims')), then this.add.sprite(100, 100, 'hero').play('idle').
  5. Route 2: this.load.aseprite('hero', 'hero.png', 'hero.json') in preload(), then this.anims.createFromAseprite('hero') and sprite.play({ key: 'idle', repeat: -1 }) for tags that should loop.
  6. Switch animations with sprite.play('attack') and listen to animationcomplete to go back to idle after a one-shot.

Check the result

  • In create(), log this.anims.get('attack').frames.map(f => f.duration): it prints 100, 100, 150, 250.
  • this.anims.get('idle').repeat is −1 on route 1.
  • The jump animation plays forward and then back towards the start: this.anims.get('jump').yoyo is true.
  • At 4× zoom the pixel edges stay hard with pixelArt: true.

Troubleshooting

SymptomLikely causeHow to checkFix
An animation plays once and stops (route 2)createFromAseprite does not read the tag's repeat, so every animation gets repeat 0this.anims.get('idle').repeat is 0Play with { key, repeat: -1 }, or use route 1, where the repeat is written in
Animations are empty or miss framesThe Aseprite JSON uses title-style frame keys, not "0"…"n"; createFromAseprite skips frames it cannot findLook at the keys of frames in the JSONExport again from Nerulio (it writes "0"…"n"), or run the Aseprite CLI with --filename-format "{frame}"
Sprites are blurryThe game runs with antialiasingGame configSet pixelArt: true
Some frames appear mirrored or scrambledAn atlas from another packer with rotated frames: Phaser draws rotated TexturePacker frames mirrored"rotated": true in the JSONPack without rotation; see wrong frames in a Phaser atlas
Per-frame durations are ignoredplay() was called with a custom frameRate, which switches Phaser to one time per frameLook at the play configDo not override the frame rate; change the durations instead
Nerulio refuses the Aseprite JSON exportThe frames need more than one page and Aseprite JSON describes one sheetThe export note names the page countRaise the page size or use route 1, which writes a multiatlas

Other ways to do it

OptionWhen it is the better choice
Aseprite's own File › Export Sprite Sheet (JSON Data, tags) + load.asepriteYou own Aseprite and prefer its exporter; the Phaser docs list the export settings it expects.
A plain grid sheet with load.spritesheet and anims.createOne animation at an even frame rate; you need the frame size, see measuring frame size.
PixiJS instead of PhaserAseprite JSON to PixiJS.

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.

TargetFilesCheck
Godot 4.tres SpriteFrames · .tscn AnimatedSprite2D · .png.importVerified 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 · AnimationClipVerified Unity 6000.5.3f1Batch mode: sprite rects, pivots, pixels, clip keys and durations checked.
Phaser 3 / 4atlas JSON (multiatlas) · .anims.jsonVerified Phaser 3.90 + 4.2Frames and animations drawn by both versions.
PixiJS 8spritesheet JSON · animations · anchor · meta.scaleVerified PixiJS 8.21Rotated and multi-page atlases included.
Aseprite JSONhash / array · frameTags · slicesVerified Phaser load.aseprite · PixiJS 8.21Tags keep their direction and repeat count.
.asepritelayers · tags · durations · slicesVerified Aseprite 1.3.18Opened and rendered by the Aseprite command line.
Spine / libGDX.atlasVerified spine-canvas 4.2Every region drawn by the Spine runtime, rotated and trimmed; libGDX itself was not run.
Starling / Sparrow XMLXML per pageVerified 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ÖVELua quads · nerulio_atlas.lua · main.luaVerified LÖVE 11.5Every frame drawn and every animation stepped through the shipped helper.
Defold.atlas · .tilesourceBuilt Defold bob.jar 1.13.1Built by Defold's command-line builder; the built texture's UVs were read back.
GameMakerspr_<name>_stripN.png · gamemaker.jsonUNVERIFIEDNot loaded in GameMaker (no headless GameMaker). The strips are cut the way its strip importer cuts them.
CSS sprites.css · preview .htmlVerified ChromiumEvery class drawn from the shipped stylesheet.
GIF / APNGone file per animationDecoded 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

  • Layers arrive flattened; blend modes are baked into the frames.
  • Hitboxes are data only: Phaser creates no physics bodies from them.
  • Route 2 needs all frames on one page.
  • 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

Both routes were loaded by Phaser 3.90 and Phaser 4.2 in the verification runs: every frame was drawn and compared with the source, and the animations created by anims.fromJSON and createFromAseprite were read back. That createFromAseprite ignores the tag repeat was read in the Phaser 3.90 and 4.2 source; the rest follows the Phaser API documentation.

Official documentation used

Questions

Which one should I use?

Aseprite JSON keeps Phaser's own Aseprite workflow. The atlas route packs several sprites into one texture and multi-page atlases.

What about Sparrow / Starling XML (FNF)?

Also exported. Use the "Sparrow XML (Phaser 3)" preset for Phaser 3.90: its XML parser draws trimmed frames wrongly.

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).

Nerulio.

A 2D game asset studio in the browser. Files stay on your device.