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

ライセンスについて

公式Spineランタイムをアプリケーションに組み込むには有効なSpineライセンスが必要ですが、評価目的でSpineランタイムを試用することは可能です。

はじめに

インストール方法

Unityプロジェクトでspine-unityランタイムを使用するには、以下の手順に従ってください :

  1. Unityをダウンロードしてインストールします。
  2. Unity Editorで新しい空のプロジェクトを作成します。
  3. spine-unityの最新のUnitypackageをダウンロードします。または、Git経由で最新の変更内容を取得することもできます(後述)。
  4. ダウンロードしたUnitypackageをインポートします(ダブルクリックすればUnityが開きます)。

Unitypackageを使わずGitで最新の変更を取得する方法

  1. spine-runtimesのGitリポジトリをクローンします。
  2. spine-runtimes/spine-unity/Assets/の中身を、ご自身のプロジェクトのAssets/フォルダーにコピーします。
  3. spine-runtimes/spine-csharp/srcフォルダを、ご自身のプロジェクトのAssets/Spine/Runtime/spine-csharpフォルダにコピーします。

Package Managerを介したインストール方法

Unitypackageの代わりに、UnityのPackage Managerから 'Add package from git URL' を利用する
お使いのUnityバージョンが比較的新しく、UnityのPackage ManagerにAdd package from git URL...オプションがある場合、以下のURLから直接3つのパッケージを追加することもできます:

  1. https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-csharp/src#4.1
  2. https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-unity/Assets/Spine#4.1
  3. https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-unity/Assets/Spine Examples#4.1 Spine Examplesパッケージのサンプルシーンを開くには、packageディレクトリのシーンファイルを、お使いのシステムのファイルマネージャー(エクスプローラーまたはFinder)を使用してAssetsディレクトリにコピーしてください。残念ながらUnityのバグにより、git URL経由でダウンロードしたパッケージ内のシーンを直接開こうとすると、以下のように"Opening scene in read-only package!"というエラーが発生してしまいます: Opening scene in readonly package

まず、UnityのWindow > Package ManagerよりPackage Managerを開きます。 3つのパッケージそれぞれについて、 + アイコンからAdd package from git URL... を選択し、上記 (またはダウンロードページから確認できる) git URLを入力します。#4.1 の部分は#5e8e4c21f11603ba1b72c220369d367582783744のように特定のgitコミットのハッシュを指定すると、プロジェクトに携わる全員が同じパッケージの状態を一貫して保持できます。 Window - Package Manager Add Package from git URL Enter git URL すると、Package Managerウィンドウに、追加されたパッケージのエントリーが表示されます。 Listed spine-unity packages ここまで完了するとProjectパネルで、Packagesの下にspine-unity Runtimeおよびspine-unity Runtime Examplesの項目が確認できます。 Project panel lists packages これらの項目がProjectパネルにまだ表示されていない場合は、Unityを一度終了し、再度開いてください。

2D Toolkitとの互換性

spine-unityは2D Toolkitをサポートしており、TK2Dのテクスチャアトラスシステムを使ってSpineのスケルトンをレンダリングすることができます。2D Toolkitとの互換性を有効にするにはEdit - Preferences(MacではUnity - Preferences)でUnityのPreferencesを開き、SpineセクションでDefine TK2D - Enableを選択してください。

オプションの拡張UPMパッケージ

spine-unityランタイムは追加のプラグインなしで動作します。Timelineやユニバーサルレンダーパイプライン (URP) のサポートなど、いくつかのオプション機能については、個別のUnity Package Manager(UPM)拡張パッケージによって提供されています。

拡張パッケージを分けている理由

Unityは、オプションモジュールの多くを新しいUnity Package Manager(UPM)エコシステムに移行しました。例えば、ユニバーサルレンダーパイプライン (URP) のベースシェーダーファイルは、「Universal RP」という名前でUPMパッケージとして提供されており、すべての新規Unityプロジェクトに最初から含まれているわけではありません。

そのため当社のUniversal RP Spineシェーダーをspine-unityランタイムに含めてしまうと、UnityのUniversal RPパッケージがプロジェクトにインストールされていない場合に紛らわしいエラーメッセージが表示されたり、追加の設定手順が必要になってしまいます。そのような依存関係を自動的に解決し、この追加機能をより簡単に使用することができるように、UPMパッケージとしてUniversal RP Spineシェーダーを提供しています。

インストール方法

オプションA - UPMパッケージをダウンロードする場合
  1. 使用したいUPMパッケージを、ダウンロードページからダウンロードするか、Gitリポジトリのspine-unity/Modulesサブディレクトリで探してください。
  2. 次のステップに進む前に、Unityプロジェクトを開いたまま新しい空のシーンを開くなどして、Spineコンポーネントを含むシーンを閉じることをお勧めします。
  3. 解凍またはクローンを行なった後、以下の2つの方法でパッケージを使用することができます :
    • a) プロジェクトにコピーする方法 パッケージの内容を、プロジェクト内のPackagesディレクトリにコピーします。するとUnityが自動的にロードを行います。
    • b) Package Managerを使用する方法 パッケージの内容をAssetsディレクトリ以外の場所にコピーし、UnityのWindow > Package ManagerよりPackage Managerを開き、+アイコンからAdd package from disk...を選択し、package.jsonファイルを指定します。 Window - Package Manager Add Package from Disk Select package.json こちらの例では、Package Managerウィンドウに、Spine Lightweight RP Shadersの項目が追加されました : Listed LWRP package また、ProjectパネルでもPackages以下にSpine Lightweight RP Shadersの項目が追加されています : Project panel lists package 追加した項目がProjectパネルにまだ表示されていない場合は、Unityを一度終了し、再度開いてください。

オプションB - git URLからパッケージを追加する場合

お使いのUnityバージョンが比較的新しく、UnityのPackage Managerに Add package from git URL... オプションがある場合、git URLを直接使用することが可能です。

重要な注意事項: git URLから URP Shaders UPM package をインストールする場合、spine-csharp および spine-unity パッケージも(unitypackageをAssetsフォルダにインストールするのではなく)Unity Package Manager経由でインストールされている必要があります。そうしないと、URP Shaders UPM package のシェーダーのインクルードパスが存在しないspine-unityパッケージディレクトリを指してしまい、シェーダーコンパイルエラーにつながってしまいます。

  1. 使用したいUPMパッケージのgit URLをダウンロードページで探してください。
  2. 次のステップに進む前に、Unityプロジェクトを開いたまま新しい空のシーンを開くなどして、Spineコンポーネントを含むシーンを閉じることをお勧めします。
  3. UnityのWindow > Package ManagerよりPackage Managerを開き、 + アイコンからAdd package from git URL... を選択し、 ダウンロードページで確認したgit URLを入力してください。 例: https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-unity/Modules/com.esotericsoftware.spine.urp-shaders#4.1  #4.1の部分は#5e8e4c21f11603ba1b72c220369d367582783744のように特定のgitコミットのハッシュを指定すると、プロジェクトに携わる全員が同じパッケージの状態を一貫して保持できます。 Window - Package Manager Add Package from git URL Enter git URL こちらの例では、Package Managerウィンドウに、Spine Lightweight RP Shadersの項目が追加されました : Listed LWRP package また、ProjectパネルでもPackages以下にSpine Lightweight RP Shadersの項目が追加されています: Project panel lists package 追加した項目がProjectパネルにまだ表示されていない場合は、Unityを一度終了し、再度開いてください。

サンプル

spin-unityランタイムのサンプルシーンを見るには :

  1. Unityをダウンロードしてインストールします。
  2. Unity Editorで新しい空のプロジェクトを作成します。
  3. spine-unityの最新のUnitypackageをダウンロードします。または、Git経由で最新の変更内容を取得することもできます(後述)。
  4. ダウンロードしたUnitypackageをインポートします(ダブルクリックすればUnityが開きます)。
  5. Unity Editorでプロジェクトを開き、ProjectパネルのSpine Examples/Getting Startedフォルダにある様々なサンプルシーンを確認します。各サンプルシーンには、実行方法のテキスト説明と、表示される内容についての説明があります。

Unitypackageを使わずGitで最新の変更を取得する方法

  1. spine-runtimesのGitリポジトリをクローンします。
  2. spine-runtimes/spine-unity/Assets/の中身を、ご自身のプロジェクトのAssets/フォルダにコピーします。
  3. spine-runtimes/spine-csharp/srcフォルダを、ご自身のプロジェクトのAssets/Spine/Runtime/spine-csharpフォルダにコピーします。

UPMパッケージからのインストールの代わりにPackage Managerとgit URLを使用する方法
また、UnityのPackage Managerで Add package from git URL を選択し、git UPM パッケージから spine-unityランタイムおよびspine-unityのサンプルをインストールすることも可能です。 詳しくはPackage Managerを介したインストール方法セクションを参照してください。

Unity Editorでプロジェクトを開き、Assets -> Open C# Projectを選択することで、サンプルとspine-unityランタイムの両方のC#コードを詳しく確認したり、修正したりすることができます。サンプルシーンの詳しい情報については、サンプルシーンセクションを参照してください。

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

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

注意: Spine 4.0以前のバージョンからエクスポートされたJsonおよびバイナリ形式のスケルトンデータファイルは、spine-unity 4.1ランタイムでは読み込めません。 スケルトンデータファイルをSpine 4.1で再エクスポートする必要があります。

プロジェクトがたくさんある場合は、こちらで説明しているように、プロジェクトファイルのエクスポートを自動化されることをお勧めします。 たとえば、当社では次のスクリプトを使ってすべてのSpineサンプルプロジェクトをエクスポートし、テクスチャアトラスを作成しています : export.sh

spine-unity 3.6 / 3.7 / 3.8 / 4.0から新しいバージョンにアップデートする場合は、以下のアップグレードガイドをご覧ください :

問題を未然に防ぐためにも、以下の手順を実行することを推奨しています :

  1. Unityのアップデートと同様に、アップデートを実行する前に、Unityプロジェクト全体をバックアップすることを常にお勧めします。
  2. Spineランタイムをアップデートする前には、必ずリードプログラマーおよびテクニカルアーティストに確認してください。SpineランタイムはSource-availableソフトウェア(ソースが利用可能なソフトウェア)で、プロジェクトの様々なニーズに応じてユーザーが変更できるように設計されています。あなたのプロジェクトのSpineランタイムは、プログラマーによって変更が加えられているかもしれません。この場合、最新のランタイムにアップデートするには、それらの変更点を新しいバージョンのランタイムに再適用する必要があります。
  3. ダウンロードしたUnitypackageに含まれている、またはgithub上にあるCHANGELOG.mdファイルをお読みください。メソッドが廃止されて新しいものに置き換えられたときに、必要なドキュメントをここで見つけることができます。

最新のspine-unityランタイムにアップデートしたいことを確信したら以下を行なってください :

  1. 最新のspine-unityランタイムを入手するには、最新のspine-unityパッケージをダウンロードします。また、Gitを使ってspine-runtimesのGitリポジトリから最新の変更点をプルしてアップデートすることもできます(後述)。
  2. Unity EditorとVisual Studio / Xcodeは閉じてください。
  3. 3.7から3.8へのアップグレードなど、異なるメジャー/マイナーバージョンへのアップグレードを行う場合は、以前のspine-unityのインストールディレクトリAssets/SpineAssets/Spine Examplesをプロジェクトから削除してください。
  4. ここまで出来たら、プロジェクトをUnity Editorで開きます。以前のspine-unityのインストールを削除した場合は、ログに出ているエラーは無視してください。
  5. Unitypackageをインポートします(ダブルクリックすればUnityが開きます)。
  6. 異なるメジャーまたはマイナーバージョンにアップグレードする場合は、Projectパネルで右クリック - Reimport Allを選択して、スケルトンアセットを再インポートします。または、すべてのアセットを再インポートする代わりに、再インポートするSpineスケルトンアセットを含むフォルダをProjectパネルで見つけて、そのフォルダを右クリックしてReimportを選択しても構いません。

Unitypackageを使わずGitで最新の変更を取得する方法

  1. spine-runtimesのGitリポジトリから最新の変更点をプルすることで、最新のspine-unityランタイムを入手できます。
  2. 3.7から3.8へのアップグレードなど、異なるメジャー/マイナーバージョンへのアップグレード時には、以前のspine-unityのインストールディレクトリAssets/SpineAssets/Spine Examplesをプロジェクトから削除してください。
  3. spine-runtimes/spine-unity/Assets/の内容を、ご自身のプロジェクトのAssets/フォルダにコピーします。
  4. spine-runtimes/spine-csharp/srcフォルダを、ご自身のプロジェクトのAssets/Spine/Runtime/spine-csharpフォルダにコピーします。

注意: spine-unityランタイムは、汎用spine-csharpランタイムをベースにしています。そのため、spine-unityとspine-csharpの両方のランタイムの変更点をGitHubで確認してください。

Add package from git URLを使用してPackage Managerでアップデートする方法

spine-unity ランタイムをリモートの git URL から Add package from git URLでパッケージとして追加した場合、UnityのPackage Managerを使用してそのパッケージを更新することができます。UnityのWindow > Package ManagerからPackage Managerを開き、 spine-csharp Runtimespine-unity Runtimespine-unity Runtime Examplesの各パッケージを選択して、Updateボタンを押すと、gitから指定されたブランチの最新版が再ダウンロードされます。https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-csharp/src#4.1のようにURLの末尾が#4.1の場合、gitリポジトリの4.1ブランチから最新版を再ダウンロードすることになります。

拡張UPMパッケージのアップデート

オプションの拡張UPMパッケージをアップグレードする場合 :

  • spine-unityランタイムのアップデートと同じ原則が適用されます。
  • 前述の通り、アップデートを行う前には必ずUnityプロジェクト全体をバックアップすることをお勧めします。

オプションA - インプレース・アップデート (ダウンロードした.zipファイルまたはgit経由の場合)

  1. Unityプロジェクトを開いている場合は a) Unityを終了する または b) (新しい空のシーンを開くなどして)Spineコンポーネントを含むシーンを閉じる ことをお勧めします。
  2. 新しいUPMパッケージのzipファイルまたはgitディレクトリの中身を既存のものにコピーします。このディレクトリは、ご自身でUPMパッケージをどのようにインストールしたかによって、プロジェクトのproject_root/Packages/package_nameディレクトリか、Add package from disk..でロードしたAssetsディレクトリの外の任意のディレクトリになっています。
  3. Unityを終了した場合は、再度Unityでプロジェクトを開きます。
  4. Unityが新しいアセットをインポートし、ローディングのプログレスバーを表示します。

オプション B - 'Add package from git URL'を使用している場合

パッケージをリモートの git URL から Add package from git URLで追加した場合、UnityのPackage Managerを使用してそのパッケージを更新することができます。UnityのWindow > Package ManagerからPackage Managerを開き、 更新したいパッケージを選択して、Updateボタンを押すと、gitから指定されたブランチの最新版が再ダウンロードされます。https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-unity/Modules/com.esotericsoftware.spine.timeline#4.1のようにURLの末尾が#4.1の場合、gitリポジトリの4.1ブランチから最新版を再ダウンロードすることになります。

Unityでのスクリプティング

C#でのプログラミングやUnityの使い方に慣れていない方は、まずUnityの公式チュートリアルをご覧になることをお勧めします。Unity EssentialsBeginner Scriptingの2つのトピックから始めるのが良いでしょう。なお、Spineでは独自のアニメーションワークフローを提供しているため、spine-unityにはアニメーション関係のトピックを直接適用できないことにご注意ください。

spine-unityランタイムを使用する

概要

spine-unityランタイムは、Spineで作成されたアニメーションの再生と操作をサポートするUnityプラグインです。spine-unityランタイムはC#で書かれており、汎用spine-csharpランタイムをベースにしています。spine-unityランタイムは、spine-csharpの構造体や関数をラップして、Unityコンポーネントとして公開します。また、spine-unityランタイムは、Spineエディターからエクスポートされたファイルをインポートし、Unityのカスタムアセットタイプに格納します。

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

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

Unity用にSpineアセットをエクスポートする

エクスポートのユーザーガイド

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

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

初心者のためのSpineからUnityへのエクスポート

以下は、SpineのアセットをUnity用にエクスポートする簡単な方法です。

  1. スケルトンとアニメーションを作成した後、Spineメニュー>Export...(エクスポート...) (CTRL+E)をクリックします。すると、Export(エクスポート)ウィンドウが開きます。

  2. Export(エクスポート)ウィンドウの左上にある JSON を選択してください。

    注意: バイナリスケルトンエクスポートの方がJSONエクスポートよりもサイズが小さくロードも早いので、製品段階ではJSONエクスポートではなくバイナリエクスポートを使用した方が良いでしょう。

  3. Texture Atlas(テクスチャアトラス) のチェックボックス Pack(パック) にチェックしてください。※初心者の方は Nonessential data(非必須データ)Pretty print(整形表示) にチェックを入れておくことをお勧めします。また、Animation cleanup(アニメーションクリーンアップ) が無効になっていることを確認してください。そうしないと、セットアップポーズと同じキーがエクスポートされなくなります。 a. Pack(パック) チェックボックスの下の Pack Settings(パック設定) をクリックします。すると Texture Packer Settings(テクスチャ・パッカー設定) ウィンドウが開きます。
    b. 右下の Atlas extension(アトラス拡張子) というテキストボックス内で .atlas.txt が設定されていることを確認してください。 c. これでTexture Packer Settings(テクスチャ・パッカー設定)ウィンドウでの操作は完了です。OK をクリックして閉じてください。

  4. Export(エクスポート)ウィンドウで出力フォルダを選択してください(新しく空のフォルダーを作成することを推奨します)

  5. Export(エクスポート) をクリックしてください。

  6. すると以下の3種類のファイルが書き出されます:

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

注意: 2D Toolkit ユーザーの場合、ステップ3(.pngと.atlas.txtのパッキング)は必要ありません。代わりにSkeletonDataAssetに適切なフィールドを用意して、tk2dSpriteCollectionData への参照を割り当てます。2D Toolkitのサポートを有効にする方法については、このページのインストール方法セクションを参照してください。

Unity向けのバイナリエクスポート

JSONではなくバイナリ形式でエクスポートすると、ファイルサイズが小さくなり、ロードが速くなります。

以下はspine-unityでバイナリ形式のエクスポートに変更する方法です。

  1. エクスポートウィンドウの左上で JSON の代わりに Binary(バイナリ) を選択します。
  2. Extension(拡張子).skel.bytes を設定します。

注意: spine-unityでは拡張子が .skel のファイルを読み込むことができません。拡張子は必ず .skel.bytes を使用してください。

高度な情報 - エクスポートの自動化

プロジェクトの数が多い場合は、Spineのコマンドラインインターフェースを使用してスケルトンとアトラスのエクスポートを自動化することをお勧めします。これにより、反復的な手作業がなくなり、新しいSpineバージョンへアップグレードする際にも全てのプロジェクトを一度に簡単に再エクスポートできるようになります。

コマンドラインインターフェイスの活用例についてはこちらを参照してください。 例えば、当社ではSpineのサンプルプロジェクトを一括してエクスポートしてテクスチャアトラスを作成するために次のスクリプトを使用しています: export.sh

高度な情報 - 単一テクスチャアトラスのエクスポートとSkeletonGraphic

一般的には、サブメッシュの追加によるドローコールの数を減らすために、単一のテクスチャ(単一ページ)のアトラスを使用することをお勧めします。これは特にSkeletonGraphicに当てはまります。UnityのCanvasRendererの制限により、SkeletonGraphicの使用はデフォルトで単一テクスチャに制限されています。SkeletonGraphicのInspectorでAdvanced - Multiple CanvasRenderersを有効にすると、サブメッシュごとに子CanvasRenderer GameObjectを生成してテクスチャの制限枚数を増やすことができますが、パフォーマンス上の理由により、可能な限り避けるべきです。よって、UIで使用されるスケルトンは、複数ページのアトラスではなく単一テクスチャ(単一ページ)のアトラスとしてパックされなければなりません。

1つのアトラスページに収まらない場合は、フォルダごとにまとめられたテクスチャアトラスページをパックすることができます。こうすることで、各スキンに必要なアトラスページを1つにすることができます。

画像をそれぞれのフォルダに配置したら、以下の手順でスケルトンをエクスポートします :

  1. Ctrl+Eを押すか、ドロップダウンメニューでExport...(エクスポート...)を選択します。
  2. Texture Atlas(テクスチャアトラス)Pack(パック)を有効にして、右にある設定をAttachments(アタッチメント)からImage Folder(画像フォルダ)に変更します。
  3. (任意)Pack Settings(パック設定)の中で、右下のOptions(オプション)にあるFlatten Paths(パス平坦化)Combine Subdirectories(サブディレクトリ結合)が無効になっていることを確認してください(デフォルトでは無効です)。
  4. Export(エクスポート)をクリックします。

高度な情報 - 乗算済み vs ストレートアルファエクスポート

Spineでは、アトラステクスチャのエクスポート方法として、「Texture Packer Settings(テクスチャ・パッカー設定)」による2つの基本的なワークフローがあります :

  1. 乗算済みアルファ(デフォルト設定。ガンマ(Gamma)色空間で事前に乗算されます)
  2. ストレートアルファ

乗算済みアルファワークフローは、ストレートアルファに比べて加算ブレンドを使用するアタッチメントのための余分なドローコールが無いことや、より良いミップマップの生成などいくつかの利点があります。

エクスポートとインポートの設定を正しく一致させることが非常に重要です。Unityでの正しい設定については、高度な情報 - 乗算済み vs ストレートアルファインポートのセクションを参照してください。

SpineアセットのUnityへのインポート

  1. Unity Editorでご自身のUnityプロジェクトを開いてください。インストール方法セクションの説明に従って、プロジェクトにspine-unityランタイムが既に入っている状態にしておいてください。
  2. エクスポートされたファイル(.json.atlas.txt.png)のフォルダを開きます。
  3. エクスポートされたファイル(またはファイルを含むフォルダ)を、プロジェクトのAssetsフォルダの任意のサブフォルダにコピーします。これを行うには、エクスポートされたファイルをエクスプローラーまたはFinderウィンドウからUnityのProjectパネルにある任意のフォルダにドラッグしてください。

spine-unityランタイムは、追加されたファイルを検出すると自動的に必要な追加Unityアセットを生成します。

以下のアセットが生成されます:

  1. _Atlasは、テクスチャアトラスファイル(.atlas.txt)用のアセットです。これは、マテリアルと.atlas.txtファイルへの参照を保持します。
  2. _Materialは、各テクスチャアトラスページ(.png)用のアセットです。これは、シェーダー.pngテクスチャへの参照を保持します。
  3. _SkeletonDataは、スケルトンデータファイル(.json.skel.bytes)用のアセットです。これは.jsonまたは.skel.bytesファイルへの参照と、生成された _Atlas アセットを保持します。このアセットには、スケルトンのカスタムインポートおよびアニメーション設定も含まれます。詳しくはSkeleton Data Assetセクションを参照してください。

高度な情報 - 乗算済み vs ストレートアルファインポート

高度な情報 - 乗算済み vs ストレートアルファエクスポートで説明されている通り、Spineはアトラステクスチャをどのようにエクスポートするかについて2つの基本的なワークフローがあります :

  1. 乗算済みアルファ(デフォルト設定。ガンマ(Gamma)色空間で事前に乗算されます)
  2. ストレートアルファ
正しいインポート設定のためのPreferencesのパラメーターAtlas Texture Settings

重要な注意事項: アトラステクスチャのエクスポートでPremultiply alpha(乗算済みアルファ)設定を使用する際の重要な注意事項として、Unity上でマテリアルの Straight Alpha Texture パラメーターとテクスチャの Alpha Is Transparency 設定を両方とも無効にすることがとても重要です(その逆も同様です)。 spine-unityランタイムはUnityの Edit - Preferences (MacではUnity - Preferences)からアクセスできる Preferences ウィンドウにSpineセクションを追加します。このセクションの Atlas Texture Settings パラメーターの設定に従って、新しいアトラステクスチャがインポートされた際にテクスチャとマテリアルの設定が自動的に適用されます。そのすぐ下に、Additive MaterialMultiply MaterialScreen Materialのマテリアルテンプレートがあります。ストレートアルファワークフローに切り替える場合、これらのテンプレートマテリアル参照もそれに応じて調整する必要があります。

Spine Preferences - Atlas Texture Settings Spine Preferences PMA Preset Selection Spine Preferences - Blend Mode Materials Spine Preferences Blend Mode Material Selection

SpineからPremultiply alpha(乗算済みアルファ)を有効(デフォルト)にしてアトラステクスチャをエクスポートしている場合は、Atlas Texture SettingsPMATexturePreset、ブレンドモードマテリアルもそれぞれ SkeletonPMAAdditiveSkeletonPMAMultiplySkeletonPMAScreen のままで問題ありません。 Premultiply alpha を無効にしている場合は、Atlas Texture SettingsStraightAlphaTexturePreset に、そしてブレンドモードマテリアルもSkeletonStraightAdditiveSkeletonStraightMultiplySkeletonStraightScreen に設定してください。 または独自の TextureImporter Preset アセットやブレンドモードマテリアルを自作して割り当てることもできます。自作する場合は、使用するブレンドモードを反映させるために、PMA または Straight を含む名前を設定されることをお勧めします。

もし透明な領域の周りに黒い境界線が見えたり、アタッチメントの画像の周囲にカラフルなストライプが見えてしまうような場合には、インポート設定が間違っている可能性があります。

テクスチャ・パッカーの正しいエクスポート設定およびテクスチャとマテリアルの正しいインポート設定
  1. 乗算済みアルファ(Premultiplied Alpha)の場合 テクスチャ・パッカー設定でPremultiply alpha(乗算済みアルファ)を有効
    UnityのTexture設定でsRGB (Color Texture)を有効、Alpha Is Transparencyを無効
    UnityのMaterialのパラメータStraight Alpha Textureを無効に設定

  2. ストレートアルファ(Straight Alpha)の場合 テクスチャ・パッカー設定でPremultiply alpha(乗算済みアルファ)を無効、Bleed(ブリード)を有効
    UnityのTexture設定でsRGB (Color Texture)を有効、Alpha Is Transparencyを有効
    UnityのMaterialのパラメータStraight Alpha Textureを有効に設定

デフォルトのテクスチャ・パッカー設定はPremultiply alphaを使用しています。spine-unityランタイムに付属している全てのSpineシェーダーは、デフォルトでPremultiply alphaワークフローを使用するように設定されており、デフォルトでStraight Alpha Textureパラメータが無効になっています。

しかし、ストレートアルファワークフローを使用したい場合もありえます。そのようなケースとしては以下が考えられます:

  1. リニア(Linear)色空間を使用している場合。この場合は必ずストレートアルファ使用してください
    事前乗算はガンマ(Gamma)空間で行われるため、インポート時にリニア(Linear)空間に変換し直すと境界線が発生してしまいます。この組み合わせがマテリアルで検出されると、警告ログメッセージが出力されます。
  2. 付属のSpineシェーダー以外のシェーダーを使用したい場合。 一般的なシェーダーはストレートアルファテクスチャを想定していることが多いため、画像アタッチメントの周りに黒い境界線ができてしまうことがあります。

ストレートアルファワークフローに切り替える際には、上記のようにすべてのテクスチャとマテリアルを適切に設定してください。現在の色空間(カラースペース)は、Project Settings - Player - Other Settings - Color Spaceで確認および変更することができます。

高度な情報 - UnityのSpriteAtlasをAtlas Providerとして使用する

注意: 基本的には、UnityのSprite Atlasアセットではなく通常のSpineのワークフローに従いSpineが作成したスプライトアトラスを使用することが推奨されます。Spineのアトラスは、効率の良いパッキングを行いますし、複数のアトラスページをサポートし、問題も発生しにくいです。そのため、UnityのSprite Atlasアセットは、通常のSpineのワークフローが使えない場合にのみ、atlas providerとして使用するようにしてください。また、収集したスキンで使用されているテクスチャ領域を、実行時に単一のアトラステクスチャに再パックできることも考慮してください。

.atlas.txt.pngの代わりにUnityのSpriteAtlasをatlas providerとして、スケルトンデータファイルと一緒に使用することができます。インポートは、Window - Spine - SpriteAtlas Importからアクセスできる、特別なSpine SpriteAtlas Importツールウィンドウで行います。

Spine SpriteAtlas Import Window

Sprite Atlasの準備手順:

  1. Assets - Create - Sprite AtlasSprite Atlasを作成します。
  2. Sprite AtlasのInspectorObjects for Packingに、アタッチメントとして使用するSpriteの入ったフォルダを追加します。
  3. (a) 2018.2以前のUnityバージョンでは、手動でTight Packingを無効にし、Read/Write Enabledを有効にしてください。 (b) 2018.2以降のUnityバージョンでは、これらの設定は自動的に調整されます。 Spine SpriteAtlas Import Window
  4. 新しいSpine SpriteAtlas ImportウィンドウのSprite AtlasプロパティにSprite Atlasを割り当ててください。すると追加のアセットが自動的に生成されます。 Spine SpriteAtlas Import Window
  5. Load regions by entering Play modeを押すと、短時間だけ再生モードに切り替わり、また戻ってきて領域情報をロードします。これでSprite AtlasがSpineアトラスとして使用できるようになります。

.jsonまたは.skel.bytesスケルトンアセットでアトラスを使用する場合 :

  1. .jsonまたは.skel.bytesファイルを、新しく作成したアトラスアセットと同じディレクトリに配置します。
  2. 配置したファイルをSpine SpriteAtlas ImportウィンドウのSkeleton json/skel fileプロパティに割り当ててください。 Spine SpriteAtlas Import Window
  3. Import Skeletonを押してSprite Atlasアセットを使った_SkeletonDataファイルを生成します。

Spine Preferences

spine-unityランタイムはUnityのEdit - Preferences(MacではUnity - Preferences)からアクセスできるPreferencesウィンドウにSpineセクションを追加します。ここでは、スケルトンのインポートやインスタンス化の際に使用されるデフォルト値を設定したり、spine-unityのアピアランスや更新動作をカスタマイズすることができます。

Spine Preferences Window

  • Show Hierarchy Icons : Spineコンポーネントがアタッチされている場合に、HierarchyパネルでGameObjectsの横に関連するアイコンを表示するかどうかを設定します。
  • Auto-reload scene components : シーン内のスケルトンコンポーネントのSkeletonDataAssetに変更が加わるたびに、そのコンポーネントを再ロードします。シーンに多数のSkeletonRendererまたはSkeletonGraphicコンポーネントがある場合、この処理に時間がかかることがあります。
  • Auto-Import Settings
    • Default Mix : 新しくインポートされたSkeletonDataAssetsのDefault Mix Durationの値を設定します。
    • Default SkeletonData Scale : 新しくインポートされたSkeletonDataAssetsのデフォルトのScale値を設定します。
    • Default Shader : 新しくインポートされたスケルトンのアトラステクスチャのために作成されたマテリアルに割り当てられるデフォルトのシェーダーを設定します
    • Apply Atlas Texture Settings : 後述のTextureImporterでリファレンスのAtlas Texture Settings設定を適用するかどうかを設定します。
    • Atlas Texture Settings : ここで選択したテクスチャインポート設定を、新しくインポートされたアトラステクスチャとマテリアルに適用します。SpineからPremultiply alpha(乗算済みアルファ)を有効(デフォルト)にしてアトラステクスチャをエクスポートしている場合、PMATexturePresetのままで問題ありません。もしPremultiply alpha(乗算済みアルファ)を無効にしているのであれば、StraightAlphaTexturePresetを設定してください。または、独自のTextureImporter Presetアセットを自作して、ここに割り当てることもできます。
    • Additive Material : スロットのブレンドモードがAdditive(加算)のマテリアルのテンプレートを設定します。詳しくはSkeletonDataのBlend Mode Materialsを参照してください。
    • Multiply Material : スロットのブレンドモードがMultiply(乗算)のマテリアルのテンプレートを設定します。詳しくはSkeletonDataのBlend Mode Materialsを参照してください。
    • Screen Material : スロットのブレンドモードがScreen(スクリーン)のマテリアルのテンプレートを設定します。詳しくはSkeletonDataのBlend Mode Materialsを参照してください。
  • Warnings
    • Atlas Extension Warning : .atlasファイルが見つかったときに、警告と勧告をログに出します。
    • Texture Settings Warning : テクスチャのインポート設定で、白い境界線が出るアーティファクト(画像の乱れ)など、望ましくない効果をもたらす可能性があるものが検出された場合、警告と勧告をログに出します。
  • Editor Instantiation
  • Mecanim Bake Settings
    • Include Folder Name in Event : 有効にすると、Mecanimのイベントは"FolderNameEventName"という名前のメソッドを呼び出し、無効にすると、"EventName"を呼び出します。
  • Handles and Gizmos
    • Editor Bone Scale : Sceneビューで表示されるボーンや同様のギズモ要素のサイズを設定します。
  • Prefabs
    • Fix Prefab Overr. MeshFilter : 同じ名前のスケルトンコンポーネントのInspectorパラメーター( Advancedセクション)のグローバル設定です。そのコンポーネントパラメーターが Use Global Settings に設定されている場合、この設定が使用されます。
  • Timeline Extension - Timeline拡張UPMパッケージに関連する項目
    • Default Mix Duration : 新しく作成した Spine Animation State ClipsDefault Mix Duration パラメーターのデフォルト値を設定します。
    • Use Blend Duration : 新しく作成したSpine Animation State ClipsのデフォルトのUse Blend Durationパラメーターを設定します。

Spineアセットの更新

開発中にスケルトンデータやテクスチャアトラスファイルを更新したい時は、単純にこれらのファイル(.json.skel.bytes.atlas.txt.png)を上書きするだけで更新できます。Spineエディターからアセットを再エクスポートしたら、エクスポートしたファイルをプロジェクトのAssetsフォルダのサブフォルダにコピーし、既存のファイルを上書きしてください。

Unityはこれらのファイルの変更を検出し、変更されたアセットを自動的に再インポートします。再インポート後は、以前にインポートしたSpineアセットへの参照はすべてそのままで、最新のデータを使用します。

注意: 時々、Unityがファイルの変更を認識できないことがあります。この場合、UnityのProjectパネルで、再インポートしたいSpineのアセットが入っているフォルダを探し、そのフォルダを右クリックして、コンテキストメニューからReimportを選択してください。

Skeleton Data Asset

スケルトンデータアセット(接尾辞が_SkeletonDataになっているアセット)には、スケルトンを構成するボーンの階層、スロット、表示順序、アニメーションなどの情報が保管されています。spine-unityランタイムで提供される他のコンポーネントは、このスケルトンデータアセットを参照・共有して、スケルトンのアニメーションや表示を行います。

スケルトンデータアセットを詳しく確認または修正するには、まずUnityのProjectパネルで選択します。するとInspectorパネルにスケルトンデータのすべてのプロパティが表示され、確認や修正ができます。

Skeleton Data

SkeletonDataセクションでは、スケルトンの一般的なインポート設定を行います。

  • Scale : このデータアセットを参照するすべてのスケルトンインスタンスに影響するカスタムインポートスケール値を指定できます。値を変更すると、このスケルトンのすべてのインスタンスに直ちに影響します。

    注意: 例えば、32pxのアートワークを1つのゲームユニット(単位)に正確に合わせたい場合(アタッチメントの画像がSpineでスケーリングされていない場合)このScaleパラメーターを1/px_per_unitに設定することができます。例えば、32px/unitの場合、Scale1/32 = 0.03125に設定します。

  • SkeletonData Modifiers : .jsonまたは.skel.bytesからのロードが完了した後に、ユーザーがスケルトンデータアセットに追加処理を加える方法を提供します。 詳細についてはSkeletonData Modifierアセットセクションを参照してください。

  • Blend Modes - Upgrade : 古いBlendModeMaterialAssetを、以下のネイティブなBlend Mode Materialsのプロパティにアップグレードします。

  • Blend Mode Materials : 特殊なブレンドモードを使用しているスケルトンのスロットには、追加のマテリアルが必要です。これらのマテリアルは、BlendModeMaterialAssetが古いUnityやspine-unityのバージョンで使用されていない限り、インポート時に自動的に設定されます。割り当てられたBlendModeMaterialAssetは、前述のBlend Modes - Upgradeボタンでアップグレードすることをお勧めします。これにより、Unityの新しいバージョンでの問題を防ぐことができます。ブレンドモードごとのマテリアルテンプレートはSpine Preferencesでカスタマイズできます。

    • Apply Additive Material : このパラメーターを有効にすると、Additive(加算)ブレンドモードを持つスロットにもマテリアルが生成されます。ストレートアルファワークフローを使用する場合はこのパラメーターを有効にします。PMAワークフローを使用している場合は、Normal(通常)Additive(加算)が設定されているスロットを同じPMAマテリアルで描画することができるため、このパラメーターは必要ありません。
    • Additive MaterialsMultiply MaterialsScreen Materials : これらのリストには、各ブレンドモードで現在使用されているブレンドモードマテリアルが表示されます。

Atlas

アトラスの参照は、スケルトンがレンダリングを行うために、エクスポートされた画像をそれぞれの画像名に従って各画像領域に分解するために使用されます。

上の画像のAtlas Assetsの配列は、アトラスアセット(_Atlasで終わるアセット)ごとに1つのエントリが自動的に入力されます。

必要なアトラスアセットの自動割り当てに失敗してしまった場合は、Atlas AssetsSizeを必要な量に合わせて変更して、必要なアトラスアセットをElement0 - ElementNに手動で割り当てることができます。

Mix Settings

スケルトンデータアセットでは、アニメーションのミックスタイムを指定することができます。

Default Mix Durationでは、デフォルトのミックスタイムを秒単位で入力できます。

Add Custom Mixボタンをクリックし、Custom Mix DurationsセクションにMix Durationを設定することで、上のDefault Mix Durationの値よりも優先される、特定の2つのアニメーション間のミックスタイムを定義することができます。

スケルトンデータアセットを使用するコンポーネント(Skeleton Animationコンポーネントなど)は、アニメーションを再生する際にこのミックスタイムを使用します。

Preview

スケルトンデータアセットのPreviewセクションでは、アセットに含まれるすべてのボーン、スロット、アニメーション、スキン、イベントを確認することができます。

各アニメーションの左側にある再生ボタンでアニメーションを再生したり、SlotsセクションのShow Attachmentsでそれぞれのスロットのライブアップデートを見ることができます。タイムラインバーには、すべてのイベントが紫色のマーカーで表示されます。再生中にマーカーにカーソルを合わせると、イベント名が表示されます。

Create Animation Reference Assetsボタンを使用するとスケルトンのすべてのアニメーションのリファレンスアセットを生成できます。AnimationReferenceAssetは、単一のSpine.Animationを参照するUnityアセットとして機能し、Inspectorでコンポーネントのプロパティに割り当てることができます。

Skeleton Mecanim

SpineのデフォルトのアニメーションシステムではなくUnityのMecanimアニメーションシステムを使用したい場合は、Generate Mecanim ControllerでMecanimコントローラーを生成して割り当てることができます。

Skeleton Baking

注意: Bakingは特殊なツールであり、spine-unityでスケルトンを使用する際に推奨される方法ではありません!また、SkeletonMecanimSkeletonAnimation または SkeletonGraphic (UI)コンポーネントには使用できません!代わりに、スケルトンをMeshRendererと互換性のあるアニメーションクリップを持ちTransformsの固定された階層を持つ、柔軟性の低いPrefabにベイクダウンします。 Spineの機能の多くはUnityのアニメーションシステムには存在しないので、変換することができず、プロセスの中で無視されます。

Skeleton Baking Windowを開くには、SkeletonDataAssetのInspectorの右上にある歯車のアイコンをクリックし、Skeleton Bakingを選択します。

サポートされている機能とサポートされていない機能の詳細なリストは、SkeletonBaker.csに記載されています。

注意: Bakingは、最近追加されたUnityの2Dアニメーションシステムではなく、以前からあった3DMeshRendererベースのシステムを使用しています。

Texture Atlasアセット

テクスチャアトラスアセットには、スケルトンで使用されるイメージに関する情報が含まれています。すなわち、どのテクスチャアトラスページにイメージが保存されているかや、テクスチャアトラスページ上のUVテクスチャ座標が含まれています。

テクスチャアトラスページのマテリアルを表示するには、Materials配列のマテリアルアセットをダブルクリックします。

注意: ご自身でテクスチャアトラスアセットが参照するマテリアルやテクスチャを修正することができます。テクスチャを変更する際は、UVテクスチャ座標が有効であることを確認してください。

Set Mipmap Bias to -0.5ボタンは高度な設定で、アトラステクスチャでGenerate Mip Mapsが有効になっている場合に、ぼやけた外観を補正するために使用できます。

Apply Regions as Texture Sprite Slicesボタンを押すと、アトラスの各画像要素に対してスプライトを生成することができます。生成されたスプライトは、テクスチャアトラスイメージ(pngファイル)の領域を参照しており、Unityのスプライトアセットとして使用できます。

SkeletonData Modifierアセット

SkeletonData modifierアセットは、.jsonまたは.skel.bytesファイルからのロードが完了した後に、ユーザーがスケルトンデータアセットに追加処理を加える方法を提供します。

SkeletonDataAssetのInspectorにはアセットを追加できるSkeleton Data Modifiersのリストがあります。

内包されるSkeletonData Modifiers - BlendModeMaterialsAsset (旧式)

注意: spine-unity では、各SkeletonDataAssetでスロットのブレンドモードAdditive(加算)Multiply(乗算)Screen(スクリーン)ネイティブサポートを提供し、新しくインポートされた各SkeletonDataAssetでは自動的にセットアップが行われます。BlendModeMaterialAssetsは廃止され、SkeletonDataAssetのネイティブ プロパティに置き換えられました。SkeletonDataAssetのInspectorには廃止されたBlendModeMaterialAssetをアップグレードするための新しいBlend Modes - Upgradeボタンがあります。このアップグレードは、Unity 2020.1以降のバージョンで報告されたBlendModeMaterialAssetの問題を防ぐために、インポートおよび再インポートされたアセットに対して自動的に実行されます。

BlendModeMaterialsAssetは、spine-unityに含まれるSkeletonData modifierのアセットクラスです。SpineエディターでAdditive(加算)Multiply(乗算)Screen(スクリーン)の各ブレンドモードが割り当てられたスロット内のアタッチメントのレンダリングに使用できるマテリアルへの参照を保持しています。

BlendModeMaterialsアセットに格納されているマテリアルの参照は、読み込まれたアタッチメントに適切なテクスチャを使用する新しいマテリアルを生成するためのテンプレートとして使用されます。

spine-unityランタイムには、Default BlendModeMaterialsという名前のBlendModeMaterialsAssetがパッケージされており、すぐに使用できます。この付属のアセットを使用することで、特別なブレンドモードを持つスロットのアタッチメントが、付属のデフォルトのMultiply(乗算)Screen(スクリーン)シェーダー、Spine/Blend Modes/Skeleton PMA MultiplySpine/Blend Modes/Skeleton PMA Screenを使用できるようになります。

異なるマテリアルやシェーダー、異なる設定のマテリアルを使用する必要がある場合は、Create -> Spine -> SkeletonData Modifiers -> Blend Mode Materialsで新しいBlendModeMaterialsAssetを作成してください。そして、作成したアセットにマテリアルのテンプレートを割り当てます。

カスタムSkeletonDataModifierAssetクラスを書くには

独自のカスタムSkeletonDataModifierAssetクラスを書いて、.jsonまたは.skel.bytesファイルから読み込んだ後のスケルトンデータアセットに追加処理を加えることができます。SkeletonDataModifierAssetは、抽象的なScriptableObjectクラスで、ここから独自のクラスを派生させることができます。

  1. SkeletonDataModifierAssetから派生した新しいクラスを作成し、void Apply (SkeletonData skeletonData)メソッドを実装します。CreateAssetMenuクラス属性を追加して、Asset -> Createメニューにクラスのエントリをリストアップします。

    C#
    [[CreateAssetMenu(menuName = "TopMenu/Submenu/SubSubmenu", order = 200)]
    public class BlendModeMaterialsAsset : SkeletonDataModifierAsset {

    public override void Apply (SkeletonData skeletonData) {
        ...
    }
    }
  2. Projectパネルで任意のフォルダを選択し、新しく作成したAsset -> Createメニューを選択して、新しいクラスのインスタンスを作成します。作成したアセットを、SkeletonDataアセットのSkeleton Data Modifiersリストの要素に割り当てます。

Apply(skeletonData)は、.jsonまたは.skel.bytesファイルからのデータのロードが完了した後に呼び出されます。

主要なコンポーネント

spine-unityランタイムは、Spineからエクスポートされたスケルトンの表示、アニメーション、追従および修正を可能にするコンポーネントのセットを提供します。これらのコンポーネントは、上述のようにインポートされたスケルトンデータとテクスチャアトラスアセットを参照します。

スケルトンをシーンに追加する

ご自身のUnityプロジェクトにSpineスケルトンを素早く表示するには :

  1. 前述のように、スケルトンデータとテクスチャアトラスをインポートします。
  2. _SkeletonDataアセットをSceneビューまたはHierarchyパネルにドラッグし、SkeletonAnimationを選択します。すると、あらかじめ必要なSpineコンポーネントが設定された新しいGameObjectがインスタンス化されます。

補足: STEP2の代わりに、同じGameObjectをいちから作ることもできます :

  1. GameObject -> Create Emptyで空のGameObjectを新規作成します。
  2. GameObjectを選択し、InspectorでAdd Componentをクリックして、SkeletonAnimationを選択します。これを行うと、追加のMeshRendererMeshFilterコンポーネントも自動的に追加されます。
  3. SkeletonAnimationコンポーネントで、必要なSkeleton Data Assetをドラッグして、_SkeletonDataプロパティに割り当てます。

注意: Sceneビューで、画像がアタッチされていないボーンだけのスケルトンが表示されてしまう場合、Initial Skinプロパティをdefault以外のスキンに切り替えると良いでしょう。

これで、コンポーネントのC# APIを使って、スケルトンをアニメーションさせたり、アニメーション中で発生するイベントへの反応などができるようになります。詳細は後述のコンポーネントのドキュメントを参照してください。

SkeletonAnimationの代わりとなるもの - SkeletonGraphic (UI) と SkeletonMecanim

UnityでSpineスケルトンを使用する上で推奨される方法はSkeletonAnimationとしてスケルトンをインスタンス化することで、3つの選択肢の中で最も完全な機能セットを提供します。

スケルトンをインスタンス化するには、3つの選択肢があります:

  1. SkeletonAnimation - Spineのカスタムアニメーションとイベントシステムを使用し、最高のカスタマイズ性を実現しています。レンダリングにはMeshRendererを使用し、UnityのスプライトのようにSpriteMaskなどのマスクと連動します。 これがUnityでSpineのスケルトンを使用する際に推奨されている方法です。
  2. SkeletonGraphic (UI) - Unity Canvasと共にUI要素として使用します。RectMask2DのようなUIマスクを、Unityに元から入っているUI要素のようにレンダリングおよび作用させることができます。アニメーションとイベントの動作はSkeletonAnimationと同じです。
  3. SkeletonMecanim - UnityのMecanimアニメーションとイベントシステムを使用して、アニメーションの開始、ミキシング、アニメーション間の移行(トランジション)を行います。SkeletonAnimationに比べて、アニメーションのミキシングやトランジションの選択肢が少ないという欠点があります。また、SkeletonMecanimを使用した場合、トランジションがSpineエディターでプレビューされた通りに表示されるかは保証されません。

高度な情報 - 実行中でのインスタンス化

注意: 通常のワークフローでは、シーンにスケルトンを追加してプレハブに格納するか、インスタンスプールからプールされたオブジェクトを再利用してインスタンス化するのが望ましいです。その方がカスタマイズや調整が容易になります。

推奨されるワークフローではありませんが、spine-unity APIでは、SkeletonDataAssetから、またはエクスポートされた3つのアセットから直接、実行中に SkeletonAnimationSkeletonGraphic をインスタンス化することができます。エクスポートされたアセットから直接インスタンスを作成するのは、通常のUnityインポートパイプラインでは SkeletonDataAssetSpineAtlasAsset を事前に自動作成できない場合にのみ行うことを推奨します。

C#
// SkeletonAnimation GameObject を SkeletonDataAsset からインスタンス化する
SkeletonAnimation instance = SkeletonAnimation.NewSkeletonAnimationGameObject(skeletonDataAsset);

// SkeletonGraphic GameObject を SkeletonDataAsset からインスタンス化する
SkeletonGraphic instance
   = SkeletonGraphic.NewSkeletonGraphicGameObject(skeletonDataAsset, transform, skeletonGraphicMaterial);
C#
// エクスポートしたアセットを事前にインポートせずにインスタンス化する
// 1. AtlasAssetを作成します (atlas.textアセットとテクスチャ、マテリアル/シェーダーが必要です);
// 2. SkeletonDataAssetを作成します (JSONまたはバイナリアセットファイル、およびAtlasAssetが必要です)
SpineAtlasAsset runtimeAtlasAsset
   = SpineAtlasAsset.CreateRuntimeInstance(atlasTxt, textures, materialPropertySource, true);
SkeletonDataAsset runtimeSkeletonDataAsset
   = SkeletonDataAsset.CreateRuntimeInstance(skeletonJson, runtimeAtlasAsset, true);
// 3. SkeletonAnimationを作成します(有効なSkeletonDataAssetが必要です)
SkeletonAnimation instance = SkeletonAnimation.NewSkeletonAnimationGameObject(runtimeSkeletonDataAsset);

サンプルシーン Spine Examples/Other Examples/Instantiate from Script や、そこで使用されているサンプルスクリプト SpawnFromSkeletonDataExample.csRuntimeLoadFromExportsExample.csSpawnSkeletonGraphicExample.cs でさらに詳しく確認できます。

SkeletonAnimationコンポーネント

SkeletonAnimationコンポーネントは、SpineスケルトンをUnityで使用する3つの方法のうちの1つです。3つの方法とは、SkeletonAnimationSkeletonMecanimSkeletonGraphic (UI)のことです。

SkeletonAnimationコンポーネントは、spine-unityランタイムの核となるものです。SpineスケルトンをGameObjectに追加し、そのスケルトンをアニメーションさせたり、アニメーションイベントに反応させたりすることができます。

Skeleton Data設定

SkeletonAnimationコンポーネントは、スケルトンのボーン階層やスロットなどの情報を取得できるスケルトンデータアセットへの参照を必要とします。

スケルトンをドラッグ&ドロップでSceneに追加した場合、そのスケルトンデータアセットが自動的に割り当てられます。 既に設定されているGameObjectがあってそのスケルトンを別のアセットに変更したくなった場合は、Inspectorプロパティを使って手動で変更することができます。

スケルトンデータを設定・変更するには

  1. SkeletonAnimation GameObjectを選択します。
  2. InspectorのSkeletonData Assetプロパティに _SkeletonData アセットを割り当てます。

初期スキンとアニメーションの設定

SkeletonAnimationのInspectorは以下のパラメーターを公開しています :

  1. Initial Skin : ここで設定したスキンがスタート時に割り当てられます。 注意: 画像がアタッチされていないボーンだけのスケルトンが表示されている場合は、default以外のスキンに切り替えて、スキンを表示した方が良いでしょう。
  2. Animation Name : ここで設定したアニメーションがスタート時に再生されます。
  3. Loop : 初期アニメーションをループさせるか、一度だけ再生するかを定義します。
  4. Time Scale : ここでタイムスケールを設定することで、アニメーションの再生を遅くしたり、速くしたりすることができます。
  5. Unscaled Time : trueに設定すると、アップデートが Time.deltaTime の代わりに Time.unscaledDeltaTime に従って実行されます。これはスローモーションなどの影響を受けずに独立したUI要素をアニメーションさせたい場合などに便利です。

ルートモーションの有効化

SkeletonAnimationおよびSkeletonGraphic (UI)コンポーネントのルートモーションは、別のSkeletonRootMotionコンポーネントを介して提供されます。SkeletonAnimationのInspectorにはRoot Motion Add Componentボタンがあり、適切なコンポーネントをスケルトンのGameObjectに素早く追加できます。

高度なパラメーターの設定

SkeletonAnimationのInspectorのAdvancedセクションを展開すると、高度な設定パラメーターが表示されます。

SkeletonAnimationのInspectorでは、以下の詳細なパラメーターを公開しています

  • Initial Flip X、Initial Flip Y : これらのパラメーターは、スタート時にスケルトンを水平または垂直方向に反転させることができます。これにより、反転した部分のScaleXScaleY-1になります。
  • Animation Update : 通常のUpdate (デフォルト)、物理ステップFixedUpdate、またはユーザーコールによる手動アニメーション更新のいずれかを指定します。Rigidbody または Rigidbody2D が割り当てられたSkeletonRootMotion コンポーネントを使用する場合、更新モードをIn FixedUpdate に設定することをお勧めします。それ以外の場合は、 In Update を推奨します。
  • Update When Invisible : MeshRendererが非表示になったときに使用されるアップデートモードを設定します。メッシュが再び表示されるようになると、アップデートモードは自動的にUpdateMode.FullUpdateにリセットされます。
  • Use single submesh : 1つのマテリアルのみを使用し、1つのサブメッシュのみを必要とすると前提した場合に、サブメッシュの生成を簡素化するために有効にすることができます。これは、複数マテリアルの使用、レンダリングの分割、カスタムスロットマテリアルを無効にします。
  • Fix Draw Order : この設定は3つ以上のサブメッシュが使用されている場合のみ適用されます(2つ以上のマテリアルが交互に並んでいる場合、例:「A B A」)。trueの場合、MaterialPropertyBlockが各マテリアルに割り当てられ、LWRPレンダラーなどによるサブメッシュの積極的なバッチ処理を防ぎ、誤った描画順序になるのを防ぎます(例:「A1 B A2」が「A1 A2 B」に変更される等)。すべてが正しく描画されている場合は、このパラメータを無効にしておくことでパフォーマンスコストを節約することができます。
  • Immutable triangles : この設定は、アタッチメントの表示状態を変更することが無いスケルトンのレンダリングを最適化するために有効にすることができます。trueの場合、三角形が更新されなくなります。スケルトンがアタッチメントの切り替えや非表示、または描画順序キーを使用しない場合、最適化のためにこれを有効にします。そうでない場合は、これをfalseに設定するとレンダリングでエラーが発生する可能性があります。
  • Clear State on Disable : このコンポーネントまたはそのGameObjectが無効になったときに、レンダーとスケルトンの状態をクリアする設定です。これにより、再び有効になったときに以前の状態が保持されるのを防ぐことができます。スケルトンをプールする場合は、これをtrueに設定すると便利です。
  • Fix Prefab Override MeshFilter : Prefabが常に変更されたものとしてマークされるのを修正します(MeshFilterの非表示フラグをDontSaveInEditorに設定)。 ただし、他のコンポーネントからのMeshFilterへの参照は失われます。Use Global Settingsに設定すると、Spine Preferencesの設定が使用されます。
  • Separator Slot Names : レンダリングを分割する場所を決めるスロットを設定します。これはSkeletonRenderSeparatorなどのコンポーネントで使用され、スケルトンを異なるGameObject上に2つの別々のレンダラーでレンダリングすることができます。
  • Z-Spacing : この設定を変更すると、アタッチメントがスケルトンレンダラーコンポーネントによって、x/y平面上で前後にレンダリングされるようになります。各アタッチメントが、z軸上のカスタマイズ可能なz-spacing値によってオフセットされ、Zファイティング(z-fighting)を回避します。

  • PMA Vertex Colors : 頂点カラーRGBと頂点カラーアルファを乗算します。レンダリングに使用されているシェーダーがSpineシェーダー(ストレートアルファテクスチャを使用している場合も)またはPMAのAdditive(加算)ブレンドモードBlend One OneMinusSrcAlphaを使用するサードパーティ製シェーダーの場合、このパラメーターを有効にします。通常のブレンドモードBlend SrcAlpha OneMinusSrcAlphaを持つ通常のシェーダーの場合は、このパラメーターを無効にします。無効にすると、加算スロットのシングルバッチレンダリングができなくなり、ドローコールの回数が増えてしまう可能性があります。
  • Tint Black (!) : ブラックティントの頂点データをメッシュに追加します。ブラックティントは、このエフェクトが機能するために、シェーダーがUV2とUV3をブラックティントカラーとして解釈する必要があります。付属のSpine/Skeleton Tint Blackシェーダーを使用することができます。個々のパーツではなくスケルトン全体を着色する必要がある場合は、効率が良く、MaterialPropertyBlockで_Blackマテリアルプロパティを変更/アニメーションさせることができるSpine/Skeleton Tintシェーダーをお勧めします。詳しくはシェーダーセクションを参照してください。複数のスケルトンを異なる方法でティントする際にバッチングを維持するにはSkeleton.R .G .B .Aによるティントをお勧めします。
  • Add Normals : 有効にすると、メッシュジェネレーターは出力メッシュに法線を追加します。使用するシェーダーが頂点法線を必要とする場合に有効にしてください。パフォーマンスを向上させ、メモリ使用量を削減するには、代わりにSpine/Skeleton Litシェーダーのような、希望する法線を想定するシェーダーを使用することができます。Spine/SpriteシェーダはFixed Normalを仮定するようにも設定できることに注意してください。
  • Solve Tangents : 一部のライトシェーダーは、通常、ノーマルマップ(法線マップ)を適用するために、頂点接線を必要とします。有効にすると、毎フレームで接線が計算され、出力メッシュに追加されます。
  • Physics Inheritance : トランスフォームの動きをスケルトンの物理コンストレイントに適用する方法を制御します。
    • Position : ゼロ以外に設定すると、X方向およびY方向のトランスフォームの位置移動がスケルトンの物理コンストレイントに適用され、ここで設定したXおよびYのスケール係数で乗算されます。一般的な組み合わせは以下の通りです:
      (1,1) にした場合、XY移動が通常通り適用されます。
      (2,2) にした場合、XY移動が倍の強さで適用されます。
      (1,0) にした場合、水平方向の移動だけが適用されます。
      (0,0) にした場合、トランスフォームの移動の動きは全く適用されなくなります。
    • Rotation : ゼロ以外に設定すると、トランスフォームの回転の動きがスケルトンの物理コンストレイントに適用され、ここで設定したスケール係数で乗算されます。一般的な値は以下の通りです:
      1 にした場合、通常通り適用されます。
      2 にした場合、倍の強さで適用されます。
      0 にした場合、トランスフォームの回転の動きは全く適用されなくなります。
    • Movement relative to 親トランスフォームなどに対する相対的なトランスフォームの動きを適用するには、これを動きを計算する基準となるトランスフォームに設定します。None に設定すると、ワールドの絶対位置(デフォルト)を使用します。
  • Add Skeleton Utility : このボタンを使用すると、ボーンの位置をトラッキングしたり、オーバーライドしたりするためのSkeletonUtilityコンポーネントをGameObject素早く追加することができます。詳しくはSkeletonUtilityを参照してください。
  • Debug : ゲームの実行中にスロットの現在のカラーやボーンのスケール値などの情報を知りたい時は、Debugボタンを押せばデバッグ用のSkeleton Debugウィンドウを開けます。ここで、ボーン、スロット、コンストレイント、表示順序、イベント、スケルトンの統計情報などの現在の状態を確認することができます。

ライフサイクル


SkeletonAnimationコンポーネントでは、AnimationStateが現在再生中のアニメーションやキューされたアニメーションのステート(状態)を保持しています。 UpdateごとにAnimationStateが更新され、アニメーションが時間的に進むようになります。そして、新しいフレームが新しいポーズとしてスケルトンに適用されます。

スクリプトは、SkeletonAnimationのUpdateの前でも後でも実行できます。 あなたのコードがSkeletonAnimationのUpdateの前にスケルトンまたはボーンの値を取得する場合、コードは現在のフレームではなく前のフレームから値を読み取ります。

このコンポーネントは、イベントコールバックデリゲートをプロパティとして公開しており、すべてのボーンのワールドトランスフォームが計算される前と後に、このライフサイクルをインターセプトすることができます。これらのデリゲートにバインドすることで、アクターやコンポーネントの更新順序を気にすることなく、ボーンの位置やスケルトンの他の側面を修正することができます。

SkeletonAnimation Update コールバック

  • SkeletonAnimation.BeforeApplyは、そのフレームのアニメーションが適用される前に発生します。このコールバックは、アニメーションが適用される前にスケルトンの状態を変更したい場合に使用します。
  • SkeletonAnimation.UpdateLocalは、そのフレームのアニメーションが更新され、スケルトンのローカル値に適用された後に発生します。ボーンのローカル値を読み込んだり修正したりする必要がある場合に使用します。
  • SkeletonAnimation.UpdateCompleteは、Skeletonのすべてのボーンに対してワールド値が計算された後に発生します。SkeletonAnimationは、この後、Updateでそれ以上の操作をしません。ボーンのワールド値を読み取る必要がある場合は、これを使用してください。これらの値は、SkeletonAnimationのUpdate後にスクリプトが変更すると、まだ変更される可能性があります。
  • SkeletonAnimation.UpdateWorldは、Skeletonのすべてのボーンについてワールド値が計算された後に発生します。このイベントをサブスクライブすると、skeleton.UpdateWorldTransformが2回目に呼び出されます。スケルトンの複雑さやあなたがやっていることによっては、これは不要であったり、無駄であったりします。このイベントは、ボーンのワールド値に基づいて、ボーンのローカル値を修正する必要がある場合に使用します。これは、Unityのコードでカスタムコンストレイントを実装するのに便利です。

C#
// your delegate method
void AfterUpdateComplete (ISkeletonAnimation anim) {
   // this is called after animation updates have been completed.
}

// register your delegate method
void Start() {
   skeletonAnimation.UpdateComplete -= AfterUpdateComplete;
   skeletonAnimation.UpdateComplete += AfterUpdateComplete;
}

SkeletonRenderer Update コールバック

  • OnRebuild は、スケルトンが正常に初期化された後に発生します。
  • OnMeshAndMaterialsUpdated は、メッシュとすべてのマテリアルが更新された後、LateUpdate() の最後に発生します。

C#
// your delegate method for OnMeshAndMaterialsUpdated
void AfterMeshAndMaterialsUpdated (SkeletonRenderer renderer) {
   // this is called after mesh and materials have been updated.
}

// your delegate method for OnRebuild
void AfterRebuild (SkeletonRenderer renderer) {
   // this is called after the Skeleton is successfully initialized.
}

// register your delegate method
void Start() {
   skeletonAnimation.OnMeshAndMaterialsUpdated -= AfterMeshAndMaterialsUpdated;
   skeletonAnimation.OnMeshAndMaterialsUpdated += AfterMeshAndMaterialsUpdated;

   skeletonAnimation.OnRebuild -= AfterRebuild;
   skeletonAnimation.OnRebuild += AfterRebuild;
}

別の方法として、スクリプトの実行順序をSkeletonAnimationのUpdateメソッドの後に実行するように変更することもできます。

UnityのMonoBehaviourのライフサイクルについては、こちらをご覧ください: docs.unity3d.com/Manual/ExecutionOrder

C#

スケルトンをコードで操作するには、SkeletonAnimationコンポーネントにアクセスする必要があります。一般的なUnityコンポーネントと同様に、一度リファレンスを参照して、その後の使用のために保存しておくことをお勧めします。

C#
...
using Spine.Unity;

public class YourComponent : MonoBehaviour {

   SkeletonAnimation skeletonAnimation;
   Spine.AnimationState animationState;
   Spine.Skeleton skeleton;

   void Awake () {
      skeletonAnimation = GetComponent<SkeletonAnimation>();
      skeleton = skeletonAnimation.Skeleton;
      //skeletonAnimation.Initialize(false); // when not accessing skeletonAnimation.Skeleton,
                                 // use Initialize(false) to ensure everything is loaded.
      animationState = skeletonAnimation.AnimationState;
   }

Skeleton

SkeletonAnimationコンポーネントは、SkeletonAnimation.Skeletonプロパティを介して、基礎となるSkeletonへのアクセスを提供します。Skeletonには、スケルトンデータアセットへの参照が格納されており、このアセットは1つまたは複数のアトラスアセットを参照します。

Skeletonでは、スキンやアタッチメントを設定したり、ボーンをリセットしてポーズやスケールを設定したり、スケルトン全体を反転させたりすることができます。

アタッチメントの設定

アタッチメントを設定するには、スロットとアタッチメント名を入力します。

C#
bool success = skeletonAnimation.Skeleton.SetAttachment("slotName", "attachmentName");
C#
// using properties
[SpineSlot] public string slotProperty = "slotName";
[SpineAttachment] public string attachmentProperty = "attachmentName";
...
bool success = skeletonAnimation.Skeleton.SetAttachment(slotProperty, attachmentProperty);

上記コード中の[SpineSlot][SpineAttachment]は、こちらのセクションで説明しているStringのプロパティ属性(Attribute)です。

セットアップポーズへのリセット

プロシージャルなアニメーションでは、ボーンやスロットをセットアップのポーズに戻すことが必要な場合があります。

C#
skeleton.SetToSetupPose();
skeleton.SetBonesToSetupPose();
skeleton.SetSlotsToSetupPose();

スキンの設定

Spineのスケルトンには、どのアタッチメントをどのスロットに装着するかを定義する複数のスキンがあります。Skeletonコンポーネントは、スキンを切り替える簡単な方法を提供します。

C#
bool success = skeletonAnimation.Skeleton.SetSkin("skinName");
C#
// using properties
[SpineSkin] public string skinProperty = "skinName";
...
bool success = skeletonAnimation.Skeleton.SetSkin(skinProperty);

スキンの組み合わせ

Spineスキンを組み合わせることで、例えば、単一の服アイテムスキンから完全なキャラクタースキンを形成することができます。 詳細は、新しいSkin APIドキュメントをご覧ください。

C#
var skeleton = skeletonAnimation.Skeleton;
var skeletonData = skeleton.Data;
var mixAndMatchSkin = new Skin("custom-girl");
mixAndMatchSkin.AddSkin(skeletonData.FindSkin("skin-base"));
mixAndMatchSkin.AddSkin(skeletonData.FindSkin("nose/short"));
mixAndMatchSkin.AddSkin(skeletonData.FindSkin("eyelids/girly"));
mixAndMatchSkin.AddSkin(skeletonData.FindSkin("eyes/violet"));
mixAndMatchSkin.AddSkin(skeletonData.FindSkin("hair/brown"));
mixAndMatchSkin.AddSkin(skeletonData.FindSkin("clothes/hoodie-orange"));
mixAndMatchSkin.AddSkin(skeletonData.FindSkin("legs/pants-jeans"));
mixAndMatchSkin.AddSkin(skeletonData.FindSkin("accessories/bag"));
mixAndMatchSkin.AddSkin(skeletonData.FindSkin("accessories/hat-red-yellow"));
skeleton.SetSkin(mixAndMatchSkin);
skeleton.SetSlotsToSetupPose();
skeletonAnimation.AnimationState.Apply(skeletonAnimation.Skeleton); // SkeletonMecanimの場合は skeletonMecanim.Update() を使用してください
ランタイムでの再パッキング

スキンを組み合わせると、複数のマテリアルが蓄積されることがあります。しかしこれは、ドローコールの増加につながってしまいます。 Skin.GetRepackedSkin()メソッドを使えば、収集したスキンに使用されているテクスチャ領域を、実行時に単一のテクスチャにまとめることができます。

C#
using Spine.Unity.AttachmentTools;

// 再パックされたスキンを作成します。
Skin repackedSkin = collectedSkin.GetRepackedSkin("Repacked skin", skeletonAnimation.SkeletonDataAsset.atlasAssets[0].PrimaryMaterial, out runtimeMaterial, out runtimeAtlas);
collectedSkin.Clear();

// 再パックされたスキンを使用します。
skeletonAnimation.Skeleton.Skin = repackedSkin;
skeletonAnimation.Skeleton.SetSlotsToSetupPose();
skeletonAnimation.AnimationState.Apply(skeletonAnimation.Skeleton); // skeletonMecanim.Update() for SkeletonMecanim

// オプションとして、複数の再パック操作後にキャッシュをクリアすることができます。
AtlasUtilities.ClearCache();

重要な注意事項: 再パッキングに失敗したり、予期せぬ結果になる場合は、以下の原因が考えられます。:

  1. Read/Writeが無効になっている : プラットフォームの性能によっては、再パックされたテクスチャに結合されるソーステクスチャにRead/Write Enabledパラメーターを設定する必要があります。
  2. Compressionが有効になっている : プラットフォームによっては、ソーステクスチャのテクスチャインポート設定のCompressionNormal QualityではなくNoneに設定されていることを確認してください。
  3. Qualityの設定で、半分または1/4の解像度のテクスチャを使用している : 半分または1/4の解像度のテクスチャが使用されている場合、正しくない領域がコピーされるというUnityの既知のバグがあります。Project SettingsのQualityの設定がすべてフル解像度のテクスチャを使用していることを確認してください。
  4. ソーステクスチャが2のべき乗になっていなくてもUnityがそれを最も近い累乗に拡大している : このため、a)パック設定Power of two(2のべき乗)を有効にしてSpineからエクスポートするか、b)Unityのアトラステクスチャのインポート設定でNon-Power of TwoNoneになっていることを確認してください。

さらに深く理解するには、サンプルシーンのSpine Examples/Other Examples/Mix and MatchSpine Examples/Other Examples/Mix and Match Equip、そして使用されているMixAndMatch.csのサンプルスクリプトを参考にしてください。

高度な情報 - ノーマルマップと一緒にランタイムで再パッキングする

メインテクスチャと一緒に、ノーマルマップ(法線マップ)やその他の追加テクスチャレイヤーを再パックすることもできます。 int[] additionalTexturePropertyIDsToCopy = new int[] { Shader.PropertyToID("_BumpMap") };GetRepackedSkin()のパラメーターとして渡すことで、メインテクスチャとノーマルマップ(法線マップ)レイヤーの両方を再パックすることができます。

C#
Material runtimeMaterial;
Texture2D runtimeAtlas;
Texture2D[] additionalOutputTextures = null;
int[] additionalTexturePropertyIDsToCopy = new int[] { Shader.PropertyToID("_BumpMap") };
Skin repackedSkin = prevSkin.GetRepackedSkin("Repacked skin", skeletonAnimation.SkeletonDataAsset.atlasAssets[0].PrimaryMaterial, out runtimeMaterial, out runtimeAtlas,
additionalTexturePropertyIDsToCopy : additionalTexturePropertyIDsToCopy, additionalOutputTextures : additionalOutputTextures);

// 再パックされたスキンを使用します。
skeletonAnimation.Skeleton.Skin = repackedSkin;
skeletonAnimation.Skeleton.SetSlotsToSetupPose();
skeletonAnimation.AnimationState.Apply(skeletonAnimation.Skeleton); // skeletonMecanim.Update() for SkeletonMecanim

注意: 通常、ノーマルマップ(法線マップ)のプロパティは"_BumpMap"という名前になっていますが、カスタムシェーダーを使用する場合は、必ずそれぞれのプロパティ名を使用してください。なお、この名前はシェーダー内のプロパティ名であり、Inspectorに表示される"Normal Map"ラベル文字列ではないことに注意してください。

スケルトンのスケール変更と反転

スケルトンを垂直または水平方向に反転させることで、アニメーションを再利用することができます。例えば、左向きの歩行アニメーションを右向きにして再生することができます。

C#
bool isFlippedX = skeleton.ScaleX < 0;
skeleton.ScaleX = -1;
bool isFlippedY = skeleton.ScaleY < 0;
skeleton.ScaleY = -1;

skeleton.ScaleX = -skeleton.ScaleX; // x反転の状態を切り替え

ボーンのトランスフォームを手動で取得・設定する

注意: こちらは非常に特殊なケースでのみ使用することをお勧めします。 SpineのBoneFollowerSkeletonUtilityBoneコンポーネントの方がより簡単にボーンを操作することができます。

Skeletonでは、ボーンのトランスフォーム値を設定・取得できるので、IKによる地形追従を実装したり、パーティクルシステムなどの他のアクターやコンポーネントをスケルトンのボーンに追従させることができます。

注意: SkeletonAnimation.UpdateWorldデリゲートをサブスクライブすることで、ワールドトランスフォームの更新のライフサイクルの一部として新しいボーンの位置を取得して適用するようにしてください。そうしないと、ロード時に修正が1フレーム遅れたり、設定したときにアニメーションによって上書きされたりする可能性があります。

C#
Bone bone = skeletonAnimation.Skeleton.FindBone("boneName");
Vector3 worldPosition = bone.GetWorldPosition(skeletonAnimation.transform);
// note: when using SkeletonGraphic, all values need to be scaled by the parent Canvas.referencePixelsPerUnit.

Vector3 position = ...;
bone.SetPositionSkeletonSpace(position);

Quaternion worldRotationQuaternion = bone.GetQuaternion();

アニメーション - AnimationState

ライフサイクル

SkeletonAnimationコンポーネントは Update メソッドを実装しています。このメソッドでは、デルタタイムに基づいて基礎となるAnimationStateを更新し、そのAnimationStateをスケルトンに適用し、スケルトンのすべてのボーンのワールドトランスフォームを更新します。

SkeletonAnimationコンポーネントは、SkeletonAnimation.AnimationState プロパティを介してAnimationStateAPIを公開しています。このセクションでは、トラック、TrackEntry、ミックスタイム、アニメーションのキューイングなどの概念について、全般的なSpineランタイムガイドのアニメーションの適用の項で説明されている内容を前提としています。

タイムスケール

SkeletonAnimationコンポーネントのタイムスケールを設定することで、アニメーションの再生を遅くしたり、速くしたりすることができます。例えば、タイムスケールが0.5の場合、アニメーションは通常の半分の速度になり、タイムスケールが2の場合、アニメーションは通常の2倍の速度になるというように、アニメーションの進行に使用されるデルタタイムは、単純にタイムスケールを乗じたものになります。

C#
float timeScale = skeletonAnimation.timeScale;
skeletonAnimation.timeScale = 0.5f;

アニメーションの設定

アニメーションを設定するには、トラックのインデックス、アニメーション名、アニメーションをループさせるかどうかを指定します。

C#
TrackEntry entry = skeletonAnimation.AnimationState.SetAnimation(trackIndex, "walk", true);
C#
// using properties
[SpineAnimation] public string animationProperty = "walk";
...
TrackEntry entry = skeletonAnimation.AnimationState.SetAnimation(trackIndex, animationProperty, true);

別の方法として、文字列ではなくAnimationReferenceAssetをパラメーターとして使用することもできます。

C#
// using AnimationReferenceAsset
public AnimationReferenceAsset animationReferenceAsset; // assign a generated AnimationReferenceAsset to this property
...
TrackEntry entry = skeletonAnimation.AnimationState.SetAnimation(trackIndex, animationReferenceAsset, true);
アニメーションのキューイング

アニメーションをキューに入れるには、トラックのインデックス、アニメーション名、アニメーションをループさせるかどうか、このアニメーションがトラックで再生を開始するまでの遅延時間を秒単位で指定します。

C#
TrackEntry entry = skeletonAnimation.AnimationState.AddAnimation(trackIndex, "run", true, 2);
C#
// using properties
[SpineAnimation] public string animationProperty = "run";
...
TrackEntry entry = skeletonAnimation.AnimationState.AddAnimation(trackIndex, animationProperty, true, 2);

空のアニメーションの設定とキューイング、トラックの消去(クリア)

SkeletonAnimationコンポーネントには、空のアニメーションを設定したり、空のアニメーションをキューに入れたり、1つまたはすべてのトラックをクリアするメソッドも用意されています。これらはすべて、上述のメソッドやノードと同様に動作します。

C#
TrackEntry entry = skeletonAnimation.AnimationState.SetEmptyAnimation(trackIndex, mixDuration);
entry = skeletonAnimation.AnimationState.AddEmptyAnimation(trackIndex, mixDuration, delay);
skeletonAnimation.AnimationState.ClearTrack(trackIndex);
skeletonAnimation.AnimationState.ClearTracks();

TrackEntry

すべてのメソッドからTrackEntryを受け取り、特定のアニメーションの再生をさらにカスタマイズしたり、TrackEntryのイベントのデリゲートにバインドしたりすることができます。詳しくは後述の「AnimationStateイベントの処理」をご覧ください。

注意: 返されたTrackEntryは、対応するアニメーションが根底となるAnimationStateから削除されるまでのみ有効です。Unityのガベージコレクターが自動的にこれらを解放します。TrackEntryのdisposeイベントを受け取った後は、もう保存もアクセスもしないようにしてください。

C#
TrackEntry entry = ...
entry.EventThreshold = 2;
float trackEnd = entry.TrackEnd;

AnimationStateイベントの処理

アニメーションがAnimationStateによって再生されている間、様々なイベントが発行され、リスナーに以下を通知します。

  1. アニメーションが開始された(start)
  2. トラックをクリアしたり、新しいアニメーションを設定するなどして、アニメーションが中断された(interrupt)
  3. 途切れることなくアニメーションが完了した(complete)。※ループしている場合は複数回発生
  4. アニメーションが終了した(end)
  5. アニメーションとそれに対応するTrackEntry破棄された(dispose)
  6. ユーザーが定義したイベント(event)が発生した。

補足: 前のアニメーションを中断して新しいアニメーションを設定した場合、completeイベントは発生せず、代わりにinterruptendイベントが発生します。

SkeletonAnimationコンポーネントは、すべてのトラックでキューイングされたすべてのアニメーションのイベントに反応するために、C#コードがバインドできるデリゲートを提供します。また、リスナーは特定のTrackEntryの対応するデリゲートにのみバインドすることもできます。例えばAnimationState.Completeに登録すればあらゆるアニメーションのCompleteイベントで処理が実行され、TrackEntry.Completeに登録すれば特定のアニメーションによって発行されたCompleteイベントのみを処理することができます。

C#

AnimationStateイベントに反応するクラスで、取得したいイベントのデリゲートを追加します:

C#
SkeletonAnimation skeletonAnimation;
Spine.AnimationState animationState;

void Awake () {
   skeletonAnimation = GetComponent<SkeletonAnimation>();
   animationState = skeletonAnimation.AnimationState;

   // あらゆるアニメーションから発生されるイベントに対して登録する
   animationState.Start += OnSpineAnimationStart;
   animationState.Interrupt += OnSpineAnimationInterrupt;
   animationState.End += OnSpineAnimationEnd;
   animationState.Dispose += OnSpineAnimationDispose;
   animationState.Complete += OnSpineAnimationComplete;

   animationState.Event += OnUserDefinedEvent;

   // 特定のアニメーショントラックエントリーから発生されるイベントに対して登録する
   Spine.TrackEntry trackEntry = animationState.SetAnimation(trackIndex, "walk", true);
   trackEntry.Start += OnSpineAnimationStart;
   trackEntry.Interrupt += OnSpineAnimationInterrupt;
   trackEntry.End += OnSpineAnimationEnd;
   trackEntry.Dispose += OnSpineAnimationDispose;
   trackEntry.Complete += OnSpineAnimationComplete;
   trackEntry.Event += OnUserDefinedEvent;
}

public void OnSpineAnimationStart(TrackEntry trackEntry) {
   // startイベントに反応させたい実装コードをここに追加してください
}
public void OnSpineAnimationInterrupt(TrackEntry trackEntry) {
   // interruptイベントに反応させたい実装コードをここに追加してください
}
public void OnSpineAnimationEnd(TrackEntry trackEntry) {
   // endイベントに反応させたい実装コードをここに追加してください
}
public void OnSpineAnimationDispose(TrackEntry trackEntry) {
   // disposeイベントに反応させたい実装コードをここに追加してください
}
public void OnSpineAnimationComplete(TrackEntry trackEntry) {
   // completeイベントに反応させたい実装コードをここに追加してください
}


string targetEventName = "targetEvent";
string targetEventNameInFolder = "eventFolderName/targetEvent";

public void OnUserDefinedEvent(Spine.TrackEntry trackEntry, Spine.Event e) {

   if (e.Data.Name == targetEventName) {
      // ユーザー定義イベントに反応させたい実装コードをここに追加してください
   }
}

// イベントデータをキャッシュすることで、文字列の比較を省略することができます
Spine.EventData targetEventData;
void Start () {
   targetEventData = skeletonAnimation.Skeleton.Data.FindEvent(targetEventName);
}
public void OnUserDefinedEvent(Spine.TrackEntry trackEntry, Spine.Event e) {

   if (e.Data == targetEventData) {
      // ユーザー定義イベントに反応させたい実装コードをここに追加してください
   }
}

詳細はSpine API Referenceをご覧ください。

コールバック内でのAnimationStateやゲームのステートの変更について

AnimationState のイベントコールバックから AnimationState.SetAnimation() を呼び出すなどして AnimationState を変更することができますが、ここには考慮すべき以下のようなタイミングの問題があります。これは、イベントコールバックからゲームステートを変更する場合にも当てはまります。

  1. AnimationState イベントコールバックは SkeletonAnimation.Update() でアニメーションが適用されるときに発行され、SkeletonAnimation.LateUpdate() でメッシュが更新されるよりも前に発行されます。
  2. AnimationState.Endコールバックから AnimationState.SetAnimation() を呼び出すと、同じフレームで AnimationState.Start イベントがトリガーされます。
  3. 1つのアニメーションから別のアニメーションへのミックストランジションのために、Start イベントは1つ目のアニメーションの End イベントよりも 前に 発行されます。これは、ゲームステートを変更するときに考慮すべきよくある落とし穴です。

このようなイベントコールバック内からの呼び出しを、次のUpdate()サイクルまで遅らせたい場合は、次のようにStartCoroutineを使用できます:

C#
trackEntry.End += e => {
   StartCoroutine(NextFrame(() => {
      YourCode();
   }));
};

...

IEnumerator NextFrame (System.Action call) {
   yield return 0;
   if (call != null)
      call();
}
コルーチンのyield命令

spine-unityランタイムは、Unityのコルーチン(Coroutines)で使用するための一連のyield命令を提供しています。Unityのコルーチンを初めて使用される方は、コルーチンのチュートリアルコルーチンのドキュメントから始めることをお勧めします。

以下のようなyield命令があります:

  1. WaitForSpineAnimation Spine.TrackEntryが指定されたイベントの1つを発生させるまで待機します。

    C#
    var track = skeletonAnimation.state.SetAnimation(0, "interruptible", false);
    var completeOrEnd = WaitForSpineAnimation.AnimationEventTypes.Complete |
                          WaitForSpineAnimation.AnimationEventTypes.End;
    yield return new WaitForSpineAnimation(track, completeOrEnd);
  2. WaitForSpineAnimationComplete Spine.TrackEntryCompleteイベントを発生させるまで待機します。

    C#
    var track = skeletonAnimation.state.SetAnimation(0, "talk", false);
    yield return new WaitForSpineAnimationComplete(track);
  3. WaitForSpineAnimationEnd Spine.TrackEntryEndイベントを発生させるまで待機します。

    C#
    var track = skeletonAnimation.state.SetAnimation(0, "talk", false);
    yield return new WaitForSpineAnimationEnd(track);
  4. WaitForSpineEvent Spine.AnimationStateが、ユーザーが定義したSpine.Event(Spineエディター内で命名)を発生させるまで待機します。

    C#
    yield return new WaitForSpineEvent(skeletonAnimation.state, "spawn bullet");
    // You can also pass a Spine.Event's Spine.EventData reference.
    Spine.EventData spawnBulletEvent; // cached in e.g. Start()
    ..
    yield return new WaitForSpineEvent(skeletonAnimation.state, spawnBulletEvent);

補足: Unityに組み込まれているyield命令と同様に、spine-unityのyield命令のインスタンスも再利用することができ、追加のメモリ割り当てを防ぐことができます。

チュートリアルページ

こちらでspine-unityのイベントのチュートリアルページを確認できます。

stringのプロパティ属性(Attribute)のスクリプティング

Inspectorでアニメーションの名前などを手入力するのは少し手間がかかります。そこでspine-unityは文字列(string)パラメーターのポップアップフィールドを提供します。stringプロパティの前に以下のプロパティ属性のいずれかを指定すると、スケルトンで利用可能なすべてのアニメーションなどが入力されたポップアップ選択フィールドが自動的に表示されます。提供されているSpineコンポーネントにこのようなポップアップフィールドがある場合、カスタムコンポーネントでもプロパティ属性を使って同じポップアップを使用することができます。以下は利用可能なプロパティ属性の一覧です。

C#
[SpineBone] public string bone;
[SpineSlot] public string slot;
[SpineAttachment] public string attachment;
[SpineSkin] public string skin;
[SpineAnimation] public string animation;
[SpineEvent] public string event;
[SpineIkConstraint] public string ikConstraint;
[SpineTransformConstraint] public string transformConstraint;
[SpinePathConstraint] public string pathConstraint;

spine-unityパッケージに含まれるサンプルシーンで、stringプロパティ属性が使用されているのを確認してみてください。

SkeletonMecanimコンポーネント

SkeletonMecanimコンポーネントは、UnityでSpineスケルトンを使用する3つの方法のうちの1つです。3つの方法とは、SkeletonAnimationSkeletonMecanimSkeletonGraphic (UI)のことです。

SkeletonMecanimコンポーネントはSkeletonAnimationコンポーネントの代わりに使用できるもので、Spineのアニメーションシステムの代わりにUnityのMecanimアニメーションシステムを使用します。SkeletonAnimationコンポーネントと同様に、SpineスケルトンをGameObjectに追加し、アニメーションさせたり、アニメーションイベントに反応させたりすることができます。ただし、SkeletonAnimationと比較して以下のようないくつかの制限と追加要件があります:

注意: SkeletonAnimationコンポーネントと異なりSkeletonMecanimは先行するアニメーションのタイムラインの状態をスムーズにミックスアウトするために、アニメーションの最初のフレームで追加のタイムラインキーを必要とします。詳しくは後述の必要になる追加のキーをご覧ください。

注意: TrackEntry.AttachmentThresholdおよび同様のミックスしきい値の機能はSkeletonMecanimでは使用できません。

SkeletonMecanimコンポーネントにはSkeletonAnimationコンポーネントと類似したパラメーターが用意されているので、詳しくはSkeletonAnimationセクションを参照してください。

必要になる追加のキー

あるアニメーションから次のアニメーションへとタイムラインの状態(ボーンの回転など)をスムーズにミックスアウトさせるために、2つ目のアニメーションでは、最初のフレームでセットアップポーズの状態の追加のキーが必要になります。そうしないと、前のアニメーションのタイムラインの状態が残ってしまうからです。これはSkeletonAnimationと比較した際のSkeletonMecanimの欠点の一つです。

簡単な例: idleアニメーションが、先に再生されているjumpアニメーションをスムーズにミックスアウトする必要があるとします。jumpの終了時にボーンbone1bone2がセットアップポーズとは異なる位置でキー設定されている場合、jumpの状態を適切にミックスアウトするためには、idleアニメーションの最初のフレームにbone1bone2のキー(セットアップポーズまたは任意のポーズ)を追加する必要があります。

Auto Resetパラメーターを使えばタイムラインの状態をリセットできますが、アニメーションのトランジション終了時に唐突にミックスアウトしてしまい、スムーズなトランジションを実現できません。

また、スケルトンを.jsonまたは.skel.bytesでエクスポートする際は必ずAnimation cleanup(アニメーションクリーンアップ)を無効にしてください。そうしないとセットアップポーズと全く同じキーはエクスポートされなくなってしまいます!

アニメーションブレンドコントロールのパラメーター

SkeletonMecanimのInspectorは以下の追加パラメーターを公開しています :

  • Mecanim Translator

    • Auto Reset : trueに設定すると、アニメーションが終了したときに、アニメーションのキーが設定されたアイテムに応じて、スケルトンの状態がセットアップポーズにミックスアウトされます。これは、アニメーションがアタッチメントの表示状態を変更した場合に特に重要になることがあります。ミックスアウトされると、アタッチメントの表示状態はセットアップポーズの状態に戻りますが、そうでなければ、現在のアタッチメントの状態は別のアニメーションがそれぞれのアタッチメントのタイムラインにキーを設定するまで保持されます。

    • Custom MixMode : 無効にすると、レイヤーのブレンドモードに応じて、推奨されるMixModeが使用されます。有効にすると、以下のようなMix Modesセクションが表示され、各MecanimレイヤーのMixModeを指定することができます。

    • Mix Modes : 上記のCustom MixModeパラメーターが有効な場合に表示されます。このパラメーターは、連続したアニメーション間、およびレイヤー間のアニメーションのミックスモードを決定します。

      • Mix Next Base LayerOverrideレイヤーで推奨されます)
        前のトラックを適用した後、Mecanimのトランジションウェイトを使って次のトラックを上からミックスします。
      • Always Mix Additiveレイヤーで推奨されます)
        前のトラックをフェードアウトし(Auto Resetが有効な場合、セットアップポーズになる可能性があります)、Mecanimのトランジションウェイトを使用して次のトラックをトップにミックスします。Base Layerに使用すると、意図しないアニメーションのディッピング効果が発生する場合がありますのでご注意ください。
      • Hard (旧名称:Spine Style 次のトラックをすぐに適用します。

Auto ResetとレイヤーのMix Modeパラメーターの結果

トランジションがアクティブになる際、現在のステートの最後のフレームセットアップポーズ前のクリップのポーズ新しいクリップのポーズの4つのポーズがあり、これらは次のように組み合わされます :

  1. まず現在のステートの最後のフレーム (またはSkeletonMecanimのupdate前のこのフレームの他の修正)で開始します。
  2. セットアップポーズを適用します :
    • Auto Resetが有効な場合、セットアップポーズ現在のステートの最後のフレームに置き換わります。
    • Auto Resetが無効な場合、セットアップポーズはミックスに含まれません。

  3. 前のクリップのポーズを適用します :
    • モードがAlways Mixに設定されている場合は、前のクリップのポーズが現在の状態とミックスされます (Auto Resetが有効な場合はセットアップポーズとミックスされます)。
    • HardまたはMix Nextに設定されている場合は、前のクリップのポーズがフルウェイトで適用され、現在のステートよりも優先されます(つまりセットアップポーズよりも優先されます)。

  4. 新しいクリップのポーズを適用します :
    • モードがAlways MixまたはMix Nextに設定されている場合、新しいクリップのポーズは現在のステートとミックスされます。つまり、Auto Resetを有効にしている場合のAlways Mixは、セットアップポーズ前のクリップのポーズ新しいクリップのポーズが混合されます。
    • モードがHardに設定されている場合、新しいクリップのポーズはフルウェイトで適用され、以前に適用されたすべてのポーズよりも優先されます。

下の表は、前のクリップPと新しいクリップNの両方が同じタイムラインの値(例えば同じボーンの回転)を変更する場合を表しています。Sは、Auto Resetが有効な場合はセットアップポーズを、無効な場合は現在のステート(例:前フレームのステート)を表します。トランジションウェイト(トランジション開始時に0、トランジション終了時に1)は、変数wで表されます。各レイヤーのブレンドモードにおけるデフォルト(推奨)のミックスモードは、太字でハイライトされています。

Always Mix Mix Next Hard
Base Layer lerp(lerp(S, P, 1-w), N, w) lerp(P, N, w) N
Override lerp(
lerp(lower_layers_result,
P, (1-w) * layer_weight),
N, w * layer_weight)
lerp(
lerp(lower_layers_result,
P, layer_weight),
N, w * layer_weight)
lerp(lower_layers_result,
N,
layer_weight)
Additive lower_layers_result +
layer_weight * lerp(P, N, w))
counts as Always Mix lower_layers_result +
layer_weight * N
省略形 意味
S Setup pose(セットアップポーズ)
P Previous clip pose(前のクリップのポーズ)
N New clip pose(新しいクリップのポーズ)
w Transition weight(トランジションウェイト)
lerp(a, b, weight) Linear interpolation from a to b by weight (aからbへのウェイトによるリニア補間)

SkeletonMecanimのControllerとAnimator

SkeletonMecanimコンポーネントは、UnityのMecanimと同様にAnimatorコンポーネントで割り当てられたControllerアセットを使用します。Controllerアセットはスケルトンをドラッグ&ドロップSkeletonMecanimとしてインスタンス化する際に自動的に生成され、割り当てられます。

補足: Apply Root Motionを有効にすると、SkeletonMecanimRootMotionコンポーネントがSkeletonMecanimGameObjectに自動的に追加されます。

Controllerのアニメーションステートマシンにアニメーションを追加するには、SpineアニメーションをAnimatorパネルにドラッグ&ドロップします。アニメーションはControllerアセットの下にあります。

SkeletonDataAssetで設定されたMix duration values値は、SkeletonMecanimでは無視されます。代わりにAnimatorパネルで設定したMecanimのトランジションタイムが使用されます。

SkeletonMecanimイベント

SkeletonMecanimを使用する場合、イベントは各AnimationClipに格納され、他のUnityのアニメーションイベントと同様に発生します。例えば、Spine内でイベント名を"Footstep"と命名した場合、SkeletonMecanimのGameObjectにMonoBehaviourスクリプトを用意し、Footstep()というメソッドを用意して処理する必要があります。Spine内でフォルダを使用している場合、メソッド名はフォルダ名とアニメーション名を連結したものになります。例えば、先ほどのイベントがFoldernameというフォルダに入っている場合、FoldernameFootstep()となります。

C#
public class YourComponentReceivingEvents : MonoBehaviour {
   // to capture event "Footstep" when it's placed outside of folders
   void Footstep() {
      Debug.Log("Footstep event received");
   }

   // to capture event "Footstep" when it's placed in a folder named "Foldername"
   void FoldernameFootstep () {
      Debug.Log("Footstep (in folder Foldername) received");
   }
}

Unity Mecanimのイベントの詳細については、アニメーションイベントに関するUnityのドキュメントを参照してください。

SkeletonGraphicコンポーネント

SkeletonGraphicコンポーネントはUnityでSpineスケルトンを使用する3つの方法のうちの1つです。3つの方法とは、SkeletonAnimationSkeletonMecanimSkeletonGraphic (UI)のことです。

SkeletonGraphicコンポーネントはSkeletonAnimationコンポーネントの代わりに使用できるもので、レイアウト、レンダリング、マスクのインタラクションにUnityのUIシステムを使用します。SkeletonAnimationコンポーネントと同様に、SpineのスケルトンをGameObjectに追加し、アニメーションさせたり、アニメーションイベントに反応させたりすることができます。

なぜ特定のUIコンポーネントなのか

UnityのUI(UnityEngine.UI)は、CanvasCanvasRenderers システムを使って、レンダリング可能なオブジェクトを分類・管理しています。TextImageRawImage などの組み込みのレンダリング可能なUIコンポーネントは CanvasRenderer に依存して正しく機能します。MeshRenderers(例:デフォルトのCubeオブジェクト)や SpriteRenderers(例:Sprite)のようなオブジェクトをUIの下に置くと、Canvas ではレンダリングされません。SkeletonAnimationMeshRenderer を使用しているため、同様の挙動になります。そのため、spine-unityランタイムでは UnityEngine.UI.MaskableGraphic のサブクラスで CanvasRenderer コンポーネントをレンダリングに使用する SkeletonAnimation のvariantである SkeletonGraphic を提供しています。

マテリアルの重要な要件

SkeletonGraphicコンポーネントでは、デフォルトで割り当てられている Spine/SkeletonGraphic* シェーダーなど、CanvasRenderer互換の特殊なシェーダーを持つマテリアルのみを使用してください。URP、LWRP、Spine/Skeleton のような通常のシェーダーを SkeletonGraphic コンポーネントで使用しないでください。ビジュアル的なエラーが出ないからといって、そのシェーダーが SkeletonGraphic で動作するとは限りません。実際に、Unity エディター上では問題なくレンダリングできるのに、対象となるモバイルデバイスでは正しくレンダリングできないケースが確認されています。他のUIコンポーネントと同様に、SkeletonGraphicMeshRenderer ではなく CanvasRenderer を使用しており、別のレンダリングパイプラインを使用しています。

SpineAtlasAsset で割り当てられた通常のマテリアルは、SkeletonDataAssetSkeletonGraphic としてインスタンス化する際には無視され、テクスチャのみが使用されます。SkeletonGraphicCustomMaterials コンポーネントを使用すれば、SkeletonGraphic コンポーネントのマテリアルをオーバーライドすることができます。

重要な注意事項: Unityの CanvasRenderer の制限により、SkeletonGraphicはデフォルトでテクスチャの枚数が1枚だけに制限されています。SkeletonGraphic コンポーネントのInspectorで Advanced - Multiple CanvasRenderers を有効にすると、サブメッシュごとに 子CanvasRenderer``GameObject を生成して、テクスチャの枚数上限を上げることができます。ただし、パフォーマンス上の理由から、これは可能な限り避けた方が良いでしょう。つまり、UIで使用されるスケルトンは、複数ページのアトラスではなく、単一テクスチャー(単一ページ)のアトラスとしてパックされなければなりません。 アタッチメントを単一のアトラスページテクスチャにパックする方法については高度な情報 - 単一テクスチャアトラスのエクスポートとSkeletonGraphicをご覧ください。

CanvasGroupアルファ

Spine/SkeletonGraphic* シェーダーを CanvasGroup で使用すると、以下の画像のように CanvasGroupAlpha値 を減らすとスケルトンが明るくなってしまいます。

これは、水面下でUnityが頂点カラーのアルファ値を変更していることにより、残念ながらspine-unityランタイムの事前乗算アルファ(PMA)シェーダーではうまく再生できないためです。

Spine/SkeletonGraphic シェーダーを使用しているマテリアルをアルファフェードアウトを伴う CanvasGroup 以下で使用する場合、そのマテリアルは CanvasGroup Compatible パラメーターを有効にする必要があります。元のマテリアルを変更する代わりに、共有されているSkeletonGraphicDefaultマ テリアルのコピーを作成し、名前を SkeletonGraphic CanvasGroup などに変更するのが最善です。そして元のマテリアルの代わりに、CanvasGroup 以下の SkeletonGraphic コンポーネントにこのマテリアルを割り当ててください。この CanvasGroup 互換マテリアルを使用する SkeletonGraphic コンポーネントでは、透明部分が二重に暗くなってしまうのを避けるために、Advanced - PMA Vertex Colors も無効にしておく必要があります。しかしこれを設定することにより、残念ながら加算スロットのシングルバッチレンダリングができなくなるため、ドローコールが増加する場合があります。

Spine/SkeletonGraphic TintBlack シェーダーを使用しているマテリアルをアルファフェードアウトを伴う CanvasGroup 以下で使用する場合にも同様の設定が必要ですが、加算スロットの制限はありません。上記と同様に、元のマテリアルを変更する代わりに共有されている SkeletonGraphicTintBlack マテリアルのコピーを作成し、名前を SkeletonGraphicTintBlack CanvasGroup などに変更してください。そしてこのマテリアルを元のマテリアルの代わりに CanvasGroup 以下の SkeletonGraphic コンポーネントに割り当ててください。この CanvasGroup 互換マテリアルを使用する SkeletonGraphic コンポーネントでは、Advanced - Canvas Group Tint Black を有効にする必要があります。コンポーネントで Advanced - PMA Vertex Colors を無効にする必要はありませんので、このパラメーターは有効のままにしてください。

RectTransformの境界を一致させて正しい表示にする

SkeletonGraphic の表示状態はRectTransformの境界によって決定されます。スケルトンが CanvasGameObjectの子としてドラッグ&ドロップでインスタンス化された場合はRectTransformの境界は自動的に初期ポーズにマッチします。また、Match RectTransform with Mesh ボタンをクリックすることで、RectTransformを現在のポーズの寸法に手動で合わせることもできます。RectTransformの境界がメッシュよりも小さくならないようにすることが重要です。そうしないと、例えば RectMask2D はメッシュの一部がまだ内側にあってレンダリングされるべきであるにもかかわらずRectTransformが外に出た時点でスケルトンの描画を省略してしまいます。現在のRectTransformの境界は、5つのトランスフォームモードのRectTransformツールがアクティブになっているときにSceneビューに表示されます。

パラメーター

SkeletonGraphic には、SkeletonAnimationコンポーネントと同様のパラメーターが用意されているので、詳細はSkeletonAnimationセクションを参照してください。

SkeletonGraphic のInspectorは、以下の追加パラメーターを公開しています :

  • PMA Vertex Colors (CanvasGroupアルファ用の追加ルール) : 頂点カラーRGBと頂点カラーアルファを乗算します。レンダリングに使用するシェーダーが Spine/SkeletonGraphic* シェーダーの場合(Straight Alpha Textureを使用している場合も含む) 、または PMA加算ブレンドモード Blend One OneMinusSrcAlpha を使用するサードパーティシェーダーの場合、このパラメーターを有効にします。"Spine/SkeletonGraphic" シェーダーをCanvasGroupアルファで使用する場合や、通常のブレンドモード Blend SrcAlpha OneMinusSrcAlpha を使用する通常のシェーダーを使用する場合は、このパラメーターを無効にしてください。無効にすると加算スロットのシングルバッチレンダリングができなくなるため、ドローコールが増加する場合があります。

  • Freeze : trueに設定すると、SkeletonGraphicはアップデートされなくなります。

  • Layout Scale Mode : SkeletonGraphic は、RectTransform の境界に基づいた自動均一スケーリングに対応しています。デフォルトは None で、以前の動作を維持します。自動スケーリングは、このパラメーターを Width Controls HeightHeight Controls WidthFit In Parent または Envelope Parent (それぞれの詳細はこちらを参照)のいずれかに設定することで有効にすることができます。参照レイアウト境界を変更するには、 Edit Layout Bounds トグルボタンを押して編集モードに入り、スケルトンの境界を調整することができます。スケルトンは、参照レイアウト境界をオブジェクトの RectTransform に合わせて、適宜スケーリングされます。

  • Edit Layout Bounds : 上記の Layout Scale Mode で使用される参照レイアウト境界を変更するには、このトグルボタンを押して編集モードにします。その後、手動で境界を調整するか、 Match RectTransform with Mesh を押して、現在のポーズに合わせることができます。調整が完了したら、 Edit Layout Bounds トグルボタンをもう一度押して、編集モードを終了します。

  • Match RectTransform with Mesh : Match ボタンをクリックすると SkeletonGraphic のRectTransformを現在のポーズの寸法に合わせることができます。RectTransformの境界がメッシュよりも小さくならないようにすることが重要です。そうしないと、例えば RectMask2D は、メッシュの一部がまだマスクの内側にあってレンダリングされるべきであったとしても、RectTransformが外に出た時点でスケルトンの描画を省略してしまいます。

  • Advanced

    • Use Clipping : false に設定すると、いかなるSpineのクリッピング・アタッチメントも無視されるようになります。

    • Canvas Group Tint Black : これは SkeletonGraphic Tint Black シェーダーを使用する場合のみ有効になります。Tint Black が無効の場合は効果がありません。CanvasGroup の下の SkeletonGraphic のスロットで Additive ブレンドモードを使用する場合に有効です。有効にすると Additive アルファ値が color.a の代わりに uv2.gに 格納され、CanvasGroupcolor.a を変更するのを捕捉します。

    • Multiple CanvasRenderers : true に設定すると、SkeletonGraphic は1つの CanvasRenderer を使用せず、必要なドローコール(サブメッシュ)ごとに、必要な数の 子CanvasRenderer GameObjectを自動的に作成します。これにより、単一テクスチャの制限を緩和することができますが、パフォーマンスのオーバーヘッド(処理負荷)が発生します。

      • Blend Mode Materials : スロットのブレンドモードごとに異なる SkeletonGraphic マテリアルを使用できるようにします。ただしここでは、"Spine/SkeletonGraphic *" または他のCanvasRenderer互換のマテリアルのみを使用してください。

      • Assign Default を選択すると、デフォルトのブレンドモードマテリアル SkeletonGraphicAdditiveSkeletonGraphicMultiplySkeletonGraphicScreen が割り当てられます。

        注意: SkeletonGraphicBlend Mode Materials の割り当ては SkeletonDataAsset のマテリアルに依存しているため、SkeletonDataAsset でブレンドモードマテリアルが適切に設定されていることを確認してください。PMA Vertex Colors が有効な場合、Additive Material は無視されます。

  • Animation Update : 通常の Update (デフォルト)、物理ステップ FixedUpdate、またはユーザーコールによる手動アニメーション更新のいずれかを指定します。Rigidbody または Rigidbody2D が割り当てられたSkeletonRootMotion コンポーネントを使用する場合、更新モードを In FixedUpdate に設定することをお勧めします。それ以外の場合は、In Update を推奨します。

    • Update When Invisible : MeshRendererが非表示になった時に使用されるUpdateモードです。メッシュが再び表示されるようになると、Updateモードは自動的に UpdateMode.FullUpdate にリセットされます。

    • Separator Slot Names : Enable Separationtrue に設定されているときに、レンダリングを分割する場所を決定するスロットです。レンダリングの分割に関する全般的な情報はSkeletonRenderSeparatorセクションを参照してください。ただし SkeletonGraphic においては追加のコンポーネントは必要ありません。

    • Enable Separation : レンダリングの分割は、このInspectorセクションで直接有効にすることができ、追加のコンポーネント(SkeletonRenderSeparatorSkeletonRenderer コンポーネントの SkeletonPartsRenderer など)は必要ありません。有効にすると、追加の分割されたGameObjectが自動的に作成され、それに応じて CanvasRenderer GameObjectが再ペアリングされます。分割されたGameObjectは、必要に応じて階層内で移動させたり再配置したりして Canvas 内での望ましい描画順序を実現することができます。

    • Update Part Location : 有効にすると、分割されたGameObjectの位置が SkeletonGraphic の位置に合わせて更新されます。これは、パーツを別のGameObjectに再ペアリングしたい場合に役立ちます。

    • Physics Inheritance : トランスフォームの動きをスケルトンの物理コンストレイントに適用する方法を制御します。

      • Position : ゼロ以外に設定すると、X方向およびY方向のトランスフォームの位置移動がスケルトンの物理コンストレイントに適用され、ここで設定したXおよびYのスケール係数で乗算されます。一般的な組み合わせは以下の通りです:
        (1,1) にした場合、XY移動が通常通り適用されます。
        (2,2) にした場合、XY移動が倍の強さで適用されます。
        (1,0) にした場合、水平方向の移動だけが適用されます。
        (0,0) にした場合、トランスフォームの移動の動きは全く適用されなくなります。
      • Rotation : ゼロ以外に設定すると、トランスフォームの回転の動きがスケルトンの物理コンストレイントに適用され、ここで設定したスケール係数で乗算されます。一般的な値は以下の通りです:
        1 にした場合、通常通り適用されます。
        2 にした場合、倍の強さで適用されます。
        0 にした場合、トランスフォームの回転の動きは全く適用されなくなります。

サンプルシーン

基本的な使用方法については、Spine Examples/Getting Started/6 Skeleton Graphicにあるサンプルシーンで確認することができます。 また、Separator Slotを設定したり、描画順序を変更する方法を紹介している高度なサンプルシーンは、Spine Examples/Other Examples/SkeletonRenderSeparator で確認できます。

SkeletonRendererコンポーネント

SkeletonRendererコンポーネントは、スケルトンの現在のステートを描画する役割を担っています。これはSkeletonAnimationSkeletonMecanimの基底クラスとなっています。

補足: ほとんどの場合、代わりにSkeletonAnimationSkeletonMecanimSkeletonGraphic (UI)のいずれかを使用することになるでしょう。これらのコンポーネントは、アニメーションを制御する高度な手段を提供します。UIのゲージ要素のように、トランジションなしで手動でアニメーションを適用する場合に限り、このコンポーネントはそのままで役立ちます。

レンダリングは、MeshRendererコンポーネントで更新されるプロシージャルメッシュによって行われます。このコンポーネントはSkeletonDataAssetによって参照されるテクスチャアトラスアセットを使用して、スケルトンのアタッチメントを描画するのに必要なテクスチャとマテリアルを見つけます。詳細はSkeletonAnimationセクションを参照してください。

SkeletonRendererコンポーネントを直接使用する方法については、サンプルシーンのSpine Examples/Other Examples/SpineGaugeで確認できます。

ユーティリティーコンポーネント

SkeletonRootMotion

spine-unityは、3つのSpineスケルトンコンポーネントすべてでルートモーションをサポートしています。SkeletonRootMotionコンポーネントは、SkeletonAnimationSkeletonGraphic (UI)のGameObjectsにアタッチすることができ、SkeletonMecanimには別のSkeletonMecanimRootMotionコンポーネントが用意されています。このルートモーションコンポーネントをアタッチすることは、UnityのMecanim AnimatorコンポーネントのApply Root Motionパラメーターを有効にするのと同じように動作します。有効にすると、選択されたRoot Motion Boneの動きに応じて、キャラクターの位置がアニメーションで駆動されます。

注意: SkeletonMecanimオブジェクトにはSkeletonMecanimRootMotionコンポーネントが用意されています。SkeletonRootMotionSkeletonAnimationSkeletonGraphic (UI)コンポーネントで使用すると失敗します。

パラメーター

  • Root Motion Bone : ルートモーションとして使用される対象のボーンを設定します。
  • X : 有効にすると、ローカルのX軸に沿った動きがルートモーションとして適用されます。
  • Y : 有効にすると、ローカルのY軸に沿った動きがルートモーションとして適用されます。
  • Root Motion Scale (X) : 水平方向のルートモーションデルタに適用されるスケール。例えば、ジャンプを必要な距離に伸ばすためのデルタ補正に使用できます。
  • Root Motion Scale (Y) : 垂直方向のルートモーションデルタに適用されるスケール。例えば、ジャンプを任意の高さに伸ばすためのデルタ補正に使用できます。
  • Animation Tracks : ルートモーションの計算にどのアニメーショントラックを含めるかを指定できます。

任意のパラメーター

  • Rigidbody2D : Rigidbody2Dが割り当てられると、TransformコンポーネントではなくRigidbody2Dによって与えられる物理演算が動きに適用されます。そのため、SkeletonAnimationコンポーネントのAdvanced - Animation Update Inspectorパラメーターを、In FixedUpdateに設定することをお勧めします。
  • Rigidbody : Rigidbodyが割り当てられると、TransformコンポーネントではなくRigidbodyによって与えられる物理演算が動きに適用されます。そのため、SkeletonAnimationコンポーネントのAdvanced - Animation Update Inspectorパラメーターを、In FixedUpdateに設定することをお勧めします。

補足: SkeletonRootMotionクラスはAdjustRootMotionToDistance()やその他のメソッドを提供し、簡単にデルタ補正を行うことができます。デルタ補正は、例えば、ジャンプを所定の距離に引き伸ばすために使用できます。skeletonRootMotion.AdjustRootMotionToDistance(targetPosition - transform.position, trackIndex);によって、アニメーションの開始時やフレームごとにルートモーションを調整することができます。

SkeletonMecanimRootMotion

これはSkeletonMecanimコンポーネントで使用される、SkeletonRootMotionコンポーネントの派生コンポーネントです。

SkeletonMecanimRootMotionコンポーネントは、UnityのMecanim AnimatorApply Root Motionパラメーターが有効になっていると、スケルトンのGameObjectに自動的に追加されます。そのため、SkeletonMecanimRootMotionコンポーネントを削除するには、まずAnimatorのApply Root Motionパラメーターを無効にする必要があります。

パラメーター

  • Root Motion Bone : ルートモーションとして使用される対象のボーンを設定します。
  • X : 有効にすると、ローカルのX軸に沿った動きがルートモーションとして適用されます。
  • Y : 有効にすると、ローカルのY軸に沿った動きがルートモーションとして適用されます。
  • Root Motion Scale (X) : 水平方向のルートモーションデルタに適用されるスケール。例えば、ジャンプを必要な距離に伸ばすためのデルタ補正に使用できます。
  • Root Motion Scale (Y) :垂直方向のルートモーションデルタに適用されるスケール。例えば、ジャンプを任意の高さに伸ばすためのデルタ補正に使用できます。
  • Mecanim Layers : ルートモーションの計算にどのMecanimレイヤーを含めるかを指定できます。

任意のパラメーター

  • Rigidbody2D : Rigidbody2Dが割り当てられると、TransformコンポーネントではなくRigidbody2Dによって与えられる物理演算が動きに適用されます。
  • Rigidbody : Rigidbodyが割り当てられると、TransformコンポーネントではなくRigidbodyによって与えられる物理演算が動きに適用されます。

補足:  SkeletonMecanimRootMotionクラスはAdjustRootMotionToDistance()やその他のメソッドを提供し、簡単にデルタ補正ができるようにしています。デルタ補正は、例えば、ジャンプを所定の距離に引き伸ばすために使用できます。skeletonRootMotion.AdjustRootMotionToDistance(targetPosition - transform.position, trackIndex);によって、アニメーションの開始時やフレームごとにルートモーションを調整することができます。

BoneFollower

このコンポーネントはSkeletonAnimationコンポーネントのボーンを参照し、Update毎に自身のトランスフォームをボーンのトランスフォームに設定します。

注意:  SkeletonGraphicオブジェクトにはBoneFollowerGraphicコンポーネントが用意されています。

SkeletonUtilityBoneコンポーネントとは対照的に、BoneFollower は親ボーンオブジェクトを持たない単一の独立したGameObjectとして使用できます。

これはパーティクルシステムなどのオブジェクトが、スケルトン上の特定のボーンを追いかけるようにするために使用できます。

BoneFollower コンポーネントの設定方法については、サンプルシーンSpine Examples/Getting Started/4 Object Oriented Sampleをご覧ください。

BoneFollowerGraphic

これはBone Followerコンポーネントの派生で、SkeletonGraphicコンポーネントと組み合わせて使用します。

SkeletonUtilityBoneコンポーネントとは対照的に、BoneFollowerGraphic は、親ボーンオブジェクトを持たない単一の独立したGameObjectとして使用できます。

これはパーティクルシステムなどのオブジェクトが、スケルトン上の特定のボーンを追いかけるようにするために使用できます。

BoneFollowerGraphic コンポーネントの設定方法については、サンプルシーンSpine Examples/Getting Started/6 Skeleton Graphicをご覧ください。

PointFollower

このコンポーネントはBone Followerコンポーネントと似ていますが、ボーンの代わりにポイント・アタッチメントに追従します。

SkeletonUtilityBoneコンポーネントとは対照的に、PointFollowerは、親ボーンオブジェクトを持たない単一の独立したGameObjectとして使用できます。

BoundingBoxFollower

このコンポーネントはスケルトンのスロットにある境界ボックスにマッチさせるために使用します。このコンポーネントは、形状を抽出して PolygonCollider2D に割り当てて、現在のアニメーションに合わせてフレームごとに有効または無効にします。

注意: ボーンの位置は自動的には追従しません。そのため、通常はBoneFollower コンポーネントと一緒に使用します。BoundingBoxFollower のInspectorの Add Bone Follower ボタンを使用して BoneFollower コンポーネントの作成と設定を行うことができます。

注意: 頂点変形アニメーション(境界ボックスの頂点をアニメーションで時間軸に従って移動させること)に対しては追従せず、初期形状のみを対象としています。

詳しくはBone Followerを参照してください。

SkeletonUtilityBone

物理演算やユーザーの入力に対応するために、実行時にプログラムでボーンの位置を変更したい場合があります。

SkeletonUtilityBoneコンポーネントは、GameObjectがボーンの位置に追従したり、手動でボーンの位置をオーバーライドしたり、2Dまたは3Dの物理演算を利用したりするための便利なインターフェースを提供します。ローカルのボーン位置に 追従する(Follow) か、Update 毎に オーバーライド(Override) するかを設定できます。Override に設定すると、SkeletonAnimationコンポーネントがワールドトランスフォームをアップデートする前に、コンポーネントがボーンの位置を設定します。

重要な注意事項: SkeletonUtilityBone は、ローカルのトランスフォーム値を使用します。これはスケルトンのボーン階層を反映したSkeletonUtilityBone GameObjectsの階層に依存しています。SkeletonUtilityBone の階層を素早く作成するには、後述SkeletonUtilityコンポーネントを使用することをお勧めします。

SkeletonUtilityBone のInspectorには、追加の子ボーンを作成したり(選択的または再帰的に)2Dおよび3Dのヒンジチェーンのヒンジチェーンを作成するためのインターフェースも用意されています。

SkeletonUtilityBones の階層ができあがると、Hierarchyパネルの SkeletonUtilityBone GameObjectの横には、以下のようにFollowに設定されているかOverrideに設定されているかで異なるアイコンが表示されます。

  • Follow に設定されている場合 :  Follow
  • Override に設定されている場合 :  Override

使用例

ユーザーがスケルトンのボーンをドラッグして移動させるようなユースケースでは、Override モードで SkeletonUtilityBone を使用します。

GameObjectが追従する必要があるのが1つのボーンだけの場合は、代わりにBoneFollowerコンポーネントを使うことで、リソースを節約することができます。

サンプルシーン

Spine Examples/Other Examples/SkeletonUtility Animated PhysicsSkeletonUtilityBone の使い方を示すサンプルシーンを確認できます。このシーンでは、一部の SkeletonUtilityBones ノードが Override ノードに必要な階層的な親となるために、ボーンの位置に対して Follow (追従)するように設定されています。

物理演算のための2Dおよび3Dヒンジチェーンの作成

Hinge Chain Demo

キャラクターのマントや、重いオブジェクトを引きずる時、モーニングスターを振るなどで物理演算を追加したい場合があります。 spine-unityランタイムでは既存のSkeletonUtilityBone階層からHingeJointまたはHingeJoint2D要素の物理リグを生成することができます(詳しくはSkeletonUtilityBonesの階層の作成をご覧ください)。

Hinge Chain Setup

最初の SkeletonUtilityBone チェーン要素を選択し、Inspectorで Create 3D Hinge Chain または Create 2D Hinge Chain を選択して、物理リグを生成します。その際、選択した要素とその SkeletonUtilityBone の子要素すべてがヒンジチェーンになります。次に、RigidbodyのDrag(空気抵抗)とMass(質量)のパラメーターを調整して、結果を微調整します。Dragの値を上げると、Rigidbodyの動きが遅くなり、重さや空気との相互作用の効果が生まれます。

チェーンのルートノードは、スケルトンのボーンに親子付けされているのではなく、シーンの最上位階層に配置されていることに注意してください。これは運動量を適切に適用するためのUnityの要件です。チェーンルートをスケルトンのボーンに再び親子付けしないでください。そうしないと、チェーン要素がスケルトンの動きの影響を受けなくなってしまいます!

3Dヒンジチェーン
  1. まず通常通りSkeletonUtilityBone階層を作成してください。
  2. Sceneパネルで最初のチェーン要素を選択し、Inspectorで Create 3D Hinge Chain を選択して、3Dヒンジチェーンリグを作成します。 Create Hinge Chain 3D
  3. これにより、前の親(この例では cape-root )からチェーンGameObjectが削除され、新しい HingeChain Parent GameObjectがシーンの最上位に配置されます。前述のように、このGameObjectはスケルトンに対して再び親子付けしないでください! Hinge Chain 3D Hierarchy
  4. チェーン要素のRigidbodyのDrag(空気抵抗)とMass(質量)のパラメーターを調整して、結果を微調整してください。

スケルトンが反転すると、HingeChain Parent GameObjectは自動的に180度回転し、反転したボーンの位置に合わせてヒンジチェーンが調整されます。

2Dヒンジチェーン
  1. まず通常通りSkeletonUtilityBone階層を作成してください。
  2. Sceneパネルで最初のチェーン要素を選択し、Inspectorで Create 2D Hinge Chain を選択して、2Dヒンジチェーンリグを作成します。 Create Hinge Chain 2D
  3. これにより、前の親(この例では cape-root )からチェーンGameObjectが削除され、新しい HingeChain Parent GameObjectがシーンの最上位に配置されます。前述のように、このGameObjectはスケルトンに対して再び親子付けしないでください! Hinge Chain 2D Hierarchy
  4. チェーン要素のRigidbody2DのDrag(空気抵抗)とMass(質量)のパラメーターを調整して、結果を微調整してください。

このGameObjectには、Hinge ChainHinge Chain FlippedX という名前の2つの子オブジェクトが含まれていることに注意してください。スケルトンが反転すると、これらのGameObjectが自動的にアクティブになったり非アクティブになったりして切り替わり、それぞれのヒンジチェーンを有効にします。

SkeletonUtility

SkeletonUtilityBonesの階層の作成

SkeletonUtility コンポーネントは、スケルトンのボーン階層を反映したSkeletonUtilityBone GameObjectsの階層を素早く作成することができます。

SkeletonUtility コンポーネントを作成するには、SkeletonAnimationコンポーネントを選択し、Inspectorの Advanced セクションを展開して Add Skeleton Utility をクリックします。作成されると、Add Skeleton Utility ボタンが消え、GameObjectに SkeletonUtility コンポーネントが追加されます。

SkeletonUtility コンポーネントには、Spawn Hierarchy というボタンがあり、クリックすると以下のオプションが表示されます:

  1. Follow all bones は全てのボーンに対して SkeletonUtilityBone GameObjectsをその階層内に作成し、モードを Follow に設定します。
  2. Follow (Root Only) はルートの SkeletonUtilityBone GameObjectのみを作成し、モードを Follow に設定します。
  3. Override all bones は全てのボーンに対して SkeletonUtilityBone GameObjectsをその階層内に作成し、モードを Override に設定します。
  4. Override (Root Only) はルートの SkeletonUtilityBone GameObjectのみを作成し、モードを Override に設定します。

SkeletonUtilityBone は、必要に応じてスケルトンのボーン位置をオーバーライドするように設定できます。

注意: 後からでも SkeletonUtilityBone のInspectorを使って SkeletonUtilityBone GameObjectを追加することができるので、Spawn Hierarchy 機能はあくまで大まかな出発点となります。また、必要のないSkeletonUtilityBone GameObjectを削除して、リソースを節約した方が良いかもしれません。ただし、親はそのままにしておく必要があるので、階層の途中でGameObjectを削除したり、親を変更したりしないように注意してください。

SkeletonUtilityConstraint

C#

これはサブクラス「SkeletonUtilityConstraint」を派生させるための基底クラスです。これは自動的に親の SkeletonUtility で自分自身を登録し、それに応じてアップデートされます。

独自のコンストレイントクラスを作成する方法については、コンストレイントクラスの例 SkeletonUtilityGroundConstraint および SkeletonUtilityEyeConstraintを参照してください。

サンプルシーン

spine-unityランタイムには、上記のコンストレイントを紹介するサンプルシーン、Spine Examples/Other Examples/SkeletonUtility GroundConstraintSpine Examples/Other Examples/SkeletonUtility Eyes が付属しています。

SkeletonRendererCustomMaterials

特定のSkeletonインスタンスのマテリアルをオーバーライドしたい場合や、特定のスロットのみのマテリアルをオーバーライドしたい場合があります。このコンポーネントは、SkeletonAnimationSkeletonMecanimサブクラスを含むSkeletonRendererに、カスタムマテリアルのオーバーライドを割り当てるためのInspectorインターフェイスを提供します。

SkeletonRenderer (またはサブクラスのSkeletonAnimationSkeletonMecanim)を右クリックして Add Basic Serialized Custom Materials を選択すると、このコンポーネントをレンダラーに追加することができます。Custom Slot Materials 配列にエントリを追加して特定のスロットでマテリアルをオーバーライドしたり、Custom Material Overrides 配列にエントリを追加して、スケルトン全体のマテリアルを別のマテリアルに置き換えられます。それぞれのマテリアルのオーバーライドを有効にするには、Override Disabled のチェックを必ず外してください。

注意: このコンポーネントは、コードによる干渉を目的としていません。コードによってSkeletonRendererのマテリアルを動的に設定するには、マテリアル配列のオーバーライド用の SkeletonRenderer.CustomMaterialOverride と、スロットのマテリアルのオーバーライド用の SkeletonRenderer.CustomSlotMaterials に直接アクセスします。

SkeletonGraphicCustomMaterials

これはSkeletonGraphic用のSkeletonRendererCustomMaterialsの派生コンポーネントです。SkeletonGraphicのカスタムマテリアルやテクスチャのオーバーライドを割り当てるためのInspectorインターフェースを提供します。

SkeletonGraphicを右クリックして Add Basic Serialized Custom Materials を選択すると、このコンポーネントをGameObjectに追加することができます。Custom Texture Overrides 配列にエントリを追加すると、スケルトン全体のテクスチャを別のテクスチャに置き換えられます。Custom Material Overrides 配列にエントリを追加して、オリジナルのテクスチャ(置換前)で使用されているマテリアルを別のマテリアルに置き換えられます。それぞれのマテリアルのオーバーライドを有効にするには、Override Enabled のチェックを必ず外してください。

注意: このコンポーネントは、コードによる干渉を目的としていません。コードによってSkeletonGraphicのマテリアルを動的に設定するには、マテリアル配列のオーバーライド用の SkeletonGraphic.CustomMaterialOverride と、テクスチャのオーバーライド用の SkeletonGraphic.CustomTextureOverride に直接アクセスしてください。

SkeletonRenderSeparator

例えば、キャラクターが木にぶつかった時に、片足は幹よりも前に、もう片方の足は幹よりも後ろに表示するなど、キャラクターのパーツの間に他のGameObjectを表示したい場合があります。SkeletonRenderSeparator コンポーネントを使うと、SkeletonRenderer (またはサブクラスのSkeletonAnimationSkeletonMecanim)を2つ以上の SkeletonPartsRenderers に分割し、レイヤーの順番をカスタマイズすることができます。

注意: SkeletonGraphicコンポーネントは、SkeletonGraphic のInspectorの Advanced セクションで直接レンダリングを分離する機能を提供しているため、追加のコンポーネントを使う必要はありません。

注意: 通常、Spineのレンダラーコンポーネントは、スケルトンのメッシュ全体を表示するために1つのレンダラーを使用します。このため、残念ながら他のUnityEngine.Renderers (SpriteRendererMeshRendererParticleSystem など) をそのパーツの間に挿入することはできません。

設定

  1. まず対象のスケルトンのDraw Order(表示順序)を確認してください。スケルトンのレンダリングをパーツに分けるために使用するスロットを確認します。スケルトンをエクスポートする前に、このスロットに明確なラベルを付けておくと便利です。

  2. SkeletonRenderSeparatorコンポーネントの追加 Spine GameObjectを選択してください。次にInspector内のSkeletonAnimationまたはSkeletonRendererを右クリックして、Add Skeleton Render Separator を選択します。これで SkeletonRenderSeparator がGameObjectに追加されます。

"Steps 2 to 4"

  1. Separator Slotsの割り当て 追加した直後はInspectorに「セパレーターのリストが空だ」という旨の警告が表示されますので、Separator Slot Names で必要なスロットを選択して、セパレータースロットを設定してください。+ ボタンからセパレータースロットを追加することができます。

    注意:  このフィールドは、SkeletonRenderer (またはそのサブクラスのSkeletonAnimationSkeletonMecanim)コンポーネントでシリアル化され、SkeletonRenderSeparatorはそのためのインターフェースを提供するだけです。

  2. Parts Renderersの追加 Inspectorに「パーツレンダラーが足りない」という旨の警告が表示されているかと思いますので、Add the missing renderers (n) ボタンをクリックして、SkeletonPartsRenderer コンポーネントで必要なGameObjectを作成してください。これらのGameObjectは、上の Parts Renderers リストに自動的に割り当てられます。

    注意: SkeletonRenderSeparator は、現在の表示順序に応じて、必要なパーツレンダラーの数を検出します。しかし実行時に表示順序が変更されると、レンダラーがより多くのパーツレンダラーを必要とすることがあります。この場合、Add Parts Renderer ボタンをクリックして、1つまたは2つの追加パーツレンダラーを手動で追加する必要があります。

  3. Sorting LayerOrder in Layerの設定SkeletonPartsRenderers には、Inspectorに Sorting LayerOrder in Layer プロパティが用意されています。これで各 SkeletonPartsRenderer でソートのプロパティを設定することができます。値が大きいほどレンダラーが前面に移動します。

補足: SkeletonPartsRenderer GameObjectは、Spine GameObjectの子である必要はありません。SkeletonRenderSeparator は参照を保持しているので、必要に応じて整理してください。

サンプルシーン

SkeletonPartsRendererSkeletonRenderSeparator の使用方法を紹介しているサンプルシーンは Spine Examples/Other Examples/SkeletonRenderSeparator にあります。

C#

有効化と無効化

デフォルトでは、SkeletonRenderSeparatorSkeletonRendererを無効にして、メッシュのレンダリングタスクを引き継ぎます。同様に、SkeletonRenderSeparator を無効にすると、SkeletonRendererが再びレンダリングを引き継ぎます。

SkeletonRenderSeparator は、任意のコンポーネントとして有効または無効にすることができます:

C#
skeletonRenderSeparator.enabled = true; // separation is enabled.
skeletonRenderSeparator.enabled = false; // separation is disabled.
分離基準の変更

分離の基準は SkeletonRenderSeparator では保持していません。 SkeletonRenderer (またはサブクラスのSkeletonAnimationSkeletonMecanim)のセパレータースロットによって定義されます。実行時にセパレータースロットを操作したい場合は、リスト SkeletonRenderer.separatorSlots にアクセスして、通常通り AddRemoveClear で操作できます。

C#
Spine.Slot mySlot = skeletonAnimation.Skeleton.FindSlot("MY SPECIAL SLOT");
skeletonAnimation.separatorSlots.Clear();
skeletonAnimation.separatorSlots.Add(mySlot);
実行時にSkeletonRenderSeparatorを追加する

新しい SkeletonRenderSeparator コンポーネントを追加して初期化するには、staticメソッド SkeletonRenderSeparator.AddToSkeletonRenderer を使用します。

C#
SkeletonAnimation skeletonAnimation = GetComponent<SkeletonAnimation>();
skeletonAnimation.SeparatorSlots.Add(mySlot); // see above

// Add the SkeletonRenderSeparator.
SkeletonRenderSeparator skeletonRenderSeparator = SkeletonRenderSeparator.AddToSkeletonRenderer(skeletonAnimation);

デフォルトでは、現在必要な SkeletonPartsRenderers が追加されます。高度なユースケースのために、多くのオプションの引数が用意されていますので、詳しくはコードのドキュメントをご覧ください。

レンダリング

シェーダー

spine-unityランタイムにはいくつかの異なるシェーダーが同梱されています。デフォルトでは Spine/Skeleton シェーダーが新しくインポートされたスケルトンのMaterialに割り当てられます。シェーダーの変更は、通常通りMaterialのShaderパラメーターで行います。以下に、同梱されているSpineシェーダーのリストをご紹介します。

重要な注意事項: SkeletonGraphicコンポーネントでは、CanvasRendererと互換性のある特別なシェーダーのみを使用してください。詳細はSkeletonGraphic - マテリアルの重要な要件をご覧ください。

重要な注意事項: spine-unityランタイムパッケージは Built-In Render Pipeline 用のシェーダーのみ同梱しており、Universal Render Pipeline を使用しているプロジェクトとは互換性がありません。Universal Render Pipelineを使用している場合は、代わりにSpine URP Shaders extension UPM packageパッケージにて提供されているURP用のシェーダーを使用してください。

注意: ディファードシェーディングレンダリングパスは、Spineシェーダーではまだサポートされていません。

  1. Spine/Skeleton (デフォルトシェーダー)
    ライティングを反映しないUnlit透明シェーダー。Zバッファ(深度バッファ)への書き込みは行いません。

  2. Spine/Skeleton Graphic (SkeletonGraphic用のデフォルトシェーダー)
    SkeletonGraphicで使用される、ライティングを反映しないUnlit透明シェーダー。Zバッファ(深度バッファ)への書き込みは行いません。CanvasGroupで使用する場合、Additive(加算)ブレンドモードはサポートされていないため、代わりにSpine/Skeleton Graphic Tint Blackを使用する必要があります。CanvasRendererの制限により、1つのテクスチャに限定されます。

  3. Spine/Skeleton Lit
    シンプルなLit透明シェーダーで、ノーマルマップ(法線マップ)はサポートしていません。Zバッファ(深度バッファ)への書き込みは行いません。

  4. Spine/Skeleton Lit ZWrite
    シンプルなLit透明シェーダーで、ノーマルマップ(法線マップ)はサポートしていません。Zバッファ(深度バッファ)への書き込みを行います。

  5. Spine/Skeleton Fill
    カスタマイズ可能なカラーオーバーレイを備えたUnlit透明シェーダー。Zバッファ(深度バッファ)への書き込みは行いません。 FillColorはオーバーレイの色を、FillPhaseはオーバーレイの色の強さを決定します。

  6. Spine/Skeleton Tint
    カスタマイズ可能な2色のティント(暗色と明色を別々に着色すること)を備えたUnlit透明シェーダーで、ティントブラックと呼ばれます。Zバッファ(深度バッファ)への書き込みは行いません。

    テクスチャの明るい色はTint Colorで染められ、テクスチャの暗い色はBlack Pointカラーで染められます。これにより、着色されたテクスチャは、通常の乗算カラーブレンドと比較して、元の色よりも明るくなります。Tint ColorBlack Pointの両方を同じ色に設定すると、ソリッドカラー(べた塗り)のオーバーレイになります。Tint Colorを黒に、Black Pointを白に設定すると、テクスチャの色を反転することができます。

  7. Spine/Skeleton Tint Black

    Spineでアニメーションされているスロットごとのティントブラックの機能を持つ、Unlit透明シェーダーです。 Zバッファ(深度バッファ)への書き込みは行いません。 Spineはスロットにティントブラック機能を提供し、アニメーションによるブラックティントを可能にします。

    以下の追加の設定ステップが必要です(ティントカラーの頂点データの場合):

    • SkeletonAnimationのInspectorのAdvancedセクションでTint Blackを有効にしてください:

  8. Spine/Skeleton Tint Black Additive
    Spineでアニメーションされているスロットごとのティントブラックの機能を持つ、Unlit透明シェーダーです。 Additive(加算)ブレンドモードを使用します。 Zバッファ(深度バッファ)への書き込みは行いません。

  9. Spine/SkeletonGraphic Tint Black
    SkeletonGraphic用のSpine/Skeleton Tint Blackシェーダーの派生です。CanvasGroupと一緒に使用する際にAdditive(加算)ブレンドモードをサポートします。

    以下の追加の設定ステップが必要です(ティントカラーの頂点データの場合):

    1. SkeletonAnimation](/spine-unity#SkeletonAnimationコンポーネント)のInspectorのAdvancedセクションでTint Blackを有効にします。
    2. SkeletonGraphicのMaterialを、Spine/Runtime/spine-unity/Materialsフォルダ内のSkeletonGraphicTintBlackマテリアルに設定します。
    3. 親キャンバスを選択し、Additional Shader ChannelsTexCoord1TexCoord2を有効にしてください。

    CanvasGroupでのAdditive(加算)ブレンドモードのためには以下の追加手順が必要です:

    1. SkeletonGraphicのInspectorのAdvancedセクションでCanvas Group Tint Blackを有効にします。
    2. シェーダーでCanvasGroup Compatibleを有効にしてください。
  10. Spine/Sprite
    これらは設定変更が可能な洗練されたシェーダーで、Spine/Skeleton Litシェーダーよりも高度なライティングが可能です。 Spine/Sprite/Vertex Litシェーダーのデモは、サンプルシーンのSpine Examples/Other Examples/Sprite Shadersで確認できます。

    1. Spine/Sprite/Unlit
      ブレンドモード、オーバーレイカラー、色相、彩度、明るさの調整が可能なUnlitシェーダーです。Zバッファ(深度バッファ)への書き込みの設定を変更可能です。Fog(フォグ)をサポートしています。
    2. Spine/Sprite/Vertex Lit
      ブレンドモードの設定変更が可能な洗練されたVertex-Litシェーダーです。 ノーマルマップ(法線マップ)、セカンダリアルベド、メタリック、エミッションマップをサポートしています。 カラーランプによるセルシェーディング風の外観と法線に基づくリムライティング、 オーバーレイの色、色相、彩度、輝度の調整、 Zバッファ(深度バッファ)への書き込みの設定を変更可能です。Fog(フォグ)をサポートしています。
    3. Spine/Sprite/Pixel Lit
      Spine/Sprite/Vertex LitシェーダーのPixel-litバージョンです。これはピクセルごとのリアルタイムシャドウを受けることが出来る唯一のシェーダーです。 このシェーダーは、常にZバッファ(深度バッファ)に書き込みます(ForwardAddパスを使用するため、ZWriteが有効になっています)。
  11. Spine/Special

    1. Spine/Special/Skeleton Grayscale
      Intensityをカスタマイズできるグレースケールレンダリング用のUnlit透明シェーダーです。Zバッファ(深度バッファ)への書き込みは行いません。
    2. Spine/Special/Skeleton Ghost
      SkeletonGhostコンポーネントがトレイルレンダリングに使用する特別なシェーダーです。
  12. Spine/Blend Modes
    これらのシェーダーは、SpineエディターでブレンドモードにAdditive(加算)Multiply(乗算)Screen(スクリーン)が割り当てられているスロットを対象としています。インポート時に、提供されているBlendModeMaterials SkeletonData Modifier assetを介して、ブレンドモードマテリアルを自動的に割り当てることをお勧めします。

    1. Spine/Blend Modes/Skeleton PMA Additive
      ライティングを反映しないUnlit透明シェーダー。Additive(加算)ブレンドモードを使用します。Zバッファ(深度バッファ)への書き込みは行いません。
    2. Spine/Blend Modes/Skeleton PMA Multiply
      ライティングを反映しないUnlit透明シェーダー。Multiply(乗算)ブレンドモードを使用します。Zバッファ(深度バッファ)への書き込みは行いません。
    3. Spine/Blend Modes/Skeleton PMA Screen
      ライティングを反映しないUnlit透明シェーダー。Screen(スクリーン)ブレンドモードを使用します。Zバッファ(深度バッファ)への書き込みは行いません。
  13. Spine/Outline
    上記のすべてのシェーダーにはOutlineパラメーターがあり、これを有効にすると、それぞれのSpine/Outlineシェーダーのバリエーションに切り替わり、スケルトンの周囲に追加のカラーアウトラインが描画されるようになります。 Spine/OutlineシェーダーのデモはサンプルシーンのSpine Examples/Other Examples/Outline Shadersでご覧いただけます。

    1. Spine/Outline/OutlineOnly-ZWrite
      アウトラインのみをレンダリングする特殊なシングルパスシェーダーです。アタッチメントが重なった時にアウトラインのオクルージョンを適切に処理するために、Zバッファ(深度バッファ)への書き込みを行います。また、スケルトンに複数のマテリアルが必要で通常のアウトラインシェーダーではスケルトン全体ではなく各サブメッシュのアウトラインをとってしまうという場合にもこちらのシェーダーを使用することで解決できます。例えば、RenderCombinedMeshコンポーネントを使用して、結合されたスケルトンメッシュをこのアウトラインのみのシェーダーで再レンダリングし、スケルトンの後ろにアウトラインを追加することができます。

ポストプロセスエフェクト

被写界深度(DoF)のようないくつかのポスト処理エフェクトは、シェーダーがZバッファ(より正確には、深度プリパス深度バッファ)に書き込む必要があります。Spineシェーダーのいくつかは、マテリアルで有効にできる Depth WriteZWriteとも呼ばれる)パラメーターを提供し、他のものはデフォルトでZバッファに書き込みます。提供されている SpineシェーダーのどれがZバッファに書き込むかについては、上記のドキュメントを参照してください。

URP-HighFidelityをレンダーパイプラインアセットとして使用している場合など、プロジェクトのGraphics設定(または Render Pipeline Asset Settings)によっては、シェーダーがZバッファに書き込むだけでは不十分な場合があります。この場合、Materialの Render QueueTransparent から AlphaTest に変更する必要があります。

提供されているシェーダーに制限を感じる場合は、修正したいSpineシェーダーをコピーして、ZWrite Off と書かれている行をすべて ZWrite On に変更し(各Passセクションで発生)、タグ "Queue"="Transparent""Queue"="AlphaTest" に変更した自作シェーダーを作ることが可能です。これを行う場合、命名の衝突を避けるために、ファイルの最初の行でシェーダーの名前を変更することを忘れないでください。

URP Shaders - 拡張UPMパッケージ

Universal Render Pipeline (URP)シェーダーは、別のUPM (Unity Package Manager)パッケージとして提供されています。このパッケージをダウンロードしてインストールする方法についてはオプションの拡張UPMパッケージセクションを、アップデートする方法については拡張UPMパッケージのアップデートセクションをご覧ください。

URPシェーダーのUPMパッケージは、2D Renderer機能を含む、Unityの Universal Render pipeline用に作られたシェーダーを提供します。

注意: SkeletonGraphic コンポーネントではURPシェーダーを使用しないでください。詳しくはSkeletonGraphic - マテリアルの重要な要件 をご覧ください。

注意: Universal Render Pipelineに最近追加されたデファードレンダリングパスは、Spine URPシェーダーではまだサポートされていません。

2Dレンダラーを使用するURPシェーダー (URP (3D)フォワードレンダラーとは一緒に使用しないでください)

  1. Universal Render Pipeline/2D/Spine/Skeleton
    Spine/Skeletonシェーダーのユニバーサル2D Rendererバージョンです。
  2. Universal Render Pipeline/2D/Spine/Skeleton Lit
    Spine/Skeleton Litシェーダーのユニバーサル2D Rendererバージョンです。
  3. Universal Render Pipeline/2D/Spine/Sprite
    Spine/Sprite/Vertex LitおよびPixel Litシェーダーのユニバーサル2D Rendererバージョンです。

3Dフォワードレンダラーを使用するURPシェーダー (URP 2Dレンダラーとは一緒に使用しないでください)

  1. Universal Render Pipeline/Spine/Skeleton
    Spine/Skeletonシェーダーのユニバーサルバージョンです。
  2. Universal Render Pipeline/Spine/Skeleton Lit
    Spine/Skeleton Litシェーダーのユニバーサルバージョンです。ピクセルごとのリアルタイムシャドウを受けるように設定することもできます。
  3. Universal Render Pipeline/Spine/Sprite
    Spine/Sprite/Vertex LitおよびPixel Litシェーダーのユニバーサルバージョンです。ピクセルごとのリアルタイムシャドウを受けます。
  4. Universal Render Pipeline/Spine/Outline/Skeleton-OutlineOnly
    Spine/Outlineシェーダーのユニバーサルバージョンです。URPはシェーダーごとに複数のパスを許可していないため、別のマテリアルが必要になります。本パッケージに含まれるサンプルシーンOutline Shaders URPで紹介している通り、RenderExistingMeshコンポーネントを使用した方が良いでしょう。スケルトンに複数のマテリアルが必要な場合は、RenderExistingMesh コンポーネントの代わりに RenderCombinedMesh コンポーネントを使用できます。

シェーダーは通常通りマテリアルに割り当てることができ、Project Settings - Graphicsで割り当てられたUniversalRenderPipelineAssetの設定が反映されます。

URPシェーダーのデモは、UPMパッケージの中のサンプルシーンcom.esotericsoftware.spine.URP-shaders/Examplesにある、3D/URP 3D Shaders.unity2D/URP 2D Shaders.unityOutline Shaders URP.unityで確認できます。

LWRP Shaders - 拡張UPMパッケージ

Lightweight Render Pipeline (LWRP)シェーダーは、別のUPM (Unity Package Manager)パッケージとして提供されています。このパッケージをダウンロードしてインストールする方法についてはオプションの拡張UPMパッケージセクションを、アップデートする方法については拡張UPMパッケージのアップデートセクションをご覧ください。

LWRPシェーダーのUPMパッケージは、以下のUnityの軽量レンダーパイプライン用に作られたシェーダーを提供します。

注意: SkeletonGraphic コンポーネントでは、LWRPシェーダーを使用しないでください。詳しくはSkeletonGraphic - マテリアルの重要な要件を参照してください。

  1. Lightweight Render Pipeline/Spine/Skeleton
    Spine/SkeletonシェーダーのLightweightバージョンです。
  2. Lightweight Render Pipeline/Spine/Skeleton Lit
    Spine/Skeleton LitシェーダーのLightweightバージョンです。
  3. Lightweight Render Pipeline/Spine/Sprite
    Spine/Sprite/Vertex LitおよびPixel LitシェーダーのLightweightバージョンです。

シェーダーは通常通りマテリアルに割り当てることができ、Project Settings - Graphicsで割り当てられたLightweightRenderPipelineAssetの設定が反映されます。

LWRPシェーダーのデモは、解凍したパッケージの中にあるサンプルシーンcom.esotericsoftware.spine.lwrp-shaders-4.1/Examples/LWRP Shaders.unityで確認できます。

Shader Graph

現在、公式のShader Graph Spineシェーダーやシェーダーノードはありません。なお、ストレートアルファ設定を使用してSpineからテクスチャをエクスポートする場合は、Spine以外のシェーダーを使用することができます。Spineシェーダーにしかない機能を再現したい場合は、フォーラム のこちらの投稿を参考にしてください。[1]、[2]。ご質問がある場合は、Unityサブフォーラムに新しいスレッドを立ててください。

Amplify Shader Editor

Amplify Shader Editorには公式に提供されているシェーダーテンプレートはありませんが、ユーザーのHanaさんがフォーラムのこちらの投稿でテンプレートコードを公開してくれています。

シェーダーを自作する

まず前提として、一般的なUnityのカスタムシェーダーの書き方を理解してください。特にTutorial: Weiting vertex and fragment shadersは良い概要となっており、speine-unityシェーダーの各部分が何をしているかをより簡単に理解することができます。

既存のspine-unityシェーダーから始める

まずは既存のspine-unityシェーダーをコピーすることから始めることを強くお勧めします。その後、すでに動作しているシェーダーを徐々に修正して、求めていた効果を得るように調整することができます。例えば、最終的な色を返す前に追加の色処理を加えることができます。例えば次のコードは、グレースケール機能で拡張されたSkeletonGraphicシェーダーの調整バージョンを作成する方法の簡単な例を示しています:

Properties
{
   _GrayIntensity("Intensity", Range(0, 1)) = 1 // この行はMaterialプロパティを提供するために追加しました
   [..]
}
sampler2D _MainTex;
float _GrayIntensity; // このパラメーターを追加しました
..
fixed4 frag (VertexOutput IN) : SV_Target
{
   ..
   color.rgb = lerp(color.rgb, dot(color.rgb, float3(0.3, 0.59, 0.11)), _GrayIntensity); // この行を追加しました
   return color;
}
Spineシェーダー以外のシェーダーやビジュアルシェーダーエディタを使用する際の注意点

典型的なspine-unityシェーダーとその他の非Spineシェーダーの以下のような違いに注意してください:

  1. Spineスケルトンをレンダリングする場合には、Cull Offを設定して必ずバックフェースカリングを無効にするようにしてください。
  2. Spineシェーダーは通常、法線を必要としないため、Litシェーダーを使用する場合はコンポーネントでAdvanced - Add Normalsを有効にする必要があります。
  3. Spineシェーダーは通常、接線を必要としないため、ノーマルマップ(法線マップ)を使用する場合はコンポーネントでAdvanced - Solve Tangentsを有効にする必要があります。
  4. Spineシェーダーはデフォルトで乗算済みアルファテクスチャを使用します。そのため、以下のいずれかを行ってください a) アトラステクスチャをストレートアルファとしてエクスポートする b) シェーダーのブレンドモードをPMAブレンドモードであるBlend One OneMinusSrcAlphaに変更する
  5. Spineの頂点の色は、通常、PMA頂点の色です。透明またはAdditive(加算)スロットを使用する場合、次のいずれかを行うことができます
    a) シェーダーのブレンドモードをPMAブレンドモードであるBlend One OneMinusSrcAlphaに変更し、PMAアトラステクスチャを使用する、または b) コンポーネントでAdvanced - PMA Vertex Colorsを無効にする(Additive(加算)スロットをレンダリングしない場合)

通常通り、UI用および非UI用シェーダーの一般的なルールが適用されます:

  1. SkeletonAnimationまたはSkeletonMecanimに対してUI用シェーダーを使用しないでください。
  2. SkeletonGraphicに対して非UI用シェーダーを使用しないでください。
Spine/Skeletonシェーダーの解析

次のセクションでは、Spine/Skeletonシェーダーの解析を行います。このシェーダーは、Spineテクスチャアトラスのインポート時にMaterialが生成されると、デフォルトで適用されます。 Spine/Skeletonシェーダーはかなり短くて典型的なもので、次のような特徴があります:

  • 乗算済みアルファ(PMA)ブレンディング
  • 深度バッファの書き込み無し
  • ライティング無し
  • バックフェースカリング無し
  • Fog(フォグ)無し
  • 頂点カラーを使って乗算でテクスチャを染める
  • オプションでPMAテクスチャの代わりにストレートアルファを使用する
  • "ShadowCaster"パスを持ち、リアルタイムに影を落とすことができる
  • Materialプロパティ:
    • _MainTex "メインテクスチャ"
    • _StraightAlphaInput "ストレートアルファテクスチャ"
    • _Cutoff "シャドウアルファのカットオフ"
    • 高度なパラメーター:
      • _StencilRef "ステンシルの参照"
      • _StencilComp "ステンシルの比較"
      • アウトラインパラメーター (_OutlineWidth "アウトラインの線幅"、その他。)

詳細:
  • 乗算済みアルファ(PMA)ブレンディング

    hlsl
    Blend One OneMinusSrcAlpha

    (Spine-Skeleton.shader:25)

    ブレンディングは、result_rgba = frag_output_rgba * src_factor + framebuffer_rgba * dst_factorで定義されます。 PMAの非標準的なブレンドモードBlend One OneMinusSrcAlphaでは、Additive(加算)ブレンドモードに設定されているスロットを、Normal(通常)レンドモードのスロットと一緒に1回のレンダリングパスで描画することができます。これは、上の行でSrcFactorに(SrcAlphaの代わりに)Oneを使うことで実現しています。これにより、修正されていないfrag_output_rgbaの値が、OneMinusSrcAlphaでウェイト付けされたframebuffer_rgbaに追加されます:
    a) Normal(通常)ブレンドでは、フラグメントシェーダーはRGBAを乗算し、Aはそのままにします。 b) Additive(加算)ブレンドでは、RGBにアルファを乗算せずにA0に設定してresult_rgba = frag_output_rgba + (1-0) * framebuffer_rgbaを受け取ります。

    SkeletonRendererまたはSkeletonGraphicコンポーネントでAdvanced - PMA Vertex Colorsが有効になっている場合、Normal(通常)およびAdditive(加算)スロットブレンドモードは、頂点カラーとしてシェーダーに暗黙的に渡されます:

    hlsl
    struct VertexInput {
        float4 vertexColor : COLOR
    }

    (Spine-Skeleton.shader:48)

    PMAの頂点カラーとサンプリングされたPMAのテクスチャカラーを掛け合わせる際、スロットのNormal(通常)またはAdditive(加算)ブレンドモードが自動的に適用されます:

    hlsl
    return (texColor * i.vertexColor);

    (Spine-Skeleton.shader:72)

    そのため、シェーダーで適切なNormal(通常)Additive(加算)PMAブレンドモードをサポートする必要があります:

    1. Blend One OneMinusSrcAlphaとしてブレンド関数を定義する。
    2. テクスチャの色と頂点の色を掛け合わせる。
    3. コンポーネントでAdvanced - PMA Vertex Colorsを有効にする。

    標準的なブレンドモードBlend SrcAlpha OneMinusSrcAlphaを使用したシェーダーを使用し、Additive(加算)スロットを必要としない場合、使用したアトラステクスチャをSpineからストレートアルファとしてエクスポートする必要があります。

  • 深度バッファの書き込み無し

    hlsl
    ZWrite Off

    (Spine-Skeleton.shader:24)

    深度バッファへの書き込みが無いのは、アルファブレンディングされた2Dスプライトシェーダーの典型です。透明なオブジェクトは、深度バッファでの深度ソートに頼らず、Camera.transparencySortModeに従って、前後の順序で描画されます。Spine/Skeletonは、この特性をUnity独自のSprites/Defaultシェーダーと共有しています。

    深度への書き込みを有効にしたシェーダーを使用する際は、特にライティングを使用している場合Z-Fightingを防ぐためにSkeletonRendererまたはSkeletonGraphicコンポーネントでAdvanced - Z-Spacing0以外の値に設定してください。 なお、深度バッファを使用すると、エッジのエイリアシング効果など、半透明領域の周囲で望ましくない結果が生じることがあります。

  • ライティング無し
    Spine/Skeletonシェーダーは、シーンに配置されているLightsの影響を受けず、常にtexColor * i.vertexColorのフル輝度でレンダリングされます。

    シェーダーでライティングを適用するには、実際に使用されているLitシェーダーから始めて、自分のコピーを適宜変更することをお勧めします。 単純にLighting OffからLighting Onに変更しただけでは期待した効果は得られず、ご自身の頂点シェーダー(頂点ごとのライティングの場合)やフラグメントシェーダー関数(ピクセルごとのライティングの場合)でライトを評価し、それに応じて色のIntensity(強度)を乗じる必要があります。また、URP、URP-2D、標準パイプラインシェーダーは、それぞれ異なるライティング評価設定を使用しているので、それに合わせてリファレンスシェーダーを選択することに注意してください。

  • バックフェースカリング無し

    hlsl
    Cull Off

    (Spine-Skeleton.shader:23)

    Spineスケルトンをレンダリングするための唯一の厳格な条件は、2Dシェーダーによく見られるバックフェースカリングを無効にすることです。

    ほとんどの3Dシェーダーでは、バックフェースカリングが有効になっています。Spineメッシュでは、パーツがマイナスにスケールされたり、スケルトンの方向を反転させたりすると、この処理によって一部の三角形が見えなくなってしまいます。

  • Fog無し
    Spine/SkeletonシェーダーはFog(フォグ)の影響を受けません。

    シェーダーでFogを有効にするには、シェーダーコードに追加の頂点パラメーターと関数呼び出しが必要です。以下UnityCG.cgincより:

    hlsl
    multi_compile_fog Will compile fog variants.
    UNITY_FOG_COORDS
    (texcoordindex) Declares the fog data interpolator.
    UNITY_TRANSFER_FOG
    (outputStruct,clipspacePos) Outputs fog data from the vertex shader.
    UNITY_APPLY_FOG
    (fogData,col) Applies fog to color "col". Automatically applies black fog when in forward-additive pass.
    Can also use UNITY_APPLY_FOG_COLOR to supply your own fog color.

    シェーダーでFogを適用する方法については、Spine/Sprite/Unlitシェーダーを参考にしてください。:

    hlsl
    #pragma multi_compile_fog

    (SpritesUnlit.shader:70)

    hlsl
    UNITY_FOG_COORDS(1) // to declare it at the free attribute TEXCOORD1

    (SpriteUnlit.cginc:L24)

    hlsl
    UNITY_TRANSFER_FOG(output,output.pos);

    (SpriteUnlit.cginc:46)

  • 頂点カラーを使って乗算でテクスチャを染める
    前述の「乗算済みアルファ(PMA)ブレンディング」をご覧ください。

  • オプションでPMAテクスチャの代わりにストレートアルファを使用する
    Spine/Skeletonシェーダーのブレンドモードは常にPMAブレンディングに設定されているため、入力テクスチャが乗算済みアルファカラーを持っていない場合、サンプリング後にPMAカラーに変換する必要があります。以下の行ではこの機能を実装しています:

    // bool Material parameter, enables the _STRAIGHT_ALPHA_INPUT shader keyword when enabled
    [Toggle(_STRAIGHT_ALPHA_INPUT)] _StraightAlphaInput("Straight Alpha Texture", Int) = 0
    ..
    // compiles the shader in two variants so that shader keywords can switch between both variants
    #pragma shader_feature _ _STRAIGHT_ALPHA_INPUT
    ..
    // when enabled, multiply texture rgb values by the texture alpha value.
    #if defined(_STRAIGHT_ALPHA_INPUT)
    texColor.rgb *= texColor.a;
    #endif
  • "ShadowCaster"パスを持ち、リアルタイムに影を落とすことができる
    Tags { "LightMode"="ShadowCaster" }を持つセカンドパスはLightModeによって自動的にShadowCasterパスとして識別されます。 ShadowCasterパスは、RGB カラーを一切書き込まず、代わりに深度情報をシャドウバッファに書き込みます。そのため、必ずZWrite Onを使用します。 半透明の深度を書き込むことはできないので、フラグメントは深度バッファに書き込まれるか、影を落とさないように破棄されます。これは、しきい値関数コールで行います:

    hlsl
    clip(texcol.a * i.uvAndAlpha.a - _Cutoff);

    (Spine-Skeleton.shader:112)

    ここでは、_Cutoff Materialパラメーターがアルファのしきい値を定義しており、x < 0の場合、clip(x)によってフラグメントが破棄されます。

  • Materialプロパティ:

    • _MainTex "メインテクスチャ"
      メインのテクスチャ。
    • _StraightAlphaInput "ストレートアルファテクスチャ"
      前述の「オプションでPMAテクスチャの代わりにストレートアルファを使用する」を参照してください。
    • _Cutoff "シャドウアルファのカットオフ"
      前述の"ShadowCaster"パスを持ち、リアルタイムに影を落とすことができる」を参照してください。
    • 高度なパラメーター:
      • _StencilRef "ステンシルの参照"
        マスク・インタラクションに使用します。
      • _StencilComp "ステンシルの比較"
        マスクインタラクションに使用され、SkeletonRendererまたはSkeletonGraphicコンポーネントがMask Interactionプロパティに従って設定されます。
      • アウトラインパラメーター(_OutlineWidth "アウトラインの線幅"、その他。)
        アウトラインシェーダーバリアントSpine/Outline/Skeletonに切り替えたときに使用されます。通常の非アウトラインシェーダーバリアントSpine/Skeletonでは使用されません。

マテリアル

各アトラスページのTextureは、スケルトンインポート時に自動的に作成される独自のMaterialを必要とします。Normal(通常)以外のSlotブレンドモードを使用する場合は、ブレンドモードごとに追加のMaterialも作成されます(PMA使用時のAdditive(加算)は除きます。これは通常のマテリアルでレンダリングが可能です)。MeshRendererのMaterials配列は、現在割り当てられているアタッチメントと、それらが含まれているAtlasAssetsに応じて、毎フレームごとにSkeletonRendererによって管理され、現在割り当てられているアタッチメントとそれらが含まれるAtlasAssets、およびSlotで使用されているブレンドモードに依存します。

注意: Materialsの配列を直接変更しても、次のLateUpdate()で上書きされてしまうので、効果はありません。マテリアルをオーバーライドするには、SkeletonRendererCustomMaterialsまたはSkeletonGraphicCustomMaterialsコンポーネントを使用してください。また、_Atlasアセットで異なるマテリアルを割り当てて、すべてのインスタンスのマテリアルを変更することもできます。アトラスアセットを変更した後は、SkeletonRendererコンポーネントのSkeletonData AssetパラメーターでReloadを押して新しいアトラスマテリアルを使用してスケルトンを再ロードする必要があります。

注意: SkeletonGraphicコンポーネントではSpine/SkeletonGraphic*シェーダーを持つマテリアルのみを使用してください。URP、LWRP、またはSpine/Skeletonのような通常のシェーダーをSkeletonGraphicコンポーネントで使用しないでください。詳しくは SkeletonGraphic - マテリアルの重要な要件 をご覧ください。

マテリアルの切り替えとドローコール

割り当てられたアタッチメントが複数のアトラスページに分散している場合、あるいはマテリアルAとマテリアルBのように異なるブレンドモードを持っている場合、Materials配列はマテリアルが必要とされる表示順序に従って設定されます。

例えば、もし表示順序が以下のようになっているとしたら:

  1. Aからのアタッチメント
  2. Aからのアタッチメント
  3. Bからのアタッチメント
  4. Aからのアタッチメント

マテリアルの配列は以下のようになります:

  1. Material A (アタッチメント1と2用)
  2. Material B (アタッチメント3用)
  3. Material A (アタッチメント4用)

Materials配列のすべてのマテリアルはドローコールに対応しています。そのため、マテリアルの切り替え量が多いとパフォーマンスに悪影響を及ぼしてしまいます。

Dragonの例では、多くのドローコールがある残念なユースケースを紹介しています:

そのため、アタッチメントは可能な限り少ないアトラスページでパックすることや、表示順序に応じてアタッチメントをアトラスページにまとめて不要なマテリアルの切り替えを防ぐことが推奨されています。 Spineアトラスのアトラス領域の配置方法についてはSpineテクスチャ・パッカー: フォルダ構造をご覧ください。

インスタンスごとにマテリアルを変更する

注意: SkeletonRendererのMaterials配列を直接変更しても次のLateUpdate()で上書きされてしまうので、効果はありません。以下の方法が適切でない場合は、SkeletonAnimation.OnMeshAndMaterialsUpdatedコールバックデリゲートを使用して、手動で毎フレームMeshRenderer.Materialsをオーバーライドすることができます。このコールバックは、アトラスマテリアルが割り当てられた後、LateUpdate()の最後に呼び出されます。

CustomMaterialOverrideとCustomSlotMaterials

SkeletonRendererでは、特定のスロットのマテリアルをオーバーライドしたり、結果のマテリアルをオーバーライドすることができます。

SkeletonRendererインスタンスの実行時にオリジナルのマテリアルを新しいマテリアルに置き換えるには、以下のようにSkeletonRenderer.CustomMaterialOverrideを使用します:

C#
// プログラムでオリジナルのマテリアルを照会するには、以下のコードを使用してください(下記注意も参照)。
// MeshRenderer.materialは動作しません。また、 MeshRenderer.sharedMaterialも場合により失敗する可能性があります。
if (originalMaterial == null)
   originalMaterial = skeletonAnimation.SkeletonDataAsset.atlasAssets[0].PrimaryMaterial;

skeletonAnimation.CustomMaterialOverride[originalMaterial] = newMaterial; // 置換を有効にする。
skeletonAnimation.CustomMaterialOverride.Remove(originalMaterial); // 置換を無効にする。

注意: .materialはマテリアルそのものではなく、プライマリマテリアルのインスタンスコピーを返すので、originalMaterial = skeletonAnimation.GetComponent<MeshRenderer>().material は使用しないでください。また、originalMaterial = skeletonAnimation.GetComponent<MeshRenderer>().sharedMaterial を使用することもお勧めしません。 アクティブなフレームにアクティブなアタッチメントが無い場合など、プライマリマテリアルがまだ割り当てられていないときにNULLを返す可能性があるからです。

特定のスロットだけに置換マテリアルを使用するにはSkeletonRenderer.CustomSlotMaterialsを使用します:

C#
skeletonAnimation.CustomSlotMaterials[slot] = newMaterial; // 置換を有効にする。
skeletonAnimation.CustomSlotMaterials.Remove(slot); // 置換を無効にする。
バッチングを維持しながらスケルトンをティント(着色)する

スケルトンインスタンスに異なる MaterialsMaterialPropertyBlocks を使用すると、バッチングが発生します。個々のスケルトンインスタンスを異なる方法でティント(着色)したいだけで、他のマテリアルプロパティを変更する必要が無い場合は、Skeleton.R .G .B .Aカラープロパティを使用できます。ティントを適用するには、SkeletonRendererのInspectorでAdvanced - PMA Vertex Colorsを有効にする必要があります。

C#
public Color color = Color.white;
...
skeleton = GetComponent<SkeletonRenderer>().Skeleton;
...
skeleton.R = color.r;
skeleton.G = color.g;
skeleton.B = color.b;
skeleton.A = color.a;

これらのスケルトンカラーの値は、頂点カラーを設定するもので、マテリアルプロパティには影響しません。

個々のアタッチメントをティントする場合も同様です。:

C#
slot = skeleton.FindSlot(slotname);
...
slot.R = slotColor.r;
slot.G = slotColor.g;
slot.B = slotColor.b;
slot.A = slotColor.a;

注意: アニメーション内でアタッチメントカラーの値を変更している場合は、アニメーションが適用された後に、SkeletonAnimation.UpdateCompleteコールバックなどでスロットカラーの値を必ず設定してください。

MaterialPropertyBlocks

Renderer.SetPropertyBlockを使って、1つの MeshRenderer のマテリアルプロパティ値を上書きすることができます。

C#
MaterialPropertyBlock mpb = new MaterialPropertyBlock();
mpb.SetColor("_FillColor", Color.red); // "_FillColor" is a named property on the used shader.
mpb.SetFloat("_FillPhase", 1.0f); // "_FillPhase" is another named property on the used shader.
GetComponent<MeshRenderer>().SetPropertyBlock(mpb);

// to deactivate the override again:
MaterialPropertyBlock mpb = this.cachedMaterialPropertyBlock; // assuming you had cached the MaterialPropertyBlock
mpb.Clear();
GetComponent<Renderer>().SetPropertyBlock(mpb);

注意: MaterialPropertyBlockで使用するパラメーター名(_FillColor_FillPhaseなど)は、それぞれシェーダー変数名と一致していなければなりません。なお、シェーダー変数名は、Inspectorで表示される名前(Fill ColorFill Phaseなど)とは異なりますのでご注意ください。シェーダー変数名を確認するには、.shaderファイルを開き(マテリアルの歯車アイコンメニューからEdit Shaderを選択)一番上のProperties { .. }を確認してください。そこには、すべてのパラメーターのリストがあります。以下のようなパラメーター行で一番左にある名前_FillColorが変数名です:

_FillColor ("Fill Color", Color) = (1,1,1,1)
^^^^^^^^^^

シェーダー変数名は通常、_で始まり、スペースは含まれません。Inscpectorに表示されるのは、"Fill Color"のような隣の文字列です。

サンプルシーンの Spine Examples/Other Examples/Per Instance Material Properties では、インスタンスごとのマテリアルプロパティのデモをご確認いただけます。

最適化の注意点

  • Renderer.SetPropertyBlockを異なるMaterial値で使用すると、レンダラー間のバッチングが発生します。MaterialPropertyBlockパラメーターが同じであれば、レンダラー間でのバッチングは行われます(例:すべてのレンダラーがティントカラーを同じ緑色に設定する)。
  • MaterialPropertyBlockのプロパティ値を変更または追加する際には必ず SetPropertyBlock を呼び出す必要があります。しかし、そのMaterialPropertyBlockをクラスの一部として保持しておけば、プロパティを変更するたびに新しいものをインスタンス化する必要はありません。
  • プロパティを頻繁に設定する必要がある場合は、静的メソッドを使用することができます: Shader.PropertyToID(string)を使うと、MaterialPropertyBlockのセッターの文字列オーバーロードを使わずに、そのプロパティのint IDをキャッシュすることができます。

透明度と表示順序

すべてのspine-unityシェーダーは、アルファブレンディングを使用して、アタッチメントの境界に半透明のトランジションをきれいに描きます。アルファブレンディングを使用しないと(ハードな透明度しきい値を使用して)、エイリアシングアーティファクトのような硬いギザギザのアウトラインができてしまいます。

残念ながらアルファブレンディングには古典的な問題があり、zバッファを自動深度ソートに使用できません。代わりに、三角形を後ろから前の順にレンダリングし、パーツを重ねてペイントする必要があります。各SkeletonRendererはそれに応じてメッシュを生成し、三角形はSpineで定義されたスロットの表示順序に従います。1つのメッシュ内では、1回のドローコールでも、正しく順序付けられたスケルトンパーツを描くことができます。

複数メッシュ間では、どのメッシュがどのメッシュの上に来るべきかを決定するために、spine-unityはUnityの描画順序システムの多くを利用しています。標準的なspine-unityの設定では、スケルトン全体のメッシュは、以下の複数の要素によって決定された順序でレンダリングされます:

  1. Camera depth マルチカメラの設定に関連しています。
  2. Material.renderQueue 設定すると、シェーダーのQueueタグを上書きします。
  3. シェーダーのQueueタグ デフォルトでは、他のスプライトと同様にSpineシェーダーで"Transparent"のキューに入っています。
  4. Sorting Groupコンポーネント MeshRendererのGameObjectや親のGameObjectsに配置された場合
  5. レンダラーのSortingLayerおよびSortingOrder within a layer
  6. カメラからの距離 カメラは平行投影(planer)または透視投影(perspective)のどちらを使用するかを設定できます

シーンのレンダラーが同じsorting layerとorderにあり、シェーダーのQueueタグが同じであれば、カメラまでの距離でSpine GameObjectのソートをコントロールすることができます。なお、カメラにはtransparencySortModeプロパティがあります。

Sorting LayerとOrder in Layer

SkeletonRenderer (またはサブクラスのSkeletonAnimationSkeletonMecanim)のInspectorにはSorting LayerOrder in Layerプロパティがあり、MeshRenderersortingLayerIDsortingOrderプロパティを実際に変更します。これらのプロパティはSkeletonRendererの一部ではなく、MeshRendererの一部として保存されます。

また、これらのプロパティにはコードでアクセスすることができます:

C#
GetComponent<MeshRenderer>().sortingOrder = 1; // Change the Order in Layer to 1.

ソートの誤りを防ぐには

特に平行投影(orthographic)カメラを使用している場合、複数のアトラスページを使用しているスケルトンが誤ってソートされてしまうことがあります。 この問題を解決するには、スケルトンGameObjectにSorting Groupコンポーネントを追加する必要があります。また、カメラを少しだけ回転させるという方法もあります。例えば、カメラのトランスフォームY回転の値を0.001に設定するなどです。

スケルトンのパーツ間にオブジェクトを描画する

例えば、キャラクターが木に突っ込んだ時に、片足を木の前に、片足を木の後ろに表示させるなど、キャラクターのパーツの間に他のGameObjectを表示させたい場合があります。

spine-unityでは、スケルトンを複数のパーツに分割するためにSkeletonRenderSeparatorコンポーネントを提供しています。

スケルトンのフェードイン、フェードアウト

残念ながら、アルファブレンディングでは、スケルトンのアルファ値を下げて半透明にするとスケルトンの下位のパーツが透けて見えてしまいます。これは、各三角形の描画時に透明度が適用されるためです。

この問題を解決する一つの方法は、一時的なRenderTextureを使用することです。キャラクター全体を通常の不透明度でRenderTextureにレンダリングし、その後、このRenderTextureのコンテンツを任意のフェード不透明度でシーンに描画することができます。 また、これを実現するために提供されているSkeletonRenderTextureとサンプルコンポーネントSkeletonRenderTextureFadeoutを使用することができます。これらのコンポーネントのデモは、サンプルシーンSpine Examples/Other Examples/RenderTexture FadeOut Transparencyで確認できます。

なお、これはフェードアウト効果を作成するための数ある方法のうちの一つに過ぎません。スケルトンを徐々にソリッドカラーで染めたり、スケールを小さくするなど、他にも簡単な方法がある可能性があります。RenderTextureは負荷のかかる解決方法であり、従来はほとんど使用されてこなかったため、既存の2Dゲームが貴重なインスピレーションとなるでしょう。

サンプルコンポーネント

spine-unityには、高度なユースケースのソリューションを示す追加のサンプルコンポーネントが付属しています。最も重要なサンプルコンポーネントを以下に示します。

SkeletonRagdoll

アニメーションしているスケルトンを人形(ラグドール)のように変えたい場合(例えば、死んだときに物理的に落ちていく様子をシミュレートしたい場合)、SkeletonRenderer (またはサブクラスのSkeletonAnimationSkeletonMecanim)でラグドールの物理コンポーネントを作成するための快適なインターフェイスを提供するSkeletonRagdollSkeletonRagdoll2Dのサンプルコンポーネントで実現できます。

SkeletonRagdoll2Dコンポーネントのデモは、サンプルシーンSpine Examples/Other Examples/SkeletonUtility Ragdollでご覧いただけます。

SkeletonRenderTexture

スケルトンを透明度でフェードアウトさせたい場合など、スケルトンを直接画面に表示するのではなくRenderTextureにレンダリングする必要がある場合があります。このコンポーネントは、スケルトンを適切なサイズと解像度で RenderTexture にレンダリングし、スケルトンにぴったり一致したQuadで表示する処理を行うので、シームレスに置き換えることができます。

後述のSkeletonRenderTextureFadeoutコンポーネントは SkeletonRenderTexture またはSkeletonGraphicRenderTextureコンポーネントを必要とします。GameObejctに SkeletonRenderTexture コンポーネントを追加した後、 SkeletonRenderTextureFadeout コンポーネントを追加すれば、正しくフェードアウトできます。

重要な注意事項: レンダリングのために中間RenderTextureを使用するのは、フレームバッファにスケルトンを直接描画するのに比べて高負荷な操作になります。そのため、このコンポーネントは必要な場合にのみ使用してください。実際に使いたいエフェクトを有効にするまでは無効にしておきましょう。例えば、フェードアウトを行うときだけ SkeletonRenderTexture コンポーネントを有効にし、その前後は無効のままにするなどです。

SkeletonGraphicRenderTexture

SkeletonGraphicを使っている場合に使用されるSkeletonRenderTextureの派生コンポーネントです。

SkeletonRenderTextureFadeout

スケルトンを透明化してフェードアウトさせるにあたって、こちらで説明したようなアタッチメントの重なりが見えてしまう問題を避けたい場合があります。このコンポーネントはSkeletonRenderTextureまたはSkeletonGraphicRenderTextureコンポーネント(最初に追加する必要があります)と共に使用することで、一時的にRenderTextureに不透明なスケルトンをレンダリングし、次にこのRenderTextureのコンテンツを任意のフェード透明度でシーンに描画することができます。

SkeletonGhost

スピード感や力強さを表現するために、キャラクターにモーショントレイルやモーションブラーの効果を与えることもできます。SkeletonGhostサンプルコンポーネントは、SkeletonRenderer (またはサブクラスのSkeletonAnimationSkeletonMecanim)にアタッチすることで、カスタマイズ可能なマテリアルを使用してスケルトンを複数回描画することができます。

SkeletonUtilityKinematicShadow

いくつかのボーンに慣性を持たせたり、他のボーンの動きに反応させたりすることもできます。これは、より説得力のある方法でキャラクターの動きにマントを追従させるのに役立つ可能性があります。これは、SkeletonUtilityKinematicShadowコンポーネントで実現できます。これにより、ヒンジチェーンは、親のトランスフォームの位置の変化や、関係のないリジッドボディから解釈された速度を継承することができます。

SkeletonUtilityKinematicShadowコンポーネントのデモは、サンプルシーンSpine Examples/Other Examples/SkeletonUtility Animated Physicsにあります。

RenderExistingMesh

アニメーションしているスケルトンの同一のコピーを異なる場所で複数回レンダリングすることで、パフォーマンスを節約したい場合があります。例えば、大きなスケルトンのグループではある程度の繰り返しが可能です。また、URPシェーダーのUniversal Render Pipeline/Spine/Outline/Skeleton-OutlineOnlyを選択して、メッシュをそれ自身の後ろで再度レンダリングすることもできます。このコンポーネントを使用すると、すでにアニメーションして更新されたスケルトンメッシュを再度レンダリングすることができ、アニメーションとメッシュの計算にかかるオーバーヘッドを節約することができます。

RenderCombinedMesh

スケルトンに複数のマテリアルが必要な場合、ランタイムに付属しているアウトラインシェーダーは、スケルトン全体ではなく、各サブメッシュのアウトラインをかたどってしまいます。このコンポーネントを使用してサブメッシュを結合して単一のメッシュとしてレンダリングすれば、正しいアウトラインをかたどることができます。

サンプルシーン

spine-unityランタイムには、一般的なユースケースで最も重要なコンポーネントやC# APIの使い方を実演するサンプルシーンが含まれています。これらは、Spine Examplesのトップレベル・ディレクトリにあります。各シーンには、関連する部分をすばやく見つけて理解するのに役立つ説明文が含まれています。以下のビデオではspine-unityランタイムに含まれる各サンプルシーンの概要をお見せしています。

初めてspine-unityランタイムを使用する場合は、少なくともSpine Examples/Getting Startedにあるサンプルシーンをチェックすることを強くお勧めします。

Spine Examples / Getting Started

Spine Examples/Getting Startedにあるサンプルシーンでは、基本的なコンポーネントと基本的な使用例が紹介されています。

1 The Spine GameObject

このシーンでは、SkeletonAnimationコンポーネントと、コンポーネントが参照するために必要なデータを提供するSkeletonDataAssetについて紹介しています。

2 Controlling Animation

このシーンでは、C# APIを使った基本的なアニメーションコード(アニメーションの開始、アニメーションイベントへの反応)を紹介しています。

再生ボタンを押すと、Spineboyは、walk、run、idle、turnのアニメーションを順番に再生します。Footstepイベントがトリガーとなって足音が鳴ります。

SpineBeginnerTwo コンポーネントのサンプルスクリプトは、GameObject spineboy にアタッチされています。このスクリプトでは SkeletonAnimation.AnimationState.SetAnimation()SkeletonAnimation.AnimationState.AddAnimation() の使い方を説明しています。 また、GameObject sound にアタッチされたスクリプトHandleEventWithAudioExample では、SkeletonAnimation.AnimationState.Event に登録することで、独自のイベントメソッドのコールバックをフックする方法を紹介しています。

3 Controlling Animation Continued

このシーンでは、複数のアニメーショントラックを使用して、アニメーションを同時に再生する方法を紹介しています。また、アニメーション名の文字列の代わりに AnimationReferenceAssets を使用する方法も紹介しています。

再生ボタンを押すと、walk アニメーションがループ再生されます。同時に、独自のタイムフレームで gungrabgunkeep アニメーションがセカンダリアニメーションとして再生されます。

GameObject raptor Skeleton にアタッチされているサンプルスクリプト Raptor を確認してみてください。このスクリプトでは、コンポーネントでAnimationReferenceAssetのプロパティを公開し、SkeletonAnimation.AnimationState.SetAnimation()メソッドを呼び出して、トラック0と1にアニメーションを割り当てる方法を紹介しています。

4 Object Oriented Sample

このシーンでは、Model-View-Controllerと呼ばれるソフトウェアアーキテクチャに従って、プラットフォーマーのキャラクターを設定する方法を紹介しています。この設定はあなたのプロジェクトに最適ではないかもしれませんが、入力、ゲームロジック、ビジュアライゼーションをどのようにコンポーネントに区分けするかのヒントになるでしょう。

再生ボタンを押すと、WASDキー(移動)、スペースバー(ジャンプ)、マウス入力(照準と射撃)でキャラクター(Spineboy)を操作することができます。また、XBOXコントローラーで操作することもできます。

GameObject PLAYER INPUT にアタッチされたサンプルスクリプト SpineboyBeginnerInput を確認してみてください。これは「Controller」としての役割を持っています。GameObject PLAYER Spineboy にアタッチされた SpineboyBeginnerModel コンポーネントが表示するモデルの状態を変更します。GameObject VIEW Spineboy にアタッチされている SpineboyBeginnerView コンポーネントは「View」としての役割を持っています。また、同じGameObjectにアタッチされているSkeletonAnimationコンポーネントで、それぞれのアニメーションを開始します。

5 Basic Platformer

このシーンでは、jump、run、fall(落下)、land(着地)などの典型的なアニメーションに、パーティクルやサウンドエフェクトを加えたプラットフォーマーのユースケースを紹介しています。 また、Spineメッシュを使ってUnityで影を落とす方法も紹介しています。

注意: キャストシャドウが表示されない場合は、Edit - Preferences - Quality - Shadowsでシャドウを有効にしてください。

再生ボタンを押すと、WASDキー(移動)とスペースバー(ジャンプ)でキャラクター(Hero)を操作することができます。また、XBOXコントローラーで操作することもできます。

GameObject Player にアタッチされているサンプルスクリプト BasicPlatformerController では、Unityの入力を使用して、新しく作成されたCharacterState属性でトラッキングされるキャラクターのステートを切り替える方法を紹介しています。ステートが変化すると、サンプルスクリプト SkeletonAnimationHandleExample によって新しいアニメーションに移行し、サンプルスクリプト HeroEffectsHandlerExample によってサウンドを再生したりパーティクルシステムを生成したりします。

6 SkeletonGraphic

このシーンでは、SkeletonGraphicコンポーネントと、それをUnityのUIシステムで組み込む方法を紹介しています。また、BoneFollowerGraphicコンポーネントを使って、テキストラベルを特定のボーンの位置に追従するようにアタッチする方法も紹介しています。これらのコンポーネントは、GameObject Detached BoneFollowerGraphicChild BoneFollowerGraphic で使用されています。

再生ボタンを押すと、DoiとSpineboyがスクロール可能なパネルに組み込まれた、Canvasベースのユーザーインターフェースが表示されます。どちらもUIの一部でありながらSkeletonAnimationコンポーネントのようにループするアニメーションを再生します。

Timeline 拡張UPMパッケージ

Timelineのサポートは、別のUPM(Unity Package Manager)パッケージとして提供されています。このパッケージをダウンロードしてインストールする方法についてはオプションの拡張UPMパッケージを、アップデートする方法については拡張UPMパッケージのアップデートを参照してください。タイムライン拡張パッケージのインストールと使い方については以下のビデオが参考になるでしょう。

Spine-Unity Timeline Playables

Spine Timelineでは現在、以下3種類のTimeline Playablesを提供しています:

  • SkeletonAnimation Track SkeletonAnimationをアニメーションさせます)
  • SkeletonGraphic Track SkeletonGraphicをアニメーションさせます)
  • Skeleton Flip Track SkeletonAnimationおよびSkeletonGraphicを反転させます)

注意: Timelineの各トラックは、読みやすさを向上させるために最近のバージョンで名前が変更されました。 SkeletonAnimation Track は、以前は Spine AnimationState TrackSkeletonGraphic Track は、以前は Spine AnimationState Graphic TrackSkeleton Flip Track は、以前は Spine Skeleton Flip Trackと呼ばれていました。

制限事項: 現在サポートされているのは、SkeletonAnimationSkeletonGraphicのみです。SkeletonMecanimはTimelineでサポートされていません。

SkeletonAnimation Track と SkeletonGraphic Track

これらのトラックタイプは、対象となるSkeletonAnimationまたはSkeletonGraphicのAnimationStateにアニメーションを設定するために使用できます。SkeletonAnimationにはSkeletonAnimation TrackSkeletonGraphicにはSkeletonGraphic Trackというトラックタイプが使用されます。

パラメーター

  • Track Index : アニメーションの設定対象となるAnimationStateトラックのインデックスです。複数のタイムライントラックを使用する場合は、忘れずにこの値を適宜設定してください。

    重要な注意事項: 現在のところ、タイムライントラックの順番は、ベーストラックが上、オーバーレイトラックが下になるようにする必要があり、そうしないとエディタープレビューで正しくない結果が表示されてしまいます。

  • Unscaled Time : このトラックの新しいアニメーションクリップを開始するたびに、SkeletonAnimation.UnscaledTime (またはSkeletonGraphic.UnscaledTime) がこの値に設定されます。これにより、Timeline クリップを通常のゲーム時間で再生したり、スケーリングされていないゲーム時間で再生することができます。 ただし、PlayableDirector.UpdateMethod が無視されてこのプロパティに置き換えられるので、Timelineトラックごとにより細かい制御が可能になることに注意してください。

Spine Animation State Clip

AnimationReferenceAssetをTimelineトラックにドラッグすることでSkeletonAnimation Track(またはSkeletonGraphic Track)にSpine Animation State Clipを追加することができます。SkeletonDataAssetAnimationReferenceAssetsを生成する方法についてはSkeletonData - Previewセクションをご覧ください。

パラメーター
Clip Timing

  • Clip In : このアニメーションを再生する際に適用される初期のローカル開始時間のオフセット。クリップの左端をドラッグして調整することもできます。
  • Blend In Duration : Use Blend Durationが有効かつDefault Mix Durationが無効な場合に使用されるブレンドトランジションのデュレーションです。クリップを前のクリップに移動させることで、トランジション時にクロスフェードの三角形が表示され、調整することができます。
  • Speed Multiplier : 再生速度の倍率。2.0に設定するとアニメーションの再生速度が2倍になり、0.5に設定すると半分に減速します。

Spine Animation State Clip

  • Don't Pause with Director : trueに設定すると、Directorが一時停止してもアニメーションが継続して再生されるようになります。
  • Don't End with Clip : 通常、タイムライン上でクリップの後に空のスペースが続くと、トラックに空のアニメーションが設定されますが、このパラメータをtrueに設定すると、代わりにクリップのアニメーションを再生し続けます。
  • Clip End Mix Out Duration : Don't End with Clipがfalseの場合で、クリップの後に空白がある、または停止していると、このMixDurationで空のアニメーションが設定されます。0未満の値を設定した場合、クリップは代わりに一時停止されます。

Mixing Setting

  • Default Mix Duration : 無効にすると、前のアニメーションからこのアニメーションへの移行時に、後述のMix Durationの値が使用されます。有効にすると、アニメーションペアのSkeletonDataアセットで設定されたMix Durationの値が使用されます。
  • Use Blend Duration : 有効にすると、Mix Durationの値は、タイムラインクリップのトランジションデュレーション「Ease In Duration」と同期するようになります。これを有効にすると、クリップを前のクリップに移動させることでトランジションのデュレーションを調整し、トランジション時にクロスフェードの三角形が表示されます。
  • Mix Duration : Default Mix Durationが無効な場合、前のアニメーションからこのアニメーションへの移行時にここで設定したミックスデュレーションが使用されます。
  • Event Threshold : TrackEntry.EventThresholdをご覧ください。
  • Attachment Threshold : TrackEntry.AttachmentThresholdをご覧ください。
  • Draw Order Threshold : TrackEntry.DrawOrderThresholdをご覧ください。
  • Alpha :  TrackEntry.Alphaをご覧ください。

無視されるパラメーター

  • Ease Out Duration、Blend Curves : これらのパラメーターは無視され、何の影響もありません。

注意: Default Mix Duration は、以前は Custom Duration と呼ばれており、有効と無効が反転していました。これは読みやすさを向上させるために変更されました。

使用方法

  1. SkeletonAnimation GameObjectにSkeletonAnimationPlayableHandleコンポーネントを、またはSkeletonGraphicの場合にはSkeletonGraphicPlayableHandleを追加します。
  2. すでにUnity Playable Directorがある状態で、Unity Timelineウィンドウで左側の何もないスペースを右クリックしてSpine - SkeletonAnimation Trackを選択します。
  3. SkeletonAnimationまたはSkeletonGraphic GameObjectを、新しいSpine AnimationState Trackの空の参照プロパティにドラッグします。
  4. トラックにアニメーションを追加するには、通常のアニメーションクリップと同じように、それぞれのAnimationReferenceAssetをクリップビュー(Timelineパネルの右側)にドラッグし てください。

アニメーションごとのAnimationReferenceAssetを作成する方法についてはspine-unityランタイムドキュメントのPreviewセクションを参照してください。

補足: 複製機能(CTRL/CMD + D)を使って、クリップビューで選択したクリップを複製することができます。

このトラックの挙動

  • AnimationState.SetAnimation()AnimationReferenceAssetに基づいてすべてのクリップの最初に呼び出されます。
  • Timelineのバージョン4.0以降、クリップのデュレーションが重要になりました。

    補足 : バージョン3.8の挙動では、クリップのデュレーションは問題ではありませんでした。タイムライン上のクリップの後に何もない空間に到達しても、アニメーションはクリアされませんでした。

  • 空のアニメーション : クリップにAnimationReferenceAssetが割り当てられていない場合は、代わりにSetEmptyAnimationが呼び出されます。
  • エラー処理 : 提供されたAnimationReferenceAssetを持つアニメーションが見つからない場合は、何もしません(前のアニメーションが通常通り再生されます)。
  • タイムラインの再生開始前に再生されているアニメーションは、最初のクリップの再生が始まるまで中断されません。
  • クリップの終わりやタイムラインの終わりに何が起こるかは、クリップの設定によって異なります。Don't End with Clipがtureの場合、クリップの終わりには何も起こりません。これは、最後のクリップのSetAnimationコールが、AnimationStateで他のコールを発行するまで持続することを意味します。Don't End with Clipがfalseの場合、Clip End Mix Out Durationに設定されたデュレーションで空のアニメーションにミックスアウトされるか、Clip End Mix Out Durationが0より小さい場合は一時停止されます。
  • 編集モードのプレビューミキシングは、再生モードのミキシングとは異なって見える場合があります。実際の結果は、実際のプレイモードで確認してください。複数のトラックを重ねてプレビューする際の正しいトラックの順序についてはSpine AnimationState Trackセクションを参照してください。

Skeleton Flip Track

このトラックタイプは、対象となるSkeletonAnimationまたはSkeletonGraphicのスケルトンを反転させるために使用できます。

Spine Skeleton Flip Clip

パラメーター

  • Flip X : クリップの範囲内で、スケルトンをX軸に沿って反転させます。
  • Flip Y : クリップの範囲内で、スケルトンをY軸に沿って反転させます。

使用方法

  1. SkeletonAnimation GameObjectにはSkeletonAnimationPlayableHandleコンポーネントを、SkeletonGraphicの場合はSkeletonGraphicPlayableHandleを追加します。
  2. すでにUnity Playable Directorがある状態で、Unity Timelineウィンドウで左側の何もないスペースを右クリックし、Spine - Skeleton Flip Trackを選択します。
  3. SkeletonAnimationまたはSkeletonGraphic GameObjectを、新しいSpine Skeleton Flip Trackの空の参照プロパティにドラッグします。
  4. Timelineのドープシートの何もないところで行を右クリックし、Add Spine Skeleton Flip Clipを選択します。
  5. 新しいクリップの開始時間と終了時間を調整し、Inspectorの上部で適切な名前を付け、必要なFlipXおよびFlipYの値を選択します。

このトラックの挙動

  • 指定されたスケルトンのFlip値は、各トラックのデュレーション内のすべてのフレームに適用されます。
  • タイムラインが終了すると、トラックはスケルトンのFlipをそのタイムラインの再生開始時に取得したFlip値に戻します。

既知の問題

  • コンソールで DrivenPropertyManager has failed to register property "m_Script" of object "Spine GameObject (spineboy-pro)" with driver "" because the property doesn't exist. という誤った無害なエラーが記録される可能性があります。これはUnity側の既知の問題です。詳しくはこちらをご覧ください: https://forum.unity.com/threads/default-playables-text-switcher-track-error.502903/

FAQ

インポート関連

"Could not automatically set the AtlasAsset for .." というウィンドウが表示されインポートに失敗するのはなぜですか?

アトラスファイルの拡張子が .atlas ではなく .atlas.txt になっていることを確認してください。詳しくは「初心者のためのSpineからUnityへのエクスポート」をご覧ください。

git UPMパッケージからシーンを開こうとすると "Opening scene in read-only package!" というエラーになるのはなぜですか?

Opening scene in readonly package

残念ながらUnityのバグにより、git URL経由でダウンロードしたパッケージから直接シーンを開こうとすると"Opening scene in read-only package!"というエラーが発生してしまいます。パッケージに含まれているサンプルシーンを開くには、お使いのシステムのファイルマネージャー(エクスプローラーまたはFinder)を使用してシーンファイルをpackageディレクトリからAssetsディレクトリにコピーしてください。

ビジュアル関連

アタッチメントの透明な部分の周りが黒く縁取られてしまうのはなぜですか?

ほとんどの場合、テクスチャを Premultiply alpha (乗算済みアルファ) (PMA)としてエクスポートしているのに、Unityでインポートしたマテリアルやテクスチャの設定が合っていないことが原因です。詳しくは「乗算済み vs ストレートアルファインポート」をご覧ください。また、Linear 色空間を使用している場合、PMAテクスチャはサポートされていないことに注意してください。

アタッチメントの透明な部分にカラフルなストライプが入ってしまうのはなぜですか?

ほとんどの場合、テクスチャをストレートアルファ(Bleed (ブリード))としてエクスポートしているのに、Unityでインポートしたマテリアルやテクスチャの設定が合っていないことが原因です。詳しくは「乗算済み vs ストレートアルファインポート」をご覧ください。

MeshRendererでマテリアルを割り当てることができません。なぜでしょうか?

マテリアルはSkeletonRendererによって毎フレーム制御されています。詳しくはマテリアルセクションをご覧ください。 各インスタンスごと、またはスロットごとにマテリアルを置換したい場合は、「インスタンスごとにマテリアルを変更する」をご覧ください。

同梱されているSpineシェーダーの一部が、私のURPプロジェクトで正しく表示されません。なぜですか?

spine-unityランタイムパッケージはBuilt-In Render Pipeline用のシェーダーのみを提供し、Universal Render Pipelineを使用しているプロジェクトとは互換性がありません。代わりにSpine URP Shaders拡張UPMパッケージで提供されているURP用のシェーダーを使用してください。

URPプロジェクトでアウトラインシェーダーがアウトラインしか表示しません。なぜですか?

以下の2つの原因が考えられます:

  1. Spine/SkeletonまたはSpine/Outline/Skeletonなど、Built-In Render Pipeline用のシェーダをUniversal Render Pipelineプロジェクトで使用している可能性があります。Built-In Render Pipeline用のシェーダーはURPプロジェクトと互換性がありません。代わりにSpine URP Shaders拡張UPMパッケージで提供されているURP用シェーダーを使用してください。

  2. URP用シェーダー、Universal Render Pipeline/Spine/Outline/Skeleton-OutlineOnlyを使用している場合、これはシングルパスシェーダーであるため、アウトラインのみをレンダリングするのは正しい結果です。スケルトン本体のイメージと一緒に描画したい場合は、例えばRenderExistingMeshコンポーネントを使用して、このアウトラインのみのシェーダーでスケルトンメッシュを再レンダリングし、スケルトンの後ろにアウトラインを追加する必要があります。

動作するセットアップ例については、Spine URP Shaders UPMパッケージに含まれているサンプルシーン、com.esotericsoftware.spine.URP-shaders/Examples/Outline Shaders URPを参照してください。

アウトラインシェーダーが、スケルトンの各パーツの周囲に対してアウトラインを表示してしまいます。なぜですか?

スケルトンに複数のマテリアルが必要な場合、付属のアウトラインシェーダーは、スケルトン全体ではなく、各サブメッシュのアウトラインを描画してしまいます。最良の解決策は、単一のマテリアルのみが使用されるようにすることです。これは、アトラスを適宜パッキングするか、ランタイムでの再パッキングによって達成できます。これが不可能な場合は、例えばRenderCombinedMeshコンポーネントを使用して、スケルトンの後ろにアウトラインのみを追加するアウトラインシェーダーで、結合されたスケルトンメッシュを再レンダリングすると良いでしょう。アウトラインのみを描画するシェーダーは、ビルトインレンダーパイプライン用には Spine/Outline/OutlineOnly-ZWrite、URP用には Universal Render Pipeline/Spine/Outline/Skeleton-OutlineOnly が用意されています。

各スロットごとにマテリアルを置換するにはどうすればよいですか?

インスタンスごとにマテリアルを変更する」をご覧ください。

スケルトンにノーマルマップ(法線マップ)を使用してみましたが、見た目がおかしくなってしまいました。なぜですか?

SkeletonRenderer(またはSkeletonAnimation)コンポーネントで Advanced - Solve Tangents が有効になっていることを確認してください。

UIパネルのフェードアウト時に、CanvasGroupのアルファによってSkeletonGraphicが明るく光ってしまうのはなぜですか?

SkeletonGraphicコンポーネント - CanvasGroupアルファ」セクションをご覧ください。

アルファでフェードアウトを行った時にスケルトンの個々のパーツの重なりが透けて見えてしまうのはなぜですか?

これは三角形が重なって描画される時に透明度が適用されてしまうという、レンダリングの一般的な問題です。詳しくは「スケルトンのフェードイン、フェードアウト」セクションをご覧ください。

再パックしたスキンが、エディターでは表示されるのにビルドした実行ファイルでは白いポリゴンで表示されてしまうのはなぜですか?

ランタイムでの再パッキング」セクションの「重要な注意事項」にて、この問題のよくある原因をリストアップしています。

別のマシンで挙動が異なる

git URL経由でUPMパッケージを使用していますが、なぜ2つのマシン間でプロジェクトの動作が異なるのでしょうか?

git URL の末尾が #4.1 などの場合、Unity Package Manager はブランチ 4.1 から最新版をダウンロードすることになります。つまり、プロジェクトに必要なパッケージの初回インストール時にその最新版がダウンロードされるため、先にそのパッケージをダウンロードしたマシンは、他のマシンよりもパッケージの状態が古くなってしまいます。Package Managerで対象のパッケージを選択し、Updateボタンを押して再ダウンロードすれば最新版に更新することができますが、あらかじめこの問題を回避したい場合は、git URLの #4.1 の部分を #5e8e4c21f11603ba1b72c220369d367582783744 のように特定のgitコミットのハッシュに置き換えることで、プロジェクト内の全員が同じ状態のパッケージを一貫して使用できるようにしてください。コミットハッシュを取得する方法は以下をご覧ください。なお、残念ながら #5e8e4c21 のような短いコミットハッシュは Unity Package Manager では機能しないようですのでご注意ください。

Package Manager の git URL に使用する gitコミットハッシュを取得するにはどうすればよいですか?

githubのCommitsページにアクセスし、目的のブランチを選択して、コミットの右側にあるコピーボタン(ツールTipsに「Copy the full SHA」とあるボタン)をクリックすると、コミットハッシュをクリップボードにコピーすることができます。

パフォーマンス関連

スケルトンをインスタンス化すると、fpsが低下したり、GCメモリが割り当てられたりしてしまいます。ローディングを改善するにはどうしたらいいですか?

  1. スケルトンを .json でエクスポートしている場合は、.skel.bytes としてバイナリエクスポートに切り替えることを検討してください。 詳しくはUnity向けのバイナリエクスポートをご覧ください。
  2. ゲームプレイ中にスケルトンprefabをインスタンス化する場合、レベルロード時にスケルトンをロードすることを検討したり、またprefabのインスタンス化と破棄の代わりにオブジェクトのプールを用いることを検討してください。例えば、クリティカルでないレベルロードの時点で10個のインスタンスをロードすることで、プールを事前準備してください。そして新しいオブジェクトをインスタンス化する代わりに有効化して再配置し、破棄の代わりに無効化(およびAnimationStateClearTracks) してください。

1つのスケルトンにたくさんのドローコール/バッチ/マテリアルが表示されるのですが、なぜですか?

複数のアトラスページを使用していたり、スロットのブレンドモードを交互に描画している可能性があります。 詳しくは「マテリアル」セクションおよび「マテリアルの切り替えとドローコール」セクションをご覧ください。 複数のアトラステクスチャからスキンやアタッチメントを組み合わせる場合、アタッチメントを単一のアトラステクスチャに再パックするランタイムでの再パッキングを検討してください(1回の再パック操作にコストがかかります)。

スケルトンのパフォーマンスを向上させるにはどうしたらいいですか?

  1. クリッピングポリゴンの使用はできるだけ避け、代わりにUnityのマスキング機能を使用することを検討してください。どうしてもクリッピングアタッチメントを使用したい場合は、クリッピングポリゴンの頂点をできるだけ少なくしてください。ポリゴンの面積は重要ではなく、頂点数だけが重要なので、例えば長方形の領域をカバーするためには、2つの三角形ではなく1つの大きな三角形を作成することを検討してください。
  2. メッシュ変形キーはなるべく少なくしてください。
  3. 頂点数はなるべく少なくしてください。
  4. 不要なキーを削除してください。
  5. Spineエディターの測定基準ビューに表示されているその他の指標を最適化してください。
  6. アトラステクスチャのページ数はなるべく少なくしてください。
  7. スケルトンごとに複数のマテリアルが必要な場合は、Spineでの表示順序を最適化してマテリアルの切り替え回数を最小限にするか、アトラステクスチャエクスポートを最適化して、表示順序リストで隣り合ったアタッチメントが同じアトラスページテクスチャにグループ化されるようにしてください。 詳しくは「マテリアル」セクションおよび「マテリアルの切り替えとドローコール」セクションをご覧ください。
  8. 可能であれば、1つの大きなアトラステクスチャを複数のスケルトンで共有するようにしてください。異なるスケルトンのSkeletonDataAssetのアトラスアセットの配列で、単一のアトラスアセットを割り当てることができます。 詳しくは、「パッキング」をご覧ください。また、 フォルダ構造を用いたパッキングコマンドラインインターフェースを使用したパッキングも検討すると良いでしょう。