PhaserMetadata export

Sprite Sheet Generator for Phaser 3

Export a JSON atlas for this.load.atlas, or a plain PNG for this.load.spritesheet. Frames are named frame_000 upward, which is what generateFrameNames expects with zeroPad: 3.

A sprite sheet exported as a JSON atlas, next to the settings it needs in Phaser 3
What you export

Format menu

Phaser / PixiJS

JSON atlas (TexturePacker format)

Format > Phaser / PixiJS downloads spritesheet.png and spritesheet.json. The JSON uses the TexturePacker hash layout: one entry per frame, keyed frame_000, frame_001 and so on, each with its frame rect. Phaser reads it through this.load.atlas, which takes the PNG and JSON URLs as separate arguments, so you can rename both files. The cells also form a plain grid with no spacing, so the same PNG works with this.load.spritesheet if you would rather address frames by number.

Step by step

Getting the sheet into Phaser

  1. 1

    Export the atlas

    Click Format in the Export panel and choose Phaser / PixiJS. The ZIP holds spritesheet.png and spritesheet.json.

  2. 2

    Load it

    In preload(), call this.load.atlas with a texture key, the PNG path, and the JSON path.

  3. 3

    Build the animation

    Use generateFrameNames with prefix frame_, zeroPad 3, start 0, and end at the frame count minus one. If you loaded the grid instead, use generateFrameNumbers.

  4. 4

    Turn on pixelArt

    Set pixelArt: true in the game config so textures use nearest-neighbour sampling.

JavaScript
// Atlas path (recommended)
function preload() {
  this.load.atlas('hero', 'hero.png', 'hero.json');
}

function create() {
  this.anims.create({
    key: 'walk',
    frames: this.anims.generateFrameNames('hero', {
      prefix: 'frame_',
      start: 0,
      end: 7,
      zeroPad: 3,
    }),
    frameRate: 12,
    repeat: -1,
  });

  this.add.sprite(100, 100, 'hero').play('walk');
}

// Grid path, if you exported the PNG only
this.load.spritesheet('hero', 'hero.png', {
  frameWidth: 32, // the cell size shown in the editor
  frameHeight: 32, // cells touch, so no spacing or margin
});
Cheat sheet
SettingPhaser value
Atlas loaderthis.load.atlas(key, png, json)
Grid loaderthis.load.spritesheet(key, png, config)
Frame namesframe_000, zeroPad: 3
spacing / margin0, the cells touch
Crisp pixelspixelArt: true in the game config
Built for the workflow

TexturePacker hash format

The JSON shape Phaser has loaded since 3.0, so atlas tutorials and plugins written for TexturePacker output apply as they are.

Grid path too

Prefer this.load.spritesheet? Export only the PNG and pass the cell size as frameWidth and frameHeight.

Reads atlases back

The Splitter accepts a TexturePacker JSON with its PNG, so an atlas from another tool can be cut into frames, edited, and exported again.

Troubleshooting

When the sheet fights Phaser

The console reports a 404 while loading the atlas

Cause
The PNG or JSON path is relative to the wrong base. Phaser resolves both against the loader baseURL and path, not against the page that calls preload.
Fix
Check the network tab for the URL Phaser requested, then fix the path or set this.load.setPath to the asset folder.

The animation plays once and freezes on the last frame

Cause
repeat defaults to 0, which plays the sequence one time.
Fix
Set repeat to -1 for an endless loop. For a one-shot that should return to idle, keep repeat at 0 and play the idle animation from the animationcomplete event.

Frames from load.spritesheet are cropped or include part of the neighbour

Cause
frameWidth or frameHeight is the size of the art rather than the cell. With Padding set in the editor, the cell is larger than the art.
Fix
Use the cell size from the Grid Layout panel and leave spacing and margin out. Or switch to the atlas, where each rect is written down for you.

Sprites look soft even with pixelArt enabled

Cause
pixelArt sets nearest sampling, but sprites at fractional coordinates, which a moving camera produces, still smear.
Fix
Add roundPixels: true to the game config. For a camera that follows a body, setting roundPixels on the camera keeps the scene on whole pixels.

Switching animations jumps to a jarring pose

Cause
play interrupts the current animation immediately, so a run that cuts to idle mid-stride snaps.
Fix
Use playAfterRepeat to let the current cycle finish first, or playAfterDelay for a timed switch.
Versions and edge cases

Versions and edge cases

Phaser 3
load.atlas has read this JSON shape since 3.0. generateFrameNames, play, and the animationcomplete event work the same across the 3.x line; playAfterRepeat and the Aseprite loader arrived in 3.50.
Phaser 4
The loader calls and the animation manager carry over, so code that loads and animates this atlas needs no change. The rewrite is mostly in the renderer.
Phaser 2 and CE
The older versions load the same file with load.atlasJSONHash. The animation API is different, so follow a Phaser 2 tutorial for the play calls.
Vite and webpack
Put the PNG and JSON in the public directory instead of importing them, so the runtime paths stay predictable and the JSON is not inlined into the bundle.
Scale manager
The scale manager can put the canvas on a fractional zoom, which softens sprites whatever the renderer settings say. Use an integer zoom, or Scale.FIT with a game size that divides the window cleanly.
Phaser FAQ

More detail in the related guide, or compare every export format.

Other engines

Export for Phaser

Load your frames, check the loop in the Preview tab, then export. For Phaser that means: JSON atlas (TexturePacker format).