Asepriteをスプライトシートに · タグを保ってパック
.asepriteをドロップしてパック＆書き出しを開くと、全フレームがワーカー内でその場でアトラスのページにパックされます。同じフレームは1回だけ格納し、空白の縁はオフセットを覚えたまま切り詰め、ファイルのタグとフレームごとの時間はエンジンが読むデータファイルにそのまま入ります。
.asepriteファイルをドロップしてパック＆書き出しを開くと、フレームがPNGにパックされ（トリム、同一フレームは1回だけ保存）、エンジンが読むデータファイルと一緒に書き出されます。Aseprite JSONターゲットはAseprite自身のFile > Export Sprite Sheetと同じ構造です。duration付きのframes、meta.frameTags、meta.slicesを、ハッシュか配列で、1ページに、PhaserのcreateFromAsepriteが前提とする0、1、…のフレームキーで書きます。Godot、Unity、PixiJSなど他のターゲットは、タグとタイミングをそれぞれの形式で持たせます。
- Phaser 3 / 4検証済み· Phaser 3.90 + 4.2
- Aseprite JSON検証済み· Phaser load.aseprite · PixiJS 8.21
- 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
- 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
Aseprite JSON付きスプライトシートの中身
スプライトシートは、全フレームを載せた画像1枚と、各フレームの位置を示すデータファイルです。Aseprite JSONのフレーム項目には、frame（シート上の矩形）、rotated、trimmed、spriteSourceSize（元のキャンバス内でのトリム後の矩形の位置）、sourceSize（キャンバス）、ミリ秒のdurationがあります。metaには画像名・サイズ・スケールがあり、指定すればframeTags（name、from、to、direction）とslicesが入ります。
ハッシュと配列の違いはframesだけです。ハッシュはフレーム名をキーにしたオブジェクト、配列は各項目にfilenameを持つリストです。フレーム名はAsepriteのファイル名形式から決まり、PhaserのcreateFromAsepriteはアイテムのファイル名が{frame}だけであることを前提にしているので、キーは0、1、2 …になります。
タグはフレームリスト上のfrom–toの範囲なので、各タグは1つの連続した並びでなければなりません。Nerulioはパックしてもこれを守ります。2つのタグが共有するフレームや、順番の乱れたタグのフレームには同じ領域を指す項目をもう1つ作り、書き出しメモに繰り返した項目の数を書きます。
- spriteSourceSize
- 元のフレーム内での、トリム後のピクセルの位置とサイズ。
- sourceSize
- トリム前の元のフレーム（キャンバス）サイズ。
- frameTags
- Asepriteのアニメーション：名前、最初と最後のフレーム、方向、設定されていれば繰り返し回数。
- エイリアス
- 見えるピクセルが他のフレームと同じフレームは1回だけ保存し、両方の項目がそこを指します。
具体例：トリムされたフレーム1つとタグ2つのJSON
"0": { "frame": { "x": 0, "y": 0, "w": 18, "h": 29 }, "rotated": false, "trimmed": true,
"spriteSourceSize": { "x": 7, "y": 3, "w": 18, "h": 29 },
"sourceSize": { "w": 32, "h": 32 }, "duration": 125 }
"frameTags": [
{ "name": "idle", "from": 0, "to": 3, "direction": "forward", "color": "#6acd5bff" },
{ "name": "attack", "from": 10, "to": 15, "direction": "forward", "color": "#fe5b59ff", "repeat": "1" } ]
"slices": [ { "name": "pivot", "color": "#0000ffff", "keys": [
{ "frame": 0, "bounds": { "x": 0, "y": 0, "w": 32, "h": 32 }, "pivot": { "x": 16, "y": 32 } } ] } ]
トリム: 32 × 32 = 1024 px² → 18 × 29 = 522 px² だけ保存 (−49 %)、(7, 3) に描き戻す無限ループのタグにはrepeatがなく、1回再生のタグは"repeat": "1"です。ピボット(16, 32)は32 × 32キャンバスの下中央で、ファイルにピボットスライスがないときに使います。キーは元ファイルではなく、このリストでの位置です。
何がどこに対応するか
| .asepriteでは | Aseprite JSONでは | 補足 |
|---|---|---|
| フレームのピクセル（表示中の全レイヤー） | PNG上のトリム後の領域：frame + spriteSourceSize | レイヤーは合成、同一フレームは1回だけ保存 |
| フレームの長さ | msのduration | 整数ミリ秒 |
| タグ | from、to、directionを持つmeta.frameTagsの項目 | 共有・順不同のフレームは項目を追加 |
| 繰り返し | 有限なら文字列のrepeat | 無限ループのタグにはない |
| ピボットスライス（なければ下中央） | meta.slicesのpivotスライス、変わる位置にキー | 範囲 = フレームのキャンバス |
| ヒット・ハートボックス | 種類と番号ごとにスライス1つ、ボックスが終わる位置に空のキー | 矩形のみ |
| レイヤー | meta.layersに1項目（Layer 1） | シートには合成済みのフレーム |
| ページ | PNGちょうど1枚 | このターゲットは1ページにパックし直す |
できること
- パッカー：配置ルール5種のMaxRects、Skyline、Guillotine。「すべて試す」で最小のページを選び、同じ入力なら常に同じバイト列。
- トリムはフレームのサイズとオフセットを保持、crop-keepはフレームを小さくしつつピボットを動かして絵の位置を保つ。見えるピクセルが同じフレームはバイト照合のうえ1回だけ格納。
- ページ：最大64枚、上限8〜16384px、2のべき乗・正方形・固定サイズ、外周と図形間の余白、縁の拡張。
- @0.5x〜@4xの倍率違い（ニアレストネイバーのみ）。整数倍の拡大はピクセルをそのまま複製。
- Aseprite本体の「スプライトシートを書き出し」と同じ形のAseprite JSON（ハッシュ・配列）：方向と繰り返し入りのframeTags、フレームごとのduration、ピボットとボックスのスライス。
使い方
- .asepriteをドロップ。スプライト作業画面がレイヤー・タグ・長さを読み込む。
- パック＆書き出しを開く。設定を変えるたびにパックし直して表示し、長い処理は取り消せます。
- エンジンのプリセットかAseprite JSONを選ぶ。1ページ限定や回転不可の書き出し先はパックし直し、変わった点をボタンの横に表示。
- パック済みフレームの一覧で、トリムされたフレームや統合されたフレームを確認。
- 書き出しを押し、PNGのページとデータファイルをプロジェクトに展開。
出力されるファイル
| ファイル | 用途 |
|---|---|
hero.png | パック済みのシート。このターゲットでは1ページです。 |
hero.json | frameTagsとslicesを持つAseprite JSON（ハッシュまたは配列）。 |
README-ASEPRITE-JSON.md | これらのファイルをPhaserで読み込むコードと、PixiJSがここから何を読むか。 |
Phaser 3・4で読み込む
hero.pngとhero.jsonをゲームのアセットフォルダにコピーします。preload()で：this.load.aseprite('hero', 'hero.png', 'hero.json')。create()で：this.anims.createFromAseprite('hero')がタグごとにタグ名のアニメーションを作ります。- 追加して再生：
this.add.sprite(100, 100, 'hero').play('walk')。ピクセルアートならゲームをpixelArt: trueで作成してください。
Godot、Unity、PixiJSにはAseprite JSONではなくそれぞれのターゲットを選んでください。AsepriteからGodotへ、AsepriteからUnityへ、Aseprite JSONからPixiJSへを参照。
結果の確認
framesの項目数は、フレーム数に書き出しメモが示す繰り返し項目数を足した数です。- ゲームでタグを再生し、1サイクルの時間をAsepriteと比べます（walk：6 × 100 ms = 0.6秒）。
hero.pngを開きます。トリムされたフレームが詰めてパックされ、同じフレームをグリッドで書き出すよりシートが小さくなっています。
1つの.asepriteから作れるシート
| 出力 | データファイル | タグと時間 | 確認方法 |
|---|---|---|---|
| Aseprite JSON（ハッシュ・配列） | meta.frameTagsとmeta.slices入りの<名前>.json | 方向・繰り返し付きのfrom..to、フレームごとのms | Phaser 3.90・4.2のload.aseprite、PixiJS 8.21のフレーム |
| Phaser 3 / 4 | アトラスJSONハッシュかmultiatlas＋.anims.json | タグごとにアニメーション、フレームごとの長さ | Phaser 3.90・4.2 |
| PixiJS 8 | animationsとanchor入りのspritesheet JSON | animationsに再生順、msはmeta.nerulio | PixiJS 8.21 |
| Godot 4 | SpriteFrames .tres＋AnimatedSprite2D .tscn | タグごとのspeed、相対的な長さ、ループ | Godot 4.7.2 |
| 汎用JSON | TexturePacker形式のframes、animationData、ピボット、ボックス | 独自のアニメーション項目に保持 | Phaser 3.90・4.2とPixiJS 8.21がTexturePackerハッシュとして読む |
| Spine / libGDXアトラス | .atlasテキスト | なし（アトラスは領域だけを持つ） | spine-canvas 4.2が全領域を描画 |
トラブルシューティング
| 症状 | 考えられる原因 | 確認方法 | 対処 |
|---|---|---|---|
| 「Aseprite JSON describes one sheet image」エラー | 現在のページサイズ上限では、フレームが1ページに収まりません | パック＆書き出しのページサイズ設定 | ページ上限を上げるか、Phaserプリセット（マルチアトラス）かPixiJS 8（リンクされたページ）を使ってください |
| Phaserでアニメーションができない | JSONにframeTagsがないか、キーが単純なフレーム番号ではありません | framesの最初のキーとmeta.frameTagsの有無を見ます | NerulioのAseprite JSONを使うか、Asepriteから書き出すときにItem Filenameを{frame}にし、MetaのTagsをオンにしてください |
| 自作ローダーでフレームが跳ねる | spriteSourceSizeを無視しているため、トリムされたフレームがオフセットを失っています | トリムされたフレームの位置をspriteSourceSizeと比べます | 各フレームをsourceSize内のspriteSourceSize.x/yに描くか、トリムをオフにしてください |
| 読み込み側でフレームが横倒しになる | パック時に回転を許可しました。Aseprite自身は回転したフレームを書きません | framesに"rotated": true | この書き出しでは回転をオフにしてください |
| ゲームでピクセルアートがぼやける | エンジンがテクスチャを線形フィルタで描いています | 縁を拡大してみます | Phaserはゲーム設定でpixelArt: true、他のエンジンはニアレストのフィルタ |
ほかの方法
| 方法 | こんなときに向いています |
|---|---|
AsepriteのFile > Export Sprite Sheet、またはaseprite -b hero.aseprite --sheet hero.png --data hero.json --format json-array --list-tags --list-slices | Asepriteがあり、その配置オプションを使いたいとき。--sheet-type packedでパック、--trimでトリムします。 |
| Aseprite JSONではなくエンジンのターゲット | エンジンがAseprite JSONからアニメーションを作らないとき（PixiJS、Godot、Unity）。ターゲットごとに何が残るかを参照。 |
エンジン別の書き出しと検証方法
「検証済み」は、実際の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は1ページです。非常に大きなセットにはマルチパック対応のエンジンプリセットが必要です。
- レイヤーを別々のシートとしては書き出しません。
- ポリゴン（メッシュ）パッキングはありません。検証したエンジンのどれも、書き出しデータからメッシュアトラスを描画しないためです。
- GameMakerのストリップはGameMaker本体では未検証です。
- 拡大縮小バリエーション（@0.5x〜@4x）はニアレストネイバーのみです。
- トリムしたStarling XMLはPhaser 3.90で正しく描画されないため、「Sparrow XML (Phaser 3)」プリセットを使ってください。
バージョンと出典
NerulioのAseprite JSONは、Phaser 3.90と4.2がload.asepriteとcreateFromAsepriteで読み込み、PixiJS 8.21がフレームを読みました。Aseprite自身が作ったJSONも基準として同じ検査に通っています。元になる.asepriteの読み込みは実ファイル231個で確認済みです。上のAsepriteとPhaserの内容はそれぞれの公式ドキュメントに基づきます。
参照した公式ドキュメント
よくある質問
Aseprite JSONが1ページだけなのはなぜ？
Aseprite JSONは1ファイルで1枚の画像を表し、Phaserのload.asepriteもそう読むため、この書き出し先は1ページにパックし直します。複数ページが必要ならPhaserプリセット（multiatlas）か、ページをrelated_multi_packsでつなぐPixiJS 8を使ってください。
フレームキーが"0"、"1"、"2"なのはなぜ？
PhaserのcreateFromAsepriteが番号でフレームを探すため、--filename-format "{frame}" の形で書きます。Phaser 3.90・4.2がload.asepriteで読み込み、PixiJS 8.21もフレームを読みました。
2つのタグが同じフレームを使うと片方が消えますか？
消えません。Aseprite JSONのタグはfrom..toの範囲なので、2つのタグが共有するフレームや順番が入れ替わったタグのフレームには、同じ領域を指す項目をもう1つ作ります。いくつ繰り返したかは書き出し時に表示されます。
無料ですか？アカウントは必要ですか？
このページの機能はすべて無料で、アカウントなしで使えます。透かしや制限された書き出しはありません。
スプライトはアップロードされますか？
いいえ。Studioはこのブラウザのタブ内でデコード・パック・書き出しを行います。プロジェクトはブラウザ（IndexedDB）に自動保存され、.nerulioファイルとして保存できます。
Asepriteやエンジンのプラグインは必要ですか？
いいえ。.asepriteファイルはブラウザで読み書きします。エンジン別のバンドルには必要なものが入っています（Godotはインポート設定とシーン、UnityとGodotのタイルセットは小さなエディタースクリプト）。