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ランタイムをインクルードします（または自分でホストします）:

<script src="https://unpkg.com/@esotericsoftware/spine-pixi@4.2.*/dist/iife/spine-pixi.js"></script>

注意: 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を追加します:

npm install @esotericsoftware/spine-pixi@~4.2.0

注意: spine-phaserの major.minor バージョンがエクスポートを行ったSpineエディターの major.minor と一致していることを確認してください。詳しくは「バージョンの同期」を参照してください。

次に、Spineクラスをインポートします:

import PIXI from "pixi.js"
import { Spine } from '@esotericsoftware/spine-pixi';

これでSpineエクステンションが自動インストールされ、spine-pixi ランタイムをプロジェクトで使用できるようになります。最小限の例として spine-pixi esbuild/TypeScript project プロジェクトを参照してください。

当社のモジュールパッケージにはデバッグと開発を改善するためにソースマップと d.ts タイピングが含まれています。

サンプル

spine-pixiランタイムには、利用できる機能セットを実演しているサンプルが多数含まれています。

サンプルをローカルで実行するには:

  1. お使いのオペレーティングシステムにGitとNode.jsをインストールします。
  2. spine-runtimesリポジトリをクローンします: git clone https://github.com/esotericsoftware/spine-runtimes
  3. 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ユーザーガイド内で紹介されています :

  1. スケルトン＆アニメーションデータのエクスポート
  2. スケルトンの画像を含むテクスチャアトラスのエクスポート

スケルトンデータとテクスチャアトラスをエクスポートすると、以下のファイルが得られます:

  1. skeleton-name.json または skeleton-name.skel:　これはスケルトンとアニメーションのデータを含んでいます。
  2. skeleton-name.atlas:　これはテクスチャアトラスの情報を含んでいます。
  3. １つまたは複数の .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-data", src: "path/to/skeleton.skel" });
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 コンテナを作成できます:

javascript
// Pixi appを作成
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を呼び出します:

javascript
spineObject.state.setAnimation(0, "walk", true);

最初のパラメーターはトラック、2番目のパラメーターはアニメーションの名前、3番目のパラメーターはアニメーションをループさせるかどうかを指定します。

addAnimationを利用して複数のアニメーションをキューに入れることもできます:

javascript
spineObject.state.setAnimation(0, "walk", true);
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 からも利用できます。デフォルトのミックスデュレーションや、特定のアニメーションのペアのミックスデュレーションを設定することができます:

javascript
spineObject.state.data.setDefaultMix = 0.2;
spineObject.state.data.setMix("walk", "jump", 0.1);

アニメーションを設定または追加すると、TrackEntry オブジェクトが返されます。例えば、アニメーションを逆再生するようにTrackEntryを設定することができます:

javascript
const entry = spineObject.state.setAnimation(0, "walk", true);
entry.mixDuration = 0.4;
entry.reverse = true;

利用できるオプションについて詳しくはTrackEntryクラスのドキュメントをご覧ください。

注意: TrackEntryインスタンスを使用している関数の外部で保持する場合には注意が必要です。TrackEntryは内部で再利用されるため、TrackEntryのdisposeイベントが発生すると無効になります。

スケルトンをスムーズにセットアップポーズに戻したい場合は、アニメーショントラックに空のアニメーションを利用します:

javascript
spineObject.state.setEmptyAnimation(0, 0);
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() を使います:

javascript
spineObject.skeleton.setToSetupPose();

これはボーンとスロットの両方をセットアップポーズの設定にリセットします。 ボーンだけリセットするには Skeleton.setBonesToSetupPose() を、スロットだけリセットするには Skeleton.setSlotsToSetupPose() を使用してください。

AnimationStateイベント

AnimationStateは、再生中のアニメーションのライフサイクル中に様々なイベントを発行します。必要に応じてこのイベントをリッスンすることで、それらに反応させることができます。SpineランタイムのAPIでは、以下のイベントタイプを定義しています:

  • start: アニメーションが開始された時に発されます。
  • interrupt: アニメーションのトラックがクリアされた、または新しいアニメーションが設定されたなどにより中断された時に発されます。
  • end: アニメーションが二度と適用されない時に発されます。
  • dispose: アニメーションのTrackEntryが破棄された時に発されます。
  • complete: アニメーションが1ループを完了するごとに発されます。
  • event: ユーザーが定義したイベントが発生した時に発されます。

イベントを受け取るには、AnimationStateListenerコールバックを、すべてのアニメーションでイベントを受信するAnimationStateか、キューされた特定のアニメーションのTrackEntryに登録します:

javascript
spineObject.state.addListener({
   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では、複数スキンを組み合わせることでこれを実現することができます。

以下のようにして、他のスキンからカスタムスキンを作成することができます:

javascript
const skeletonData = spineObject.skeleton.data;
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つの便利なメソッドがあります。

addSlotObject (slotRef: number | string | Slot, pixiObject: Container): void

これは slotRef で参照されているスロットに pixiObject を追加します。これには名前、スロットのインデックス、またはスロットオブジェクト自体を渡すことができます。

1つのスロットに割り当てられるPixiオブジェクトは1つだけです。Pixiオブジェクトが追加されると、そのトランスフォームは Spine オブジェクトによって自動的に変更されるようになります。

追加したオブジェクトをもっとコントロールしたい場合は、Pixi Container を追加して、好きなだけPixiオブジェクトを追加し、位置、角度、スケールなどをオフセットすることができます。

コンテナを削除したい場合は、これに対応したメソッドを呼び出します:

removeSlotObject (slotRef: number | string | Slot, pixiObject?: Container): void

pixiObject はオプションです。渡された場合、Pixiオブジェクトは slotRef で参照されているスロットにあるものと一致する場合のみ削除されます。

Pixiオブジェクトは取り除かれるだけで、破棄されないことに注意してください。また、手動で追加したPixiオブジェクトのライフサイクルに注意してください。

スロットにアタッチされたPixiオブジェクトを取得するには、以下のメソッドを使用します:

getSlotObject (slotRef: number | string | Slot): Container | undefined

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 を含むオブジェクトを返します。

javascript
const { spineData, spineAtlas } = await Assets.load("spineboy.skel");

spine-pixiランタイムでは、アトラスデータとスケルトンデータは別々にロードされ、異なる名前を持つことができます。

javascript
await Assets.load(["spineboy-pro.skel", "spineboy-pma.atlas"]);

Spineコンテナインスタンスの作成

pixi-spineで Spine コンテナを作成するには、Spine コンストラクタに SkeletonData を渡す必要があります。

javascript
const spineboy = new Spine(spineData);

spine-pixiランタイムでは、スケルトンデータとアトラスの両方のアセット参照を指定する必要があります。

javascript
const spineboy = Spine.from("spineboy-pro.skel", "spineboy-pma.atlas");