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フォルダにコピーします。

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シェーダーを提供しています。

インストール方法

  1. ダウンロードページから使用したいUPMパッケージをダウンロードするか、Gitリポジトリのspine-unity/Modulesサブディレクトリでお探しください。
  2. すでにご自身のUnityプロジェクトを開いている場合は、次のいずれかを行うことを推奨します
    • a) Unityを終了する。
    • b) (新しい空のシーンを開くなどして)Spineコンポーネントを含むシーンを閉じる。

  3. 解凍またはクローンを行なった後、以下の2つの方法でパッケージを使用することができます :
    • a) 自身のプロジェクトにコピーする方法
      パッケージの内容を、プロジェクト内のPackagesディレクトリにコピーします。するとUnityが自動的に読み込みを行います。
    • b) Package Managerを使用する方法
      パッケージの内容をAssetsディレクトリ以外の場所にコピーし、UnityのPackage Manager(Window > 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パネルのPackagesSpine 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フォルダにコピーします。

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

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

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

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

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

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

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

  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で確認してください。

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

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

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

インプレース・アップデート (.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が新しいアセットをインポートし、ローディングのプログレスバーを表示します。

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を選択してください。

  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を使用してください。

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

一般的には、サブメッシュの追加によるドローコールの数を減らすために、単一のテクスチャ(単一ページ)のアトラスを使用することをお勧めします。これは特にSkeletonGraphicに当てはまります。使用しているUnityのCanvasRendererの制限により、SkeletonGraphicの使用はデフォルトで単一テクスチャに制限されています。SkeletonGraphicのInspectorでAdvanced - Multiple CanvasRenderersを有効にすると、サブメッシュごとに子CanvasRendererGameObjectを生成して、テクスチャの制限枚数を増やすことができます。しかしパフォーマンス上の理由から、これは可能な限り避けた方がよいでしょう。つまり、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 パラメーターの設定に従って、新しいアトラステクスチャがインポートされた際にテクスチャとマテリアルの設定が自動的に適用されます。

Spine Preferences - Atlas Texture Settings Spine Preferences PMA Preset Selection

SpineからPremultiply alpha(乗算済みアルファ)を有効(デフォルト)にしてアトラステクスチャをエクスポートしている場合、このパラメーターはPMATexturePresetのままで問題ありません。もしPremultiply alphaを無効にしている場合は、StraightAlphaTexturePresetに設定してください。または独自のTextureImporter``Presetアセットを自作して、ここに割り当てることもできます。

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

テクスチャパッカーの正しいエクスポート設定およびテクスチャとマテリアルの正しいインポート設定
  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として使用するようにしてください。また、ランタイムで単一のアタッチメントからSpineのスプライトアトラスを再パックすることができることも考慮してください。

.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
    • Default Slot Z-Spacing : 新しくインスタンス化されたSkeletonRendererまたはSkeletonGraphicコンポーネントのデフォルトのZ Spacingパラメータを設定します。
    • Default Loop : 新しくインスタンス化されたSkeletonRendererまたはSkeletonGraphicコンポーネントのデフォルトのLoopパラメータを設定します。
  • Mecanim Bake Settings
    • Include Folder Name in Event : 有効にすると、Mecanimのイベントは"FolderNameEventName"という名前のメソッドを呼び出し、無効にすると、"EventName"を呼び出します。
  • Handles and Gizmos
    • Editor Bone Scale : Sceneビューで表示されるボーンや同様のギズモ要素のサイズを設定します。
  • Timeline Extension - Timeline拡張UPMパッケージに関連する項目
    • Use Blend Duration : 新しく作成したSpine Animation State ClipsのデフォルトのUse Blend Durationパラメータを設定します。

Spineアセットの更新

開発中、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エディターでプレビューされた通りに表示されるかは保証されません。

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 : ここでタイムスケールを設定することで、アニメーションの再生を遅くしたり、速くしたりすることができます。

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

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

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

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

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

  • Initial Flip X、Initial Flip Y : これらのパラメーターは、スタート時にスケルトンを水平または垂直方向に反転させることができます。これにより、反転した部分のScaleXScaleY-1になります。
  • 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への参照は失われます。
  • Separator Slot Names : レンダリングを分割する場所を決めるスロットを設定します。これはSkeletonRenderSeparatorなどのコンポーネントで使用され、スケルトンを異なるGameObject上に2つの別々のレンダラーでレンダリングすることができます。
  • Z-Spacing : この設定を変更すると、アタッチメントがスケルトンレンダラーコンポーネントによって、x/y平面上で前後にレンダリングされるようになります。各アタッチメントが、z軸上のカスタマイズ可能なz-spacing値によってオフセットされ、Zファイティング(z-fighting)を回避します。

  • PMA Vertex Colors : 頂点カラーRGBと頂点カラーアルファを乗算します。レンダリングに使用されているシェーダーがSpineシェーダー(ストレートアルファテクスチャを使用している場合も)またはPMAの加法的ブレンドモード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 : 一部のライトシェーダーは、通常、ノーマルマップ(法線マップ)を適用するために、頂点接線を必要とします。有効にすると、毎フレームで接線が計算され、出力メッシュに追加されます。
  • 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のコードでカスタムコンストレイントを実装するのに便利です。
  • OnMeshAndMaterialsUpdatedは、Meshとすべてのマテリアルがアップデートされた後、LateUpdate()の最後に発生します。

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;
}

別の方法として、スクリプトの実行順序を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;
   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 Property Attributesです。

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

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

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();
ランタイムでの再パッキング

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

C#
using Spine.Unity.AttachmentTools;

// Create a repacked skin.
Skin repackedSkin = collectedSkin.GetRepackedSkin("Repacked skin", skeletonAnimation.SkeletonDataAsset.atlasAssets[0].PrimaryMaterial, out runtimeMaterial, out runtimeAtlas);
collectedSkin.Clear();

// Use the repacked skin.
skeletonAnimation.Skeleton.Skin = repackedSkin;
skeletonAnimation.Skeleton.SetSlotsToSetupPose();
skeletonAnimation.AnimationState.Apply(skeletonAnimation.Skeleton);

// You can optionally clear the cache after multiple repack operations.
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);

// Use the repacked skin.
skeletonAnimation.Skeleton.Skin = repackedSkin;
skeletonAnimation.Skeleton.SetSlotsToSetupPose();
skeletonAnimation.AnimationState.Apply(skeletonAnimation.Skeleton);

注意: 通常、ノーマルマップ(法線マップ)のプロパティは"_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; // toggle flip x state

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

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

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を公開しています。このセクションでは、トラック、トラックエントリ、ミックスタイム、アニメーションのキューイングなどの概念について、全般的な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を受け取り、この特定のアニメーションの再生をさらにカスタマイズしたり、トラックエントリ固有のイベントのデリゲートにバインドしたりすることができます。詳しくは後述の「AnimationStateイベントの処理」をご覧ください。

注意: 返されたトラックエントリは、対応するアニメーションが基礎となるアニメーションステートから削除されるまでのみ有効です。Unityのガベージコレクターが自動的にこれらを解放します。トラックエントリの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;

   // registering for events raised by any animation
   animationState.Start += OnSpineAnimationStart;
   animationState.Interrupt += OnSpineAnimationInterrupt;
   animationState.End += OnSpineAnimationEnd;
   animationState.Dispose += OnSpineAnimationDispose;
   animationState.Complete += OnSpineAnimationComplete;

   animationState.Event += OnUserDefinedEvent;

   // registering for events raised by a single animation track entry
   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) {
   // Add your implementation code here to react to start events
}
public void OnSpineAnimationInterrupt(TrackEntry trackEntry) {
   // Add your implementation code here to react to interrupt events
}
public void OnSpineAnimationEnd(TrackEntry trackEntry) {
   // Add your implementation code here to react to end events
}
public void OnSpineAnimationDispose(TrackEntry trackEntry) {
   // Add your implementation code here to react to dispose events
}
public void OnSpineAnimationComplete(TrackEntry trackEntry) {
   // Add your implementation code here to react to complete events
}


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

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

   if (e.Data.Name == targetEventName) {
      // Add your implementation code here to react to user defined event
   }
}

// you can cache event data to save the string comparison
Spine.EventData targetEventData;
void Start () {
   targetEventData = skeletonAnimation.Skeleton.Data.FindEvent(targetEventName);
}
public void OnUserDefinedEvent(Spine.TrackEntry trackEntry, Spine.Event e) {

   if (e.Data == targetEventData) {
      // Add your implementation code here to react to user defined event
   }
}

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

コルーチンの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セクションを参照してください。

必要になる追加のキー

1つのアニメーションから次のアニメーションへとタイムラインの状態(ボーンの回転など)をスムーズにミックスアウトさせるために、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を提供しています。

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

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

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

パラメーター

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

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

  • Unscaled Time : trueに設定すると、アップデートはTime.deltaTimeではなくTime.unscaledDeltaTimeに従って実行されます。これは、UI要素をスローモーション効果とは無関係にアニメーションさせたい場合に便利です。

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

  • 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 GameObjecttを自動的に作成します。これにより、単一テクスチャの制限を緩和することができますが、パフォーマンスのオーバーヘッド(処理負荷)が発生します。

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

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

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

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

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

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

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

サンプルシーン

基本的な使用方法については、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によって与えられる物理演算が動きに適用されます。
  • Rigidbody : Rigidbodyが割り当てられると、TransformコンポーネントではなくRigidbodyによって与えられる物理演算が動きに適用されます。

補足: 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は、親ボーンオブジェクトを持たない単一の独立したゲームオブジェクトとして使用できます。

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

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

PointFollower

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

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

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パネルのSkeletonUtilityBoneGameObjectの横には、以下のよう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 ParentGameObjectがシーンの最上位に配置されます。前述のように、この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 ParentGameObjectがシーンの最上位に配置されます。前述のように、このGameObjectはスケルトンに対して再び親子付けしないでください! Hinge Chain 2D Hierarchy
  4. チェーン要素のRigidbody2DのDrag(空気抵抗)とMass(質量)のパラメーターを調整して、結果を微調整してください。

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

SkeletonUtility

SkeletonUtilityBonesの階層の作成

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

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

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

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

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

注意: SkeletonUtilityBoneのInspectorを使って、後からでもSkeletonUtilityBoneGameObjectを追加することができ、Spawn Hierarchy機能が大まかな出発点となります。また、必要のないSkeletonUtilityBoneGameObjectを削除して、リソースを節約することもできます。ただし、親はそのままにしておく必要があるので、階層の途中で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

例えば、キャラクターが木にぶつかった時に、足を前に1本、幹の後ろに1本表示するなど、キャラクターのパーツの間に他のゲームオブジェクトを表示したい場合があります。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でソートのプロパティを設定することができます。値が大きいほどレンダラーが前面に移動します。

補足: SkeletonPartsRendererGameObjectは、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シェーダーのリストをご紹介します。

注意: ディファードシェーディングレンダリングパスは、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(加算)ブレンドモードをサポートします。

    以下の追加の設定ステップが必要です(ティントカラーの頂点データの場合): a. SkeletonAnimation](/spine-unity#SkeletonAnimationコンポーネント)のInspectorのAdvancedセクションでTint Blackを有効にします。 b. SkeletonGraphicのMaterialを、Spine/Runtime/spine-unity/Materialsフォルダ内のSkeletonGraphicTintBlackマテリアルに設定します。 c. 親キャンバスを選択し、Additional Shader ChannelsTexCoord1TexCoord2を有効にしてください。

    CanvasGroupでのAdditive(加算)ブレンドモードのためには以下の追加手順が必要です: a. SkeletonGraphicのInspectorのAdvancedセクションでCanvas Group Tint Blackを有効にします。 b. シェーダーでCanvasGroup Compatibleを有効にしてください。

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

  11. Spine/Special a. Spine/Special/Skeleton Grayscale
    Intensityをカスタマイズできるグレースケールレンダリング用のUnlit透明シェーダーです。Zバッファ(深度バッファ)への書き込みは行いません。 b. Spine/Special/Skeleton Ghost
    SkeletonGhostコンポーネントがトレイルレンダリングに使用する特別なシェーダーです。

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

  13. Spine/Outline
    上記のすべてのシェーダーにはOutlineパラメーターがあり、これを有効にすると、それぞれのSpine/Outlineシェーダーのバリエーションに切り替わり、スケルトンの周囲に追加のカラーアウトラインが描画されるようになります。 Spine/OutlineシェーダーのデモはサンプルシーンのSpine Examples/Other Examples/Outline Shadersでご覧いただけます。
    a. Spine/Outline/OutlineOnly-ZWrite
    アウトラインのみをレンダリングする特殊な2パスシェーダーです。アタッチメントが重なった時にアウトラインのオクルージョンを適切に処理するために、Zバッファ(深度バッファ)への書き込みを行います。

URP Shaders - 拡張UPMパッケージ

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

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

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

  1. Universal Render Pipeline/2D/Spine/Skeleton Lit
    Spine/Skeleton Litシェーダーのユニバーサル2D Rendererバージョンです。
  2. Universal Render Pipeline/2D/Spine/Sprite
    Spine/Sprite/Vertex LitおよびPixel Litシェーダーのユニバーサル2D Rendererバージョンです。
  3. Universal Render Pipeline/Spine/Skeleton
    Spine/Skeletonシェーダーのユニバーサルバージョンです。
  4. Universal Render Pipeline/Spine/Skeleton Lit
    Spine/Skeleton Litシェーダーのユニバーサルバージョンです。
  5. Universal Render Pipeline/Spine/Sprite
    Spine/Sprite/Vertex LitおよびPixel Litシェーダーのユニバーサルバージョンです。
  6. Universal Render Pipeline/Spine/Outline/Skeleton-OutlineOnly
    Spine/Outlineシェーダーのユニバーサルバージョンです。URPはシェーダーごとに複数のパスを許可していないため、別のマテリアルが必要になります。本パッケージに含まれるサンプルシーンOutline Shaders URPで紹介している通り、RenderExistingMeshコンポーネントを検討した方が良いかもしれません。

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

URPシェーダーのデモは、解凍されたパッケージの中のサンプルシーンcom.esotericsoftware.spine.URP-shaders-3.8/Examples/URP Shaders.unityで確認できます。

LWRP Shaders - 拡張UPMパッケージ

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

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

  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-3.8/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:47)

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

    hlsl
    return (texColor * i.vertexColor);

    (Spine-Skeleton.shader:71)

    そのため、シェーダーで適切な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:111)

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

  • Materialプロパティ:

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

マテリアル

MeshRendererのMaterials配列は、現在割り当てられているアタッチメントと、それらが含まれているAtlasAssetsに応じて、毎フレームごとにSkeletonRendererによって管理されます。

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

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

マテリアル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とCustomSlotMaterial

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

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

C#
skeletonAnimation.CustomMaterialOverride[originalMaterial] = newMaterial; // to enable the replacement.
skeletonAnimation.CustomMaterialOverride.Remove(originalMaterial); // to disable that replacement.

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

C#
skeletonAnimation.CustomSlotMaterial[slot] = newMaterial; // to enable the replacement.
skeletonAnimation.CustomSlotMaterial.Remove(slot); // to disable that replacement.
バッチングを維持しながらスケルトンをティント(着色)する

スケルトンインスタンスに異なるMaterialsMaterialProeprtyBlocksを使用すると、バッチングが発生します。個々のスケルトンインスタンスを異なる方法でティント(着色)したいだけで、他のマテリアルプロパティを変更する必要が無い場合は、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)のどちらを使用するかを設定できます

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

Sorting LayerとOrder in Layer

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

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

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のコンテンツを希望のフェード不透明度でシーンに描画することができます。

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

サンプルコンポーネント

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

SkeletonRagdoll

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

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

SkeletonGhost

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

SkeletonUtilityKinematicShadow

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

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

RenderExistingMesh

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

サンプルシーン

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

初めて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コンポーネントのサンプルスクリプトは、spineboy GameObjectにアタッチされているので、確認することができます。SkeletonAnimation.AnimationState.SetAnimation()SkeletonAnimation.AnimationState.AddAnimation()の使い方を説明しています。 また、soundGameObjectにアタッチされたスクリプトHandleEventWithAudioExampleは、SkeletonAnimation.AnimationState.Eventに登録することで、独自のイベントメソッドのコールバックをフックする方法を示している。

3 Controlling Animation Continued

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

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

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

4 Object Oriented Sample

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

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

PLAYER INPUT GameObjectにアタッチされたサンプルスクリプトSpineboyBeginnerInputをご覧ください。これはcontrollerとしての役割を持っています。PLAYER Spineboy GameObjectにアタッチされたSpineboyBeginnerModelコンポーネントが表現するモデルの状態を変更します。SpineboyBeginnerViewコンポーネントは、VIEW Spineboy GameObjectにアタッチされており、viewとして機能します。また、同じGameObjectにアタッチされているSkeletonAnimationコンポーネントで、それぞれのアニメーションを開始します。

5 Basic Platformer

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

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

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

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

6 SkeletonGraphic

このシーンでは、SkeletonGraphicコンポーネントと、それを既存のUnityのUIにどのように統合できるかを示しています。また、BoneFollowerGraphicコンポーネントを使って、ボーンの位置をフォローするためにテキストラベルをアタッチする方法も紹介しています。これらのコンポーネントは、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を提供しています:

  • Spine AnimationState Track SkeletonAnimation用)
  • Spine AnimationState Graphic Track SkeletonGraphic用)
  • Spine Skeleton Flip Track SkeletonAnimationおよびSkeletonGraphicの両方用)

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

Spine AnimationState Track

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

パラメーター

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

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

Spine Animation State Clip

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

パラメーター
Clip Timing

  • Clip In : このアニメーションを再生する際に適用される初期のローカル開始時間のオフセット。クリップの左端をドラッグして調整することもできます。
  • Blend In Duration : Use Blend DurationCustom 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

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

無視されるパラメーター

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

使用方法

  1. SkeletonAnimation GameObjectにSkeletonAnimationPlayableHandleコンポーネントを、またはSkeletonGraphicの場合にはSkeletonGraphicPlayableHandleを追加します。
  2. 既存のUnity Playable Directorがある状態で、Unity Timelineウィンドウで左側の何もないスペースを右クリックしてSpine.Unity.Playables - Spine Animation State 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セクションを参照してください。

Spine 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.Unity.Playables - Spine Skeleton Flip Trackを選択します。
  3. SkeletonAnimationまたはSkeletonGraphic GameObjectを、新しいSpine Skeleton Flip Trackの空の参照プロパティにドラッグします。
  4. タイムラインのドープシートの何もないところで行を右クリックし、Add Spine Skeleton Flip Clip 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/