28 KiB
spine-unity 4.3 分離コンポーネントへのアップグレードガイド
コンポーネントアーキテクチャの再構築
📋 本ドキュメントの対象範囲
本ドキュメントでは、spine-unityにおける分離コンポーネントへの移行のみを扱います。 バージョン 4.2 から 4.3 への変更では、分離コンポーネント関係以外にも、spine-csharp および spine-unity の両方で破壊的変更が加えられています。分離コンポーネントへの対応を行う前に、先に以下を処理する必要があります：
- spine-csharp API の変更： ボーン、スロット、コンストレイントのプロパティに影響を与える新しいポーズシステム
4.2 から 4.3 へのすべての変更を網羅する完全な移行手順については、以下を参照してください：
- CHANGELOG.md ドキュメント（「C#」および「Unity」セクション）
- フォーラム投稿 "Spine-Unity 4.2 to 4.3 Upgrade Guide" (こちらは包括的な移行ガイドです)
重要： spine-csharp API の移行を最初に完了してから、本ドキュメントで説明されている分離コンポーネントへの移行に進んでください。
⚠️ 重要：アップグレード前の必読事項
この警告は、アップグレードを行う既存のプロジェクトのみに適用されます。新規プロジェクトの場合はこのセクションを安全に無視できます。
何が起こるか
以下のコンポーネントが自動的にアップグレードされ、アニメーションコンポーネントとレンダリングコンポーネントに分離されます：
SkeletonAnimation→SkeletonAnimation+SkeletonRendererコンポーネントSkeletonMecanim→SkeletonMecanim+SkeletonRendererコンポーネントSkeletonGraphic→SkeletonAnimation+SkeletonGraphicコンポーネント
すべてのコンポーネント設定とフィールドは自動的に転送されますので、それらが失われることはありません。
ただし： 今回の型の変更により、コンポーネントタイプが一致しなくなるため、カスタムスクリプトの既存の参照が失われる可能性があります（例えば、SkeletonAnimation はもはや SkeletonRenderer のサブクラスではなくなっています）。
必要なアップグレード手順（上から順番に行ってください）：
-
🔒 プロジェクトのバックアップを作成する
アップグレード前に完全なバックアップを作成してください。これらの変更によって、シーンとプレハブが変更されることになります。 -
📖 このドキュメント全文を読む
続行する前にすべての破壊的変更の内容を把握してください。 -
✏️ コードのテストと更新を行う
- スクリプトを更新する： このドキュメントに従って、Spineコンポーネントを参照するカスタムスクリプトを修正してください。メンバーが分離されたクラスに移動されると、コードがコンパイルできなくなる可能性があります。
- テストを行う： いくつかのテストシーンを開いてみて、どのコンポーネント参照が失われるかを確認してください。未保存のシーンには古いコンポーネントデータが含まれており、セーフティバックアップとして機能します。保存すると、分離されたコンポーネントが古いものを置き換え、参照が失われます。
⚠️ 警告： プレハブの場合は動作が異なります！「Prefab Edit Mode」でプレハブを開くと、Unityのプレハブ自動保存機能により、コンポーネントの移行が自動的に保存されてしまいます。まずはシーンでテストし、プレハブでテストしないようにしてください。 - 対応を決める： 失われた参照を手動で再割り当てするか、移行コードを記述して自動的に処理してください(詳しくは後述)。
⚠️ 重要な注意事項： 自動コンポーネント分離は、Unityエディターでシーン/プレハブが開かれたときにのみ発生します。ゲームをビルドする前に必ず、
Upgrade Allを選択するか、各シーン/プレハブを保存してください。そうしないと、古い単一コンポーネントが分離されず、ビルドで必要なコンポーネントの半分が欠落してしまう可能性があります！💡 ヒント： Consoleログに「SendMessage cannot be called during Awake, CheckConsistency, or OnValidate」という出力が表示された場合、これは古い未移行のアセットがシーンに存在し、自動アップグレードされたことを示しています。これらのメッセージの後に、古いコンポーネントが分離コンポーネントに自動移行されたことを確認するログメッセージが続きます。
-
🔄 アップグレード方法を選択する
オプション A - 手動再割り当て（小規模プロジェクトの場合に推奨）：
- 各シーンとプレハブを個別に開く
- インスペクターで失われた参照を手動で再割り当てする
- 問題が起きていないことを確認したら保存
オプション B - 自動移行（多数のシーン/プレハブを持つ大規模プロジェクトの場合）：
- 最初に移行コードを記述：
- 参照移行パターンを実装（後述の「コンポーネント参照の損失を防ぐには」セクションを参照してください）
SkeletonGraphic参照については、「既存の参照を SkeletonAnimation に変更」セクションを参照してください
- いくつかのファイルで移行コードをテスト
- その後
Upgrade Allを使用：Edit → Preferences → Spineに移動Upgrade Scenes & Prefabsの下でUpgrade Allボタンをクリック
準備しないと何が壊れるか：
- シーンまたはプレハブを保存すると、シーンまたはプレハブ内のコンポーネント参照が失われる可能性があります（null に設定されます）
- すべてのシーン/プレハブをアップグレードする前にビルドしてしまうと、ビルドでコンポーネントが欠落します
ステップ 1-3 を完了せずに続行しないでください。プロジェクトが壊れるリスクがあります。
📦 (任意)4.2 からの2ステップ移行
spine-unity 4.2から移行する場合、潜在的な問題を分離するために2ステップでアップグレードする方が簡単な場合があります：
ステップ 1：コンポーネント分離前の4.3-betaバージョンへアップグレードする
まず、コンポーネント分離の変更が加わる前の4.3-betaバージョンにアップグレードしてください：
- コミットハッシュ:
a07b1de - Git URL でパッケージを追加:
https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-csharp/src#a07b1de - または unitypackage を利用: https://esotericsoftware.com/files/runtimes/unity/spine-unity-4.2-2025-09-26.unitypackage
この中間ステップで、次の作業を行ってください：
- 4.2 → 4.3 spine-csharp API 変更に関連する問題を修正し、プロジェクトが正常に動作することを確認してください
- 続行する前にプロジェクトが安定していることを検証してください
- この 4.3-beta バージョンでプロジェクトが正常に動作したら、ステップ2に進む前に別のバックアップを作成してください
ステップ 2：最新の4.3-betaバージョン（分離コンポーネントに対応したバージョン）へアップグレードする
4.3-betaでプロジェクトが正常に動作したら：
- 最新の4.3-betaパッケージにアップグレードしてください
- 先述のコンポーネント分離移行ガイドに従ってください
- 分離されたアニメーションコンポーネントとレンダリングコンポーネントを処理してください
この2ステップアプローチは、問題の原因を分離するのに役立ちます。つまり、何か問題が発生した場合に、それが 4.2 → 4.3 spine-csharp の変更によるものか、コンポーネント分離によるものかを判断できます。
📋 概要
spine-unity 4.3 ランタイムでは、大きなアーキテクチャ変更として、コンポーネント継承ではなく、2つの独立したコンポーネントでアニメーションとレンダリングを分離する仕組みが導入されました。これにより、以前は不可能だった SkeletonMecanim をアニメーションに、SkeletonGraphic をレンダリングに使用するなどの柔軟な組み合わせが可能になりました。
主な変更点：
- コンポーネント分離: 以前の一体型コンポーネントが、レンダリングとアニメーションでそれぞれ別のコンポーネントに分離されました。
- 個別のコンポーネント:
SkeletonAnimationとSkeletonMecanimはSkeletonRendererから継承されなくなり、SkeletonRendererやSkeletonGraphicなどの個別のレンダラーコンポーネント（ISkeletonRendererのサブクラス）と連携して動作します。 - インターフェースの更新: プロパティ名が更新された新しい
ISkeletonRendererおよびISkeletonAnimationインターフェース。 - 設定のグループ化: メッシュ生成設定が
MeshSettingsプロパティにまとめられました。 - 自動移行:
AUTO_UPGRADE_TO_43_COMPONENTSが定義されている場合（デフォルト）、Unityエディターがコンポーネントを新しい分離コンポーネントに自動アップグレードし、古いフィールドを移行します。 - すべてのシーンとプレハブをアップグレード: すべてのシーンとプレハブを一度にアップグレードするには、
Edit - Preferences - Spineに移動し、Automatic Component Upgradeの下のUpgrade Scenes & Prefabs-Upgrade Allをクリックします。
コンポーネントの関係：
| 旧アーキテクチャ | 新アーキテクチャ |
|---|---|
SkeletonAnimation は SkeletonRenderer から継承 |
SkeletonAnimation + 個別の SkeletonRenderer コンポーネント |
SkeletonMecanim は SkeletonRenderer から継承 |
SkeletonMecanim + 個別の SkeletonRenderer コンポーネント |
SkeletonGraphic は埋め込み AnimationState を提供 |
SkeletonGraphic + 個別の SkeletonAnimation コンポーネント |
コードの適応
各コンポーネントの変更点：
▶️ SkeletonRenderer
破壊的変更
1. インターフェースの変更
IHasSkeletonRendererインターフェースのプロパティ名がSkeletonRendererからRendererに、型がSkeletonRendererからISkeletonRendererに変更されました。
2. イベントの変更
SkeletonRendererDelegate型はSkeletonRendererのネストされた型ではなくなりました。 コンパイルエラーを修正するには、SkeletonRenderer.SkeletonRendererDelegateをSkeletonRendererDelegateに置き換えてください。BeforeApplyデリゲート型がSkeletonRendererDelegateからSkeletonAnimationDelegateに変更されました。SkeletonRendererDelegate型がSkeletonRendererDelegate(SkeletonRenderer)からSkeletonRendererDelegate(ISkeletonRenderer)に変更されました。これはOnRebuildおよびOnMeshAndMaterialsUpdatedイベントに影響します。 コンパイルエラーを修正するには、メソッドパラメータをSkeletonRendererからISkeletonRendererに変更してください。- ボーンイベント
UpdateLocal、UpdateWorld、UpdateCompleteをISkeletonAnimationクラス（SkeletonAnimation、SkeletonMecanim）からISkeletonRendererクラス（SkeletonRenderer、SkeletonGraphic）に移動しました。デリゲート型をUpdateBonesDelegateからSkeletonRendererDelegateに変更し、パラメータをISkeletonAnimationからISkeletonRendererに変更しました。
2. メソッドの変更
LateUpdateMesh()がUpdateMesh()に変更されました。MeshGenerator.TryReplaceMaterialsを削除しました。
3. 実行順序
SkeletonRendererとSkeletonGraphicコンポーネントはDefaultExecutionOrder(1)]を受け取り、デフォルト*（order=0）*スクリプトの後に実行されます。これにより、UpdateTimingがInLateUpdateに設定されていても、スケルトンが更新される前にアニメーションが適用されます。
4. 動作の変更
singleSubmeshが有効な場合、generateMeshOverrideも呼び出されるようになりました。
フィールドとプロパティの移行
メッシュ生成設定
| 旧 API | 新 API | 備考 |
|---|---|---|
skeletonRenderer.zSpacing |
skeletonRenderer.MeshSettings.zSpacing |
MeshSettings に移動 |
skeletonRenderer.useClipping |
skeletonRenderer.MeshSettings.useClipping |
MeshSettings に移動 |
skeletonRenderer.immutableTriangles |
skeletonRenderer.MeshSettings.immutableTriangles |
MeshSettings に移動 |
skeletonRenderer.pmaVertexColors |
skeletonRenderer.MeshSettings.pmaVertexColors |
MeshSettings に移動 |
skeletonRenderer.tintBlack |
skeletonRenderer.MeshSettings.tintBlack |
MeshSettings に移動 |
skeletonRenderer.addNormals |
skeletonRenderer.MeshSettings.addNormals |
MeshSettings に移動 |
skeletonRenderer.calculateTangents |
skeletonRenderer.MeshSettings.calculateTangents |
MeshSettings に移動 |
非推奨の小文字属性
- 小文字の属性
initialFlipX、initialFlipY、initialSkinNameは非推奨となりました。将来のランタイムバージョンで削除される予定です。代わりに同じ名前の大文字のプロパティ、InitialFlipX、InitialFlipY、InitialSkinNameを使用してください。
▶️ SkeletonAnimation
破壊的変更
1. コンポーネントアーキテクチャ
- SkeletonAnimation は SkeletonRenderer とは別のコンポーネントになりました、もはやサブクラスではありません。
- レンダラーにアクセスしたい場合は
skeletonAnimation.Rendererを使用してください。 - レンダラーからアニメーションにアクセスしたい場合は
skeletonRenderer.Animationを使用してください。
2. プロパティの変更
stateはパブリックではなくなりました。代わりにAnimationStateプロパティを使用します。validは削除されました。代わりにIsValidを使用します。
3. メソッドの変更
UpdateOncePerFrame()を追加 - このフレームでUpdateが呼び出されていない場合に更新します。既存のUpdate(float time)は呼び出されると常に更新します。- パラメータなしの
Update()はパブリックではなくなりました。このフレームで更新が実行されていない場合はUpdateOncePerFrame()を使用し、 アニメーションの更新を強制する場合はUpdate(0)を使用します。
フィールドとプロパティの移行
SkeletonAnimation は独立したコンポーネントになったため、SkeletonRenderer が提供するメソッドとプロパティは SkeletonAnimation オブジェクトから直接アクセスできなくなりました。SkeletonAnimation オブジェクトから対応する ISkeletonRenderer にアクセスしたい場合は、skeletonAnimation.Renderer プロパティを使用してください。
また、SkeletonRenderer や SkeletonGraphic オブジェクトから関連する ISkeletonAnimation にアクセスしたい場合は、skeletonRenderer.Animation プロパティうを使用してください。
ISkeletonRenderer インターフェースで公開されていないメンバーにアクセスする必要がある場合は、skeletonAnimation.Renderer を SkeletonRenderer または SkeletonGraphic にキャストしてレンダラーメンバー変数にアクセスできます。
コード例
// 旧式の SkeletonAnimation から SkeletonRenderer プロパティへのアクセス方法
skeletonAnimation.zSpacing = 0.1f;
skeletonAnimation.AnySkeletonRendererProperty;
// 新しくなった SkeletonAnimation から SkeletonRenderer プロパティへのアクセス方法
skeletonAnimation.Renderer.MeshSettings.zSpacing = 0.1f; // ISkeletonRenderer インターフェースで公開
var skeletonRenderer = (SkeletonRenderer)skeletonAnimation.Renderer;
skeletonRenderer.AnySkeletonRendererProperty; // ISkeletonRenderer インターフェースで公開されていない
▶️ SkeletonMecanim
破壊的変更
1. コンポーネントアーキテクチャ
- SkeletonMecanim は SkeletonRenderer とは別のコンポーネントになりました、もはやサブクラスではありません。
- アクセスパターンはSkeletonAnimation と同じです。
2. メソッドの変更
Update()はパブリックではなくなりました。- 強制更新には
UpdateIfNecessary()またはUpdate(0)を使用します。
フィールドとプロパティの移行
先述の SkeletonAnimation と同じです。
▶️ SkeletonGraphic
破壊的変更
1. コンポーネントアーキテクチャ
- SkeletonGraphic はアニメーションを扱わなくなりました。個別のアニメーションコンポーネントとして SkeletonAnimation を追加してください。
- アニメーションにアクセスしたい場合は
skeletonGraphic.Animationを使用してください。
2. 既存の参照を SkeletonAnimation に変更
コンポーネントがアニメーションプロパティを変更するためだけに SkeletonGraphic への参照を保持している場合は、参照タイプを SkeletonAnimation に変更することをお勧めします。
これにより、((SkeletonAnimation)skeletonGraphic.Animation).AnimationState のようにキャストする代わりに
skeletonAnimation.AnimationState のようにAnimationStateにアクセスできます。シリアライズされたコンポーネント変数の名前を変更したい場合は、変数定義の前に [FormerlySerializedAs("previousName")] 属性を付与することで、既存のシリアライズ値を自動的に再割り当てできます。
コード例
// 以前のシリアライズされた値を自動的に再割り当て
[FormerlySerializedAs("skeletonGraphic")]
public SkeletonAnimation skeletonAnimation; // アップグレード後も参照を維持
3. プロパティの変更
- プロパティ
AnimationStateを削除しました。 代わりにSkeletonAnimationコンポーネントから照会します。 MeshGeneratorはパブリックではなくなりました。代わりにMeshSettingsプロパティとSetMeshSettings()を使用します。MaterialsMultipleCanvasRenderersの型がExposedList<Material>からMaterial[]に変更。
4. 作成ヘルパーメソッド
NewSkeletonGraphicGameObjectは既存の動作を維持するためにSkeletonGraphicとSkeletonAnimationの両方を作成するようになりました。戻り値の型が変更され、両方のコンポーネント参照を単一の構造体で返します。AddSkeletonGraphicComponentは削除され、次のものに置き換えられました：AddSkeletonGraphicAnimationComponents-SkeletonGraphicとSkeletonAnimationコンポーネントの両方を作成。AddSkeletonGraphicRenderingComponent-SkeletonGraphicコンポーネントのみを作成。
5. イベントの変更
- デリゲートシグネチャが
SkeletonRendererDelegate(SkeletonGraphic)からSkeletonRendererDelegate(ISkeletonRenderer)に変更されました。これは、OnRebuildおよびOnMeshAndMaterialsUpdatedイベントに影響します： コンパイルエラーを修正するには、メソッドパラメータを SkeletonGraphic から ISkeletonRenderer に変更してください。
6. 実行順序
SkeletonRendererとSkeletonGraphicコンポーネントはDefaultExecutionOrder(1)]を受け取り、デフォルト*（order=0）*スクリプトの後に実行されます。これにより、UpdateTimingがInLateUpdateに設定されていても、スケルトンが更新される前にアニメーションが適用されます。
7. 動作の変更 - マテリアルの更新
- 各
CanvasRendererのマテリアルは、毎回LateUpdateで更新されなくなりました。代わりに次の場合に更新されます：- a) 更新されたスケルトンがマテリアルの変更を必要とする場合、または
- b)
CustomMaterialOverrideまたはCustomTextureOverrideがアクセスされ、潜在的に変更された場合。
フィールドとプロパティの移行
アニメーションプロパティ
| 旧 API | 新 API | 備考 |
|---|---|---|
skeletonGraphic.AnimationState |
((SkeletonAnimation)skeletonGraphic.Animation).AnimationState |
キャストが必要 |
skeletonGraphic.startingAnimation |
skeletonAnimation.AnimationName |
アニメーションコンポーネント経由 |
skeletonGraphic.startingLoop |
skeletonAnimation.loop |
アニメーションコンポーネント経由 |
skeletonGraphic.timeScale |
skeletonAnimation.timeScale |
アニメーションコンポーネント経由 |
skeletonGraphic.unscaledTime |
skeletonAnimation.unscaledTime |
アニメーションコンポーネント経由 |
メッシュジェネレーター設定
| 旧 API | 新 API | 備考 |
|---|---|---|
skeletonGraphic.MeshGenerator.settings |
skeletonGraphic.MeshSettings |
設定への直接アクセス |
⚠️ その他の重要な注意事項
コンポーネント参照の損失を防ぐには
SkeletonRenderer コンポーネントを参照し、SkeletonAnimation または SkeletonMecanim ターゲットを持っていた他のコンポーネント（例：SkeletonRenderSeparator）は、アップグレード後に null を指すようになります。SkeletonAnimation と SkeletonMecanim コンポーネントはもはや SkeletonRenderer のサブクラスではなく、有効な参照ではないためです。手動の解決策は、型を SkeletonRenderer のままにして SkeletonAnimation への参照を失うことです（none に設定されます）。その後、シーンとプレハブで失われた参照を手動で再割り当てする必要があります。半自動の代替解決策は次のとおりです：SkeletonRenderer 変数の型を Component に変更して（オブジェクト参照をキャプチャして失わないようにする）、SkeletonRenderer（または SkeletonAnimation）型の 2 番目の変数を追加し、プログラム的に Component 変数から読み取って新しく追加された変数に割り当てます。たとえば、コンポーネントに [ExecuteAlways] タグを追加して、Unityエディターの Awake() で自動的にこれを実行できます。
コード例
// アップグレード前の古いクラス
public class TestMigrateReferences : MonoBehaviour {
public SkeletonRenderer skeletonRenderer; // アップグレード後、ここに割り当てられた SkeletonAnimation 参照は失われます。
public void Foo () {
skeletonRenderer.skeleton.ScaleX = -1;
}
}
// アップグレード後の新しいクラス
[ExecuteAlways] // または [ExecuteInEditMode]
public class TestMigrateReferences : MonoBehaviour {
#if UNITY_EDITOR
[SerializeField, HideInInspector, FormerlySerializedAs("skeletonRenderer")] Component previousSkeletonRenderer; // これは skeletonRenderer という名前で割り当てられた古い SkeletonAnimation 参照をキャプチャします。
#endif
public SkeletonRenderer skeletonRenderer;
public void Foo () {
skeletonRenderer.skeleton.ScaleX = -1;
}
#if UNITY_EDITOR
public void Awake () {
AutoUpgradeReferences();
}
public void AutoUpgradeReferences () {
if (previousSkeletonRenderer != null && skeletonRenderer == null) {
skeletonRenderer = previousSkeletonRenderer.GetComponent<SkeletonRenderer>();
if (skeletonRenderer != null)
Debug.Log("Upgraded SkeletonRenderer reference.");
}
}
#endif
}
コンポーネントの有効化/無効化
ISkeletonRenderer と ISkeletonAnimation コンポーネントが分離されたため、これらのコンポーネントのいずれかを有効/無効にするスクリプトは、両方を有効/無効にするように調整する必要があります。
SkeletonUtilityBone の動作変更
Overrideモードでは、SkeletonUtilityBone は UpdatePhase.World でTransformを調整しなくなりました。UpdatePhase.Complete でのみ調整します（冗長な更新を削除）。
自動移行
AUTO_UPGRADE_TO_43_COMPONENTSが定義されている場合、Unityエディターは、廃止されたフィールドを自動的に転送します。- すべてのシーンとプレハブを一度にアップグレードするには、
Edit - Preferences - Spineに移動し、Upgrade Scenes & Prefabs-Upgrade Allを選択します。 - 各クラスの
UpgradeTo43とTransferDeprecatedFields()メソッドがシリアライズされたデータの移行を処理します。 - ランタイムアクセスには手動のコード更新が必要です。
最も一般的な変更の要約
- アニメーションコンポーネントからレンダリングプロパティにアクセスする場合は、プレフィックス
.Renderer.を付けてアクセスしてください。 - メッシュ生成設定にアクセスするには
.MeshSettings.を付けてアクセスしてください。 - SkeletonGraphic から AnimationState にアクセスする場合は、 SkeletonAnimation にキャストしてください。
- 具体的な型からインターフェースへのデリゲートメソッドシグネチャ更新してください。
- アップグレード後は、上記の移行パターンを使用して失われた参照を再割り当てしてください。
自動アップグレードチェックの無効化
すべてのSpineアセット、シーン、プレハブの移行が完了したら、エディターのパフォーマンスを向上させるために自動アップグレードチェックを無効にしてください：
Edit → Preferences → Spineに移動Automatic Component Upgradeの下で、Split Component Upgrade→Disableをクリック
これにより、Unityエディターがシーンまたはプレハブのロード時にコンポーネントの移行が必要かどうかを判断するためのエディター内チェックの実行を停止します。追加のアセットを移行する必要がある場合は、いつでも再度有効にできます。
ヘルプが必要な場合
移行中に予期しない問題が発生した場合や、コンポーネントプロパティが正しく移行されない場合は、どうぞ遠慮なくSpineフォーラムで質問してください。できるだけスムーズに自動移行できるように、喜んで問題解決のお手伝いをします。