AsepriteをPhaser 3・4へ · アトラスとアニメーションJSON

1つの.asepriteから2通り：anims.fromJSONで読むアトラス＋アニメーションファイル、またはPhaserのload.aseprite・createFromAsepriteが読むAseprite JSON。どちらもPhaser 3.90・4.2で描画を確認しました。

Phaser 3・4は.asepriteファイルを読まず、PNGとJSONを読みます。NerulioはファイルをPhaserが対応する2つのJSONの経路のどちらかに変換します。this.anims.fromJSON()用の.anims.json付きTexturePackerアトラス（ループ・ピンポン・フレームごとのミリ秒入り）か、this.load.aseprite()とthis.anims.createFromAseprite()用のAseprite JSONです。どちらもPhaser 3.90と4.2で読み込んで描画しました。フレームをくっきり保つため、ゲーム設定にpixelArt: trueを入れてください。

スプライトシート、連番フレーム、GIF・APNG、.asepriteファイルをドロップ

空のStudioを開く

ブラウザ内で処理し、ファイルはアップロードされません。

書き出し先

Phaser 3 / 4検証済み· Phaser 3.90 + 4.2
Aseprite JSON検証済み· Phaser load.aseprite · PixiJS 8.21
Starling / Sparrow XML検証済み· Phaser 4.2
Godot 4検証済み· Godot 4.7.2
Unity 6検証済み· Unity 6000.5.3f1
PixiJS 8検証済み· PixiJS 8.21
.aseprite検証済み· Aseprite 1.3.18
Spine / libGDX検証済み· spine-canvas 4.2
LÖVE検証済み· LÖVE 11.5
Defoldビルド確認· Defold bob.jar 1.13.1
GameMaker未検証
CSS sprites検証済み· Chromium
GIF / APNGデコード確認· Pillow

PhaserがJSONからアニメーションを作る2つの方法

Phaserはテクスチャアトラスからフレームを描きます。PNGと、フレームごとの矩形・トリム・ピボットを並べたJSONです。アニメーションは別のオブジェクトで、キー、フレーム一覧、フレームレート、繰り返し回数（−1は無限）、先頭まで逆に戻るyoyoを持ちます。アニメーションのフレームごとにミリ秒の長さを持たせることができ、再生時にフレームレートを上書きしない限り、Phaserはそれをそのフレームの時間として使います。

経路1、アトラス＋アニメーションファイル：load.atlas（複数ページならload.multiatlas）がTexturePacker形式のJSONを読み、anims.fromJSONが設定をすべて含むJSONからアニメーションを作ります。経路2、Aseprite JSON：load.asepriteがAsepriteのFile › Export Sprite Sheetの書き出すJSONを読み、createFromAsepriteがタグごとにアニメーションを作り、フレームごとの長さと方向（逆方向、ピンポンはyoyo）を読みます。Phaser 3.90と4.2のソースでは、タグの繰り返し回数は読まないため、再生時に繰り返しを指定しなければ1回だけ再生されます。

Nerulioはブラウザで.asepriteを読み、フレームごとに表示中のレイヤーを合成してパックします。経路1では、タグごとに∞ならrepeat: -1、回数ならn − 1を書き、逆方向は順序を逆にして書き、ピンポンはyoyoにし、フレームごとのミリ秒を書きます。経路2では、createFromAsepriteが求める"0" … "n"のフレームキー、方向と繰り返しを持つframeTags、ピボットとボックス用のスライスを書きます。この経路は全フレームが1ページに収まる必要があります。検証で両バージョンとも回転したTexturePackerフレームを鏡像で描いたため、回転はオフにします。

アトラスJSON: 矩形・トリム・ピボットを持つTexturePacker形式のフレーム一覧（ハッシュ、複数ページならmultiatlas）。
anims.fromJSON: アニメーション設定のJSONファイルからアニメーションを作る関数。
createFromAseprite: 読み込んだAseprite JSONのframeTagごとにアニメーションを1つ作る関数。
repeat: 最初の再生の後に追加で繰り返す回数。−1は無限。
yoyo: フレームを順に再生したあと、先頭まで逆順に戻る。

例：タグ3つ、2つの経路

Asepriteのタグ                         hero.anims.json（経路1）
idle    4 × 125 ms、∞                  frameRate 10、repeat -1、duration 125 ×4
attack  100, 100, 150, 250 ms、×1      repeat 0（1回再生）、duration 100, 100, 150, 250
jump    3 × 80 ms、ピンポン、∞          フレーム0, 1, 2 + yoyo: true、repeat -1

Aseprite JSON（経路2）：frameTags  idle 0–3、attack 4–7（repeat "1"）、jump 8–10 pingpong
  createFromAseprite → idle・attack・jump、すべてrepeat 0
  sprite.play({ key: 'idle', repeat: -1 })   ← ループするタグに必要

どちらの経路でもattackは100 + 100 + 150 + 250 = 600ms再生されます。Phaserがフレームごとのdurationをそのフレームの時間として使うからです。

変換後に残るもの

Aseprite	Nerulio	Phaser 3 / 4
フレームのピクセル（表示中のレイヤー）	合成したフレームをPNGにパック	トリムのオフセット付きのアトラスフレーム
フレームの長さ（ms）	フレームごとに保持	AnimationFrameの`duration`（ms）、そのフレームの時間
タグ	同じ名前のアニメーション1つ	アニメーションキー（anims.json）またはframeTag（Aseprite JSON）
方向：逆方向	フレーム順を逆にして記録	逆順に並んだフレーム
方向：ピンポン	フレームは順方向で並べる	`yoyo: true`
繰り返し ∞ / 繰り返し n	ループ / n回再生	経路1：`repeat: -1` / n − 1。経路2：再生時に`repeat`を自分で指定
ピボットスライスかPのピボット	フレームのピボット	経路1：フレームの`pivot`、Phaserはカスタムピボットとして読む。経路2：Phaserが使わない`pivot`スライス
hit / hurtのスライス	ボックス	経路2のみ、自分のコード用に`meta`のスライスとして

できること

アトラスJSONハッシュ（複数ページならmultiatlas）と、フレームごとの長さ入り.anims.json。
frameTags（方向・繰り返し）とスライス付きのAseprite JSON（ハッシュ・配列）。createFromAsepriteが必要とする"0".."n"のフレームキー。
Phaser向けは回転をオフ。両バージョンとも回転したTexturePackerフレームの向きを正しく戻して描けなかったためです。
PixiJS 8向けにはanimationsとanchor付きの専用spritesheet JSON。

使い方

.asepriteファイルをドロップ。
タイムラインでタグを確認。
パック＆書き出しでPhaser 3/4かAseprite JSONを選ぶ。
this.load.atlas・multiatlas＋anims.fromJSON、またはthis.load.asepriteで読み込み。

出力されるファイル

経路1（パック＆書き出し › Phaser 3 / 4）と経路2（Aseprite JSONのハッシュ・配列）のファイルです。

ファイル	用途
`hero.png`	パックしたフレーム（トリム、2px間隔、回転なし）。
`hero.json`	経路1：アトラスJSONハッシュ（複数ページなら`hero.multiatlas.json`）。経路2："0"…"n"の`frames`、`meta.frameTags`、`meta.slices`を持つAseprite JSON。
`hero.anims.json`	経路1のみ：タグごとの`anims.fromJSON`用アニメーション設定。
`README-PHASER.md / README-ASEPRITE-JSON.md`	このバンドルを読み込むコード。

Phaserで読み込む

PNGとJSONのファイルをゲームのアセットフォルダーにコピーします。
ゲーム設定にpixelArt: trueを入れて作成します。アンチエイリアスを切り、位置を整数に丸めます。
経路1、preload()で：this.load.atlas('hero', 'hero.png', 'hero.json')とthis.load.json('hero-anims', 'hero.anims.json')。
経路1、create()で：this.anims.fromJSON(this.cache.json.get('hero-anims'))、続いてthis.add.sprite(100, 100, 'hero').play('idle')。
経路2：preload()でthis.load.aseprite('hero', 'hero.png', 'hero.json')、続いてthis.anims.createFromAseprite('hero')、ループすべきタグはsprite.play({ key: 'idle', repeat: -1 })。
sprite.play('attack')でアニメーションを切り替え、1回きりの動作のあとはanimationcompleteを受けてidleに戻します。

結果の確認

create()でthis.anims.get('attack').frames.map(f => f.duration)を出力すると、100, 100, 150, 250になるはずです。
経路1ではthis.anims.get('idle').repeatが−1のはずです。
jumpは順に再生したあと先頭へ戻るように動くはずです。this.anims.get('jump').yoyoがtrueです。
pixelArt: trueなら、4倍に拡大してもピクセルの境界がくっきりしているはずです。

トラブルシューティング

症状	考えられる原因	確認方法	対処
アニメーションが1回再生して止まる（経路2）	`createFromAseprite`はタグの繰り返しを読まず、すべてrepeat 0になる	`this.anims.get('idle').repeat`が0	`{ key, repeat: -1 }`で再生するか、繰り返しが書き込まれる経路1を使う
アニメーションが空、またはフレームが欠ける	Aseprite JSONのフレームキーが"0"…"n"ではなくタイトル形式で、`createFromAseprite`は見つからないフレームを飛ばす	JSONの`frames`のキーを確認	Nerulioで書き出し直す（"0"…"n"で書く）か、Aseprite CLIを`--filename-format "{frame}"`で実行
スプライトがぼやける	ゲームがアンチエイリアスありで動いている	ゲーム設定	`pixelArt: true`にする
一部のフレームが反転したり崩れたりする	別のパッカーの回転フレーム：Phaserは回転したTexturePackerフレームを鏡像で描く	JSONの`"rotated": true`	回転なしでパックする。Phaserアトラスのフレームの乱れを参照
フレームごとの長さが無視される	`play()`にカスタムの`frameRate`を渡し、Phaserが全フレームに同じ時間を使っている	再生の設定を確認	フレームレートを上書きせず、長さのほうを変える
NerulioがAseprite JSONの書き出しを拒否する	フレームが1ページに収まらず、Aseprite JSONはシート1枚しか表せない	書き出しの注意にページ数が出る	ページサイズを上げるか、multiatlasを書く経路1を使う

ほかの方法

方法	こんなときに向いています
Aseprite自体のFile › Export Sprite Sheet（JSON Data、タグ）＋`load.aseprite`	Asepriteを持っていて、その書き出しを使いたいとき。必要な書き出し設定はPhaserのドキュメントに載っています。
`load.spritesheet`と`anims.create`で使うグリッドのシート	フレームレートが一定のアニメーション1つ。フレームサイズが必要です：フレームサイズの測り方。
Phaserの代わりにPixiJS	Aseprite JSONをPixiJSへ。

エンジン別の書き出しと検証方法

「検証済み」は、実際のCC0アセットから書き出したファイルを本物のエンジン・ツールで読み込み、元データと比較したという意味です。読み込んでいない形式はそのように表示します。

書き出し先	ファイル	検証
Godot 4	`.tres SpriteFrames · .tscn AnimatedSprite2D · .png.import`	検証済み Godot 4.7.2Godotで読み込み、全アニメーションフレームを描画して元ファイルと比較。シーンはNearestフィルターで、回転は使いません。
Unity 6	`.unity.json · Editor/NerulioSpriteImporter.cs · AnimationClip`	検証済み Unity 6000.5.3f1バッチモードでスプライト範囲・ピボット・ピクセル・クリップのキーと長さを確認。
Phaser 3 / 4	`atlas JSON (multiatlas) · .anims.json`	検証済み Phaser 3.90 + 4.2両バージョンでフレームとアニメーションを描画。
PixiJS 8	`spritesheet JSON · animations · anchor · meta.scale`	検証済み PixiJS 8.21回転・複数ページのアトラスも確認。
Aseprite JSON	`hash / array · frameTags · slices`	検証済み Phaser load.aseprite · PixiJS 8.21タグの方向と繰り返し回数を保持。
.aseprite	`layers · tags · durations · slices`	検証済み Aseprite 1.3.18Asepriteのコマンドラインで開いて描画。
Spine / libGDX	`.atlas`	検証済み spine-canvas 4.2Spineランタイムで回転・トリム領域をすべて描画。libGDX本体は未実行。
Starling / Sparrow XML	`XML per page`	検証済み Phaser 4.2Phaser 3.90はトリムされたXMLフレームを誤って描画します（Phaser側の不具合）。「Sparrow XML (Phaser 3)」プリセットはトリムを切り、3.90・4.2とも合格。
LÖVE	`Lua quads · nerulio_atlas.lua · main.lua`	検証済み LÖVE 11.5同梱ヘルパーで全フレームを描画し、全アニメーションを再生。
Defold	`.atlas · .tilesource`	ビルド確認 Defold bob.jar 1.13.1Defoldのコマンドラインビルダーでビルドし、生成テクスチャのUVを読み戻して確認。
GameMaker	`spr_<name>_stripN.png · gamemaker.json`	未検証GameMakerでは読み込んでいません（ヘッドレス実行不可）。ストリップはGameMakerの取り込み方式どおりに切ります。
CSS sprites	`.css · preview .html`	検証済み Chromium同梱スタイルシートで全クラスを描画。
GIF / APNG	`one file per animation`	デコード確認 Pillow書き出し後に全フレームと遅延を再デコード。APNGは完全一致。

検証の根拠

GIFデコーダー：実在のGIF 29本で408/408フレームがPillowと一致、APNG 16本で132/132。.aseprite：コーパス231ファイルを読み込み・書き直し、Aseprite 1.3.18で開いてタグ・長さ・ピクセルが231/231一致。書き出し：実在のCC0アセットで実際のエンジンを49回実行し47回合格。失敗2回はPhaser 3.90のトリムXMLの不具合で、Phaser 3プリセットで回避できます。

制限

レイヤーは統合され、合成モードはフレームに焼き込まれます。
ヒットボックスはデータだけで、Phaserが物理ボディを作るわけではありません。
経路2は全フレームが1ページに収まる必要があります。
グリッド・島の推定は信頼度つきのプレビューで、「適用」を押すまで何も切りません。すべての選択に代替案があり、ワンクリックで切り替えられます。
レイヤーが正確に合成できない.asepriteファイル（グループの不透明度など）は統合して読み込み、理由を読み込みパネルに表示します。
読み込んだアトラス内の回転フレームは回転したままで、その書き出しは未検証です。
画像は一辺32,768px（2億6,800万ピクセル）まで。ブラウザのメモリにも依存します。

バージョンと出典

検証の実行では、両方の経路をPhaser 3.90とPhaser 4.2が読み込みました。全フレームを描いて元画像と比べ、anims.fromJSONとcreateFromAsepriteが作ったアニメーションを読み戻しています。createFromAsepriteがタグの繰り返しを無視することはPhaser 3.90・4.2のソースで確認し、それ以外はPhaser APIドキュメントに基づきます。

参照した公式ドキュメント

よくある質問

どちらを使えばいい？

Aseprite JSONはPhaserのAseprite用の流れをそのまま使えます。アトラス方式は複数スプライトを1枚のテクスチャや複数ページにまとめます。

Sparrow・Starling XML（FNF）は？

書き出せます。Phaser 3.90ではXMLパーサーがトリムしたフレームを誤描画するので「Sparrow XML (Phaser 3)」プリセットを使ってください。

無料ですか？アカウントは必要ですか？

このページの機能はすべて無料で、アカウントなしで使えます。透かしや制限された書き出しはありません。

スプライトはアップロードされますか？

いいえ。Studioはこのブラウザのタブ内でデコード・パック・書き出しを行います。プロジェクトはブラウザ（IndexedDB）に自動保存され、.nerulioファイルとして保存できます。

Asepriteやエンジンのプラグインは必要ですか？

いいえ。.asepriteファイルはブラウザで読み書きします。エンジン別のバンドルには必要なものが入っています（Godotはインポート設定とシーン、UnityとGodotのタイルセットは小さなエディタースクリプト）。