MonoObj Lifecycle

MonoObj 的每幀更新透過 WorldUpdateSimulator 集中管理，以介面驅動方式分階段執行。

執行時序

LocalSimulatorRunner.FixedUpdate / FusionSimulatorRunner.BeforeTick + FixedUpdateNetwork
├── World.BeforeSimulate(...)               → IBeforeSimulate
├── World.Simulate(...)                     → IUpdateSimulate
└── World.AfterSimulate(...)                → IAfterSimulate

LocalSimulatorRunner.LateUpdate / FusionSimulatorRunner.Render
└── World.Render(...)                       → IRenderUpdate

LocalSimulatorRunner.LateUpdate 尾段 / FusionSimulatorRunner.AfterRender
└── World.AfterRender()                     → IAfterRenderMono

每顆註冊的 MonoObj 都是獨立 scope。[AutoChildren(StopAtType = typeof(MonoObj))] 不會跨進 nested MonoObj；nested MonoObj 會自己註冊並被 WorldUpdateSimulator 呼叫，不是由 root 遞迴代跑。

初始化時序：ISceneAwake / ISceneStart

一次性初始化不要寫在 Unity 的 Awake() / Start()，改用這兩個介面（都在 global namespace， 定義於 MonoFSM/1_MonoFSM_Core/Runtime/Entity/IResetter.cs）：

介面	方法	時機
ISceneAwake	EnterSceneAwake()	由 WorldUpdateSimulator.WorldInit() 分派，早於 ISceneStart
ISceneStart	EnterSceneStart()	WorldInit 後段，此時 MonoDict 等系統已 prepared

WorldInit 的觸發點：單機是 LocalSimulatorRunner.Start()；Fusion 是 FusionSimulatorRunner.OnSceneLoadDone()（幾乎鐵定晚於一般 Unity Start()）。

坑 1：ISceneAwake 只由 MonoObj 對自己子樹分派

MonoObj（MonoFSM/1_MonoFSM_Core/Runtime/LifeCycle/Update/MonoObj.cs）是對自己的 GetComponentsInChildren<ISceneAwake> 分派；SceneLifecycleManager.HandleGameLevelAwake(level) 同樣只掃指定 level 物件的子樹。

→ 直接在 scene 建一顆裸 root GameObject 掛 ISceneAwake 元件，EnterSceneAwake() 永遠不會被呼叫， 而且完全沒有錯誤訊息。症狀是「元件欄位都填好了但初始化沒發生」（例如 static 注入仍是 null）。

做法：這類「場景放一顆就好」的 installer 要掛在某個帶 MonoObj 的節點子樹下（本專案用 FusionFPS Core/GameCore）。除錯時先檢查它要寫的目標值是否真的被設，再往上確認 parent 有沒有 MonoObj。

MonoObj._sceneStarts 是 [AutoChildren] 的 interface array，runtime 由 AutoAttributeManager 重抓， 改完不需要重存 prefab（除非該 prefab 有 PrefabSerializeCache）。

坑 2：在 Start() 裡呼叫 GetVar 會靜默拿到 null

MonoDict.Get(key)（MonoFSM/1_MonoFSM_Core/Runtime/0_Pattern/MonoDict.cs）在 _isPrepared == false && Application.isPlaying 時只印一行 GetFrom {key} Dict, Not prepared 就回 default。 _isPrepared 要等 MonoDict.EnterSceneAwake()，也就是 WorldInit 之後才成立。

→ 任何在 Unity Start() 裡呼叫 entity.GetVar(tag) / VariableFolder.GetVariable(...) 的程式碼都不保證拿得到東西。 危險的是常見的過濾寫法 RemoveAll(e => e.GetVar(tag) == null)：整份清單被清空，又只 cache 一次不會重抓 —— Console 只留一行 error，遊戲端是靜默空資料，很難聯想到時序問題。

做法：「一次性抓取 + 快取」的 component 一律實作 ISceneStart.EnterSceneStart()，不要用 Start() （AbstractDescriptionBehaviour.Start() 本身就標了 //FIXME: 不該用這個？）。前提同樣是該 component 要在有 MonoObj 的子樹下（見坑 1）。

更新介面

所有介面定義於 MonoFSM/1_MonoFSM_Core/Runtime/LifeCycle/Update/Simulate/IUpdateSimulate.cs。

介面	方法	時機	用途
IBeforeSimulate	BeforeSimulate(float deltaTime)	FixedUpdate 開頭	輸入處理、前置計算
IUpdateSimulate	Simulate(float deltaTime)	FixedUpdate 主體	核心模擬邏輯
IAfterSimulate	AfterSimulate(float deltaTime)	FixedUpdate 尾段	後處理、同步
IRenderUpdate	Render(float runnerLocalRenderTime)	Local LateUpdate / Fusion Render	視覺更新、插值、動畫；不吃 ShouldSimulte authority gate
IAfterRenderMono	AfterRender()	Fusion AfterRender / local render 尾段	必須晚於一般 Render 的視覺收尾

實作模式

實作任一介面並掛在 MonoObj 子物件上，會被 [AutoChildren] 自動收集。

public class MyVisualUpdater : MonoBehaviour, IRenderUpdate
{
    public void Render(float deltaTime)
    {
        // 視覺插值、動畫更新等
    }
}

public class MySimulator : MonoBehaviour, IUpdateSimulate
{
    public void Simulate(float deltaTime)
    {
        // 核心模擬邏輯
    }

    // 可選：控制執行順序（數字越小越先）
    public int SimulateOrder => 10;
}

關鍵檔案

檔案	職責
WorldUpdateSimulator.cs	世界更新中心，管理所有 MonoObj 的註冊與每幀迭代
LocalSimulatorRunner.cs	本地模式的 Runner，驅動 FixedUpdate/LateUpdate
MonoObj.cs	持有各階段介面陣列，轉發更新呼叫
IUpdateSimulate.cs	所有更新介面定義

Culling phase gate

MonoObj 支援三種 handle，三者都由自己 scope 內的 [AutoChildren(StopAtType = MonoObj)] 自動收集：

Handle	停止的 phase	用途
CullingActiveHandle	Simulate + Render 全部	legacy 相容；只有真的要整顆暫停才用
SimulationCullingActiveHandle	BeforeSimulate / Simulate / AfterSimulate	距離型 gameplay、AI、sensor 成本控制
RenderCullingActiveHandle	Render / AfterRender	Renderer、VFX、Animator 等本機視覺成本控制

MonoObj.IsCulling 為既有 gameplay 相容介面，等同 IsSimulationCulling。Render 專用判斷看 IsRenderCulling。parent 的 simulation/render culling 會分 phase 傳給 nested MonoObj； _isIgnoreParentObjCulling 會同時切斷兩種 parent phase 繼承。

共用 module Packages/com.monofsm.pro/Prefabs/Prefab Modules/Culling Event Target.prefab 的標準串法：

• NearOnly → SimulationCullingActiveHandle
• Visible OR Near → RenderCullingActiveHandle

CullingEventTarget、root MonoObj、NetworkObject / NetworkBehaviour、同步用 Var/FSM 與 RenderLoopHandler 本身留在 always-on shell，不要放進被 CullingTargetGameObjects 關閉的 root。 CullingGroup visibility 是各 peer 的 camera-local 結果，只能控制本機 scheduling/visual，不能拿來改 network state 或 authority。

注意事項

項目	說明
nested MonoObj 獨立更新	每顆 nested MonoObj 都要註冊；StopAtType 讓各 scope 不重複收集 loop component
Proxy 的 logic / visual 分流	Simulate 由 ShouldSimulte（State/Input Authority）擋；Render 不吃 authority gate，所以 non-simulated proxy 也能更新本機視覺
IsReady 檢查	WorldUpdateSimulator 在 WorldInit() 後才開始更新
TimeScale	透過 WorldUpdateSimulator.DeltaTime 取得含 TimeScale 的 deltaTime
Simulate vs Render	local 為 FixedUpdate/LateUpdate；Fusion 為 FixedUpdateNetwork/Render。不要把 Render 寫成依賴 local camera 的 authoritative logic