Initial commit: Client Doc docs Server Tools

Co-authored-by: Cursor <cursoragent@cursor.com>

Client/Assets/Spine/Documentation/4.3-split-component-upgrade-guide-ja.md

@@ -0,0 +1,371 @@
+# 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/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バージョンへアップグレードする
+まず、コンポーネント分離の変更が加わる前の4.3バージョンにアップグレードしてください：
+- **コミットハッシュ**: `a07b1de9ce972d4e38898ccf2cc84de16ff66c9b`
+- **Git URL でパッケージを追加**: `https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-csharp/src#a07b1de9ce972d4e38898ccf2cc84de16ff66c9b`
+- または **unitypackage** を利用: https://esotericsoftware.com/files/runtimes/unity/spine-unity-4.2-2025-09-26.unitypackage
+
+この中間ステップで、次の作業を行ってください：
+- 4.2 → 4.3 spine-csharp API 変更に関連する問題を修正し、プロジェクトが正常に動作することを確認してください
+- 続行する前にプロジェクトが安定していることを検証してください
+- この 4.3 バージョンでプロジェクトが正常に動作したら、ステップ2に進む前に別のバックアップを作成してください
+
+### ステップ 2：最新の4.3バージョン（分離コンポーネントに対応したバージョン）へアップグレードする
+4.3でプロジェクトが正常に動作したら：
+- 最新の4.3パッケージにアップグレードしてください
+- 先述のコンポーネント分離移行ガイドに従ってください
+- 分離されたアニメーションコンポーネントとレンダリングコンポーネントを処理してください
+
+この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 に移動 |
+
+#### 非公開の小文字属性
+- `skeletonRenderer.maskInteraction` は、プロパティ `skeletonRenderer.MaskInteraction` に置き換えられました。
+
+#### 非推奨の小文字属性
+- 小文字の属性 `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` のようにAnimationStateにアクセスできます。シリアライズされたコンポーネント変数の名前を変更したい場合は、変数定義の前に `[FormerlySerializedAs("previousName")]` 属性を付与することで、既存のシリアライズ値を自動的に再割り当てできます。
+
+#### コード例
+```csharp
+// 以前のシリアライズされた値を自動的に再割り当て
+[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()` で自動的にこれを実行できます。
+
+#### コード例
+  ```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<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()` メソッドがシリアライズされたデータの移行を処理します。
+- ランタイムアクセスには手動のコード更新が必要です。
+
+### 最も一般的な変更の要約
+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)で質問してください。できるだけスムーズに自動移行できるように、喜んで問題解決のお手伝いをします。

Client/Assets/Spine/Documentation/4.3-split-component-upgrade-guide-ja.md.meta

@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: 84b6c350ead7f64469652d531034991c
+timeCreated: 1759835002
+licenseType: Free
+DefaultImporter:
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

Client/Assets/Spine/Documentation/4.3-split-component-upgrade-guide-zh.md

@@ -0,0 +1,418 @@
+# spine-unity 4.3 模块化组件升级指南
+
+## 组件架构重构
+
+---
+
+## 📋 本指南的适用范围
+
+**本文档仅涵盖 spine-unity 模块化组件迁移流程.** 当从 4.2 升级至 4.3 时, spine-csharp 和 spine-unity 中仍包含其他破坏性更改, 在着手模块化组件升级前应先解决这些问题:
+
+* **spine-csharp API 变更:** 全新引入的姿态(pose)系统显著地改变了访问骨骼、槽位和约束属性的方式
+
+如需获取涵盖 4.2 至 4.3 所有变更的完整迁移步骤, 请参阅以下官方文档:
+
+* 运行时 [CHANGELOG.md](https://github.com/EsotericSoftware/spine-runtimes/blob/4.3/CHANGELOG.md#c-2) 的 C# 和 Unity 一节
+* 论坛置顶帖 ["Spine-Unity 4.2 to 4.3升级指南"](https://zh.esotericsoftware.com/forum/d/29263-zh-cnspine-unity-42-to-43%E5%8D%87%E7%BA%A7%E6%8C%87%E5%8D%97)
+
+**重要提示:** 请务必优先完成 spine-csharp API 的迁移, 再依据本指南执行模块化组件迁移操作.
+
+---
+
+## ⚠️ 重要提醒: 升级前须知
+
+**本提醒仅用于升级现有项目, 新项目可忽略本节内容.**
+
+### 升级后将发生的变化
+
+组件将**自动升级**并分离为相互独立的动画与渲染组件:
+
+* `SkeletonAnimation` → `SkeletonAnimation` + `SkeletonRenderer` 组件
+* `SkeletonMecanim` → `SkeletonMecanim` + `SkeletonRenderer` 组件
+* `SkeletonGraphic` → `SkeletonAnimation` + `SkeletonGraphic` 组件
+
+所有组件设置与字段将被自动迁移 - 不会造成数据丢失.
+
+**但请注意:** 由于变更了组件类型, 项目脚本中对原组件的引用可能失效 (例如, `SkeletonAnimation` 不再继承自 `SkeletonRenderer`).
+
+### 必须****依序****执行的项目升级步骤
+
+1. **🔒 备份项目**
+   在升级前请完整备份项目. 升级操作将修改场景与预制件文件.
+
+2. **📖 通读本指南全文**
+   在执行升级操作前, 务必充分理解全部的破坏性变更点.
+
+3. **✏️ 测试并更新你的代码**
+   * **更新代码:** 根据本指南修正所有引用了 Spine 组件的脚本, 由于类成员已迁移至模块化类, 项目代码将可能无法编译.
+   * **测试:** 打开若干测试场景, 检查丢了失哪些引用. 未保存的场景仍会保留旧组件数据, 不妨将其作为安全备份——仅当你保存场景后旧组件才会被替换为模块化组件, 此时旧的组件引用便会失效.
+     **⚠️ 警告:** 小心对待预制件(Prefab)! 在预制件编辑模式中打开预制件的话, 它会因 Unity 的自动保存机制立即触发组件迁移. 请优先在场景范围内测试, 避免直接操作预制体.
+   * **可选操作:** 也可以一个个地手动重新分配丢失的引用, 或编写一套自动化迁移脚本(详见下文)来自动迁移组件.
+
+   **⚠️ 重要提示:** 自动组件升级仅在 Unity 编辑器打开了场景或预制件时触发. 在构建项目前, 你必须选择 'Upgrade All' 或逐一保存所有场景与预制件来确保没有残留旧组件, 否则可能导致构建中缺失必要组件而失败!
+
+   **💡 提示:** 若控制台输出信息中包含 "SendMessage cannot be called during Awake, CheckConsistency, or OnValidate" 字样，则表明场景中的旧资产已完成自动升级. 此消息将后附日志信息来确认旧组件已成功迁移至模块化组件.
+
+4. **🔄 选择升级方式**
+
+   **选项 A - 手动重分配 (推荐小型项目采用):**
+   * 逐一打开各场景与预制件
+   * 在检查器(Inspector)中手动分配缺失的引用
+   * 确认无误后保存
+
+   **选项 B - 自动化迁移 (推荐含大量场景/预制件的大型项目采用):**
+   * 首先编写迁移代码:
+     * 实现引用迁移模式 (详见下文中的 "防止丢失组件引用" 一节)
+     * 对于 `SkeletonGraphic` 的引用, 请见 "将已有引用迁至 SkeletonAnimation" 一节
+   * 在少量文件上测试迁移代码
+   * 使用 `Upgrade All` 按钮:
+     * 打开 `Edit → Preferences → Spine`
+     * 在 "Upgrade Scenes & Prefabs" 中
+     * 点击 `Upgrade All` 按钮
+
+### 若仓促升级可能会导致以下后果
+
+* 场景或预制件中的 Spine 组件引用在保存后将丢失 (引用被置null)
+
+* 在未能升级全部场景/预制件便匆忙执行构建, 可能导致构建过程中缺失必要组件而失败
+
+**请勿跳过步骤 1-3, 否则项目极有可能遭到破坏.**
+
+---
+
+## 📦 可选方案: 4.2 版的两阶段迁移
+
+若你正从 spine-unity 4.2 升级至最新版, 建议遵循两阶段迁移方案来隔离潜在问题:
+
+### 阶段 1: 升级至 4.3 非模块化组件版本
+
+第一步是升级至 4.3 非模块化组件版本:
+
+* **Commit Hash**: `a07b1de9ce972d4e38898ccf2cc84de16ff66c9b`
+* **使用 Git URL 添加包**: `https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-csharp/src#a07b1de9ce972d4e38898ccf2cc84de16ff66c9b`
+* 或使用 **unitypackage**: <https://esotericsoftware.com/files/runtimes/unity/spine-unity-4.2-2025-09-26.unitypackage>
+
+这一阶段可以:
+
+* 优先解决 4.2 → 4.3 spine-csharp API 变更问题, 同时确保项目正常
+* 在升级模块化组件前验证项目稳定性
+* 确认项目在 4.3 下稳定后, 有机会再次备份完整项目, 为阶段 2的迁移工作作出充分准备
+
+### 阶段 2: 升级至最新的 4.3 模块化组件版本
+
+当项目能够在 4.3 非模块化组件版下稳定工作后:
+
+* Up升级至最新 4.3 包
+* 按照本指南所述执行模块化组件迁移
+* 处理独立的动画与渲染组件
+
+这种两阶段策略可有效隔离问题源头: 项目出现故障时, 可以明确地判断出是 4.2 → 4.3 的 spine-csharp API 变更导致的, 还是模块化组件所致.
+
+---
+
+## 📋 简介
+
+spine-unity 4.3 运行时引入了重大架构变更: **相互独立的动画与渲染组件取代原有的继承结构**. 该设计让用户可灵活地选用组件, 例如在项目中让 `SkeletonMecanim` 负责控制动画, 同时采用 `SkeletonGraphic` 执行渲染——这是此前无法实现的.
+
+### 关键更改
+
+* **模块化组件**: 旧组件被拆分为了相互独立的渲染与动画组件.
+
+* **独立组件架构**: `SkeletonAnimation` 和 `SkeletonMecanim` 不再继承自 `SkeletonRenderer`, 而是与独立渲染器组件(`ISkeletonRenderer` 的子类)协同工作, 例如 `SkeletonRenderer` 和 `SkeletonGraphic`.
+* **接口更新**: 新增了命名统一的 `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`, 参数由 `ISkeletonRenderer` 改为了 `ISkeletonAnimation`.
+
+#### 2. 方法变更
+
+* `LateUpdateMesh()` 改为了 `UpdateMesh()`.
+
+* 移除了 `MeshGenerator.TryReplaceMaterials`.
+
+#### 3. 执行顺序
+
+* `SkeletonRenderer` 和 `SkeletonGraphic` 组件接受 `DefaultExecutionOrder(1)]` 参数, 以确保其在默认脚本*(即 order=0)*之后执行. 此举保证了即使 `UpdateTiming` 置为 `InLateUpdate`, 动画仍能先于 skeleton 更新.
+
+#### 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 |
+
+#### 已更改的小写属性
+
+* `skeletonRenderer.maskInteraction` 改为了 `skeletonRenderer.MaskInteraction`.
+
+#### 已弃用的小写属性
+
+* 小写属性 `initialFlipX`, `initialFlipY` 和 `initialSkinName` 已被弃用并将于后续版本中移除. 请转用同名大写属性 `InitialFlipX`, `InitialFlipY` 和 `InitialSkinName`.
+
+---
+
+## ▶️ SkeletonAnimation
+
+### 破坏性变更
+
+#### 1. 组件架构
+
+* **SkeletonAnimation 现为独立于 SkeletonRenderer 的组件**, 不再继承自 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.Animation` 属性则可通过 `SkeletonRenderer` 或 `SkeletonGraphic` 实例中的 `ISkeletonAnimation` 访问. 对于未在 `ISkeletonRenderer` 接口中暴露的成员, 可将 `skeletonAnimation.Renderer` 显式转换为 `SkeletonRenderer` 或 `SkeletonGraphic` 以访问渲染器成员变量.
+
+### 示例代码
+
+```csharp
+// 升级前: 直接访问 SkeletonRenderer 属性
+skeletonAnimation.zSpacing = 0.1f;
+skeletonAnimation.AnySkeletonRendererProperty;
+
+// 升级后: 通过 Renderer 对象访问
+skeletonAnimation.Renderer.MeshSettings.zSpacing = 0.1f; // 访问 ISkeletonRenderer 接口暴露出的成员
+var skeletonRenderer = (SkeletonRenderer)skeletonAnimation.Renderer;
+skeletonRenderer.AnySkeletonRendererProperty; // 访问 ISkeletonRenderer 接口未暴露的成员
+
+```
+
+---
+
+## ▶️ SkeletonMecanim
+
+### 破坏性变更
+
+#### 1. 组件架构
+
+* **SkeletonMecanim 现为独立于 SkeletonRenderer 的组件**, 不再继承自 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")]` 特性, Unity 将自动将原字段中保存的序列化值迁移至新变量, 从而保留你在场景或预制件中的已有配置.
+
+#### 示例代码
+
+```csharp
+// Automatically reassign previous serialized values
+[FormerlySerializedAs("skeletonGraphic")]
+public SkeletonAnimation skeletonAnimation; // Will maintain the reference after upgrade
+```
+
+#### 3. 属性变更
+
+* 已移除属性 `AnimationState` - 请通过 `SkeletonAnimation` 组件查询该属性.
+
+* 不再公开 `MeshGenerator` - 请改用 `MeshSettings` 属性和 `SetMeshSettings()` 方法.
+* `MaterialsMultipleCanvasRenderers` 类型由 `ExposedList<Material>` 改为 `Material[]`.
+
+#### 4. 创建辅助器(Creation Helper)方法
+
+* `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`, 动画仍能先于 skeleton 更新.
+
+#### 7. 行为变更 - Material 更新
+
+* 各 `CanvasRenderer` 的 material 不再于每个 `LateUpdate` 中更新, 而仅在以下情况时更新:
+  * a) 当 skeleton 更新需更换 materials, 或者
+  * b) 代码访问了 `CustomMaterialOverride` 或 `CustomTextureOverride` 并可能修改它们.
+
+### 字段与属性迁移
+
+#### A动画属性
+
+| **旧 API** | **新 API** | **说明** |
+|-------------------|-------------------|-----------|
+| `skeletonGraphic.AnimationState` | `((SkeletonAnimation)skeletonGraphic.Animation).AnimationState` | 需显式转换 |
+| `skeletonGraphic.startingAnimation` | `skeletonAnimation.AnimationName` | 通过 Animation 组件访问 |
+| `skeletonGraphic.startingLoop` | `skeletonAnimation.loop` | 通过 Animation 组件访问 |
+| `skeletonGraphic.timeScale` | `skeletonAnimation.timeScale` | 通过 Animation 组件访问 |
+| `skeletonGraphic.unscaledTime` | `skeletonAnimation.unscaledTime` | 通过 Animation 组件访问 |
+
+#### 网格生成器设置
+
+| **旧 API** | **新 API** | **说明** |
+|-------------------|-------------------|-----------|
+| `skeletonGraphic.MeshGenerator.settings` | `skeletonGraphic.MeshSettings` | 直接访问设置 |
+
+---
+
+## ⚠️ 其他重要注意事项
+
+### 防止丢失组件引用
+
+其他组件(例如 `SkeletonRenderSeparator`)若持有对 `SkeletonRenderer` 的引用, 且其目标引用曾为 `SkeletonAnimation` 或 `SkeletonMecanim`, 则升级后该引用将被置为 *null*. 这是由于 `SkeletonAnimation` 与 `SkeletonMecanim` 不再继承自 `SkeletonRenderer`, 因而不再构成有效的类型引用. 对此, 手动解决方案是直接不管, 变量类型保持 `SkeletonRenderer` 不变, 任凭 `SkeletonAnimation` 的引用被置为 *none*. 随后再在各场景与预制件中手动分配丢失的引用. 而半自动方案则是: 将项目中 `SkeletonRenderer` 变量的类型改为 `Component` (保持对象引用避免丢失目标), 新增一个类型为 `SkeletonRenderer`(或 `SkeletonAnimation`)的变量，然后在代码中从 `Component` 类型变量读取目标对象, 并将其赋给新变量. 例如, 在 Unity 编辑器中给组件添加 [ExecuteAlways] 特性标记, 并在 `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<SkeletonRenderer>();
+   if (skeletonRenderer != null)
+    Debug.Log("Upgraded SkeletonRenderer reference.");
+  }
+ }
+#endif
+}
+```
+
+### 组件的启用/禁用
+
+由于 `ISkeletonRenderer` 和 `ISkeletonAnimation` 组件现已一分为二, 任何控制组件启用/禁用的脚本都必须**同时启用/禁用这两个组件**.
+
+### SkeletonUtilityBone 行为更改
+
+在 Override 模式下, `SkeletonUtilityBone` 仅在 `UpdatePhase.Complete` 阶段调整变换(Transform), 不再于 `UpdatePhase.World` 阶段重复更新, 以减少冗余操作.
+
+### 自动化迁移
+
+* 当启用了 `AUTO_UPGRADE_TO_43_COMPONENTS` 后, Unity 编辑器将自动迁移废弃字段.
+* 如需一键升级全部场景与预制件, 请打开 `Edit - Preferences - Spine`, 并在 `Automatic Component Upgrade` 中点击 `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) 发帖反馈. 我们将全力协助，确保自动迁移过程尽可能顺畅无痛.

Client/Assets/Spine/Documentation/4.3-split-component-upgrade-guide-zh.md.meta

@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: 6c12bf9dde3ca4146b5d422361d438de
+timeCreated: 1759835002
+licenseType: Free
+DefaultImporter:
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

Client/Assets/Spine/Documentation/4.3-split-component-upgrade-guide.md

@@ -0,0 +1,375 @@
+# spine-unity 4.3 Split Component Upgrade Guide
+## Component Architecture Restructuring
+
+> **Note:** You can find Chinese and Japanese translations of this upgrade guide right next to this file.
+>
+> * [中文版 4.3 模块化组件升级指南 - Chinese 4.3 Split Component Upgrade Guide](https://github.com/EsotericSoftware/spine-runtimes/tree/4.3/spine-unity/Assets/Spine/Documentation/4.3-split-component-upgrade-guide-zh.md)
+> * [日本語版 4.3 分割コンポーネントアップグレードガイド - Japanese 4.3 Split Component Upgrade Guide](https://github.com/EsotericSoftware/spine-runtimes/tree/4.3/spine-unity/Assets/Spine/Documentation/4.3-split-component-upgrade-guide-ja.md)
+
+---
+
+## 📋 Scope of This Document
+
+**This document covers only the spine-unity component split migration.** From version 4.2 to 4.3, there have been additional breaking changes in both spine-csharp and spine-unity that you need to address before handling the component split:
+
+- **spine-csharp API changes:** New pose system affecting bone, slot, and constraint properties
+
+For complete migration steps covering all 4.2 to 4.3 changes, please refer to:
+- The [CHANGELOG.md](https://github.com/EsotericSoftware/spine-runtimes/blob/4.3/CHANGELOG.md#c-2) document (sections C# and Unity)
+- The forum post ["Spine-Unity 4.2 to 4.3 Upgrade Guide"](https://esotericsoftware.com/forum) for a comprehensive migration guide
+
+**Important:** Complete the spine-csharp API migration first, then proceed with the component split migration described in this document.
+
+---
+
+## ⚠️ IMPORTANT: Before You Upgrade
+
+**This warning only applies to existing projects being upgraded. New projects can safely ignore this section.**
+
+### What Will Happen
+
+Components will be **automatically upgraded** and split into separate animation and rendering components:
+- `SkeletonAnimation` → `SkeletonAnimation` + `SkeletonRenderer` components
+- `SkeletonMecanim` → `SkeletonMecanim` + `SkeletonRenderer` components
+- `SkeletonGraphic` → `SkeletonAnimation` + `SkeletonGraphic` components
+
+All component settings and fields will be automatically transferred - nothing will be lost.
+
+**However:** Due to these type changes, existing references in your custom scripts may be lost because the component types no longer match (e.g., `SkeletonAnimation` is no longer a subclass of `SkeletonRenderer`).
+
+### Required Upgrade Steps (In Order)
+
+1. **🔒 BACKUP YOUR PROJECT**
+   Create a complete backup before upgrading. These changes will modify your scenes and prefabs.
+
+2. **📖 READ THIS ENTIRE DOCUMENT**
+   Understand all breaking changes before proceeding.
+
+3. **✏️ TEST AND UPDATE YOUR CODE**
+   - **Update your scripts:** Fix custom scripts that reference Spine components according to this document, as your code may no longer compile when members were moved to the split classes
+   - **Test:** Open a few test scenes to see which component references are lost. Unsaved scenes still contain the old component data and serve as a safety backup - only when you save will the split components replace the old ones and references be lost.
+     **⚠️ WARNING:** Prefabs behave differently! Opening a prefab in Prefab Edit Mode will automatically save the component migration due to Unity's prefab auto-save feature. Always test with scenes first, not prefabs.
+   - **Decide:** Either manually re-assign lost references, or write migration code (explained below) to handle this automatically
+
+   **⚠️ IMPORTANT:** Automatic component splitting only happens when scenes/prefabs are opened in the Unity Editor. You must choose 'Upgrade All' or save each scene/prefab before building your game, otherwise the old single components won't be split and half the required components might be missing in the build!
+
+   **💡 HINT:** If you encounter the Console log output "SendMessage cannot be called during Awake, CheckConsistency, or OnValidate", this is a sign that old un-migrated assets were present in the scene which were just auto-upgraded. These messages will be followed by a log message confirming that an old component was auto-migrated to split components.
+
+4. **🔄 CHOOSE YOUR UPGRADE PATH**
+
+   **Option A - Manual re-assignment (recommended for small projects):**
+   - Open each scene and prefab individually
+   - Manually re-assign lost references in the Inspector
+   - Save when satisfied
+
+   **Option B - Automatic migration (for large projects with many scenes/prefabs):**
+   - Write migration code first:
+     - Implement the reference migration pattern (see "Preventing Lost Component References" section below)
+     - For `SkeletonGraphic` references, see "Changing Existing References to SkeletonAnimation" section
+   - Test migration code on a few files
+   - Then use `Upgrade All`:
+     - Go to `Edit → Preferences → Spine`
+     - Under "Upgrade Scenes & Prefabs"
+     - Click `Upgrade All` button
+
+### What Will Break If You Don't Prepare
+- Component references in scenes or prefabs may be lost (set to null) once you save your scenes or prefabs
+- Building before upgrading all scenes/prefabs may result in missing components in the build
+
+**Do not proceed without completing steps 1-3, or you risk breaking your project.**
+
+---
+
+## 📦 Optional Two-Step Migration from 4.2
+
+If you're migrating from spine-unity 4.2, you may find it easier to upgrade in two steps to isolate potential issues:
+
+### Step 1: Upgrade to a 4.3 pre-split version
+First upgrade to a 4.3 version before the component split changes:
+- **Commit Hash**: `a07b1de9ce972d4e38898ccf2cc84de16ff66c9b`
+- **add package via Git URL**: `https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-csharp/src#a07b1de9ce972d4e38898ccf2cc84de16ff66c9b`
+- or **unitypackage**: https://esotericsoftware.com/files/runtimes/unity/spine-unity-4.2-2025-09-26.unitypackage
+
+This intermediate step allows you to:
+- Fix any issues related to the 4.2 → 4.3 spine-csharp API changes first and ensures your project works
+- Verify your project is stable before proceeding
+- Once your project is working with this 4.3 version, create another backup before proceeding to step 2
+
+### Step 2: Upgrade to latest 4.3 version (with split components)
+Once your project is working with 4.3:
+- Upgrade to the latest 4.3 package
+- Follow the component split migration guide above
+- Handle the separated animation and rendering components
+
+This two-step approach helps isolate issues - if something breaks, you'll know whether it's due to the 4.2 → 4.3 spine-csharp changes or the component split specifically.
+
+---
+
+## 📋 Introduction
+
+The spine-unity 4.3 runtime introduces a major architectural change: **separation of animation from rendering by using two separate components instead of component inheritance**. This enables flexible combinations like using `SkeletonMecanim` for animation with `SkeletonGraphic` for rendering, which was previously not possible.
+
+### Key Changes
+- **Component Split**: The previously monolithic components have been split into separate rendering and animation components.
+- **Separate Components**: `SkeletonAnimation` and `SkeletonMecanim` no longer inherit from `SkeletonRenderer`. They now work alongside a separate renderer component (a subclass of `ISkeletonRenderer`), such as `SkeletonRenderer` and `SkeletonGraphic`.
+- **Interface Updates**: New `ISkeletonRenderer` and `ISkeletonAnimation` interfaces with updated property names.
+- **Settings Grouping**: Mesh generation settings are now grouped under `MeshSettings` property.
+- **Automatic Migration**: The Unity Editor will automatically upgrade your components to the new split components and transfer deprecated fields when `AUTO_UPGRADE_TO_43_COMPONENTS` is defined (*the default*).
+- **Upgrade all Scenes and Prefabs**: To upgrade all scenes and prefabs at once, go to `Edit - Preferences - Spine` and under `Automatic Component Upgrade` hit `Upgrade Scenes & Prefabs` - `Upgrade All`.
+
+### Component Relationships
+
+| **Old Architecture** | **New Architecture** |
+|---------------------|---------------------|
+| `SkeletonAnimation` inherits from `SkeletonRenderer` | `SkeletonAnimation` + separate `SkeletonRenderer` component |
+| `SkeletonMecanim` inherits from `SkeletonRenderer` | `SkeletonMecanim` + separate `SkeletonRenderer` component |
+| `SkeletonGraphic` provides embedded AnimationState | `SkeletonGraphic` + separate `SkeletonAnimation` component |
+
+---
+
+## Adapting Your Code
+
+Here's what changes for each component:
+
+## ▶️ SkeletonRenderer
+
+### Breaking Changes
+
+#### 1. Interface Changes
+- `IHasSkeletonRenderer` interface changed property name from `SkeletonRenderer` to `Renderer`, type from `SkeletonRenderer` to `ISkeletonRenderer`.
+
+#### 2. Event Changes
+- `SkeletonRendererDelegate` type is no longer a nested type in `SkeletonRenderer`.  
+  To fix any compile errors, replace `SkeletonRenderer.SkeletonRendererDelegate` with `SkeletonRendererDelegate`.
+- `BeforeApply` delegate type changed from `SkeletonRendererDelegate` to `SkeletonAnimationDelegate`.
+- `SkeletonRendererDelegate` type changed from `SkeletonRendererDelegate(SkeletonRenderer)` to `SkeletonRendererDelegate(ISkeletonRenderer)`. This affects events: `OnRebuild`, `OnMeshAndMaterialsUpdated`.  
+  To fix any compile errors, change your method parameter from `SkeletonRenderer` to `ISkeletonRenderer`.
+- Moved bone events `UpdateLocal`, `UpdateWorld`, and `UpdateComplete` from `ISkeletonAnimation` classes (`SkeletonAnimation`, `SkeletonMecanim`) to `ISkeletonRenderer classes (SkeletonRenderer, SkeletonGraphic)`. Changed delegate type from `UpdateBonesDelegate` to `SkeletonRendererDelegate`, with parameter `ISkeletonRenderer` instead of `ISkeletonAnimation`.
+
+#### 2. Method Changes
+- `LateUpdateMesh()` has been changed to `UpdateMesh()`.
+- Removed `MeshGenerator.TryReplaceMaterials`.
+
+#### 3. Execution Order
+- `SkeletonRenderer` and `SkeletonGraphic` components received `DefaultExecutionOrder(1)]` which makes them run after default *(order=0)* scripts. This ensures animations are applied before the skeleton is updated even if `UpdateTiming` is set to `InLateUpdate`.
+
+#### 4. Behaviour Changes
+- `generateMeshOverride` is now also called when `singleSubmesh` is enabled.
+
+### Field and Property Migration
+
+#### Mesh Generation Settings
+| **Old API** | **New API** | **Notes** |
+|-------------------|-------------------|-----------|
+| `skeletonRenderer.zSpacing` | `skeletonRenderer.MeshSettings.zSpacing` | Moved to MeshSettings |
+| `skeletonRenderer.useClipping` | `skeletonRenderer.MeshSettings.useClipping` | Moved to MeshSettings |
+| `skeletonRenderer.immutableTriangles` | `skeletonRenderer.MeshSettings.immutableTriangles` | Moved to MeshSettings |
+| `skeletonRenderer.pmaVertexColors` | `skeletonRenderer.MeshSettings.pmaVertexColors` | Moved to MeshSettings |
+| `skeletonRenderer.tintBlack` | `skeletonRenderer.MeshSettings.tintBlack` | Moved to MeshSettings |
+| `skeletonRenderer.addNormals` | `skeletonRenderer.MeshSettings.addNormals` | Moved to MeshSettings |
+| `skeletonRenderer.calculateTangents` | `skeletonRenderer.MeshSettings.calculateTangents` | Moved to MeshSettings |
+
+#### Hidden Lowercase Attributes
+- `skeletonRenderer.maskInteraction` is replaced by Property `skeletonRenderer.MaskInteraction`.
+
+#### Deprecated Lowercase Attributes
+- Lowercase attributes `initialFlipX`, `initialFlipY` and `initialSkinName` are now deprecated and will be removed in future runtime versions. Use the added properties of the same name but uppercase instead:  `InitialFlipX`, `InitialFlipY` and `InitialSkinName`.
+
+---
+
+## ▶️ SkeletonAnimation
+
+### Breaking Changes
+
+#### 1. Component Architecture
+- **SkeletonAnimation is now a separate component from SkeletonRenderer**, no longer a subclass.
+- Access renderer via: `skeletonAnimation.Renderer`.
+- Access animation from renderer via: `skeletonRenderer.Animation`.
+
+#### 2. Property Changes
+- `state` is no longer public. Use `AnimationState` property instead.
+- `valid` removed. Use `IsValid` instead.
+
+#### 3. Method Changes
+- Added `UpdateOncePerFrame()` - updates if `Update` has not been called this frame. The existing `Update(float time)` still always updates when called.
+- `Update()` without parameters is no longer public, use either `UpdateOncePerFrame()` to update when no update has been performed this frame,
+or `Update(0)` to force an animation update.
+
+### Field and Property Migration
+
+As `SkeletonAnimation` is now a separate component, methods and properties provided by `SkeletonRenderer` can no longer be accessed directly via a `SkeletonAnimation` object. There is a `skeletonAnimation.Renderer` property available to access the associated `ISkeletonRenderer` from a `SkeletonAnimation` object,
+and an `skeletonRenderer.Animation` property to access the associated `ISkeletonAnimation` from a `SkeletonRenderer` or `SkeletonGraphic` object. For members that are not exposed by the `ISkeletonRenderer` interface,  you can cast `skeletonAnimation.Renderer` to `SkeletonRenderer` or `SkeletonGraphic` respectively to access the renderer member variables.
+
+### Example Code
+```csharp
+// Old SkeletonRenderer property access from SkeletonAnimation
+skeletonAnimation.zSpacing = 0.1f;
+skeletonAnimation.AnySkeletonRendererProperty;
+
+// New SkeletonRenderer property access from SkeletonAnimation
+skeletonAnimation.Renderer.MeshSettings.zSpacing = 0.1f; // exposed in ISkeletonRenderer interface
+var skeletonRenderer = (SkeletonRenderer)skeletonAnimation.Renderer;
+skeletonRenderer.AnySkeletonRendererProperty; // not exposed in ISkeletonRenderer interface
+
+```
+
+---
+
+## ▶️ SkeletonMecanim
+
+### Breaking Changes
+
+#### 1. Component Architecture
+- **SkeletonMecanim is now a separate component from SkeletonRenderer**, no longer a subclass.
+- Same access pattern as [SkeletonAnimation](#▶️-skeletonanimation).
+
+#### 2. Method Changes
+- `Update()` is no longer public.
+- Use `UpdateIfNecessary()` or `Update(0)` to force update.
+
+### Field and Property Migration
+
+Same as [SkeletonAnimation](#▶️-skeletonanimation) above.
+---
+
+## ▶️ SkeletonGraphic
+
+### Breaking Changes
+
+#### 1. Component Architecture
+- **SkeletonGraphic no longer covers animation, add SkeletonAnimation as a separate animation component**.
+- Animation accessed via: `skeletonGraphic.Animation`.
+
+#### 2. Changing Existing References to SkeletonAnimation
+
+If your components are holding a reference to `SkeletonGraphic` only to modify its animation properties, it is recommended to change the reference type to `SkeletonAnimation`.
+This way you can access animation state like `skeletonAnimation.AnimationState`
+instead of having to cast it like `((SkeletonAnimation)skeletonGraphic.Animation).AnimationState`. Note that if you want to change the name of serialized component variables, you can use the `[FormerlySerializedAs("previousName")]` attribute in front of a variable definition to automatically reassign your existing serialized value.
+
+#### Example Code
+```csharp
+// Automatically reassign previous serialized values
+[FormerlySerializedAs("skeletonGraphic")]
+public SkeletonAnimation skeletonAnimation; // Will maintain the reference after upgrade
+```
+
+#### 3. Property Changes
+- Removed property `AnimationState` - query it from the `SkeletonAnimation` component instead.
+- `MeshGenerator` is no longer public - use `MeshSettings` property and `SetMeshSettings()` instead.
+- `MaterialsMultipleCanvasRenderers` type changed from `ExposedList<Material>` to `Material[]`.
+
+#### 4. Creation Helper Methods
+- `NewSkeletonGraphicGameObject` now creates both `SkeletonGraphic` and `SkeletonAnimation` to maintain existing behaviour. Return type changed to return both component references in a single struct.
+- `AddSkeletonGraphicComponent` is removed and replaced by:
+  - `AddSkeletonGraphicAnimationComponents` - creates both `SkeletonGraphic` and `SkeletonAnimation` components.
+  - `AddSkeletonGraphicRenderingComponent` - creates only `SkeletonGraphic` component.
+
+#### 5. Event Changes
+- Delegate signature changed from `SkeletonRendererDelegate(SkeletonGraphic)` to `SkeletonRendererDelegate(ISkeletonRenderer)`. This affects events: `OnRebuild`, `OnMeshAndMaterialsUpdated`.  
+To fix any compile errors, change your method parameter from SkeletonGraphic to ISkeletonRenderer.
+
+#### 6. Execution Order
+- `SkeletonRenderer` and `SkeletonGraphic` components received `DefaultExecutionOrder(1)]` which makes them run after default *(order=0)* scripts. This ensures animations are applied before the skeleton is updated even if `UpdateTiming` is set to `InLateUpdate`.
+
+#### 7. Behaviour Changes - Material Updates
+- Materials at each `CanvasRenderer` are no longer updated every `LateUpdate`, instead they are updated when either:
+  - a) the updated skeleton requires a change of materials, or
+  - b) when `CustomMaterialOverride` or `CustomTextureOverride` were accessed and thus potentially modified.
+
+### Field and Property Migration
+
+#### Animation Properties
+| **Old API** | **New API** | **Notes** |
+|-------------------|-------------------|-----------|
+| `skeletonGraphic.AnimationState` | `((SkeletonAnimation)skeletonGraphic.Animation).AnimationState` | Cast required |
+| `skeletonGraphic.startingAnimation` | `skeletonAnimation.AnimationName` | Via Animation component |
+| `skeletonGraphic.startingLoop` | `skeletonAnimation.loop` | Via Animation component |
+| `skeletonGraphic.timeScale` | `skeletonAnimation.timeScale` | Via Animation component |
+| `skeletonGraphic.unscaledTime` | `skeletonAnimation.unscaledTime` | Via Animation component |
+
+#### Mesh Generator Settings
+| **Old API** | **New API** | **Notes** |
+|-------------------|-------------------|-----------|
+| `skeletonGraphic.MeshGenerator.settings` | `skeletonGraphic.MeshSettings` | Direct access to settings |
+
+---
+
+## ⚠️ Additional Important Notes
+
+### Preventing Lost Component References
+Any references by other components (e.g. `SkeletonRenderSeparator`) that reference a `SkeletonRenderer` component and had a `SkeletonAnimation` or `SkeletonMecanim` target will be pointing to *null* after the upgrade, since the `SkeletonAnimation` and `SkeletonMecanim` components are no longer subclasses of `SkeletonRenderer` and thus no valid reference. The manual solution is to leave the type as `SkeletonRenderer` and lose references to `SkeletonAnimation` (will be set to *none*). Then you need to manually re-assign the lost references in your scenes and prefabs. A semi-automatic alternative solution is as follows: change the type of your `SkeletonRenderer` variable to `Component` (to capture the object reference and not lose it) and add a second variable of type `SkeletonRenderer` (or `SkeletonAnimation`) and then programmatically read it from the `Component` variable and assign it to the newly added variable. You can e.g. do this automatically in the Unity Editor in `Awake()` with an `[ExecuteAlways]` tag added to your component.  
+
+#### Example code
+  ```csharp
+// Old class before upgrading
+public class TestMigrateReferences : MonoBehaviour {
+	public SkeletonRenderer skeletonRenderer; // this SkeletonAnimation reference assigned here would be lost after upgrading.
+
+	public void Foo () {
+		skeletonRenderer.skeleton.ScaleX = -1;
+	}
+}
+
+// New class after upgrading
+[ExecuteAlways] // or [ExecuteInEditMode]
+public class TestMigrateReferences : MonoBehaviour {
+#if UNITY_EDITOR
+	[SerializeField, HideInInspector, FormerlySerializedAs("skeletonRenderer")] Component previousSkeletonRenderer; // this captures the old SkeletonAnimation reference assigned at the name skeletonRenderer.
+#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
+}
+```
+
+### Component Enable/Disable
+Since `ISkeletonRenderer` and `ISkeletonAnimation` components are now separate, scripts that enable/disable any of these components need adjustment to **enable/disable both**.
+
+### SkeletonUtilityBone Behaviour Change
+In mode Override, `SkeletonUtilityBone` no longer adjusts the Transform in `UpdatePhase.World`, only in `UpdatePhase.Complete` (removes redundant update).
+
+### Automatic Migration
+- Unity Editor automatically transfers deprecated fields when `AUTO_UPGRADE_TO_43_COMPONENTS` is defined.
+- To upgrade all scenes and prefabs at once, go to `Edit - Preferences - Spine` and select `Upgrade Scenes & Prefabs` - `Upgrade All`.
+- The `UpgradeTo43` and `TransferDeprecatedFields()` methods in each class handles serialized data migration.
+- Manual code updates are still required for runtime access.
+
+### Summary of Most Common Changes
+1. **Add `.Renderer.`** prefix to access rendering properties from animation components.
+2. **Add `.MeshSettings.`** to access mesh generation settings.
+3. **Cast to SkeletonAnimation** when accessing AnimationState from SkeletonGraphic.
+4. **Update delegate method signatures** from concrete types to interfaces.
+5. **Re-assign lost references** after upgrade using the migration pattern above.
+
+---
+
+## Disabling Automatic Upgrade Checks
+
+Once you have completed the migration of all your Spine assets, scenes, and prefabs, you can disable the automatic upgrade checks to improve editor performance:
+
+1. Go to `Edit → Preferences → Spine`
+2. Under `Automatic Component Upgrade`, click `Split Component Upgrade` → `Disable`
+
+This will stop the Unity Editor from performing in-editor checks upon scene or prefab loading to determine whether components need to be migrated. You can re-enable it at any time if you need to migrate additional assets.
+
+---
+
+## Need Help?
+
+If you encounter any unexpected problems during migration or find that component properties are incorrectly migrated, please post on the [Spine forum](https://esotericsoftware.com/forum). We're happy to help and fix any issues to make automatic migration as painless as possible.

Client/Assets/Spine/Documentation/4.3-split-component-upgrade-guide.md.meta

@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: 3c30cad54c352c542a01a50ad3b6b8fe
+timeCreated: 1759519802
+licenseType: Free
+DefaultImporter:
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: