spine-pixiランタイム ドキュメント
ライセンスについて
Spineランタイムをアプリケーションに組み込む前に、必ずSpine Runtimes Licenseを確認してください。
はじめに
spine-pixiランタイムは、レンダラーに依存しない Spine Runtimes コア API の TypeScript 実装であるspine-ts coreをベースとして実装されています。spine-pixiランタイムは現在のところPixiJS 7 と互換性があり、WebGLを使用してレンダリングします。canvas APIを使用したレンダリングはサポートされていないので注意してください。
spine-pixiランタイムはすべてのSpineの機能をサポートしています。
インストール方法
Pixiプロジェクトでspine-pixiを使用するには、まずそのソースをインクルードする必要があります。
バニラJavaScriptの場合
バニラJavaScript(カスタマイズされていないJavaScript)では、script
タグを使ってunpkgからspine-pixiランタイムをインクルードします(または自分でホストします):
注意: spine-pixiの
major.minor
バージョンがエクスポートを行ったSpineエディターのmajor.minor
と一致していることを確認してください。詳しくは「バージョンの同期」を参照してください。
これでSpineエクステンションが自動的にインストールされ、あなたのPixiプロジェクトで spine-pixi
ランタイムを使用できるようになります。完全な例は index.html
をご覧ください。
spine-pixiパッケージは、デバッグ用のソースマップも提供しています。また、spine-pixiのminified版も提供しています。利用するにはunpkgのURLの .js
ファイルの末尾を .min.js
に置き換えてください。
spine-pixi.js
を自分でビルドしたい場合は、 spine-tsのREADME.mdに記載されている指示に従ってください。
NPM または Yarn の場合
依存関係の管理にNPMまたはYarnを使用している場合は、通常の方法でspine-pixiを追加します:
注意: spine-phaserの
major.minor
バージョンがエクスポートを行ったSpineエディターのmajor.minor
と一致していることを確認してください。詳しくは「バージョンの同期」を参照してください。
次に、Spineクラスをインポートします:
import { Spine } from '@esotericsoftware/spine-pixi';
これでSpineエクステンションが自動インストールされ、spine-pixi
ランタイムをプロジェクトで使用できるようになります。最小限の例として spine-pixi esbuild/TypeScript project
プロジェクトを参照してください。
当社のモジュールパッケージにはデバッグと開発を改善するためにソースマップと d.ts
タイピングが含まれています。
サンプル
spine-pixiランタイムには、利用できる機能セットを実演しているサンプルが多数含まれています。
サンプルをローカルで実行するには:
- お使いのオペレーティングシステムにGitとNode.jsをインストールします。
- spine-runtimesリポジトリをクローンします:
git clone https://github.com/esotericsoftware/spine-runtimes
spine-runtimes/spine-ts
に移動してnpm install & npm run dev
を実行します。
これにより、spine-pixiランタイムをビルドし、ブラウザを開いてspine-tsをベースとしているすべてのランタイムのサンプルの目次を表示することができます。
気になったspine-pixiのサンプルをクリックして、spine-runtimes/spine-ts/spine-pixi/example
フォルダ内のコードをチェックしてみてください。
spine-pixiランタイムのアップデート
プロジェクトのspine-pixiランタイムをアップデートする前に、Spineエディターとランタイムのバージョン管理に関するガイドをよく確認してください。
バニラJavaScriptでspine-pixiランタイムをアップデートする場合は、src
属性またはunpkgからspine-pixiを取得する script
タグのバージョン文字列を変更してください。
NPM、またはYarnで依存関係を管理している場合にspine-pixiランタイムをアップデートするには、package.json
ファイルのバージョン文字列を変更してください。
注意: spine-phaserの
major.minor
バージョンがエクスポートを行ったSpineエディターのmajor.minor
と一致していることを確認してください。詳しくは「バージョンの同期」を参照してください。
spine-pixiを使用する
spine-pixiランタイムはすべてのSpineの機能をサポートしています。ただしWebGLレンダラーを使用し、Canvasレンダラーはサポートされていません。
アセットのマネージメント
spine-pixi用にエクスポートする
以下の実行方法については、Spineユーザーガイド内で紹介されています :
スケルトンデータとテクスチャアトラスをエクスポートすると、以下のファイルが得られます:
skeleton-name.json
またはskeleton-name.skel
: これはスケルトンとアニメーションのデータを含んでいます。skeleton-name.atlas
: これはテクスチャアトラスの情報を含んでいます。- 1つまたは複数の
.png
ファイル: これはテクスチャアトラスの各ページで、スケルトンが使用するイメージを含んでいます。
補足: JSONエクスポートよりもバイナリ形式でのスケルトンエクスポートの方がサイズが小さく、読み込みが速いので、基本的にはそちらを選択したほうが良いでしょう。
これらのファイルを提供する際には、サーバーが正しいMIMEタイプを出力するようにしてください:
skel
ファイルはapplication/octet-stream
json
ファイルはapplication/json
atlas
ファイルはapplication/octet-stream
png
ファイルはimage/png
Spineアセットの更新
開発中にスケルトンデータやテクスチャアトラスファイルを更新したい時は、単純にSpineエディターから再エクスポートを行なって、Pixiプロジェクト内の既存のファイル(.json
、.skel
、.atlas
、.png
)を置き換えるだけで簡単にこれらのソースファイルを更新できます。
その際、spine-pixiの major.minor
バージョンとエクスポートを行ったSpineエディターの major.minor
が一致していることを確認してください。詳しくは「バージョンの同期」を参照してください。
コアクラス
spine-pixiのAPIは、汎用TypeScript spine-coreランタイムの上に構築されており、プラットフォームに依存しないコアクラスとSpineスケルトンのロード、クエリ、変更、アニメーションを行うアルゴリズムを提供します。
ここではspine-pixiを使用する際によく見ることになる最も重要なコアクラスについてのみ簡単に説明しています。Spineランタイムのアーキテクチャ、コアクラス、APIの使用法の詳細については、Spineランタイムガイドを参照してください。
TextureAtlas
クラスは、.atlas
ファイルとそれに対応する .png
画像ファイルからロードしたデータを保管します。
SkeletonData
クラスは、.json
または .skel
ファイルからロードされたデータを保管します。このスケルトンデータには、ボーン階層、スロット、アタッチメント、コンストレイント、スキン、アニメーションに関する情報が含まれます。SkeletonData
インスタンスは、通常、それが表すスケルトンで使用されるイメージをソースとする Atlas
(アトラス) も一緒に提供することによってロードされます。これは、Skeleton
インスタンスを作成するための設計図として機能します。複数のスケルトンを同じアトラスとスケルトンデータからインスタンス化し、ロードされたデータを共有することで、ロード時間と実行時のメモリ消費を最小限に抑えることができます。
Skeleton
クラスは、SkeletonData
インスタンスから作成されたスケルトンのインスタンスを格納します。スケルトンは現在のポーズを保管します。つまり、ボーンの位置、スロット、アタッチメント、アクティブなスキンの現在の構成を保管します。現在のポーズは、手動でボーンのトランスフォームを変更するか、より一般的には、AnimationState
を介してアニメーションを適用することで計算されます。
AnimationState
クラスは、スケルトンに適用する(単数または複数の)アニメーションを追跡し、最後のレンダリングフレームと現在のレンダリングフレームの間の経過時間に基づいてそれらのアニメーションを進め、ミックスを行い、スケルトンインスタンスにアニメーションを適用して現在のポーズを設定します。AnimationState
は AnimationStateData
インスタンスに問い合わせ(処理要求)をして、アニメーション間のミキシング時間を取得します。特定のアニメーション間に使用するミキシング時間が無ければデフォルトミックスデュレーションを取得します。
spine-pixiランタイムはこれらのコアクラスの上に構築されています。
Spine Pixiランタイム
spine-pixiランタイムは、LoadParser
タイプの2つの拡張機能、skeletonLoader
とatlasLoader
を自動的にPixiにインストールします。これらは、エクスポートされた .json
、.skel
、および..atlas
ファイルを(事前に)ロードする機能をPIXI.Assetsに追加します。
Spine
クラスはPixiの Container
クラスを拡張し、ロードしたスケルトンデータとアトラスファイルから Spine
コンテナインスタンスを作成するファクトリ関数を提供します。
さらに、RendererPlugin
タイプの拡張機能をインストールし、少なくとも1つのアタッチメントに黒の色合いを使用する Spineコンテナをレンダリングするために使用します。
Spineアセットのロード
.json
/.skel
ファイルや .atlas
ファイルのようなSpineアセットは、Assets.load
のようなPIXI.Assetsクラスのインスタンスで利用可能な通常の関数によってロードされます。
Spine
コンテナのインスタンスを作成する前に、それぞれのスケルトンファイルとアトラスファイルをロードする必要があります。これを行うには、Assets.add
関数と Assets.load
関数を使用します。
Assets.add({ alias: string, src: string })
: URLを使用してアセットのエイリアスを解決する(関連づける)方法を指定できます。この関数は、すべてのスパインアセットファイル(.json
、.skel
、.atlas
)に使用できます。Assets.load(string[])
:Assets.add
で追加したアセットエイリアスをロードします。
例えばスケルトンデータを skeleton.skel
というバイナリ形式のスケルトンファイルにエクスポートし、アトラスを skeleton.atlas
というファイルに、対応する1つの skeleton.png
ファイルと一緒にエクスポートしたと仮定した場合、以下のようにしてアセットをロードすることができます:
PIXI.Assets.add({ alias: "skeleton-atlas", src: "path/to/skeleton.atlas" });
await PIXI.Assets.load["skeleton-data", "skeleton-atlas"];
Assets.load
関数は、skeleton.skel
ファイルからSkeletonDataをロードし、キー skeleton-data
の下にキャッシュします。また、skeleton.atlas
ファイルから TextureAtlasをロードし、対応する skeleton.png
ファイルからテクスチャをロードします。アトラスは、キー skeleton-atlas
の下にキャッシュされます。個々のテクスチャアトラスページ画像は明示的にロードする必要はなく、透過的にロードされます。
事前ロードが完了したら、Asset.get(atlasKey)
を介して TextureAtlas
にアクセスできます。同様に、Asset.get(skeletonKey)
で、生(raw) .skel
ファイルにアクセスできます。この段階では、SkeletonData
インスタンスはまだ利用できないことに注意してください。
生のスケルトン データとアトラス単体では、アニメーションやレンダリングはできません。代わりに、それらから Spine
コンテナが構築されます。同じアセットキーでインスタンス化された Spine
コンテナは、同じスケルトンデータとアトラスを共有します。
Spineコンテナインスタンスの作成
生のスケルトンデータと対応するアトラスがロードされると、Spine
クラスの from()
静的関数によって Spine
コンテナを作成できます:
const app = new PIXI.Application({ ... });
...
// Spine.fromファクトリでSpineコンテナを作成
const spineboy = Spine.from("spineboyData", "spineboyAtlas", { ... });
// ステージにSpineコンテナを追加
app.stage.addChild(spineboy);
Spine
クラスの from()
関数は、スケルトンデータのキー、アトラスのキー、ISpineOptions をパラメータとして受け取ります。
デフォルトでは、Spine
コンテナの境界は計算されません。getBounds()
関数を呼び出すことで、現在のスキンとアニメーションに基づいたサイズの境界を計算することができます。セットアップポーズに基づいて境界を計算したい場合は、コンテナ作成直後に getBounds()
を呼び出してください。また、その場合最初にスキンを設定しておいた方がよいでしょう。
Spineコンテナ
Spine
コンテナは Pixi Containerを拡張したもので、Skeleton
とそれに関連する AnimationState
の保存、更新、レンダリングを行います。Spineコンテナのインスタンスは、前のセクションで説明したように、スケルトンデータとアトラスから作成されます。Skeleton
と AnimationState
は、それぞれ skeleton
フィールドと state
フィールドからアクセスできます。
毎フレーム、Spine
コンテナは以下のことを行います:
AnimationState
を更新AnimationState
をSkeleton
に適用Skeleton
のワールドトランスフォームを更新して、新しいポーズにするSkeleton
を現在のポーズで描画
アニメーションの適用
Spine
コンテナで表示されるスケルトンにアニメーションを適用するには、AnimationState
を使用します。
注意: アニメーショントラックやアニメーションのキューイングなど、より詳しい情報については、Spineランタイムガイドの「アニメーションの適用」を参照してください。
トラック0に特定のアニメーションを設定するには、AnimationState setAnimation
を呼び出します:
最初のパラメーターはトラック、2番目のパラメーターはアニメーションの名前、3番目のパラメーターはアニメーションをループさせるかどうかを指定します。
addAnimation
を利用して複数のアニメーションをキューに入れることもできます:
spineObject.state.addAnimation(0, "jump", 2, false);
spineObject.state.addAnimation(0, "run", 0, true);
addAnimation()
の最初のパラメーターはトラックです。2番目のパラメーターはアニメーションの名前です。3番目のパラメーターは、このアニメーションが同じトラック上の前のアニメーションと置き換わるまでの時間(ディレイ)を秒単位で指定します。最後のパラメーターはアニメーションをループさせるかどうかを指定します。
上の例では、まず "walk"
アニメーションが再生されます。その2秒後に"jump"
アニメーションが一度再生され、続いて"run"
アニメーションに切り替わり、ループします。
あるアニメーションから別のアニメーションに遷移するとき、 AnimationState
はミックスデュレーションと呼ばれる特定の時間だけアニメーションをミックス(クロスフェード)します。これらのミックスデュレーションは AnimationStateData
インスタンスで定義され、 AnimationState
はそこからミックスデュレーションを取得します。
AnimationStateData
インスタンスは SpineGameObject
からも利用できます。デフォルトのミックスデュレーションや、特定のアニメーションのペアのミックスデュレーションを設定することができます:
spineObject.state.data.setMix("walk", "jump", 0.1);
アニメーションを設定または追加すると、TrackEntry
オブジェクトが返されます。例えば、アニメーションを逆再生するようにTrackEntryを設定することができます:
entry.mixDuration = 0.4;
entry.reverse = true;
利用できるオプションについて詳しくはTrackEntry
クラスのドキュメントをご覧ください。
注意:
TrackEntry
インスタンスを使用している関数の外部で保持する場合には注意が必要です。TrackEntryは内部で再利用されるため、TrackEntryのdisposeイベントが発生すると無効になります。
スケルトンをスムーズにセットアップポーズに戻したい場合は、アニメーショントラックに空のアニメーションを利用します:
spineObject.state.addAnimation(0, "walk", 0).mixDuration = 0.5;
spineObject.state.addEmptyAnimation(0, 0.5, 6);
setAnimation
と同様に、setEmptyAnimation()
の最初のパラメーターはトラックを指定します。2番目のパラメーターは、前のアニメーションをミックスアウトし、"空の"アニメーションをミックスするために使用するミックスデュレーションを秒単位で指定します。
addAnimation
と同様に、addEmptyAnimation()
の最初のパラメーターはトラックを指定します。2番目のパラメーターはミックス時間を指定します。3番目のパラメーターはディレイ(秒単位)で、このディレイの後に空のアニメーションがミキシングされてトラック上の前のアニメーションと置き換わります。
AnimationState.clearTrack()
を使えばトラック上のすべてのアニメーションを即座にクリアすることができます。すべてのトラックを一度にクリアするには AnimationState.clearTracks()
を使います。しかしこれはスケルトンを最後に適用されたポーズのままにする点に注意してください。
スケルトンのポーズをセットアップポーズに戻すには、 Skeleton.setToSetupPose()
を使います:
これはボーンとスロットの両方をセットアップポーズの設定にリセットします。 ボーンだけリセットするには Skeleton.setBonesToSetupPose()
を、スロットだけリセットするには Skeleton.setSlotsToSetupPose()
を使用してください。
AnimationStateイベント
AnimationState
は、再生中のアニメーションのライフサイクル中に様々なイベントを発行します。必要に応じてこのイベントをリッスンすることで、それらに反応させることができます。SpineランタイムのAPIでは、以下のイベントタイプを定義しています:
start
: アニメーションが開始された時に発されます。interrupt
: アニメーションのトラックがクリアされた、または新しいアニメーションが設定されたなどにより中断された時に発されます。end
: アニメーションが二度と適用されない時に発されます。dispose
: アニメーションのTrackEntryが破棄された時に発されます。complete
: アニメーションが1ループを完了するごとに発されます。event
: ユーザーが定義したイベントが発生した時に発されます。
イベントを受け取るには、AnimationStateListener
コールバックを、すべてのアニメーションでイベントを受信するAnimationState
か、キューされた特定のアニメーションのTrackEntry
に登録します:
start: (entry) => log(`Started animation ${entry.animation.name}`),
interrupt: (entry) => log(`Interrupted animation ${entry.animation.name}`),
end: (entry) => log(`Ended animation ${entry.animation.name}`),
dispose: (entry) => log(`Disposed animation ${entry.animation.name}`),
complete: (entry) => log(`Completed animation ${entry.animation.name}`),
event: (entry, event) => log(`Custom event for ${entry.animation.name}: ${event.data.name}`)
})
trackEntry.listener = {
event: (entry, event) => log(`Custom event for ${entry.animation.name}: ${event.data.name}`)
}
詳しくはevents-example.html
をご覧ください。
スキン
多くのアプリケーションやゲームでは、髪や目、ズボン、イヤリングやバッグなどのアクセサリーなど、さまざまなアイテムを組み合わせてカスタムアバターを作ることができます。Spineでは、複数スキンを組み合わせることでこれを実現することができます。
以下のようにして、他のスキンからカスタムスキンを作成することができます:
const skin = new spine.Skin("custom");
skin.addSkin(skeletonData.findSkin("skin-base"));
skin.addSkin(skeletonData.findSkin("nose/short"));
skin.addSkin(skeletonData.findSkin("eyelids/girly"));
skin.addSkin(skeletonData.findSkin("eyes/violet"));
skin.addSkin(skeletonData.findSkin("hair/brown"));
skin.addSkin(skeletonData.findSkin("clothes/hoodie-orange"));
skin.addSkin(skeletonData.findSkin("legs/pants-jeans"));
skin.addSkin(skeletonData.findSkin("accessories/bag"));
skin.addSkin(skeletonData.findSkin("accessories/hat-red-yellow"));
spineObject.skeleton.setSkin(skin);
spineObject.skeleton.setToSetupPose();
まず、Skin()
コンストラクタで新しい空のスキンを作成します。
次に、スケルトンから SkeletonData
を取得します。これは SkeletonData.findSkin()
でスキンを名前から探すのに使用します。
Skin.addSkin()
で新しいスキンにまとめたいスキンをすべて追加します。
最後に、Skeleton
に出来上がった新しいスキンをセットし、Skeleton.setSlotsToSetupPose()
を呼び出して、以前のスキンやアニメーションのアタッチメントが残らないようにします。
コード例の全文については mix-and-match-example.html
を確認してください。
ボーンのトランスフォームの設定
Spineエディター内でスケルトンを構築する際、スケルトンは、スケルトンのワールド座標系または「スケルトン座標系」と呼ばれるもので定義されます。この座標系は、Pixiの座標系と一致しない場合があります。そのため、例えばユーザーがタッチでボーンを動かせるようにしたい場合などはSpine
コンテナに対するマウス座標やタッチ座標は、スケルトン座標系に変換する必要があります。
Spine
コンテナには pixiWorldCoordinatesToBone(point: { x: number, y: number}, bone: Bone)
というメソッドがあり、Spine
コンテナからの相対点を取り、指定したボーンからの相対点をスケルトンの座標系に変換します。
その逆、つまりスケルトン座標系からPixi座標系への変換は、Spine.skeletonToPixiWorldCoordinates(point: { x: number, y: number})
で行えます。
コード例の全文については control-bones-example.html
を確認してください。
Pixiオブジェクトをスロットに追加する
Spine
クラスには、pixi Container
をスロットにアタッチしたり、デタッチしたりするために使える3つの便利なメソッドがあります。
これは slotRef
で参照されているスロットに pixiObject
を追加します。これには名前、スロットのインデックス、またはスロットオブジェクト自体を渡すことができます。
1つのスロットに割り当てられるPixiオブジェクトは1つだけです。Pixiオブジェクトが追加されると、そのトランスフォームは Spine
オブジェクトによって自動的に変更されるようになります。
追加したオブジェクトをもっとコントロールしたい場合は、Pixi Container
を追加して、好きなだけPixiオブジェクトを追加し、位置、角度、スケールなどをオフセットすることができます。
コンテナを削除したい場合は、これに対応したメソッドを呼び出します:
pixiObject
はオプションです。渡された場合、Pixiオブジェクトは slotRef
で参照されているスロットにあるものと一致する場合のみ削除されます。
Pixiオブジェクトは取り除かれるだけで、破棄されないことに注意してください。また、手動で追加したPixiオブジェクトのライフサイクルに注意してください。
スロットにアタッチされたPixiオブジェクトを取得するには、以下のメソッドを使用します:
slotRef
で参照されているスロットにアタッチされている Container
があれば、それを返します。
完全なサンプルコードは slot-objects.html
を参照してください。
メッシュバッチサイズ
Spine
オブジェクトは、アタッチメントのレンダリングにPixiメッシュを使用します。Pixiのデフォルトでは、頂点数が100を超えるメッシュはバッチ処理不可能とマークされます。その結果、バッチ処理が中断され、ドローコールの回数が増え、パフォーマンスが低下します。この不都合を解消するには、グローバルの PIXI.Mesh.BATCHABLE_SIZE
をスケルトンに合った値に設定します。
SpineランタイムAPIアクセス
spine-pixiは、Spine
プロパティの skeleton
、animationStateData
、animationState
を介してspine-tsコアAPI全体を公開しています。一般的なSpineランタイムガイドと同様に、これらのクラスのJSドキュメントを参照してください。
pixi-spineとの違い
Pixiは独自のSpine拡張機能(pixi-spine)を提供しており、spine-ts core
汎用ランタイムを使用しています。主な違いは、pixi-spineはSpineスケルトン階層を複数のPixiオブジェクトとして再作成するのに対し、spine-pixiはより効率的なレンダリングのために低レベルのPixiテクスチャとメッシュを使用する単一のPixiオブジェクトであるという点です。それでもスロットにPixiオブジェクトをアタッチすることはできます。
Spine 4.2以降、spine-pixiランタイムは他のSpineランタイムと同様にメンテナンスされます。つまり、新しいSpineエディターバージョンがリリースされるたびにタイムリーなアップデートが提供され、次のSpineエディターバージョンのベータ版ランタイムにアクセスすることができ、最新の改善やバグフィックスがタイムリーに提供されます。Pixiのメンテナーは、Spine拡張を最優先事項としていないため、このような保証を提供できない場合があります。
また、APIの面では、注意すべき違いがいくつかあります。
スケルトンとアトラスデータのロード
pixi-spineでスケルトンとそのアトラスをロードするには、アトラスとスケルトンファイルが必ず同じ名前である必要があります。AssetsローダーにスケルトンのURLを渡すだけで、SkeletonData
と TextureAtlas
を含むオブジェクトを返します。
spine-pixiランタイムでは、アトラスデータとスケルトンデータは別々にロードされ、異なる名前を持つことができます。
Spineコンテナインスタンスの作成
pixi-spineで Spine
コンテナを作成するには、Spine
コンストラクタに SkeletonData
を渡す必要があります。
spine-pixiランタイムでは、スケルトンデータとアトラスの両方のアセット参照を指定する必要があります。