MonoFSM

Files (23)

• SKILL.md
• SKILL.md.meta
• references.meta
• components.md · references/
• components.md.meta · references/
• csharp-patterns.md · references/
• csharp-patterns.md.meta · references/
• design-patterns.md · references/
• design-patterns.md.meta · references/
• effect-system.md · references/
• effect-system.md.meta · references/
• fsm-traversal.md · references/
• fsm-traversal.md.meta · references/
• scene-editing.md · references/
• scene-editing.md.meta · references/
• serialization-migration.md · references/
• serialization-migration.md.meta · references/
• value-source.md · references/
• value-source.md.meta · references/
• var-wrapper.md · references/
• var-wrapper.md.meta · references/
• writing-actions.md · references/
• writing-actions.md.meta · references/

SKILL.md (first lines)

# MonoFSM

以 GameObject 層級為核心的有限狀態機框架。

## 核心設計

**GameObject 層級表達式**：狀態、轉換、動作和條件都是場景中的 GameObject。

```
[FSM Root]                           # MonoFSMOwner
├── [VarFolder] VariableFolder       # 變數區（VariableFolder + StateMachineLogic）
│   └── f_varName                    # VarFloat / VarEntity 等
│       └── BoundModifier            # VariableFloatBoundModifier（可選）
├── [SchemaFolder] SchemaFolder
├── [StateFolder] StateFolder        # StateMachineLogic 主體
│   └── [State] StateName            # GeneralState
│       ├── OnStateEnterHandler      # 進入時觸發 → 子層放 Action
│       │   └── [Action] XxxAction   # AbstractStateAction 實作
│       ├── [Timer] TimerName        # VarFloatCountDownTimer（可選）
│       └── [Transition] => Target   # TransitionBehaviour
│           └── [Condition] Name     # AbstractConditionBehaviour 實作
└── Context                          # MonoContext
```

## 場景編輯（Unity MCP）

直接用 MCP 工具在 Scene 中編輯 FSM，見 [references/scene-editing.md](references/scene-editing.md)。

## 程式化讀取 FSM 結構

實作 Editor 工具（匯出、視覺化、批次修改）需要 traverse MonoFSM 階層時，見 [references/fsm-traversal.md](references/fsm-traversal.md)。涵蓋 StateFolder 偵測、變數/狀態/轉換/條件/動作的走訪規則，以及 `AnimatorPlayAction` 不繼承 `AbstractStateAction` 等 gotcha。實作範本：`MonoFSM/1_MonoFSM_Core/Editor/PrefabExporter/FsmTextExporter.cs`。

## Auto Attributes

```csharp
[Auto]                               // GetComponent<T>()
[AutoParent]                         // GetComponentInParent<T>()
[AutoChildren]                       // GetComponentsInChildren<T>()
[AutoChildren(DepthOneOnly = true)]  // 僅直接子物件
```

欄位型別可以是 interface（`[AutoParent] private ICurrentEntityOwner _owner;`），底層走 `GetComponentInParent(Type, true)`，取到的是**最近的一顆** parent，可用來當「多種容器共用同一個 child 元件」的自動接線。

### Editor 下 Auto 欄位還沒解析：用 AutoReferenceFieldEditor

Auto 系列在 **editor 下要等 Inspector 被點開才會解析**，所以 `Description`、`IsValid` 這類「畫 hierarchy 就會被呼叫」的成員裡，Auto 欄位常常還是 null → NRE 或一直噴 error。**不要**自己寫 `GetComponentInParent` 補，也不要用 `if (Application.isPlaying)` 迴避，要當場補解析：

```csharp
[ShowInInspector] [AutoParent] private ICurrentEntityOwner _owner;

private ICurrentEntityOwner Owner
{
    get
    {
        if (_owner == null)
            AutoAttributeManager.AutoReferenceFieldEditor(this, nameof(_owner));
        return _owner;
    }
}
```

- `AutoAttributeManager` 在 global namespace，不用 using；方法標了 `[Conditional("UNITY_EDITOR")]`，build 時整個 call site 被移除，內部又自己 `if (Application.isPlaying) return`，**runtime 零成本**
- 走的是同一顆 attribute 的 `Execute`，`LimitedType` / includeSelf 等設定都會被尊重，不會把語意寫死
- 反射結果進 `FieldCache`，比每次 `GetComponentInParent` 便宜
- 即使補了解析仍可能是 null（真的沒接），呼叫端還是要 null guard；**error log 只在 `Application.isPlaying` 時才印**，否則 editor 會刷滿 console
- 既有範例：`AbstractMonoVariable.HasParentVarEntity`、`MonoEntity._fsmLogic`、`MonoBlackboard` 的各 folder、`ValueProvider._parentEntity`、`VarEntityCurrentItem.Owner`

## 其他常用 Attributes

```csharp
[Required]       // 必填欄位（Inspector 警告）
[CompRef]        // 標記為組件引用
[DropDownRef]    // 下拉選擇（需手動在 Inspector 設定，MCP 無法設定此類型）
[SOConfig("子資料夾名")] // ScriptableObject 欄位用，提供 Create 按鈕與路徑選擇器
```

### SOConfig 注意事項

`[SOConfig]` 的 Drawer（`SOConfigAttributeDrawer`）使用 `IList.Add()` 新增資產，因此：
- **集合欄位必須用 `List<T>`，不可用 `T[]`**（原生陣列大小固定，`Add()` 會拋 `NotSupportedException`）
- 範例：`[SerializeField] [SOConfig("StateTags")] private List<StateTag> _stateTags = new();`

## 狀態優先級

狀態有 `Priority` 屬性，高優先級狀態不會被低優先級狀態打斷。

## 狀態進入條件

**優先把「能否進入此 State」的條件放在目標 State 的 `CanEnterState`。**
不要把相同條件分散複製到各個來源 State 的 Transition；這樣多個 State 要轉入同一目標時，只需各自建立轉向該 State 的 Transition，進入資格仍由目標 State 統一維護。

只有條件確實取決於「從哪個來源 State 離開」時，才放在該來源的 Transition。

## Transition 評估順序（AbstractStateBehaviour.IMonoState.OnFixedUpdate）

1. 目前 state 底下的 transition 照 **sibling 順序**跑，第一條成立就 `TryActivateState` 並 return。
2. 自己的都沒過，才問 `StateFolder.AllAnyStates` 的 transition；AnyState 指向目前 state 的那條會跳過。
3. 一條 transition 要過：condition 全部 AND（`IsAllValid`）+ source（自己或 AnyState）的 CanExit + target 的 CanEnter；
   接著 `TryActivateState` 再問一次**目前 state** 的 CanExit（含 priority）+ target CanEnter，target 也不能是目前 state。
4. 條件過了但 TryActivateState 被擋，**不會記任何東西**：看 `FsmTrace.CaptureSnapshot` 的 `canExit` / `canEnter` 欄。
5. 因為 2、3 兩道擋，AnyState 目標 state 的 CanEnter **不用自己加「!Is 自己」**。要擋的是「終點 state → 又回到這裡」，例如 Destroying 的 CanEnter 加 `!Is [State] Destroyed`。

### 網路同步會繞過 transition 直接改 state

- `StateMachine.Network.cs` 的 `ReadNetworkData`（IBeforeAllTicks）、`RestoreState`（resim / restore）、proxy 的 `Interpolate()`，
  都會**直接覆寫 `_activeStateId` / `_stateChangeTick`**，不走 transition、CanEnter，也不會跑 OnExit。
- `StateMachine.Render()` 只要看到 state id **或** changeTick 變了，就重跑 `OnEnterStateRender`。所以 client 上看到 enter 的視覺重播，
  不一定是 sim 重進，可能只是 changeTick 被同步蓋過去。
- 懷疑是這條路時，先開 FsmTrace 看 `Previous` 和 `IsResim` / `ProxyRender`。`IsResimFalse` 而且 Previous 是終點 state，就是 authority sim 自己轉的，
  不是網路蓋的，回去查 CanEnter 的 condition。

### 陷阱：module pack 的 state 靠 `_bindingRoot` 找 Owner

- 靠 `StateFolder._bindingRoot` 併進宿主 FSM 的 module pack（例如 Hittable_Destroyable ModulePack），parent 鏈上沒有 MonoFSMOwner。
  `AbstractStateBehaviour.Owner` 找不到的時候，會改抓 binding root 上的 owner（2026-10-01 補的）。
- 補之前 Owner 是 null，`IsStateCondition` 永遠 false，勾 Inverted 就變成永遠 true。實際發生過：`!Is [State] Destroyed` 沒擋到，
  造成 AnyState → Destroying → Destroyed 一直循環。現在 Owner 找不到的 IsStateCondition 會在 hierarchy 標紅。

## ModulePack：併進宿主 entity 的模組

From RED-CANDLE-GAMES-CO-LTD/MonoFSM, MIT.

More from RED-CANDLE-GAMES-CO-LTD/MonoFSM