スプライトシート出力形式ガイド
Sprite sheet 本体は PNG です。metadata ファイルは loader、importer、custom script に各 frame の位置と名前を伝えます。形式を間違えると座標ずれ、frame name エラー、追加 parser 作業が発生します。このガイドでは Phaser、PixiJS、Unity、Godot、Web animation に合う形式を整理します。
形式が重要な理由
多くの export は PNG と metadata ファイルで構成されます。ただし各エンジンが読む metadata 構造は同じではありません。Phaser と PixiJS は TexturePacker 風 JSON を使うことが多く、CSS では background-position、Unity と Godot では native editor slicing、addon、または custom import が必要になることがあります。
画像ファイルは普遍的
PNG スプライトシート自体は出力形式に関係なく同じです。すべてのフレームが配置された 1 枚の高品質な画像が得られます。
メタデータが互換性を決める
付属ファイルにはフレーム座標（x、y、幅、高さ）、フレーム名、トリミングや回転などのオプションプロパティが含まれます。これが形式を区別するものです。
出力形式と対応エンジンの対応表
JSON Hash 形式
JSON Hash は frame name を object key にする形式です。Phaser 3 の標準的な TexturePacker 風 atlas 構造で、PixiJS loader でも named dictionary から frame を参照する workflow に向きます。
構造
各フレームは JSON オブジェクトのトップレベルキーとして保存されます。値にはスプライトシート内の x、y 位置、幅、高さ、およびオプションの isTrimmed フラグが含まれます。
Phaser と PixiJS atlas loader の安全な初期選択
Phaser 3 は this.load.atlas(...) で JSON Hash を読み込みます。PixiJS も spritesheet loader や Assets pipeline で TexturePacker 風 JSON Hash を扱いやすいです。runtime が frame name で参照する場合に選びます。
高速なフレームアクセス
Hash 形式はフレーム名による O(1) 検索を提供します。コードが正確なフレーム名（idle_0001、walk_left_0005）を知っている場合、配列を反復せずに直接アクセスできます。
JSON Array 形式
JSON Array は frame を順序付き list として保存します。custom pipeline や converter、順序を重視する animation code には便利ですが、parser がその schema を要求していない限り PixiJS の default atlas 形式とは考えないでください。
構造
フレームは frames キーの下の配列に保存されます。各配列要素には同じ矩形データに加えてファイル名文字列が含まれます。順序はアップロードまたは生成されたフレームシーケンスと一致します。
順序重視の custom workflow 向け
自作 importer が index 順に frame を読む場合、metadata を変換する場合、または特定の engine plugin が array input を明記している場合に選びます。PixiJS/Phaser の atlas loading では通常 JSON Hash がより安全です。
インデックスベースのアクセス
フレーム名はまだ使用できますが、配列形式は予測可能な順序付けを提供します。これは、ゲームロジックがシーケンシャルにフレームを反復する場合（固定ステップ順のアニメーション）に役立ちます。
XML TextureAtlas 形式
XML TextureAtlas は TexturePacker/Sparrow 系の metadata 形式です。対応 tool や addon が明記されている場合は有用ですが、Unity や Godot が任意の generic XML を自動で animation frames に変換するわけではありません。
構造
XML root は imagePath 属性を持つ TextureAtlas です。各 SubTexture は name、x、y、width、height を持ち、trim 用に frameX/frameY/frameWidth/frameHeight を含むことがあります。
Unity workflow
Unity は通常 PNG から始めます。Sprite Mode を Multiple にし、Sprite Editor で slice するか Unity Sprite Atlas を使います。XML TextureAtlas には対応 third-party importer または custom editor script が必要です。
Godot workflow
Godot 4 では PNG を SpriteFrames、Sprite2D regions、AtlasTexture resources として使うのが基本です。XML/JSON 座標は addon、plugin、custom GDScript parser がある場合のみ役立ちます。
Importer 依存の連携
XML は metadata 交換用ファイルであり universal native import ではありません。export 前に engine version、plugin、build pipeline が TextureAtlas/SubTexture をサポートするか確認してください。
CSS スプライト形式
CSS スプライト形式は、各フレームの background-position ルールを含むスタイルシートを出力します。これはゲームエンジンをまったく必要としない Web アニメーション、UI アイコン、CSS ベースのゲームに最適です。
構造
CSS ファイルは、スプライトシート URL に background-image を設定し、background-position を正しいピクセルオフセットに設定した各フレーム名のクラスを定義します。負の値は背景画像を左または上にシフトします。
Web アニメーションに最適
CSS スプライトをホバー状態、ボタンアニメーション、または純粋な Web プロジェクトのシンプルなキャラクターアニメーションに使用します。要素にクラスを追加し、必要に応じて CSS トランジションで background-position を切り替えたりアニメーション化したりします。
JavaScript 不要
基本的なスプライト再生は HTML と CSS のみで動作します。JavaScript でスプライトシートをロードしたり JSON をパースしたりする必要はありません。フレームクラスを適用し、必要に応じて位置をアニメーション化するだけです。
形式選択のワークフロー
一般的な形式の問題
ほとんどのスプライトシートインポートエラーは形式の不一致です。エンジンはある構造を期待していますが、別の形式をエクスポートしました。これらは警告サインと修正方法です。
フレーム名が見つからないエラー
コードがフレーム walk_left_0001 を参照しているが、JSON が walkLeft0001 を使用している場合に発生します。エクスポートされたメタデータファイルを確認し、コード内のフレーム名を更新するか、正しい命名規則でスプライトシートを再生成します。
座標がビジュアルと一致しない
スプライトがオフセットまたはトリミングして表示される場合、JSON をエクスポートしたが、異なるパーサーをデフォルトとするエンジンで XML としてロードした（またはその逆）可能性があります。インポートコードがエクスポート形式と一致していることを確認してください。
アニメーションが間違ったフレームを再生する
フレームが順不同で再生される場合、エクスポート形式が意図されたシーケンスを保持していない可能性があります。エンジンが順序が保証されない Hash 形式を期待するかどうかを確認し、ゲームがシーケンシャルフレームアクセスに依存している場合は配列形式に切り替えます。
エンジンがメタデータをロードできない
Unity や Godot が metadata を読めない場合、原因は PNG ではなく importer support であることが多いです。まず native slicing/SpriteFrames を使うか、documented XML/JSON importer を追加してください。
スプライトシート出力形式 FAQ
正しい形式でエクスポート
Sprite Sheet Maker で一度作成し、実際の loader/importer に合う形式を選びます。座標、frame name、engine slicing が合わない場合は troubleshooting を確認してください。