Phaser テクスチャアトラス作成 · アトラスJSONとアニメーション
フレームを入れると、this.load.atlas（またはmultiatlas）とanims.fromJSONが読むファイルが得られます。密なアトラス、JSONハッシュ、フレームごとの長さ入りのアニメーションファイルで、検証ではPhaser 3.90・4.2が描画しました。
Phaserはテクスチャアトラスを、PNGとTexturePacker形式のJSON（ハッシュまたは配列）としてthis.load.atlas(key, png, json)で読み込みます。読み込んだ後はthis.add.sprite(x, y, key, "run_0")のようにフレーム名で指定します。Nerulioはフレームをこの形式にパックし、this.anims.fromJSON向けに全タグとフレームごとの長さを入れた.anims.jsonを添えます。検証の実行でPhaser 3.90と4.2は回転したフレームを戻して描けなかったため回転はオフにし、トリムしたフレームは正しく描かれます。Phaser 3.90と4.2で確認済みです。
- Phaser 3 / 4検証済み· Phaser 3.90 + 4.2
- Starling / Sparrow XML検証済み· Phaser 4.2
- Godot 4検証済み· Godot 4.7.2
- Unity 6検証済み· Unity 6000.5.3f1
- PixiJS 8検証済み· PixiJS 8.21
- Aseprite JSON検証済み· Phaser load.aseprite · 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がアトラスからフレームを探す仕組み
ローダーはframesの各項目から、1つのテクスチャキーに属する名前付きフレームを作ります。frameはPNGから切り出す矩形です。trimmedが真なら、PhaserはsourceSizeとspriteSourceSizeをフレームのトリム情報として渡すので、切り出した断片は元の大きさの枠の中に描かれ、スプライトはトリムしていないかのように振る舞います。項目にpivotがあれば、フレームを設定したときにスプライトの原点になります。
アニメーションはこの名前を参照します。コードでthis.anims.generateFrameNames(key, {prefix, start, end, zeroPad})を使って作るか、データとしてthis.anims.fromJSONに渡します。アニメーションのフレームごとにミリ秒単位のdurationを持てます。Phaser 3.90のアニメーションのコードでは、その長さが過ぎると次のフレームに進み、0ならアニメーションの1フレームあたりのミリ秒を使います。
フレームが複数ページにまたがるときは、this.load.multiatlas(key, json, path)がtexturesリストを持つJSONを1つ読みます。ページ画像ごとに項目が1つあり、フレーム名はページをまたいで一意なので、コード側はフレームがどのページにあるかを気にしなくて済みます。
- テクスチャキー
- ローダーに渡した名前（"run"）。すべてのフレームがこの下にあります。
- フレーム名
framesの項目のキー（"run_0"）。add.spriteやアニメーションが参照します。- JSONハッシュ / 配列
- 同じフレームデータを、名前をキーにしたオブジェクトか、
filenameを持つリストで書いたもの。Phaserは両方読めます。 - multiatlas
texturesリストを持つJSON 1つ。ページ画像ごとに1項目。
例：Phaserが受け取る走りモーション
run.png 38 × 50px、40 × 29のフレーム6枚、トリムあり、間隔2、回転なし
"run_0": { "frame": {"x":0,"y":34,"w":18,"h":15},
"spriteSourceSize": {"x":10,"y":10,"w":18,"h":15},
"sourceSize": {"w":40,"h":29}, "rotated": false, "trimmed": true }
"pivot": {"x":0.5,"y":1} → スプライトの原点 (0.5, 1)：両足の間の点
run.anims.json { "key":"run", "frameRate":10, "repeat":-1, "yoyo":false,
"frames":[ {"key":"run","frame":"run_0","duration":100}, … ×6 ] }
this.add.sprite(100, 100, "run", "run_0")
→ 足が (100, 100) に立つ40 × 29のスプライト。18 × 15の断片はその中の (10, 10) に描かれる
6フレーム × 100ms = 0.6秒で1周。repeat -1 = 無限ループPhaserのrepeatは追加の再生回数を数えます。AsepriteやStudioで3回再生にしたタグはrepeat: 2と書かれ、ピンポンのタグはyoyo: trueになります。
できること
- アトラスのJSONハッシュ、フレームが複数ページにまたがる場合はmultiatlas。
- タグごとに1アニメーション、フレームごとの長さ入りの.anims.json（this.anims.fromJSON用）。
- Phaser向けは回転オフ。3.90・4.2とも回転したTexturePackerフレームの向きを正しく戻して描けなかったためです。
- フレームのオフセットを保つトリム、同一フレームの統合、余白と縁の拡張。
使い方
- 連番フレーム、GIF、.asepriteをドロップ。
- タイムラインでアニメーションを確認。
- パック＆書き出しでPhaser 3 / 4プリセットを選ぶ。
- this.load.atlas（またはmultiatlas）でアトラス、this.anims.fromJSONでアニメーションを読み込み。
出力されるファイル
| ファイル | 用途 |
|---|---|
run.json | 1ページ用のアトラスJSONハッシュ：frame、trimmed、spriteSourceSize、sourceSize、rotated、正規化したpivotを持つframesと、meta.image、meta.size。 |
run.multiatlas.json | フレームが複数ページにまたがるときにrun.jsonの代わりに作成：run-0.png、run-1.png …とそのフレームを持つtexturesリスト。 |
run.anims.json | タグごとに1つのアニメーション：ms単位のduration付きフレーム、frameRate、repeat（−1 = ループ）、ピンポン用のyoyo。タグがなければ作らない。 |
run.png | パックしたページ。256色以下ならインデックスPNG。 |
README-PHASER.md | このバンドル用のpreloadとcreateのコード。 |
Phaser 3・4で使う
- PNGとJSONファイルを一緒にゲームのassetsフォルダーへコピーします。multiatlasはJSON内の画像名でページを探します。
preload()でthis.load.atlas("run", "assets/run.png", "assets/run.json")（またはthis.load.multiatlas("run", "assets/run.multiatlas.json", "assets/")）とthis.load.json("run-anims", "assets/run.anims.json")を呼びます。create()でthis.anims.fromJSON(this.cache.json.get("run-anims"))によりアニメーションを登録し、const hero = this.add.sprite(160, 120, "run", "run_0")のあとhero.play("run")を呼びます。- ドット絵ならゲームを
pixelArt: trueで作成します。antialiasをオフ、roundPixelsをオンにする設定です。 - アニメーションを自分で作るなら
this.anims.create({ key: "run", frames: this.anims.generateFrameNames("run", { prefix: "run_", start: 0, end: 5 }), frameRate: 10, repeat: -1 })を使います。
結果の確認
this.textures.get("run").getFrameNames()にrun_0 … run_5が拡張子なしで並ぶはずです。this.add.image(100, 100, "run", "run_0")と"run_4"を同じ点に置きます。保存された断片のオフセットが違っても、足は一直線にそろうはずです。this.anims.exists("run")が真で、hero.play("run")の1周が0.6秒になるはずです。
トラブルシューティング
| 症状 | 考えられる原因 | 確認方法 | 対処 |
|---|---|---|---|
| フレーム名で違う絵が出る・何も出ない | このキーの下にその名前がない：打ち間違い、拡張子が残っている、別のテクスチャキー | this.textures.get(key).getFrameNames() | JSONにある名前をそのまま使う。Nerulioは拡張子を外す（run_0であってrun_0.pngではない） |
| 一部のフレームだけ反転・回転して見える | 回転ありでパックしたアトラス（例：回転を有効にしたTexturePacker）。Phaser 3.90と4.2はこうしたフレームを戻せなかった | その項目に"rotated": true | 回転なしでパックし直す。Phaserのアトラスのフレームがおかしいを参照 |
| ドット絵がぼやける・動くとちらつく | 線形フィルターとピクセルの間の位置 | ゲーム設定にpixelArt: trueがない | pixelArt: true、またはantialias: falseとroundPixels: true |
play("run")で何も起きない | アニメーションが登録されていない：JSONの読み込み前にfromJSONを実行した、または別のキャッシュキーを読んだ | this.anims.exists("run") | preload後のcreate()でthis.anims.fromJSON(this.cache.json.get("run-anims"))を呼ぶ |
| 再生速度がエディターと違う | play()に渡したframeRateがアニメーションの値と違い、Phaserがフレームごとのdurationではなく1フレームあたりのミリ秒を使う | 再生設定を見る | frameRateを上書きせず、長さはタグ側で変える |
ほかの方法
| 方法 | こんなときに向いています |
|---|---|
PhaserのAsepriteローダー：this.load.asepriteとthis.anims.createFromAseprite | 絵がAsepriteにあり、JSONのタグをそのまま使いたいとき。1ページのみ、回転なし。AsepriteからPhaserへを参照。 |
this.load.atlasXMLで読むStarling / Sparrow XML | すでにXMLを使うパイプライン（FNF形式の素材）。Phaser 3.90ではトリムをオフに。Sparrow XMLを参照。 |
| TexturePackerのPhaser書き出し | TexturePackerを持っているとき。Phaser形式は既定で回転せず、試した4セットすべてでPhaser 3.90と4.2に合格しました。 |
エンジン別の書き出しと検証方法
「検証済み」は、実際の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は完全一致。 |
検証の根拠
書き出し：実在のCC0アセットで実際のエンジンを49回実行し47回合格。失敗2回はPhaser 3.90のトリムXMLの不具合で、Phaser 3プリセットで回避。実在の5フレームセットでパッカー比較（CodeAndWeb無料Webパッカー、GAPTools、free-tex-packer）：回転ありで5つすべて最小、回転なしで5つ中4つ。全フレームがピクセル単位で復元できます。
制限
- ポリゴン（メッシュ）パッキングはありません。検証したエンジンのどれも、書き出しデータからメッシュアトラスを描画しないためです。
- GameMakerのストリップはGameMaker本体では未検証です。
- 拡大縮小バリエーション（@0.5x〜@4x）はニアレストネイバーのみです。
- トリムしたStarling XMLはPhaser 3.90で正しく描画されないため、「Sparrow XML (Phaser 3)」プリセットを使ってください。
バージョンと出典
Nerulioのアトラスとアニメーションのファイルを、実在のCC0フレームセットでPhaser 3.90.0と4.2.1（Chromium上の実際のphaser.min.js）に読み込み、全フレームを元画像と比較しました。ローダーとアニメーションの呼び出しはPhaser公式ドキュメントに、ピボットが原点になる動作とフレームの長さの扱いはPhaser 3.90のソースに基づきます。
参照した公式ドキュメント
よくある質問
回転がオフなのはなぜ？
テストでPhaser 3.90・4.2とも回転したTexturePackerフレームの向きを正しく戻して描けなかったため、Phaserプリセットは回転しません。
Phaser純正のAsepriteローダーでもいい？
はい。load.asepriteとcreateFromAseprite用のAseprite JSONを書き出せます。同じPhaserのバージョンで検証済みです。
無料ですか？アカウントは必要ですか？
このページの機能はすべて無料で、アカウントなしで使えます。透かしや制限された書き出しはありません。
スプライトはアップロードされますか？
いいえ。Studioはこのブラウザのタブ内でデコード・パック・書き出しを行います。プロジェクトはブラウザ（IndexedDB）に自動保存され、.nerulioファイルとして保存できます。
Asepriteやエンジンのプラグインは必要ですか？
いいえ。.asepriteファイルはブラウザで読み書きします。エンジン別のバンドルには必要なものが入っています（Godotはインポート設定とシーン、UnityとGodotのタイルセットは小さなエディタースクリプト）。