27 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 のようにアニメーション状態にアクセスできます。シリアライズされたコンポーネント変数の名前を変更したい場合は、変数定義の前に [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 フォーラム に投稿してください。自動移行をできるだけ痛みのないものにするために、喜んでお手伝いし、問題を修正します。