# spine-unity 4.3 コンポーネント分離アップグレードガイド ## コンポーネントアーキテクチャの再構築 --- ## 📋 本ドキュメントの対象範囲 **本ドキュメントは spine-unity コンポーネント分離の移行のみを扱います。** バージョン 4.2 から 4.3 では、spine-csharp と spine-unity の両方に追加の破壊的変更があり、コンポーネント分離を処理する前に対処する必要があります: - **spine-csharp API の変更:** ボーン、スロット、コンストレイントのプロパティに影響を与える新しいポーズシステム 4.2 から 4.3 へのすべての変更を網羅する完全な移行手順については、以下を参照してください: - [CHANGELOG.md](https://github.com/EsotericSoftware/spine-runtimes/blob/4.3-beta/CHANGELOG.md#c-2) ドキュメント(C# および Unity セクション) - 包括的な移行ガイドとして、フォーラム投稿 ["Spine-Unity 4.2 to 4.3 Upgrade Guide"](https://esotericsoftware.com/forum) を参照してください **重要:** spine-csharp API の移行を最初に完了してから、本ドキュメントで説明されているコンポーネント分離の移行に進んでください。 --- ## ⚠️ 重要:アップグレード前の必読事項 **この警告は、アップグレードされる既存のプロジェクトにのみ適用されます。新規プロジェクトはこのセクションを安全に無視できます。** ### 何が起こるか コンポーネントは**自動的にアップグレード**され、個別のアニメーションとレンダリングコンポーネントに分離されます: - `SkeletonAnimation` → `SkeletonAnimation` + `SkeletonRenderer` コンポーネント - `SkeletonMecanim` → `SkeletonMecanim` + `SkeletonRenderer` コンポーネント - `SkeletonGraphic` → `SkeletonAnimation` + `SkeletonGraphic` コンポーネント すべてのコンポーネント設定とフィールドは自動的に転送されます - 何も失われません。 **ただし:** これらの型の変更により、コンポーネントタイプが一致しなくなるため、カスタムスクリプトの既存の参照が失われる可能性があります(例:`SkeletonAnimation` はもはや `SkeletonRenderer` のサブクラスではありません)。 ### 必要なアップグレード手順(順番に): 1. **🔒 プロジェクトのバックアップ** アップグレード前に完全なバックアップを作成します。これらの変更により、シーンとプレハブが変更されます。 2. **📖 このドキュメント全体を読む** 続行する前にすべての破壊的変更を理解します。 3. **✏️ コードのテストと更新** - **スクリプトの更新:** このドキュメントに従って Spine コンポーネントを参照するカスタムスクリプトを修正します。メンバーが分離されたクラスに移動されると、コードがコンパイルされない可能性があります - **テスト:** いくつかのテストシーンを開いて、どのコンポーネント参照が失われるかを確認します。未保存のシーンには古いコンポーネントデータが含まれており、セーフティバックアップとして機能します - 保存すると、分離されたコンポーネントが古いコンポーネントを置き換え、参照が失われます。 **⚠️ 警告:** プレハブは動作が異なります!Prefab Edit Mode でプレハブを開くと、Unity のプレハブ自動保存機能によりコンポーネントの移行が自動的に保存されます。常に最初にシーンでテストし、プレハブではテストしないでください。 - **決定:** 失われた参照を手動で再割り当てするか、移行コードを記述して(以下で説明)自動的に処理します **⚠️ 重要:** 自動コンポーネント分離は、Unity エディターでシーン/プレハブが開かれたときにのみ発生します。ゲームをビルドする前に `Upgrade All` を選択するか、各シーン/プレハブを保存する必要があります。そうしないと、古い単一コンポーネントが分離されず、ビルドで必要なコンポーネントの半分が欠落する可能性があります! **💡 ヒント:** Console ログ出力「SendMessage cannot be called during Awake, CheckConsistency, or OnValidate」が表示される場合、これは古い未移行のアセットがシーンに存在し、自動アップグレードされたことを示しています。これらのメッセージの後に、古いコンポーネントが分離コンポーネントに自動移行されたことを確認するログメッセージが表示されます。 4. **🔄 アップグレードパスを選択** **オプション 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` にキャストしてレンダラーメンバー変数にアクセスできます。 ### サンプルコード ```csharp // 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](#▶️-skeletonanimation) と同じアクセスパターン。 #### 2. メソッドの変更 - `Update()` はパブリックではなくなりました。 - 強制更新には `UpdateIfNecessary()` または `Update(0)` を使用します。 ### フィールドとプロパティの移行 上記の [SkeletonAnimation](#▶️-skeletonanimation) と同じ。 --- ## ▶️ SkeletonGraphic ### 破壊的変更 #### 1. コンポーネントアーキテクチャ - **SkeletonGraphic はアニメーションをカバーしなくなりました、個別のアニメーションコンポーネントとして SkeletonAnimation を追加**。 - アニメーションへのアクセス:`skeletonGraphic.Animation`。 #### 2. 既存の参照を SkeletonAnimation に変更 コンポーネントがアニメーションプロパティを変更するためだけに `SkeletonGraphic` への参照を保持している場合は、参照タイプを `SkeletonAnimation` に変更することをお勧めします。 これにより、`((SkeletonAnimation)skeletonGraphic.Animation).AnimationState` のようにキャストする代わりに `skeletonAnimation.AnimationState` のようにアニメーション状態にアクセスできます。シリアライズされたコンポーネント変数の名前を変更したい場合は、変数定義の前に `[FormerlySerializedAs("previousName")]` 属性を使用して、既存のシリアライズ値を自動的に再割り当てできることに注意してください。 #### サンプルコード ```csharp // 以前のシリアライズされた値を自動的に再割り当て [FormerlySerializedAs("skeletonGraphic")] public SkeletonAnimation skeletonAnimation; // アップグレード後も参照を維持 ``` #### 3. プロパティの変更 - プロパティ `AnimationState` を削除 - 代わりに `SkeletonAnimation` コンポーネントから照会します。 - `MeshGenerator` はパブリックではなくなりました - 代わりに `MeshSettings` プロパティと `SetMeshSettings()` を使用します。 - `MaterialsMultipleCanvasRenderers` の型が `ExposedList` から `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()` で自動的にこれを実行できます。 #### サンプルコード ```csharp // アップグレード前の古いクラス 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(); 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()` メソッドがシリアライズされたデータの移行を処理します。 - ランタイムアクセスには手動のコード更新が必要です。 ### 最も一般的な変更の要約 1. アニメーションコンポーネントからレンダリングプロパティにアクセスするには **`.Renderer.`** プレフィックスを追加。 2. メッシュ生成設定にアクセスするには **`.MeshSettings.`** を追加。 3. SkeletonGraphic から AnimationState にアクセスする際に **SkeletonAnimation にキャスト**。 4. 具体的な型からインターフェースへの**デリゲートメソッドシグネチャの更新**。 5. アップグレード後、上記の移行パターンを使用して**失われた参照を再割り当て**。 --- ## 自動アップグレードチェックの無効化 すべての Spine アセット、シーン、プレハブの移行が完了したら、エディターのパフォーマンスを向上させるために自動アップグレードチェックを無効にできます: 1. `Edit → Preferences → Spine` に移動 2. `Automatic Component Upgrade` の下で、`Split Component Upgrade` → `Disable` をクリック これにより、Unity エディターがシーンまたはプレハブのロード時にコンポーネントの移行が必要かどうかを判断するためのエディター内チェックの実行を停止します。追加のアセットを移行する必要がある場合は、いつでも再度有効にできます。 --- ## ヘルプが必要ですか? 移行中に予期しない問題が発生した場合、またはコンポーネントプロパティが正しく移行されないことがわかった場合は、[Spine フォーラム](https://esotericsoftware.com/forum) に投稿してください。自動移行をできるだけ痛みのないものにするために、喜んでお手伝いし、問題を修正します。