Aseprite JSONをPixiJSへ · タグをアニメーションに
Aseprite JSONをPixiJSで読み込むと、テクスチャはできてもアニメーションはできません。Spritesheetはフレームだけを読み、meta.frameTagsとフレームごとのdurationを使わないからです。JSONとPNGをここに入れてPixiJS 8向けに書き出し直すと、タグは再生順のanimationsマップに、スライスのピボットはanchorになり、ミリ秒はAnimatedSprite用に残ります。
PixiJS 8はAseprite JSONをスプライトシートとして読み込みますが、読むのはフレームだけです。meta.frameTagsと各フレームのdurationは無視され、sheet.animationsは空のままです。JSONとPNGを一緒にNerulioへドロップしてPixiJS 8で書き出すと、animationsマップ（タグごとに1項目、再生順のフレーム）、フレームごとのanchor、meta.nerulio.animationsのミリ秒が入ります。このミリ秒を{texture, time}としてAnimatedSpriteに渡します。PixiJS 8.21で確認済みです。
- PixiJS 8検証済み· PixiJS 8.21
- Godot 4検証済み· Godot 4.7.2
- Unity 6検証済み· Unity 6000.5.3f1
- Phaser 3 / 4検証済み· Phaser 3.90 + 4.2
- Aseprite JSON検証済み· Phaser load.aseprite · PixiJS 8.21
- .aseprite検証済み· Aseprite 1.3.18
- Spine / libGDX検証済み· spine-canvas 4.2
- Starling / Sparrow XML検証済み· Phaser 4.2
- LÖVE検証済み· LÖVE 11.5
- Defoldビルド確認· Defold bob.jar 1.13.1
- GameMaker未検証
- CSS sprites検証済み· Chromium
- GIF / APNGデコード確認· Pillow
PixiJSがスプライトシートJSONから読むもの
PixiJSのSpritesheetはTexturePackerの構造を受け取ります。frames（それぞれframe、spriteSourceSize、sourceSize、任意のanchor）、名前をフレーム名のリストに結びつける任意のanimationsオブジェクト、画像とscaleを持つmetaです。PixiJSのドキュメントによれば既定のアンカーとアニメーションのグループはTexturePacker形式のデータでのみサポートされ、AsepriteのframeTagsはこの形式にありません。検証でもPixiJSはframeTagsからアニメーションを作りませんでした。
AnimatedSpriteはテクスチャのリストを1つの速度で再生するか、timeがミリ秒の{texture, time}オブジェクトのリストを再生します。loop、updateAnchor、onCompleteなどのコールバックはありますが、ピンポンや繰り返し回数はないので、方向はフレーム順に展開して書く必要があります。
NerulioのPixiJS 8書き出しはその両方を行います。animations[tag]に1サイクルの再生順でフレームキーを並べ（逆方向・ピンポンは展開）、meta.nerulio.animations[tag]にfps、loop、direction、ステップごとに1つの数値を持つdurationsMsを入れ、テクスチャとそのまま組み合わせられるようにします。
- Spritesheet
- JSONを
texturesとanimationsに変換するPixiJSのクラス。 - FrameObject
{texture, time}：AnimatedSpriteの1ステップ、時間はミリ秒。- anchor
- フレームのテクスチャの既定アンカー（サイズに対する0–1）。Nerulioはフレームのピボットを書きます。
- related_multi_packs
- このページと一緒に読み込まれる他のJSONページ。
具体例：ピンポンのwalkタグをAseprite JSONからPixiJSへ
Aseprite JSON フレーム "4" … "9"、それぞれ "duration": 100
{ "name": "walk", "from": 4, "to": 9, "direction": "pingpong" }
PixiJS 8 JSON "animations": { "walk": ["4","5","6","7","8","9","8","7","6","5"] }
meta.nerulio.animations.walk.durationsMs = [100, 100, … 10個]
1サイクル: 6 + 4 = 10ステップ × 100 ms = 1.0 s
const { durationsMs, loop } = sheet.data.meta.nerulio.animations.walk;
const walk = new AnimatedSprite(sheet.animations.walk.map((texture, i) => ({ texture, time: durationsMs[i] })));
walk.loop = loop; walk.play();フレームキーはJSONのフレーム名から作られます。hero 4.asepriteのようなAsepriteの既定の名前ならhero_4になります。
何がどこに対応するか
| 書き出したJSONでは | PixiJSのAPI | すること |
|---|---|---|
animations[tag] | sheet.animations[tag]：テクスチャの配列 | {texture, time}オブジェクトに変換 |
meta.nerulio.animations[tag].durationsMs | FrameObject.time | ステップごとに1つ、同じ順 |
meta.nerulio.animations[tag].loop | AnimatedSprite.loop | 設定する。有限の繰り返し回数はPixiJSに対応がない |
frames[key].anchor（ピボット） | テクスチャの既定アンカー | フレームごとにピボットが違うならupdateAnchor = true |
meta.scale | sheet.resolution | @2xのシートが@1xのサイズで描かれる |
meta.related_multi_packs | 最初のページと一緒に読み込み（linkedSheets） | 他のページのテクスチャはキャッシュから取得 |
できること
- ハッシュ・配列形式のAseprite JSONを、frameTags（方向・繰り返し）とフレームごとの長さごと、シートのPNGと組にして読み込み。
- タグごとに1項目のanimationsマップ。フレームキーが再生順なので、逆再生やピンポンもコードなしで正しく再生。
- フレームごとにピボットからanchor：Pで置いたピボット、なければ下中央（JSONのmeta.slicesは読まない）。
- meta.nerulio.animationsにタグごとのfps・loop・方向・durationsMsを保存。READMEにその時間でAnimatedSpriteを作るコード。
- 複数ページはrelated_multi_packsでつないで一緒に読み込み、倍率違いはそれぞれのmeta.scaleを持つ。
使い方
- Aseprite JSONとPNGを一緒にドロップ。
- タイムラインでタグを確認し、anchorを変えたいところはPでピボットを動かす。
- パック＆書き出しでPixiJS 8を選ぶ。この書き出し先は回転を使えます。
- 書き出したJSONをAssets.loadで読み込み、meta.nerulioの時間でsheet.animationsからAnimatedSpriteを作る。
出力されるファイル
| ファイル | 用途 |
|---|---|
hero.json | PixiJS 8スプライトシート：anchor付きのframes、animations、meta.nerulio.animations。複数ページならhero-0.json、hero-1.json …がrelated_multi_packsでつながります。 |
hero.png | パック済みのページ（このターゲットは回転を許可します）。 |
README-PIXI.md | このバンドルを読み込み、AnimatedSpriteを作るコード。 |
PixiJS 8で再生する
hero.jsonとhero.pngを、アプリがアセットを配信する場所に並べて置きます。- ピクセルアートなら読み込み前に：
TextureSource.defaultOptions.scaleMode = 'nearest'。 const sheet = await Assets.load('hero.json')がページを読み込み、sheet.texturesとsheet.animationsを作ります。- 例のように
sheet.animations[tag]とdurationsMsからアニメーションを作り、loopを設定してplay()し、ステージに追加します。 - フレームごとにピボットが動くなら、AnimatedSpriteに
updateAnchor = trueを設定して各フレームが自分のアンカーを使うようにします。
結果の確認
Object.keys(sheet.animations)にAsepriteのタグ名がすべて出ます。- 1ステップ100 msの10ステップのピンポンwalkは1秒に1回ループし、
onLoopがその間隔で呼ばれます。 - キャンバスを拡大します。
nearestならピクセルの縁が四角いままです。
Aseprite JSONの項目とPixiJS 8での対応
| Aseprite JSON | PixiJS 8スプライトシートJSON | PixiJSでの扱い |
|---|---|---|
| frames[…].frame | 新しいページのframes[key].frame | テクスチャの範囲 |
| spriteSourceSize、sourceSize | 同じ項目 | トリムのオフセットを反映 |
| frames[…].duration | meta.nerulio.animations[タグ].durationsMs | 単独では使わない、AnimatedSpriteの時間として渡す |
| meta.frameTagsのfrom・to・direction | 再生順のanimations[タグ] | sheet.animations[タグ]でテクスチャ一覧 |
| frameTagsのrepeat | meta.nerulio.animations[タグ].loop | スプライトのloopを自分で設定 |
| meta.slicesのピボット（読まない。Pで置いたピボット、既定は下中央） | frames[key].anchor | テクスチャの既定のanchor |
| meta.image、1ページ | ページごとのmeta.imageとrelated_multi_packs | 残りのページも一緒に読み込み |
トラブルシューティング
| 症状 | 考えられる原因 | 確認方法 | 対処 |
|---|---|---|---|
sheet.animationsが空 | 書き出したファイルではなく元のAseprite JSONを読み込んでいます。PixiJSはframeTagsを無視します | Assets.loadがどのJSONを受け取っているか確認します | NerulioのPixiJS 8書き出しを読み込んでください |
| 全フレームが同じ速度で再生される | 時間なしでテクスチャだけ渡したため、animationSpeedが使われています | AnimatedSpriteの生成コードを見ます | durationsMsから作った{texture, time}オブジェクトを渡してください |
| フレーム間でスプライトが跳ねる・滑る | フレームごとにピボットが違うのに、スプライトが最初のフレームのアンカーのままです | frames[key].anchorの値を比べます | updateAnchor = trueにするか、Nerulioでタグのピボットを1つ（P）に揃えてください |
| アンカーがすべて下中央 | 読み込み時にAseprite JSONのmeta.slicesを読まないため、既定のピボットから始まっています | 書き出したファイルのanchorを見ます | NerulioでPキーでピボットを置くか、ピボットスライスを読める.asepriteファイル自体を読み込んでください |
| @2xのシートが2倍の大きさで描かれる | meta.scaleが1なので、PixiJSが解像度1として扱っています | sheet.resolution | Nerulioから@2xのバリアントを書き出してください。meta.scaleを"2"で書きます |
ほかの方法
| 方法 | こんなときに向いています |
|---|---|
frameTagsとdurationを読むローダーを自作する | パイプラインでAseprite JSONをそのまま使う必要があるとき。meta.frameTagsと長さを読み、FrameObjectを自分で作ります。 |
| .asepriteファイルから書き出す | .asepriteの元データがあるとき。Aseprite JSONの読み込みと違い、スライス（ピボット、ボックス）も読みます。 |
| バラのフレームからPixiJSスプライトシートを作る | フレームがAsepriteの書き出しではなく、別々のPNGのとき。 |
エンジン別の書き出しと検証方法
「検証済み」は、実際の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つ。全フレームがピクセル単位で復元できます。
制限
- Aseprite JSONの
meta.slicesは読みません。スライスのピボットには.asepriteファイルが必要です。 - PixiJSには繰り返し回数がなく、アニメーションはループするか1回再生するかのどちらかです。
- ポリゴン（メッシュ）パッキングはありません。検証したエンジンのどれも、書き出しデータからメッシュアトラスを描画しないためです。
- GameMakerのストリップはGameMaker本体では未検証です。
- 拡大縮小バリエーション（@0.5x〜@4x）はニアレストネイバーのみです。
- トリムしたStarling XMLはPhaser 3.90で正しく描画されないため、「Sparrow XML (Phaser 3)」プリセットを使ってください。
バージョンと出典
PixiJS 8ターゲットは、回転・複数ページのアトラスも含めてPixiJS 8.21が読み込んで描画し、@2xのバリアントはmeta.scaleに従って@1xのサイズで描かれました。ここに書いたPixiJSの挙動はPixiJS 8のAPIドキュメントに基づきます。
参照した公式ドキュメント
よくある質問
PixiJSはAsepriteのframeTagsを読みますか？
読みません。Spritesheetはフレームからテクスチャを作るだけなので、Aseprite JSONからはPixiJSでアニメーションができません。この書き出しはPixiJSが読むanimationsマップを書きます。
フレームごとに違う長さで再生するには？
meta.nerulio.animations[名前]のdurationsMsを読み、{texture, time}の組でnew AnimatedSpriteに渡してください。書き出したREADMEに例があります。ドット絵ならTextureSource.defaultOptions.scaleModeを'nearest'に。
PixiJSで確認しましたか？
はい。この書き出し先のファイルをPixiJS 8.21が読み込んで描画し、回転・複数ページのアトラスも含めて確認しました。
無料ですか？アカウントは必要ですか？
このページの機能はすべて無料で、アカウントなしで使えます。透かしや制限された書き出しはありません。
スプライトはアップロードされますか？
いいえ。Studioはこのブラウザのタブ内でデコード・パック・書き出しを行います。プロジェクトはブラウザ（IndexedDB）に自動保存され、.nerulioファイルとして保存できます。
Asepriteやエンジンのプラグインは必要ですか？
いいえ。.asepriteファイルはブラウザで読み書きします。エンジン別のバンドルには必要なものが入っています（Godotはインポート設定とシーン、UnityとGodotのタイルセットは小さなエディタースクリプト）。