バイナリ出力形式

ここでは、Spineのスケルトンとアニメーションデータのバイナリ出力形式について説明します。Spineランタイムは、このデータをロードしてアニメーションを表示します。また、Spineはこの形式のデータをインポートすることができ、他のツールとの相互運用が可能です。実際にバイナリ形式でエクスポートされたファイルを確認するには、Spineランタイムの各種プロジェクト例をご覧ください。

SpineランタイムはJSONやバイナリデータのロードを行います。独自のランタイムをゼロから書く場合（これは膨大な作業量になります）を除き、独自のロードコードを書く必要はありません。

バイナリ形式はファイルサイズが非常に小さく、ランタイムでの読み込みも非常に高速です。デメリットは、データのロードに影響を与えるようなランタイムの変更があった場合、Spineプロジェクトからそのバイナリデータを再エクスポートする必要があることです。また、バイナリ形式は非可読形式なので、データの検査にはJSON形式の方が適している可能性があります。

「※非必須」とマークされたデータは、エクスポート設定の非必須データ(Nonessential data)がチェックされている場合のみ出力されます。このデータはレンダリングには必要ありませんが、ツールやSpineにデータをインポートする際に役立つ場合があります。

バイナリ形式は、ボーン、スロット、コンストレイント、スキン、アニメーションのリストを持つ”skeleton data”インスタンスをシリアライズしたものです。これは、画面上の特定のスケルトンインスタンスに結びつかないステートレス(処理状態を把握しない)データです。

データ型

バイナリ形式では、いくつかの基本的なデータ型が使用されます。参考までにC言語でのコード例を示します。

Boolean

booleanは1バイトで、trueの場合は1を、falseの場合は0を格納します。

Short

shortは16ビットで、2バイトとして格納されます。

Int

intは32ビットで、4バイトとして格納されます。

Varint

varintはint型ですが、値によって1バイトから5バイトで格納されます。varintには2種類あり、varint+は小さな正の値、varint-は小さな負の値（および正の値）に対して容量を取らないように最適化されています。

varint の各バイトについて、追加のバイトがある場合は MSB が設定されます。結果が小さな負の値に対して最適化されている場合は、シフトされます。

Float

floatは32ビットで、4バイトとして格納されます。言語やアーキテクチャによっては、バイトを組み合わせてintにし、さらにfloatに変換することも可能です。

String

stringは、varint+lengthに0個以上のUTF-8文字が続くものです。lengthが0の場合、stringはnullです（ほとんどの場合、空と同じと考えることができます）。lengthが1であれば、stringは空です。それ以外の場合は、length の後にlength - 1バイトの文字列が続きます。UTF-8文字は1バイト以上であることがあるので、UTF-8文字よりもバイト数が多い場合があります。

アタッチメント名など、スケルトンデータ全体で共有できる文字列(shared strings)もあります。ファイルサイズを小さくするために、shared stringsはすべてバイナリフォーマットの最初のメタデータセクションの後にリストとして格納されます。

このリストから読み出すべきstringを、以下ではref stringと表記します。ref stringは、shared stringsのリストへのvarint+インデックスです。インデックスが0の場合、stringはnullです（ほとんどの場合、空と同じと考えることができます）。それ以外の場合は、インデックス値を1つ減らして、shared stringsのリストへのインデックスを作成します:

Color

colorはRGBA値でint型に格納されます。

定数

場所によっては、識別のために定数が使用されます。定数は1バイトです。定数は接頭語をALLCAPS(全て大文字)で表示します。

フォーマット

データは以下の順番で表示されます:

string hash: すべてのそのスケルトンデータのハッシュ。これは、ツールで前回ロードしたときからデータが変更されたかどうかを検出するために利用することができます。

string version: そのデータをエクスポートしたSpineのバージョン。これは、ツールで特定のSpineのバージョンを強制的に使用するために利用することができます。

float x: Spineで設定したセットアップポーズにおける、スケルトンのアタッチメントのAABB(軸に沿ったバウンディングボックス)の左下のx座標。

float y: Spineで設定したセットアップポーズにおける、スケルトンのアタッチメントのAABBの左下のy座標。

float width: Spineで設定したセットアップポーズにおける、スケルトンのアタッチメントのAABB幅。スケルトンのAABBはポーズの取り方によって異なりますが、これはスケルトンの一般的なサイズとして使用できます。

float height: Spineで設定したセットアップポーズにおける、スケルトンのアタッチメントのAABBの高さ。

boolean nonessential: false の場合、非必須データは省略されます。

float fps: Spine内でのドープシートのフレームレート(frames per second)。省略された場合は 30 となります。※非必須

string images: Spine内でのイメージパス。※非必須

string audio: Spine内でのオーディオパス。※非必須

varint+ string count: 後に続く共有文字列(shared strings)の数。

各stringごとに:

string shared string: スケルトン内のデータ間で共有されるstring。すべてのshared stringsのリストに追加されます。

varint+ bone count: 後に続くボーンの数。

各ボーンごとに:

string name: ボーンの名前。これはスケルトンにおいてユニーク(一意)になります。

varint+ parent index: 親ボーンのインデックスに1を足した値です。rootボーンでは、この値は省略されます。

float rotation: セットアップポーズにおける、親に対するボーンの回転 (度)。

float x: セットアップポーズにおける親に対するボーンの X 位置。

float y: セットアップポーズにおける親に対するボーンの Y 位置。

float scaleX: セットアップポーズにおけるボーンの X スケール。

float scaleY: セットアップポーズにおけるボーンの Y スケール。

float shearX: セットアップポーズにおけるボーンのシアー X。

float shearY: セットアップポーズにおけるボーンのシアー Y。

float length: ボーンの長さ。ボーンの長さは、2つのボーンによるIKとボーンのデバッグラインの描画を除いて、実行時にはあまり使用されません。

TRANSFORM_* transform mode: 親ボーンのトランスフォームをどのように継承するかを決定します。

boolean skin required: trueの場合、アクティブなスキンがボーンを持っているときのみ、このボーンはアクティブになります。

color color: Spine内でのボーンのカラー。※非必須

varint+ slot count: 後に続くスロットの数。

各スロットごとに:

string name: スロットの名前。これはスケルトンにおいてユニーク(一意)になります。

varint+ bone index: このスロットがアタッチされているボーンのインデックス。

color color: セットアップポーズにおけるスロットのカラー。

dark color: セットアップポーズにおけるスロットのダークカラー。スロットがティントブラックを使用しない場合は-1になります。

ref string attachment: セットアップポーズ用のスロットのアタッチメントの名前。null の場合、セットアップポーズではアタッチメントが無いということになります。

BLEND_MODE_* blend: スロットの表示アタッチメントを描画する際に使用するブレンドのタイプ。

varint+ ik constraint count: 後に続くコンストレイントの数。

各コンストレイントごとに:

string name: コンストレイントの名前。これはスケルトンにおいてユニーク(一意)になります。

varint+ order index: コンストレイントが適用される順番を表す序数。

boolean skin required: trueの場合、アクティブなスキンがコンストレイントを持つときのみこのコンストレイントが適用されます。

varint+ bone count: 後に続くボーンの数( 1 または 2 )。

各ボーンごとに:

varint+ bone index: コンストレイントによって回転が制御されるボーンのインデックス。

varint+ target index: ターゲットボーンのインデックス。

float mix: 0 から 1 の値で、コンストレイントがボーンに及ぼす影響を示します。0 は FK のみ、1 は IK のみ、そして中間は FK と IK のミックスを意味します。

float softness: 2つのボーンによるIKのための値で、回転が遅くなるボーンの最大到達点からの距離を表しています。

byte bendDirection: 1 の場合、ボーンは正の回転方向に曲がります。-1の場合、ボーンは負の回転方向に曲がります。

boolean compress: true の場合、単一のボーンのみが制約され、ターゲットが近すぎる場合、ボーンはそれに到達するようにスケーリングされます。

boolean stretch: trueかつターゲットが範囲外である場合、親ボーンはターゲットに達するようにスケーリングされます。複数のボーンが制約され、親ボーンが非均一なローカルスケールを持つ場合、ストレッチは適用されません。

boolean uniform: trueの場合、単一のボーンのみが制約され、compress(圧縮) または stretch(ストレッチ) が使用されると、そのボーンはX軸とY軸の両方でスケーリングされます。

varint+ transform constraint count: 後に続くコンストレイントの数。

各コンストレイントごとに:

string name: コンストレイントの名前。これはスケルトンにおいてユニーク(一意)になります。

varint+ order index: コンストレイントが適用される順番を表す序数。

boolean skin required: trueの場合、アクティブなスキンがコンストレイントを持つときのみこのコンストレイントが適用されます。

varint+ bone index: コンストレイントによってトランスフォームが制御されるボーンのインデックス。

varint+ target index: ターゲットボーンのインデックス。

boolean local: trueの場合はターゲットのローカルトランスフォームが影響を受け、そうでない場合はワールドトランスフォームが影響を受けます。

boolean relative: trueの場合はターゲットのトランスフォームが相対的に調整され、そうでない場合はトランスフォームが絶対的に設定されます。

float offset rotation: ターゲットボーンからオフセットする回転値。

float offset x: ターゲットボーンからオフセットするX距離。

float offset y: ターゲットボーンからオフセットするY距離。

float offset scale x: ターゲットボーンからオフセットするXスケール。

float offset scale y: ターゲットボーンからオフセットするYスケール。

float offset shear y: ターゲットボーンからオフセットするYシアー。

float rotate mix: 0から1までの値で、コンストレイントがボーンに及ぼす影響を示します。0は影響なし、1は制約のみ、そして間は通常のポーズとコンストレイントのミックスを意味します。

float translate mix: rotate mixと同様です。

float scale mix: rotate mixと同様です。

float shear mix: rotate mixと同様です。

varint+ path constraint count: 後に続くコンストレイントの数。

各コンストレイントごとに:

string name: コンストレイントの名前。これはスケルトンにおいてユニーク(一意)になります。

varint+ order index: コンストレイントが適用される順番を表す序数。

boolean skin required: trueの場合、アクティブなスキンがコンストレイントを持つときのみこのコンストレイントが適用されます。

varint+ bone count: 後に続くボーンの数。

各ボーンごとに:

varint+ bone index: その回転および/またはトランスレートがコンストレイントによって制御されるボーンのインデックスです。

varint+ target index: ターゲットスロットのインデックス。

PATH_POSITION_* position mode: パスの位置の計算方法を決定します。

PATH_SPACING_* spacing mode: ボーン間の間隔をどのように計算するかを決定します。

PATH_ROTATE_* rotate mode: ボーンの回転をどのように計算するかを決定します。

float offset rotation: パスの回転からオフセットする回転値を指定します。

float position: パスの位置。

float spacing: ボーンとボーンの間の間隔。

float rotate mix: 0から1までの値で、コンストレイントがボーンに及ぼす影響を示します。0は影響なし、1は制約のみ、そして間は通常のポーズとコンストレイントのミックスを意味します。

float translate mix: rotate mixと同様です。

Skin default skin: Spineでスキンが割り当てられていないアタッチメントを保持する、デフォルトスキンのアタッチメント。デフォルトスキンは、名前、ボーン、IKコンストレイント、トランスフォームコンストレイント、パスコンストレイントを含まないことに注意してください!

varint+ skin count: 続くスキンの数。

各スキンごとに:

ref string name: スキンの名前。これはスケルトンにおいてユニーク(一意)になります。

varint+ bones count: そのスキンにおけるのボーンの数。

各ボーンごとに:

varint+ bone index: IKコンストレイントのインデックス。

varint+ ik constraint count: スキンのIKコンストレイントの数。

各IKコンストレイントごとに:

varint+ ik constraint index: IKコンストレイントのインデックス。

varint+ transform constraint count: スキンのトランスフォーム・コンストレイントの数。

各トランスフォームコンストレイントごとに:

varint+ transform constraint index: トランスフォーム・コンストレイントのインデックス。

varint+ path constraint count: スキンのパス・コンストレイントの数。

各パスコンストレイントごとに:

varint+ path constraint index: パスコンストレイントのインデックス。

Skin skin: スキンアタッチメント。

varint+ event count: 後に続くイベントの数。

各イベントごとに:

ref string name: イベントの名前。これはスケルトンにおいてユニーク(一意)になります。

varint- int: イベントのInteger(整数)の値。

float float: イベントのFloat(浮動小数点)の値。

string string: イベントのString(文字列)の値。

string audio: (このイベントがオーディオを再生するためのものである場合)オーディオファイルへのパス。

float volume: オーディオファイルの再生に使用するボリューム。

float balance: オーディオファイルの再生に使用するステレオバランス。

varint+ animation count: 後に続くアニメーションの数。

各アニメーションごとに:

varint+ slot count: 後に続くスロットの数。

各スロットごとに:

varint+ slot index: スロットのインデックス。

varint+ timeline count: 後に続くタイムラインの数。

各タイムラインごとに:

SLOT_* timeline type: スロットのタイムラインの種類。

varint+ frame count: タイムライン上のキーフレーム数。

SLOT_ATTACHMENT:

各キーフレームごとに:

float time: キーフレームの時間（秒）。

ref string attachment name: スロットに設定するアタッチメントの名前、またはスロットのアタッチメントをクリアするためのnull。

SLOT_COLOR:

各キーフレームごとに:

float time: キーフレームの時間（秒）。

color color: そのキーフレームでのスロットカラー。

Curve curve: そのキーフレームのカーブ。最後のキーフレームではカーブは省略されます。

SLOT_TWO_COLOR:

各キーフレームごとに:

float time: キーフレームの時間（秒）。

color light: そのキーフレームでのスロットのライトカラー。

color dark: そのキーフレームでのスロットのダークカラー。

Curve curve: そのキーフレームのカーブ。最後のキーフレームではカーブは省略されます。

varint+ bone count: 後に続くボーンの数。

各ボーンごとに:

varint+ bone index: ボーンのインデックス。

varint+ timeline count: 後に続くタイムラインの数。

各タイムラインごとに:

BONE_* timeline type: ボーンのタイムラインの種類。

varint+ frame count: タイムライン上のキーフレーム数。

BONE_ROTATE:

各キーフレームごとに:

float time: キーフレームの時間（秒）。

float rotation: そのキーフレームでの回転値。

Curve curve: そのキーフレームのカーブ。最後のキーフレームではカーブは省略されます。

BONE_TRANSLATE、BONE_SCALE、BONE_SHEAR:

各キーフレームごとに:

float time: キーフレームの時間（秒）。

float x: そのキーフレームでのX軸のトランスレート、スケール、またはシアー。

float y: そのキーフレームでのY軸のトランスレート、スケール、またはシアー。

Curve curve: そのキーフレームのカーブ。最後のキーフレームではカーブは省略されます。

varint+ ik constraint timeline count: 後に続くIKコンストレイントのタイムラインの数。

各IKコンストレイントのタイムラインごとに:

varint+ ik constraint index: IKコンストレイントのインデックス。

varint+ frame count: タイムライン上のキーフレーム数。

各キーフレームごとに:

float time: キーフレームの時間（秒）。

float mix: IKコンストレイントのミックス。

byte bend direction: IKコンストレイントの曲げ方向（ 1 または -1 ）。

Curve curve: そのキーフレームのカーブ。最後のキーフレームではカーブは省略されます。

varint+ transform constraint timeline count: 後に続くトランスフォーム・コンストレイントのタイムラインの数。

各トランスフォーム・コンストレイントのタイムラインごとに:

varint+ transform constraint index: トランスフォーム・コンストレイントのインデックス。

varint+ frame count: タイムライン上のキーフレーム数。

各キーフレームごとに:

float time: キーフレームの時間（秒）。

float rotate mix: トランスフォーム・コンストレイントの回転ミックス。

float translate mix: トランスフォーム・コンストレイントのトランスレートミックス。

float scale mix: トランスフォーム・コンストレイントのスケールミックス。

float shear mix: トランスフォーム・コンストレイントのシアーミックス。

varint+ path constraint entry count: 後に続くパスコンストレイントのエントリ数。

各パスコンストレイントのエントリごとに:

varint+ path constraint index: パスコンストレイントのインデックス。

varint+ path constraint timeline count: 後に続くパスコンストレイントのタイムラインの数。

各パスコンストレイントのタイムラインごとに:

PATH_* path constraint timeline type: パスコンストレイントのタイムラインの種類。

varint+ frame count: タイムライン上のキーフレーム数。

各キーフレームごとに:

float time: キーフレームの時間（秒）。

PATH_POSITION:

float position: パスコンストレイントの位置。

PATH_SPACING:

float spacing: パスコンストレイントの間隔。

PATH_MIX:

float rotate mix: パスコンストレイントの回転ミックス値。

float translate mix: パスコンストレイントのトランスレートミックス値。

Curve curve: そのキーフレームのカーブ。最後のキーフレームではカーブは省略されます。

varint+ skin count: 後に続くスキンの数。

各スキンごとに:

varint+ skin index: スキンのインデックス。

varint+ slot count: 後に続くスロットの数。

各スロットごとに:

varint+ slot index: スロットのインデックス。

varint+ deform timeline count: 後に続く変形のタイムラインの数。

各変形のタイムラインごとに:

ref string name: スキンやスロットにおけるアタッチメントの名前。

varint+ frame count: 変形のタイムラインのキーフレーム数。

各キーフレームごとに:

float time: キーフレームの時間（秒）。

varint+ end vertex: 最後の頂点値のインデックス。0の場合、start vertexと頂点の値は省略されます。

varint+ start vertex: 最初の頂点値のインデックス。

開始（含まれる）と終了（含まれない）の間の各頂点値ごとに:

float value: アタッチメントのセットアップポーズを基準にして、頂点を調整する量。

Curve curve: そのキーフレームのカーブ。最後のキーフレームではカーブは省略されます。

varint+ draw order count: 後に続く表示順序のキーフレームの数。

表示順序のキーフレームごとに:

float time: キーフレームの時間（秒）。

varint+ change count: 後に続く表示順序の変更回数。

各変更ごとに:

varint+ slot index: 表示順序を変更するためのスロットインデックス。

varint+ amount: 表示順序でスロットを移動させる量。

varint+ event count: 後に続くイベントキーフレームの数。

各イベントのキーフレームごとに:

float time: キーフレームの時間（秒）。

varint+ event index: キーフレームにおけるイベントのインデックス。

varint- int: そのキーフレームにおけるInteger(整数)の値。

float float: そのキーフレームにおけるFloat(浮動小数点)の値。

boolean has string: falseの場合はstringを省略。

string string: そのキーフレームにおけるString(文字列)の値。

float volume: オーディオファイルの再生に使用するボリューム。

float balance: オーディオファイルの再生に使用されるステレオバランス。

スキンフォーマット

varint+ slot count: 後に続くスキンのスロット数。

各スロットごとに:

varint+ slot index: このスキンにおいて、後に続くアタッチメントが属するスロットのインデックス。

varint+ attachment count: スロットに属するアタッチメントの数。

各アタッチメントごとに:

ref string placeholder name: そのアタッチメントが保管されているスキン内での名前。

ref string name: アタッチメントの名前。nullの場合、placeholder nameを使用します。これはスケルトンにおいてユニーク(一意)です。画像アタッチメントの場合、これはディスクやテクスチャアトラスでテクスチャ領域を検索するためのキーになります。

ATTACHMENT_* attachment type: アタッチメントの種類。

ATTACHMENT_REGION:

ref string path: nullでない場合、テクスチャ領域を検索するためにアタッチメント名の代わりにこの値が使用されます。

float rotation: スロットのボーンを基準にした画像の回転（度）。

float x: スロットのボーンに対する画像のX位置。

float y: スロットのボーンに対する画像のY位置。

float scaleX: 画像のXスケール。

float scaleY: 画像のYスケール。

float width: 画像の幅。

float height: 画像の高さ。

color color: アタッチメントのティント用カラー。

ATTACHMENT_BOUNDING_BOX:

varint+ vertex count: 境界ボックスの頂点の数。

Vertices vertices: 境界ボックスの頂点。

color color: Spine内での境界ボックスのカラー。※非必須

ATTACHMENT_MESH:

ref string path: nullでない場合、テクスチャ領域を検索するためにアタッチメント名の代わりにこの値が使用されます。

color color: アタッチメントのティント用カラー。

varint+ uv count: メッシュのUV数。

各UVごとに:

float x: 頂点のテクスチャ座標X。

float y: 頂点のテクスチャ座標Y。

varint+ triangle count: 後に続くメッシュの三角形の点の数。

各三角形の点ごとに:

short vertex index: この点の頂点のインデックス。

Vertices vertices: メッシュの頂点。

varint+ hull count: ポリゴンのハルを構成する頂点の数。ハルの頂点は常にverticesリストで最初に表示されます。

varint+ edge count: 接続された頂点間のエッジを定義する、後に続くエッジの点の数。※非必須

各エッジの点ごとに:

short vertex index: この点の頂点のインデックス。※非必須

float width: そのメッシュで使用する画像の幅。※非必須

float height: そのメッシュで使用する画像の高さ。※非必須

ATTACHMENT_LINKED_MESH:

ref string path: nullでない場合、テクスチャ領域を検索するためにアタッチメント名の代わりにこの値が使用されます。

color color: アタッチメントのティント用カラー。

ref string skin: ソースメッシュを含むスキンの名前。nullの場合、ソースメッシュはデフォルトのスキンに含まれているということになります。

ref string parent: ソースメッシュの名前で、常にこのメッシュと同じスロットにあります。ソースメッシュがデフォルトスキンに無い場合、この名前はスキン内の実際のアタッチメントを検索するために使用されます。

boolean deform: falseの場合、ソースメッシュのデフォームタイムラインはこのメッシュに適用されません。

float width: そのメッシュで使用する画像の幅。※非必須

float height: そのメッシュで使用する画像の高さ。※非必須

ATTACHMENT_PATH:

boolean closed: 最後の頂点と最初の頂点が繋がっている場合はtrueになります。

boolean constantSpeed: パスに沿った移動が一定速度で行われる場合はtrueになります。

varint+ vertex count: パスの頂点の数。

Vertices vertices: パスの頂点。

vertex count / 3 の長さごとに:

float length: セットアップポーズでのパスの始点から各カーブの終点までの長さ。

color color: Spine内でのパスのカラー。※非必須

ATTACHMENT_POINT:

float rotation: スロットが属するボーンに対するポイントの回転（度）。

float x: スロットが属するボーンに対するポイントのX位置。

float y: スロットが属するボーンに対するポイントのY位置。

color color: Spine内でのポイントのカラー。※非必須

ATTACHMENT_CLIPPING:

int end slot index: クリッピングを停止するスロットのインデックス。

varint+ vertex count: クリッピングポリゴンの頂点の数。

Vertices vertices: クリッピングポリゴンの頂点。

color color: Spine内でのクリッピングアタッチメントのカラー。※非必須

カーブフォーマット

カーブは、キーフレームと次のキーフレームとの間で使用する補間方法を、リニア、ステップ、ベジエカーブのいずれかで定義します。

ベジエカーブは、cx1、cy1、cx2、cy2 の4つの値で制御点を定義しています。X軸は0から1までで、2つのキーフレーム間の時間の割合を表します。Y軸は0から1までで、キーフレームの値の差のパーセントを表します。

CURVE_* curve type: カーブタイプ。

CURVE_BEZIER:

float c1

float c2

float c3

float c4

頂点フォーマット

boolean weighted: 頂点にウェイトが設定されている場合はtrueとなります。

weightedがtrueの場合:

各頂点ごとに:

float x: スロットが属するボーンに対する頂点のX位置。

float y: スロットが属するボーンに対する頂点のY位置。

weightedがfalseの場合:

各頂点ごとに:

float bone count: 頂点に影響を与えるボーンの数。

そのボーンの数だけ:

float bone index: 頂点に影響を与えるボーンのインデックス。

float bind position X: ボーンに対する頂点のX位置。

float bind position Y: ボーンに対する頂点のY位置。

float weight: そのボーンへのウェイト。