ライセンスについて
Spineランタイムをアプリケーションに組み込むにはSpineライセンスが必要です。
インストール方法
Unityプロジェクトでspine-unityランタイムを使用するには、前提条件として、spine-unityランタイムを追加できるUnityプロジェクトがある必要があります:
- Unityをダウンロードしてインストールします。
- Unity Editorで新しい空のプロジェクトを作成します。
そして作成したUnityプロジェクトにspine-unityランタイムを追加するには、複数のインストール方法があります:
Unitypackageを介したインストール
以下のようにspine-unity unitypackageを使ってspine-unityランタイムをAssetsフォルダにインストールできます。
- spine-unityの最新のUnitypackageをダウンロードします。
- ダウンロードしたUnitypackageをインポートします(ダブルクリックするか、またはUnity内のProjectパネルにドロップしてインポートしてください)。
最新のspine-unityのunitypackageはSpine Unity ダウンロードページで入手できます。
Gitを介したインストール
Unitypackageからインストールする代わりに、以下のようにGit経由で最新の変更点を取得することもできます。
- spine-runtimesのGitリポジトリをクローンします。
spine-runtimes/spine-unity/Assets/
の中身を、作成したプロジェクトのAssets/
フォルダにコピーします。spine-runtimes/spine-csharp/src
フォルダを、作成したプロジェクトのAssets/Spine/Runtime/spine-csharp
フォルダにコピーします。
Package Managerを介したインストール
または、Unity Package Managerを利用してspine-unityランタイムをインストールおよび更新することもできます。
お使いのUnityバージョンが比較的新しく、Unity Package Managerに Add package from git URL...
オプションがある場合、以下のURLから直接3つのパッケージを追加できます:
https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-csharp/src#4.2
https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-unity/Assets/Spine#4.2
https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-unity/Assets/Spine Examples#4.2
最新のUnity Package ManagerのURLも、Spine Unityダウンロードページから入手できます。
Spine Examples
パッケージのサンプルシーンを開くには、packageディレクトリのシーンファイルを、お使いのシステムのファイルマネージャー(エクスプローラーまたはFinder)を使用してAssets
ディレクトリにコピーしてください。残念ながらUnityのバグにより、git URL経由でダウンロードしたパッケージ内のシーンを直接開こうとすると、以下のように"Opening scene in read-only package!"
というエラーが発生してしまいます:
詳細
まず、Unityで Window > Package Manager
から Package Manager
を開きます。 3つのパッケージについてそれぞれ、 +
アイコンから Add package from git URL...
を選択し、上記 (またはダウンロードページから確認できる) git URLを入力します。#4.2
の部分は#5e8e4c21f11603ba1b72c220369d367582783744
のように特定のgitコミットのハッシュを指定すると、プロジェクトに携わる全員が同じパッケージの状態を一貫して保持できます。 すると、Package Manager
ウィンドウに、追加されたパッケージのエントリーが表示されます。 ここまで完了すると Project
パネルで、Packages
の下にspine-unity Runtime
および spine-unity Runtime Examples
の項目が確認できます。 これらの項目が Project
パネルにまだ表示されていない場合は、Unityを一度終了し、再度開いてください。
オプションの拡張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シェーダーを提供しています。
インストール方法
拡張UPMパッケージのインストールには2つの方法があります:
- オプション A - UPMパッケージをダウンロードしてローカルでインストールする方法。
- オプション B - git URLからパッケージを追加する方法。
A - UPMパッケージをダウンロードする
- 使用したいUPMパッケージを、ダウンロードページからダウンロードするか、Gitリポジトリのspine-unity/Modulesサブディレクトリで探してください。
- 次のステップに進む前に、Unityプロジェクトを開いたまま新しい空のシーンを開くなどして、Spineコンポーネントを含むシーンを閉じることをお勧めします。
- 解凍またはクローンを行なった後、以下の2つの方法でパッケージを使用することができます :
- a) プロジェクトにコピーする方法 パッケージの内容を、プロジェクト内の
Packages
ディレクトリにコピーします。するとUnityが自動的にロードを行います。 - b) Package Managerを使用する方法 パッケージの内容を
Assets
ディレクトリ以外の任意の場所にコピーし、UnityのWindow > Package Manager
からPackage Manager
を開き、+
アイコンからAdd package from disk...
を選択し、package.json
ファイルを指定します。 こちらの例では、Package Manager
ウィンドウに、Spine Lightweight RP Shaders
の項目が追加されました : また、Project
パネルでもPackages
以下にSpine Lightweight RP Shaders
の項目が追加されています : 追加した項目がProject
パネルにまだ表示されていない場合は、Unityを一度終了し、再度開いてください。
- a) プロジェクトにコピーする方法 パッケージの内容を、プロジェクト内の
- Spine URP Shaders UPMパッケージのようなUPMパッケージで利用可能なサンプルシーンを追加するには、まずパッケージを選択し、
Samples
そしてImport
を選択してください。
B - git URLからパッケージを追加する
お使いのUnityバージョンが比較的新しく、UnityのPackage Managerに Add package from git URL...
オプションがある場合、git URLを直接使用することが可能です。
重要な注意事項: git URLから
URP Shaders UPM package
をインストールする場合、spine-csharp
およびspine-unity
パッケージも(unitypackageをAssets
フォルダにインストールするのではなく)Unity Package Manager経由でインストールされている必要があります。そうしないと、URP Shaders UPM package
のシェーダーのインクルードパスが存在しないspine-unityパッケージディレクトリを指してしまい、シェーダーコンパイルエラーにつながってしまいます。
- 使用したいUPMパッケージのgit URLをダウンロードページで探してください。
- 次のステップに進む前に、Unityプロジェクトを開いたまま新しい空のシーンを開くなどして、Spineコンポーネントを含むシーンを閉じることをお勧めします。
- Unityの
Window > Package Manager
からPackage Manager
を開き、+
アイコンからAdd package from git URL...
を選択し、 ダウンロードページで確認したgit URLを入力してください。 例:https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-unity/Modules/com.esotericsoftware.spine.urp-shaders#4.2
#4.2
の部分は#5e8e4c21f11603ba1b72c220369d367582783744
のように特定のgitコミットのハッシュを指定すると、プロジェクトに携わる全員が同じパッケージの状態を一貫して保持できます。 こちらの例では、Package Manager
ウィンドウに、Spine Lightweight RP Shaders
の項目が追加されました : また、Project
パネルでもPackages
以下にSpine Lightweight RP Shaders
の項目が追加されています: 追加した項目がProject
パネルにまだ表示されていない場合は、Unityを一度終了し、再度開いてください。 - Spine URP Shaders UPMパッケージのようなUPMパッケージで利用可能なサンプルシーンを追加するには、まずパッケージを選択し、
Samples
そしてImport
を選択してください。
古いUPMパッケージに関する注意事項:
UPMパッケージの古いバージョンでは、通常のパッケージ構造の中にサンプルシーンが直接含まれています。 その場合、パッケージ内のサンプルシーンを開くには、システムのファイルマネージャ(それぞれ エクスプローラーまたはFinder)を使用して、パッケージディレクトリからAssets
ディレクトリにシーンファイルをコピーしてください。git URL経由でダウンロードしたパッケージ内のシーンを直接開こうとすると、残念ながらUnityのバグにより、"Opening scene in read-only package!
というエラーが表示されてしまうので注意してください:
サンプル
spin-unityランタイムのサンプルシーンを見るには :
- Unityをダウンロードしてインストールします。
- Unity Editorで新しい空のプロジェクトを作成します。
- spine-unityの最新のUnitypackageをダウンロードしてインポートします。または、上記のインストール方法セクションで説明したように、GitまたはUnity Package Manager経由でspine-unityをインストールすることもできます。
- Unity Editorでプロジェクトを開き、Projectパネルの
Spine Examples/Getting Started
フォルダにある様々なサンプルシーンを確認します。各サンプルシーンには、実行方法に関するテキスト説明と、表示される内容についての説明があります。
Unityエディターでプロジェクトを開き、Assets -> Open C# Project
を選択することで、サンプルとspine-unityランタイムの両方のC#コードを確認したり、修正することができます。サンプルシーンの詳細については、サンプルシーンセクションを参照してください。
spine-unityランタイムのアップデート
アップグレードガイド
ご自身のプロジェクトで使用しているspine-unityランタイムをアップデートする前に、Spineエディターとランタイムのバージョンの管理に関するガイドを参照してください。
注意: Spine 4.1以前のバージョンからエクスポートされたJsonおよびバイナリ形式のスケルトンデータファイルは、spine-unity 4.2ランタイムでは読み込めません! スケルトンデータファイルをSpine 4.2で再エクスポートする必要があります。
プロジェクトがたくさんある場合は、こちらで説明しているように、プロジェクトファイルのエクスポートを自動化されることをお勧めします。 たとえば、当社では次のスクリプトを使ってすべてのSpineサンプルプロジェクトをエクスポートし、テクスチャアトラスを作成しています : export.sh
spine-unity 3.6 / 3.7 / 3.8 / 4.0/ 4.1から新しいバージョンにアップデートする場合は、以下のアップグレードガイドをご覧ください :
- spine-unity 3.6 to 3.7 Upgrade-Guide
- spine-unity 3.7 to 3.8 Upgrade-Guide
- spine-unity 3.8 から 4.0 へのアップグレードガイド
- spine-unity 4.0 から 4.1 へのアップグレードガイド
- spine-unity 4.1 から 4.2 へのアップグレードガイド
問題を未然に防ぐためにも、以下の手順を実行することを推奨しています :
- Unityのアップデートと同様に、アップデートを実行する前に、Unityプロジェクト全体をバックアップすることを常にお勧めします。
- Spineランタイムをアップデートする前には、必ずリードプログラマーおよびテクニカルアーティストに確認してください。SpineランタイムはSource-availableソフトウェア(ソースが利用可能なソフトウェア)で、プロジェクトの様々なニーズに応じてユーザーが変更できるように設計されています。あなたのプロジェクトのSpineランタイムは、プログラマーによって変更が加えられているかもしれません。この場合、最新のランタイムにアップデートするには、それらの変更点を新しいバージョンのランタイムに再適用する必要があります。
- ダウンロードしたUnitypackageに含まれている、またはgithub上にある
CHANGELOG.md
ファイルをお読みください。メソッドが廃止されて新しいものに置き換えられたときに、必要なドキュメントをここで見つけることができます。
最新のspine-unityランタイムにアップデートしたいことが確認できたら、パッケージをインストールした時の方法に従って spine-unityをアップデートしてください。
Unitypackageを介したアップデート
- 最新のspine-unityランタイムを入手するには、最新のspine-unityパッケージをダウンロードします。また、Gitを使ってspine-runtimesのGitリポジトリから最新の変更点をプルしてアップデートすることもできます(後述)。
- Unity EditorとVisual Studio / Xcodeは閉じてください。
- 3.7から3.8へのアップグレードなど、異なるメジャー/マイナーバージョンへのアップグレードを行う場合は、以前のspine-unityのインストールディレクトリ
Assets/Spine
とAssets/Spine Examples
をプロジェクトから削除してください。 - ここまで出来たら、プロジェクトをUnity Editorで開きます。以前のspine-unityのインストールを削除した場合は、ログに出ているエラーは無視してください。
- Unitypackageをインポートします(ダブルクリックすればUnityが開きます)。
- 異なるメジャーまたはマイナーバージョンにアップグレードする場合は、Projectパネルで
右クリック - Reimport All
を選択して、スケルトンアセットを再インポートします。または、すべてのアセットを再インポートする代わりに、再インポートするSpineスケルトンアセットを含むフォルダをProjectパネルで見つけて、そのフォルダを右クリックしてReimport
を選択しても構いません。
Gitを介したアップデート
- spine-runtimesのGitリポジトリから最新の変更点をプルして、最新のspine-unityランタイムを入手します。
- 3.7から3.8へのアップグレードなど、異なるメジャー/マイナーバージョンへのアップグレード時には、以前のspine-unityのインストールディレクトリ
Assets/Spine
とAssets/Spine Examples
をプロジェクトから削除してください。 spine-runtimes/spine-unity/Assets/
の 内容を、ご自身のプロジェクトのAssets/
フォルダにコピーします。spine-runtimes/spine-csharp/src
フォルダを、ご自身のプロジェクトのAssets/Spine/Runtime/spine-csharp
フォルダにコピーします。
注意: spine-unityランタイムは、汎用spine-csharpランタイムをベースにしています。そのため、spine-unityとspine-csharpの両方のランタイムの変更点をGitHubで確認してください。
Unity Package Managerを介したアップデート
spine-unity ランタイムをリモートの git URL から Add package from git URL
でパッケージとして追加した場合、UnityのPackage Managerを使用してそのパッケージを更新することができます。
Unityで Window > Package Manager
から Package Manager
を開き、 以下のパッケージをそれぞれ選択してください
spine-csharp Runtime
spine-unity Runtime
spine-unity Runtime Examples
そして Update
ボタンを押すと、gitから指定されたブランチの最新版が再ダウンロードされます。
例えば https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-csharp/src#4.2
のようにURLの末尾が #4.2
の場合、gitリポジトリの4.2
ブランチから最新版を再ダウンロードすることになります。
拡張UPMパッケージのアップデート
オプションの拡張UPMパッケージをアップグレードする場合 :
- spine-unityランタイムのアップデートと同じ原則が適用されます。
- 前述の通り、アップデートを行う前には必ずUnityプロジェクト全体をバックアップすることをお勧めします。
インストールオプションに続いて、パッケージのアップデートにも2つのオプションがあります:
A - インプレース・アップデート
- Unityプロジェクトを開いている場合は a) Unityを終了する または b) (新しい空のシーンを開くなどして)Spineコンポーネントを含むシーンを閉じる ことをお勧めします。
- 新しいUPMパッケージのzipファイルまたはgitディレクトリの中身を既存のものにコピーします。このディレクトリは、ご自身でUPMパッケージをどのようにインストールしたかによって、プロジェクトの
project_root/Packages/package_name
ディレクトリか、Add package from disk..
でロードしたAssets
ディレクトリの外の任意のディレクトリになっています。 - Unityを終了した場合は、再度Unityでプロジェクトを開きます。
- Unityが新しいアセットをインポートし、ローディングのプログレスバーを表示します。
B - Add package from git URL
パッケージをリモートの git URL から Add package from git URL
で追加した場合、UnityのPackage Managerを使用してそのパッケージを更新することができます。UnityのWindow > Package Manager
から Package Manager
を開き、 更新したいパッケージを選択して、Update
ボタンを押すと、gitから指定されたブランチの最新版が再ダウンロードされます。https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-unity/Modules/com.esotericsoftware.spine.timeline#4.2
のようにURLの末尾が #4.2
の場合、gitリポジトリの 4.2
ブランチから最新版を再ダウンロードすることになります。