spine-godotランタイム ドキュメント

ライセンスについて

Spineランタイムをアプリケーションに組み込む前に、必ずSpine Runtimes Licenseを確認してください。

はじめに

インストール方法

spine-godotランタイムは2種類あります:

• spine-godot GDExtension: 既存のGodotプロジェクトの bin/ フォルダにドロップするパッケージです。Godotがサポートするすべてのプラットフォームをサポートし、将来的にはW4Gamesが提供するコンソールもサポートする可能性があります。ただし、AnimationPlayer に対応しておらず、専用のC#バインディングが無い他、一部のエディター機能がありません。
• spine-godot カスタムC++エンジンモジュール: これはカスタムGodotエディタビルドおよびGodotテンプレートを使用する必要があります。また、将来的にコンソールをサポートする可能性は低いです。しかし AnimationPlayer のような追加機能と専用のC#バインディングをサポートしています。

spine-godot GDExtensionのダウンロード

ご使用のGodotのバージョンに対応するGDExtension版spine-godotをダウンロードしてください。次に、.zip ファイルを解凍し、bin/ フォルダをプロジェクトのルートフォルダにコピーしてください。つまり、your-project/bin と、your-project/bin/spine_godot_extension.gdextension ファイルがあるという状態にしてください(your-projectにはご自身のプロジェクトのフォルダ名が入ります)。それからGodotエディタを実行します。

spine-godotエンジンモジュールのダウンロード

注意: エディタビルドはすべて64-bitサポートが必要です。Windows、Linux、macOS用のエクスポートテンプレートも64-bitのサポートが必要です。iOSデバイス用のエクスポートテンプレートは64-bit ARMデバイスのみをサポートしています。

上記のリンクから、お使いのOSに対応したGodotエディタと、Godotエクスポートテンプレートをダウンロードしてください。

Windows または Linux の場合は、.zip ファイルを解凍後、解凍された実行ファイルをお好きな場所に置くことができます。macOSの場合は、.zip ファイルを解凍後、 Godot.app を /Applications/ フォルダに配置してください。既存のGodotインストールがある場合は、Godot.app パッケージの名前を変更することができます。

エクスポートテンプレートの .tpz ファイルをインストールするには、Godotエディタを開き、Editor > Manage export templates ... を選択してください。 Install from file をクリックして、上記のリンクからダウンロードした .tzp ファイルを選択します。これで通常通り、Windows、Linux、macOS、iOS、Android、およびWeb用にプロジェクトをエクスポートできるようになります。また、Godotのワンクリック・デプロイ機能を使えば、Godotエディタ内からAndroidやWeb向けに直接デプロイすることも可能です。

サンプル

spine-godotランタイムには、各機能を紹介しているさまざまなサンプルが付属しています。サンプルを確認したり再生するには:

1. 上の「インストール」セクションのリンクから、お使いのOS用のビルド済みGodotエディタをダウンロードします。
2. spine-runtimesのGitリポジトリをクローンします。Gitを使いたくない場合は、最新のバージョンをZIPでダウンロードして解凍してください。
3. Godotエディタを開き、Importをクリックし、ご使用のGodotエディターバージョンに対応するファイルを選択します。
   • GDExtensionの場合: spine-runtimes/spine-godot/example-v4-extension/project.godot
   • GDExtensionを解凍し、Godotエディタでプロジェクトを開く前に bin/ をプロジェクトルートにコピーしてください。
   • C++エンジンモジュールの場合:
     • Godot 3.x: spine-runtimes/spine-godot/example/project.godot
     • Godot 4.x: spine-runtimes/spine-godot/example-v4/project.godot
     • Godot 4.x with C# support: spine-runtimes/spine-godot/example-v4-csharp/project.godot

以下のような例があります:

• 01-helloworld: SpineSpriteノードを使用して、Spineスケルトンを表示し、アニメーションさせる方法を紹介しています。
• 02-animation-state-listener: SpineSpriteのアニメーションのステートの変化をシグナルで受信する方法を紹介しています。
• 03-mix-and-match: 他のスキンを組み合わせてカスタムスキンを作成し、mix-and-matchアバターを作成する方法を紹介しています。
• 04-simple-input: 入力イベントに反応してアニメーションを再生する方法を紹介しています。
• 05-mouse-following: SpineSprite スケルトンのボーンを手動でマウスやタッチイベントに追従させる方法を紹介しています。
• 06-bone-following: SpineSprite 上の SpineBoneNode を使用して、子ノードがスケルトンのボーンに追従するようにする方法を紹介しています。
• 07-slot-node: SpineSlotNode を使用して子ノードをスケルトンのスロットに従わせ、SpineSprite の描画順序に子ノードを正しく挿入する方法を紹介しています。
• 08-animation-player: GodotのAnimationPlayerユーザーインターフェースを使って、SpineAnimationTrack ノードを使用してカットシーンを作成する方法を紹介しています。
• 09-custom-material: SpineSlotNodeを介して、SpineSprite全体および個々のスロットにカスタムマテリアルを適用する方法を紹介しています。
• 10-2d-lighting: Godotの2Dライティングシステムに対応するために、SpineSpriteと組み合わせて法線マップ(ノーマルマップ)を使用する方法を紹介しています。
• 11-bone-node: SpineBoneNodeインスタンスを使用して、Godotの物理演算によってSpineSpriteボーンを動作させる方法を紹介しています。
• 12-bone-node: Celestial Circusスケルトンを使ってSpineの物理演算を紹介しています。
• 13-load-from-disk: 実行時にSpineの .skel/.json および .atlas ファイルをディスクからロードする方法を紹介しています。

ソースからのspine-godotのコンパイル

異なるGodotバージョンを使いたい、他のカスタムC++モジュールがある、spine-godotランタイム自体の作業をしたいなどの理由で、spine-godot GDExtensionやspine-godotエンジンモジュール(Godotエディタやエクスポートテンプレート)を自分でコンパイルする必要がある場合のために、プロセスを簡単にするシェルスクリプトを提供しています。

注意: これを試す前に、Godot公式の指示に従って、すべてのビルド依存関係がインストールされていることを確認してください。

GDExtensionのコンパイル

GDExtensionのバイナリをビルドするには、まずspine-runtimesリポジトリをクローンします。そして Spine Runtimes をクローンしたディレクトリの中から Bash シェル (Windows では Git Bash を使用) で以下を実行します:

setup-extension.sh ビルドは外部依存関係のクローンとビルドの設定を行います。setup-extension.sh の最初の引数は、GDExtensionをビルドするGodotリポジトリのブランチかコミットハッシュです。二番目の引数は、デバッグ情報を使ってビルドをコンパイルするかどうかを指定します。これは開発用に便利です。セットアップスクリプトは適切なバージョンの godot-cpp をクローンし、デバッグ用のビルドを作成する場合はオプションでGodotエディタリポジトリをクローンします。また、spine-godot/spine_godot_extension.gdextension ファイルを spine-godot/example-v4-extension/bin にコピーします。

build-extension.sh スクリプトは、ビルドを実行し、特定のオペレーティングシステム用の GDExtensionバイナリを生成します。build-extension.sh の <os> 引数はビルドするOSを指定します。ホストOSとアーキテクチャに合わせてビルドしたい場合は省略できます。<os> の有効な値は windows、linux、macos、ios、android、web です。GDExtensionのバイナリは spine-godot/example-v4-extension/bin フォルダのそれぞれのOS固有のサブフォルダに置かれます。

GitHub Actionsによるビルド

Spine Runtimes リポジトリには .github/workflows/spine-godot-extension-v4.yml と .github/workflows/spine-godot-extension-v4-all.yml というGitHubワークフローがあり、GitHub Actionsを使用して spine-godot GDExtension をビルドできます。こちらの方が、これらのビルド成果物をローカルでコンパイルするよりも簡単かもしれません。GitHubワークフローを使うには

1. まずSpine Runtimesリポジトリをクローンします。
2. クローンしたリポジトリでGitHubワークフローを有効にします。
3. 手動で spine-godot-extension-v4-all ワークフローを起動します。

ワークフローの実行に成功すると、結果のバイナリが成果物として添付されます。

C++エンジンモジュールのコンパイル

Godot 3.5.x

Godotエディタバイナリをビルドするには、まずspine-runtimesリポジトリをクローンします。Spine Runtimesをクローンしたディレクトリ内で、Bashシェル（WindowsではGit Bashを使用）で以下を実行します。:

setup.shの最初の引数は、GodotエディタをビルドしたいGodotリポジトリのブランチまたはコミットハッシュになります。第2引数には、開発用にエディタをコンパイルするかどうかを指定します。有効な値はtrueおよびfalseです。trueに設定すると、LIVEPP環境変数をLive++のインストールディレクトリに設定した場合、Windows上のLive++のサポートが追加され、コンパイルを高速化するために多くのモジュールが無効になります。

build.shの最初の引数は、生成されるバイナリの最適化レベルを指定します。サポートされている値は、完全なデバッグが可能になる代わりに最適化されていないため遅くなることがあるdebugと、一般的にGodotエディタのリリースビルドに使用されるrelease_debugです。

出来上がったGodotエディタバイナリは、spine-godot/godot/binに保存されます。

特定のプラットフォーム用のエクスポートテンプレートをビルドするには、Bashシェル（WindowsではGit Bashを使用）で以下を実行します:

setup.shの最初の引数は、GodotエディタをビルドしたいGodotリポジトリのブランチまたはコミットハッシュです。第2引数は必ずfalseでなければなりません。

built-templates.shの最初の引数は、テンプレートをコンパイルするためのプラットフォームです。有効な値は、windows、linux、macos、web、android、iosです。macOSとiOSのエクスポートテンプレートは、macOSが動作しているマシンでのみビルドできることに注意してください。詳しくはGodotによる公式の説明を参照してください。

出来上がったGodotエクスポートテンプレートバイナリは、spine-godot/godot/binに保存されます。

Godot 4.x

Godotエディタバイナリをビルドするには、まずspine-runtimesリポジトリをクローンします。Spine Runtimesをクローンしたディレクトリ内で、Bashシェル（WindowsではGit Bashを使用）で以下を実行します。:

setup.sh の最初の引数は、GodotエディタをビルドしたいGodotリポジトリのブランチまたはコミットハッシュになります。第2引数には、開発用にエディタをコンパイルするかどうかを指定します。有効な値はtrueおよびfalseです。trueに設定すると、LIVEPP環境変数をLive++のインストールディレクトリに設定した場合、Windows上のLive++のサポートが追加され、コンパイルを高速化するために多くのモジュールが無効になります。

出来上がったGodotエディタバイナリは、spine-godot/godot/binに保存されます。

特定のプラットフォーム用のエクスポートテンプレートをビルドするには、Bashシェル（WindowsではGit Bashを使用）で以下を実行します:

setup.shの最初の引数は、GodotエディタをビルドしたいGodotリポジトリのブランチまたはコミットハッシュです。第2引数は必ずfalseでなければなりません。

built-templates-v4.shの最初の引数は、テンプレートをコンパイルするためのプラットフォームです。有効な値は、windows、linux、macos、web、android、iosです。macOSとiOSのエクスポートテンプレートは、macOSが動作しているマシンでのみビルドできることに注意してください。詳しくはGodotによる公式の説明を参照してください。

出来上がったGodotエクスポートテンプレートバイナリは、spine-godot/godot/binに保存されます。

Godot 4.x with C# support

注意: C#対応のGodot 4.xは現在、Windows、Linux、およびmacOSでのみ動作します。上流のGodotリリースがモバイルとウェブに対応し次第、spine-godotランタイムもそれに追随する予定です。

C#対応のGodotエディタバイナリをビルドするには、まずspine-runtimesリポジトリをクローンします。Godotのドキュメントに従って、C#の追加要件がインストールされていることを確認してください。そしてSpine Runtimesをクローンしたディレクトリ内で、Bashシェル（WindowsではGit Bashを使用）で以下を実行します。:

setup.sh の最初の引数は、GodotエディタをビルドしたいGodotリポジトリのブランチまたはコミットハッシュになります。第2引数には、開発用にエディタをコンパイルするかどうかを指定します。有効な値は true および false です。trueに設定すると、LIVEPP環境変数をLive++のインストールディレクトリに設定した場合、Windows上のLive++のサポートが追加され、コンパイルを高速化するために多くのモジュールが無効になります。第3引数はオプションで、C#をサポートしてビルドするかどうかを指定します。有効な値は true および false です。この場合、C#サポートを有効にするためにtrueが設定されています。

build-v4.shの引数はオプションで、C#をサポートしてビルドするかどうかを指定します。有効な値は true および false です。この場合、C#サポートを有効にするためにtrueが設定されています。

出来上がったGodotエディタバイナリは、spine-godot/godot/binに保存されます。さらに、spine-godot/godot/bin ディレクトリ内に GodotSharp フォルダが保存されます。これにはspine-godotランタイムAPIを含む、Godot API用のすべてのC#バインディングアセンブリが含まれています。新しいプロジェクトを作成するときは、NuGet経由でこれらを結びつける必要があります。詳しくは、後述のC#プロジェクトのセットアップセクションをご覧ください。

特定のプラットフォーム用のエクスポートテンプレートをビルドするには、Bashシェル（WindowsではGit Bashを使用）で以下を実行します:

setup.shの最初の引数は、GodotエディタをビルドしたいGodotリポジトリのブランチまたはコミットハッシュです。第2引数は必ずfalseでなければなりません。

built-templates-v4.shの最初の引数は、テンプレートをコンパイルするためのプラットフォームです。有効な値は、windows、linux、macos、web、android、iosです。macOSとiOSのエクスポートテンプレートは、macOSが動作しているマシンでのみビルドできることに注意してください。詳しくはGodotによる公式の説明を参照してください。

出来上がったGodotエクスポートテンプレートバイナリは、spine-godot/godot/binに保存されます。

GitHub Actionsによるビルド

Spine Runtimes リポジトリには .github/workflows/spine-godot.yml、.github/workflows/spine-godot-v4.yml、.github/workflows/spine-godot-v4-all.yml というGitHubワークフローがあり、GitHub Actionsを使用して 全てのGodotエディターおよびエクスポートテンプレートをビルドできます。こちらの方が、これらのビルド成果物をローカルでコンパイルするよりも簡単かもしれません。GitHubワークフローを使うには:

1. まずSpine Runtimesリポジトリをクローンします
2. クローンしたリポジトリでGitHubワークフローを有効にします
3. 手動で spine-godot、spine-godot-v4、spine-godot-v4-all ワークフローのいずれかを起動します。

ワークフローの実行に成功すると、結果のバイナリが成果物として添付されます。

C#プロジェクトのセットアップ

注意: spine-godot GDExtension には現在、C# バインディングは付属していません。以下の手順は、spine-godot C++ エンジンモジュールおよび上記の対応するカスタムGodotエディタビルド用です。

C#対応のGodotエディタバイナリを使用する場合、新しいGodotプロジェクトをセットアップする際に、追加のステップを踏む必要があります。

まず、上のインストールセクションでダウンロードしたC#対応のGodotエディタバイナリを使用してGodotプロジェクトを作成します。

次に、Godotを閉じて、ご自身のプロジェクトフォルダを開いてください。ルートディレクトリに godot-nuget という新しいフォルダを作成します。

ダウンロードしたGodotエディタのZIPファイルから、Godot C# アセンブリをそのフォルダにコピーします。以下がコピーする必要のあるファイルです:

• GodotSharpEditor.<version>.snupkg
• Godot.NET.Sdk.<version>.nupkg
• Godot.SourceGenerators.<version>.nupkg
• GodotSharp.<version>.nupkg
• GodotSharp.<version>.snupkg
• GodotSharpEditor.<version>.nupkg

<version>の部分にはダウンロードしたGodotのバージョンに応じたバージョン番号が入ります。例: 4.1.1

GodotエディタのZIPをダウンロードして解凍すると、以下のフォルダ内に上記のファイルがあります:

• Windows: godot-editor-windows-mono.zip\GodotSharp\Tools\
• Linux: godot-editor-linux-mono.zip/GodotSharp/Tools/
• macOS: Godot.app/Contents/Resources/GodotSharp/Tools、またはFinder上でGodot.appファイルを右クリックして、Show Package Contents(パッケージの内容を表示)を選択することでContents/Resources/GodotSharp/Tools/へナビゲートできます。

最後に、プロジェクトのルートディレクトリに以下の内容でnuget.configという新しいファイルを作成します:

これは godot-nuget ディレクトリを NuGet パッケージのパッケージソースとして設定します。これにより、NuGetパッケージレジストリから公式のGodot C#アセンブリを取得する代わりに、spine-godotランタイム用のC#バインディングが含まれているgodot-nuget ディレクトリのアセンブリが使用されるようになります。

これで再びGodotでプロジェクトを開くと、GDScriptの代わりに、Godotおよびspine-godotのC# APIを使用することができます！

重要な注意事項: 以前に公式Godot C#エディタビルドを使用したことがある場合、NuGet キャッシュの $USER_HOME/.nuget に公式Godot C#のアセンブリが保存されている可能性があります。残念ながら、NuGetはこれらのアセンブリをSpine対応のアセンブリに置き換えることはありません。Spine対応のGodot C#プロジェクトをビルドする前に、NuGetキャッシュを消去してください。

詳しくはGodot C#の公式ドキュメントをご覧ください。

spine-godotランタイムのアップデート

ご自身のプロジェクトのspine-godotランタイムをアップデートする前に、Spineエディターとランタイムのバージョン管理に関するガイドを参照してください。

spine-godot GDExtensionを更新するには、上記の インストール セクションから最新バージョンをダウンロードし、ご自身のGodotプロジェクトにコピーしてください。

spine-godot C++エンジンモジュールを更新するには、以下の手順に従ってください。:

1. 上のインストールセクションから、使用するSpineランタイムとエディタのバージョンに対応した最新のビルド済みGodotエディタバイナリをダウンロードしてください。
2. 同じく上のインストールセクションから、使用するSpineランタイムとエディタのバージョンに対応した最新のビルド済みGodotエクスポートテンプレートバイナリをダウンロードしてください。
3. Godotエディタを開いて、Editor > Manage export templates ...と進み、Install from fileをクリックして、先ほどダウンロードした.tzpファイルを選択してエクスポートテンプレートをインストールします。
4. Spineのメジャーバージョンを別のバージョンに切り替える場合は、SpineのエディターバージョンとSpineランタイムのバージョンを一致させてSpineプロジェクトを再エクスポートし、Godotプロジェクトで古いエクスポートファイルを置き換えます。Godot内でご自身のGodotプロジェクトを開くことで、更新されたファイルの再インポートを行うことができます。
5. GodotでC#を使用している場合は、上記のように、エディタのダウンロードに含まれる GodotSharp ディレクトリから、プロジェクトの godot-nuget/ ディレクトリに新しいアセンブリをコピーしてください。

あるいは、Spineに対応しているGodotエディタとエクスポートテンプレートを上記のようにコンパイルし、必要に応じてステップ4を実行することもできます。

spine-godotを使用する

spine-godotランタイムはGodotのためのカスタムC++モジュールで、Spineで作成されたアニメーションのロード、再生、操作をサポートします。spine-godotランタイムはC++で書かれており、汎用spine-cppランタイムをベースにしています。spine-godotランタイムは spine-cppのクラスと関数をラップして、GDScriptに公開しています。また、spine-cppのAPIのほとんどを公開することに加え、spine-godotランタイムはSpineスケルトンを簡単に表示し、インタラクトするためのGodotノードも提供します。

Spineランタイムのアーキテクチャの詳細については、Spineランタイムガイドをご覧ください。

アセットのマネージメント

Godot用にエクスポートする

以下の実行方法については、Spineユーザーガイド内で紹介されています :

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

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

1. skeleton-name.spine-json または skeleton-name.skel:　これはスケルトンとアニメーションのデータを含んでいます。
2. skeleton-name.atlas:　これはテクスチャアトラスの情報を含んでいます。
3. １つまたは複数の.pngファイル:　これはテクスチャアトラスの各ページで、スケルトンが使用するイメージを含んでいます。

注意: JSONエクスポートよりもバイナリ形式でのスケルトンエクスポートの方がサイズが小さく、読み込みが速いので、基本的にはそちらを選択したほうが良いでしょう。どうしてもJSONを使いたい場合は、ファイルの拡張子が .json ではなく .spine-json になっていることを確認してください。既存のプロジェクトでまだ .json エクスポート ファイルを使用している場合は、こちらの Pythonスクリプトを使用して、新しい拡張子 .spine-json に変換することができます。

spine-godotランタイムは、これらのファイルを特別なGodotリソースタイプにインポートすることができます。

注意: spine-godotランタイムは現在、Godot側の技術的な制限により、乗算済みアルファ(pre-multiplied alpha)を使用してエクスポートされたアトラスをサポートしていません。Godotはデフォルトで、事前乗算されていないテクスチャ画像に対してブリード処理を行います。これは通常、乗算済みアルファを使用することで修正されるアーティファクトを回避するのに十分なものです。

Godotへのインポート

1. GodotプロジェクトをGodotエディタで開きます。
2. .skel/.spine-json、.atlas、.pngの各ファイルを任意のフォルダにドラッグしてください。

すると、アセットインポーターが、.skel または .spine-json スケルトンファイルごとに SpineSkeletonFileResource を、.atlas ごとに SpineAtlasAssetResource を、.png ファイルごとにGodotテクスチャリソースを作成します。

注意: SpineAtlasResource のインポート設定では、各アトラスページに使用する法線マップ(ノーマルマップ)画像の接頭辞を指定することもできます。デフォルトの接頭辞はnです。法線マップはオプションですが、2Dライティングのサポートに必要です。

ソースファイルのインポートが完了したら、SpineSkeletonFileResource と SpineAtlasResource を組み合わせて、SpineSprite で使用するSpineSkeletonDataResource を作成することができます。

Godotエディタのファイルシステムパネルで、Spineアセットを配置したフォルダを右クリックし、New Resource... を選択します。ポップアップダイアログで、SpineSkeletonDataResource を選択し、Create をクリックして、リソースに名前を付け、Save をクリックします。

新しく作成したリソースをダブルクリックして、インスペクタパネルに表示されるようにします。先にインポートしたアトラスリソースとスケルトンファイルリソースをスケルトンに割り当てます。スケルトンデータリソースにはアニメーションのミックスタイムも保存されており、インスペクタで変更できます。

注意: 特定のスケルトンファイルとアトラスの組み合わせのためのスケルトンデータリソースは、その組み合わせを表示するすべての SpineSprite のインスタンスで共有される必要があります。ゲームに読み込まれるデータ量が重複してしまうので、スケルトンデータをSpineSpriteのインラインリソースとして定義しないでください。

Spineアセットの更新

開発中にスケルトンデータやテクスチャアトラスファイルを更新したい時は、単純にSpineエディターから再エクスポートを行なって、Godotプロジェクト内の既存のファイルを置き換えるだけで簡単にこれらのソースファイル(.spine-json、.skel、.atlas、.png)ファイルを更新できます。

Godotエディタはこれらのソースファイルへの変更を検出し、それに応じてアセットを再インポートし、その過程でこれらのアセットを参照している他のリソースを更新します。もしGodotエディタがソースファイルの変更を認識できない場合、Godotエディタ内のファイルのインポート設定パネルで強制的に再インポートすることができます。

ノード

spine-godotランタイムは、Spineからエクスポートされたスケルトンを表示したり、アニメーションさせたり、変更を加えるためのノード群を提供します。

SpineSpriteノード

SpineSpriteノードはSkeletonDataResourceに格納されたスケルトンデータとアトラスを表示するノードです。このノードでは、スケルトンをアニメーションさせることができるAnimation stateを公開しています。SpineAnimationState は、SpineSprite.get_animation_state() で取得することができます。また、このノードは SpineSprite.get_skeleton() でスケルトンインスタンス (SpineSkeleton) を取得し、ボーンやスロット、アタッチメント、スキン、コンストレイントなどのプロパティを取得することができます。

SpineSpriteの作成

SpineSprite ノードを作成するには、シーンパネルの + ボタンをクリックし、 SpineSprite を選択します。次に、SpineSpriteノードが表示する SkeletonDataResourceを、上の画像のようにインスペクタの対応するプロパティに割り当てます。

Godotエディタのビューポートで各種ツールやキーボードショートカットを使って SpineSprite ノードを自由に変形させることができます。 SpineSprite のエディタ内のバウンディングボックス(境界)は、Spineエディターの設定モードでのスケルトンのバウンディングボックスに一致します。

ボーン、スロット、アタッチメントを確認する

SpineSprite に SkeletonDataResource を割り当てると、スケルトンのボーン、スロット、アタッチメントを確認することができます。

エディタビューポートで SpineSprite を選択し、Debug プロパティセクションで確認したいスケルトンコンポーネントにチェックを入れてください。

また、エディタビューポートで各パーツにマウスを乗せると、そのパーツ名が表示されます。

アニメーションのプレビュー

Preview プロパティセクションでは、エディタビューポートですぐに再生されるアニメーションを設定することができます。

Preview Frame をチェックすると、現在の Preview Time におけるアニメーションフレームが表示されます。また、Preview Time スライダでアニメーションをスクラブすることができます。

カスタムマテリアル設定

Materials プロパティセクションでは、サポートされているSpineのブレンドモードごとにカスタムマテリアルを設定することができます。設定したマテリアルは、SpineSprite のすべてのスロットとそのアタッチメントに適用されます。

単一のスロットにマテリアルを設定したい場合は SpineSlotNode を使用することができます。これは SpineSpriteに設定されているカスタムマテリアルを上書きします。

詳しくはサンプルプロジェクト内の example/09-custom-material シーンをご覧ください。

Update Mode設定

デフォルトでは SpineSprite は毎フレーム、可能な限り高速にその基礎データを更新します。この挙動を変更するには、Update Mode プロパティを変更します。

デフォルトは Process モードで、これはフレームレートに依存します。Physics モードは一定の間隔(デフォルトでは1秒間に60回)で SpineSprite を更新し、Godotの物理エンジン関連のコードに有用です。Manual モードは自動更新を全て無効にします。このモードでは、 _process(delta) や _physics_process(delta) をオーバーライドするときに SpineSprite.update_skeleton() を呼び出して手動で SpineSprite を更新する必要があります。このモードでは SpineSprite がいつ更新されるかを完全にコントロールすることができます。

詳しくはGodotの公式ドキュメントの「Idle and Physics Processing」を参照してください。

SpineSpriteをアニメーションさせるには

SpineSpriteをアニメーションさせるには、GDScriptまたはC#を使ってコードで行います。以下では、GDScriptを使用したコード例を示しますが、 これはspine-godotのC# APIにも直接対応しています。GDScriptからC#へのAPIのマッピング方法の詳細については、GodotのC#ドキュメントを参照してください。

SpineSprite は get_animation_state() 経由で SpineAnimationState を公開しています。より詳細な情報、特にアニメーショントラックとアニメーションのキューイングについてはSpineランタイムガイドの「アニメーションの適用」を参照してください。

SpineSprite のトラック0に特定のアニメーションを設定するには、以下のように SpineAnimationState.set_animation() を呼び出します。:

最初のパラメータはアニメーションの名前で、2つ目のパラメータはアニメーションをループするか否かを指定し、最後のパラメータはそのアニメーションが再生されるアニメーショントラックを指定します。

アニメーションのキューイングも、以下のようにAnimationStateメソッドで行います:

add_animation()の最初のパラメータはアニメーションの名前です。2つ目のパラメータはディレイを秒で指定します。このディレイの後にこのアニメーションがそのトラックの前のアニメーションを置き換えます。3つ目のパラメータはアニメーションをループするか否かを指定し、最後のパラメータはそのアニメーションが再生されるアニメーショントラックを指定します。

アニメーションステートのトラックにアニメーションを設定(set)または追加(add)すると、SpineTrackEntry が返されます。これを利用して特定のアニメーションの再生のプロパティをさらに変更することができます。例えば、TrackEntryを以下のように設定することでそのアニメーションを逆再生することができます。:

注意: SpineTrackEntry インスタンスは、使用中の関数以外では保持しないでください。TrackEntryは内部で再利用されるため、それが表すアニメーションが完了すると無効になります。

以下のように set_empty_animation() または add_empty_animation() を使用してアニメーショントラックに空のアニメーションを設定したりキューに入れることで、スケルトンをスムーズにセットアップポーズに戻すことができます:

set_empty_animation() の最初のパラメータはトラックを指定します。2つ目のパラメータは前のアニメーションをミックスアウトして「空(empty)」アニメーションをミックスインするのに使われるミックスデュレーションを秒単位で指定します。

add_empty_animation() の最初のパラメータはトラックを指定します。2つ目のパラメータは前のアニメーションをミックスアウトして「空(empty)」アニメーションをミックスインするのに使われるミックスデュレーションを秒単位で指定します。3つ目のパラメータはディレイを秒単位で指定します。このディレイの後にミキシングによって前のアニメーションを「空(empty)」アニメーションに置き換えます。

単一のトラック上のすべてのアニメーションを直ちに消去するには、 clear_track(track_id) を使用します。全てのトラックを一度に消去するには、clear_tracks() を使用します。この場合、スケルトンが最後にとったポーズがそのまま残されます。

スケルトンのポーズをセットアップポーズにリセットするには、SpineSprite.get_skeleton().set_to_setup_pose() を使います。これはボーンとスロットの両方をセットアップポーズの設定にリセットします。スロットだけをセットアップポーズの設定に戻したい時は、 SpineSprite.get_skeleton().set_slots_to_setup_pose() を使用してください。

シグナル

SpineSprite は、ライフサイクルを通してイベントに反応するために、複数のシグナルを公開しています。

アニメーションステートの変化に反応するために、以下のシグナルに接続することができます:

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

アニメーションステートのイベントに加えて、SpineSprite はより高度なライフサイクルのためのシグナルも公開しています:

• before_animation_state_update: アニメーションステートが現在のデルタタイムで更新される前に発信されます。
• before_animation_state_apply: アニメーションステートがスケルトンのポーズに適用される前に発信されます。
• before_world_transforms_change: スケルトンのボーンのワールドトランスフォームが更新される前に発信されます。
• world_transforms_changed: スケルトンのボーンのワールドトランスフォームが更新された後に発信されます。

これらのシグナルは、ボーンや他のスケルトンコンポーネントを手動で更新したいときに便利です。しかし一般的には、代わりに SpineBoneNode や SpineSlotNode を使用することをお勧めします。それらは、マウスカーソルの位置に基づいてボーンを配置するような使用例の99％をカバーしながらも、そのような手動更新の複雑さを軽減してくれるからです。

詳しくはサンプルプロジェクト内の example/02-animation-state-listeners シーンをご覧ください。

スキンの組み合わせ

髪や目、パンツ、イヤリングやバッグなどのアクセサリーを組み合わせて、自分だけのアバターを作ることができるアプリケーションやゲームはよくあります。Spineでは、スキンを組み合わせることでこれを実現することができます。

他のスキンからカスタムスキンを作成するには、以下のようにします:

まずSpineSprite.new_skin(name)でカスタムスキンを作成します。次に、SpineSpriteが管理しているSpineSkeletonからSpineSkeletonDataを取得します。これはSpineSkeletonData.find_skin()で名前を指定してスキンを探すために使用されます。そして SpineSkin.add_skin() で結合したいスキンを全て追加します。最後に、 SpineSkeleton.set_skin() でスケルトンに新しいスキンを設定します。

詳しくはサンプルプロジェクト内の example/03-mix-and-match シーンをご覧ください。

ボーントランスフォームの取得と設定

SpineSprite は、Spineのランタイムスケルトンをラップしたもので、ボーン、スロット、アタッチメント、コンストレイントから構成されています。スケルトンは、Spineエディタ上でスケルトンの原点を基準とした座標系で、ボーンのトランスフォームを管理します。

SpineSprite クラスは、ヘルパーメソッド get_global_bone_transform(name) および set_global_bone_transform(name, transform) を公開しており、これらはGodotのキャンバス空間でボーンのトランスフォームを取得、設定できるようにします。取得または設定されたトランスフォームは、スキュー(skew)をエンコードしないことに注意してください。

ボーンのトランスフォームを手動で設定したい場合は、SpineSprite がスケルトンのボーンのワールドトランスフォームを更新する前に行う必要があります。これは、 before_world_transforms_change シグナルへ反応させることで行うことができます。

また、ボーンのトランスフォームを直接設定する代わりに、SpineBoneNode を使用することができます。

SpineBoneNode

SpineBoneNode は、スケルトンのボーンに追従(follow)させたり、そのトランスフォームを操作(drive)することができます。マウスの位置など、何らかの入力に基づいてボーンのトランスフォームを制御したい場合では、driveモードで SpineBoneNode を使用します。CollisionShape を SpineSprite のボーンにアタッチしたい場合など、他のノードをスケルトンのボーンに追従させたい場合は、followモードで SpineBoneNode を使用します。

SpineBoneNode を作成するには、まずノードをアタッチしたい SpineSprite を右クリックし、 Add child node... を選択します。利用可能なノードタイプの一覧から SpineBoneNode を選択し、名前を付けます。その後、インスペクタでノードの設定を変更することができます。

注意: SpineBoneNode は常に SpineSprite の直接の子である必要があります。さもないと、追従または操作すべきボーンを見つけることができなくなってしまいます。

Bone Name プロパティのドロップダウンには、選択可能なすべてのボーンが表示されます。Bone Mode は、ノードが SpineSprite のボーンに追従するか、それを操作するかを指定します。ノードは有効にも無効にもでき、必要に応じて追従と操作をオン・オフすることができます。

SpineBoneNodeは、エディタビューポートにも表示されます。Debug セクションのプロパティで見た目を定義できます。

SpineBoneNode を使って SpineSprite 内のボーンをマウスの動きで操作する例については example/05-mouse-following シーンをご覧ください。

SpineBoneNode を使って SpineSprite　のボーンを追従する例は example/06-bone-following シーンをご覧ください。この例では、 SpineBoneNode 自体が子ノードを持ち、それが SpineSprite のボーンを追っているように見えるでしょう。

注意: 子ノードは SpineSprite の描画順序には正しく挿入されません。SpineSprite を構成するパーツの描画順序に任意のノードを挿入したい場合には SpineSlotNode が適しています。

SpineSlotNode

SpineSlotNode を使うと、 SpineSprite の描画順序に独自のノードを挿入することができます。これにより、パーティクルシステムやカスタムスプライト、他の SpineSprite のノードをスケルトンの特定のスロットのアタッチメントとして使うことができます。SpineSlotNode の子ノードは、そのスロットのアタッチメントがアクティブであれば、その上にレンダリングされます。また、SpineSlotNode を使って特定のスロットのマテリアルをオーバーライドすることもできます。

SpineSlotNode を作成するには、まずノードをアタッチしたい SpineSprite を右クリックし、Add child node... を選択します。利用可能なノードタイプの一覧から SpineSlotNode を選択し、名前を付けます。その後、インスペクタでノードの設定を変更することができます。

注意: SpineSlotNode は常に SpineSprite の直接の子である必要があります。さもないと、割り当てられたスロットを見つけることができなくなってしまいます。

Slot Name プロパティのドロップダウンには、選択可能なすべてのスロットが表示されます。Materials セクションでは、このスロットのデフォルトマテリアルを上書きするために使用するマテリアルを設定することができます。

SpineSlotNode を使用して SpineSprite の描画順序にノードを挿入する方法について詳しくは example/07-slot-node シーンを参照してください。

SpineSlotNode を使用して SpineSprite の特定のスロットのマテリアルをオーバーライドする方法について詳しくは example/09-custom-material シーンを参照してください。

SpineAnimationTrack

注意: SpineAnimationTrack は非常に実験的なものであることに注意してください。なぜなら、Godotのアニメーションエンジンはサードパーティのプラグインが、例えばインポートされた3Dキャラクターのアニメーションに見られるような完全な忠実度をサポートするほどオープンではないからです。

SpineAnimationTrack ノードを使うと、GodotのAnimationPlayerや強力なアニメーションエディタを使って SpineSprite をアニメーションさせることができます。コードで手作りするのではなく、Godotのアニメーションエディタを使ってカットシーンを作るのに適しています。

SpineAnimationTrack を作成するには、まずノードをアタッチしたい SpineSpriteを右クリックし、 Add child node... を選択します。利用可能なノードタイプの一覧から SpineAnimationTrack を選択し、名前をつけます。その後、インスペクタでノードの設定を変更することができます。

注意: : SpineAnimationTrack は常に SpineSprite の直接の子である必要があります。さもないと、割り当てられたスロットを見つけることができなくなってしまいます。

SpineAnimationTrack を作成すると、AnimationPlayer ノードが作成され、子ノードとしてアタッチされます。

SpineAnimationTrack とその子である AnimationPlayer をキーとして記録することで SpineSprite のアニメーションが行われます。再生するアニメーションを設定するには、子AnimationPlayer にキーを入力します。ループの可否や逆再生などのアニメーションのプロパティを変更するには、 SpineAnimationTrack プロパティをキーにします。

この2段構えにより、アニメーションエディタが子AnimationPlayer のキーとなるアニメーションのデュレーションを表示できるようになり、複雑なアニメーションシーケンスを簡単に作成できるようになっています。また、アニメーションエディタでタイムラインをスクラブしてプレビューすることも可能です。

注意: SpineSkeletonDataResource で定義された SpineSprite が使用するミックスタイムは、Godotアニメーションエディタの技術的制限により、エディタでプレビューすることができないことに注意してください。

単一の SpineSprite に対して複数の SpineAnimationTrack ノードをアタッチすることができます。これは複数のアニメーションを重ねるために使用できます。 SpineAnimationTrack にはそれぞれトラックインデックスが設定されています。同じスケルトンプロパティをキーとする場合、上位トラックのアニメーションは下位トラックのアニメーションの効果を上書きします。

詳しくは example/08-animation-player シーンをご覧ください。シーンのルートにアタッチされた AnimationPlayer には SpineAnimationTrack ノードとその子AnimationPlayer ノードをキーにした2つのアニメーションがあります。slow-moonwalk アニメーションは、SpineAnimationTrack　の基本的な原理を簡単に説明したものです。 cutscene アニメーションはより凝ったアニメーションで、複数トラックのキーイングと複雑なアニメーションシーケンスを実演しています。

2Dライティング

spine-godotはGodotの2Dライティングシステムと統合されています。

Godotの2Dライティングシステムをサポートするためには、テクスチャアトラスの法線マップ(ノーマルマップ)を提供する必要があります。テクスチャアトラスページを構成する各 .png は、ファイル階層でその隣に対応する .png 法線マップ画像を持たなければなりません。また、法線マップ画像ファイルは、共通の接頭辞を持つ必要があります。デフォルトの接頭辞は n_ です。例:raptor.png というテクスチャアトラスページ画像は、その隣に n_raptor.png という法線マップ画像を持つ必要があります。

テクスチャアトラスのインポート時に、spine-godotは各テクスチャアトラスページ画像に対して、法線マップ画像の検索とロードを試みます。テクスチャアトラスインポートビューで、独自の法線マップ画像の接頭辞を定義することができます。

テクスチャアトラスページと法線マップ画像が正常にインポートされたら、Godotの2Dライティングシステムを SpineSprite ノードに適用することができます。

詳しくはサンプルの中の 10-2d-lighting シーンをご覧ください。

ディスクからの.skel/.json/.atlasファイルのロード

MODの実装などのために、ディスク上の任意の場所から、エクスポートしたSpineアセットをロードしたい場合があります。これを実現するために、.skel と .json スケルトンファイルにはSpineSkeletonFileResource.load_from_file() 関数を、.atlas ファイルには SpineAtlasResource.load_from_atlas_file() 関数を使用できます。

大まかな原則:

• スケルトンファイルをロード
• アトラスファイルをロード
• スケルトンとアトラスから SpineSkeletonDataResource を構築
• SpineSkeletonDataResource から1つまたは複数の SpineSprite インスタンスを作成。データリソースは共有されます！

GDScriptでの全プロセス:

詳しくはサンプルシーン 13-load-from-disk をご覧ください。

SpineランタイムAPIアクセス

spine-godotは、SpineランタイムAPIのほとんどをGDSCriptにマッピングしています。SpineSprite.get_skeleton() 経由で SpineSprite から返される SpineSkeleton のようなオブジェクトは、spine-cpp APIをGDScriptに1対1で変換したものです。このため、Spineランタイムガイドに記載されている資料のほとんどをGDScriptに適用することができます。

しかし、GDScriptの性質上、以下のようにいくつかの制約があります:

• 返される配列やマップはすべて内部配列のコピーです。修正しても影響はありません。
• 個々の SpineTrackEntry オブジェクトにリスナーを設定することはできません。代わりに SpineSprite にシグナルを設定します。
• ボーンやスロット、その他のSpineオブジェクトを直接作成、追加、削除することはできません。
• アタッチメントとタイムラインのC++クラス階層は、GDScriptでは公開されません。