{"record":{"id":"e6101c86f8326d70","repo":"EllanJiang/GameFramework","slug":"you-must-set-ui-form-helper-first","errorCode":null,"errorMessage":"You must set UI form helper first.","messagePattern":"You must set UI form helper first\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"critical","filePath":"GameFramework/UI/UIManager.cs","lineNumber":732,"sourceCode":"        /// <summary>\n        /// 打开界面。\n        /// </summary>\n        /// <param name=\"uiFormAssetName\">界面资源名称。</param>\n        /// <param name=\"uiGroupName\">界面组名称。</param>\n        /// <param name=\"priority\">加载界面资源的优先级。</param>\n        /// <param name=\"pauseCoveredUIForm\">是否暂停被覆盖的界面。</param>\n        /// <param name=\"userData\">用户自定义数据。</param>\n        /// <returns>界面的序列编号。</returns>\n        public int OpenUIForm(string uiFormAssetName, string uiGroupName, int priority, bool pauseCoveredUIForm, object userData)\n        {\n            if (m_ResourceManager == null)\n            {\n                throw new GameFrameworkException(\"You must set resource manager first.\");\n            }\n\n            if (m_UIFormHelper == null)\n            {\n                throw new GameFrameworkException(\"You must set UI form helper first.\");\n            }\n\n            if (string.IsNullOrEmpty(uiFormAssetName))\n            {\n                throw new GameFrameworkException(\"UI form asset name is invalid.\");\n            }\n\n            if (string.IsNullOrEmpty(uiGroupName))\n            {\n                throw new GameFrameworkException(\"UI group name is invalid.\");\n            }\n\n            UIGroup uiGroup = (UIGroup)GetUIGroup(uiGroupName);\n            if (uiGroup == null)\n            {\n                throw new GameFrameworkException(Utility.Text.Format(\"UI group '{0}' is not exist.\", uiGroupName));\n            }\n","sourceCodeStart":714,"sourceCodeEnd":750,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/UI/UIManager.cs#L714-L750","documentation":"OpenUIForm uses a UI form helper (set via SetUIFormHelper) to actually instantiate UI form instances. If OpenUIForm runs before SetUIFormHelper was called, the framework throws this GameFrameworkException because it has no way to create the form.","triggerScenarios":"Calling OpenUIForm when m_UIFormHelper is null — i.e. SetUIFormHelper was never invoked, or was invoked on a different UIManager instance.","commonSituations":"Custom UI helper setup skipped in bootstrap, creating a raw UIManager without the helper wiring that UIComponent normally does, or init-order issues where OpenUIForm precedes helper registration.","solutions":["Call uiManager.SetUIFormHelper(new DefaultUIFormHelper(...)) (or your custom helper) during initialization","If using UnityGameFramework's UIComponent, let it wire the helper instead of using a raw UIManager","Verify initialization completes before any UI opening code runs"],"exampleFix":"// before\nuiManager.OpenUIForm(\"BattleHud\"); // helper never set\n// after\nuiManager.SetUIFormHelper(new DefaultUIFormHelper());\nuiManager.OpenUIForm(\"BattleHud\");","handlingStrategy":"try-catch","validationCode":"if (!uiInitialized) { Log.Error(\"UIManager helper not set yet\"); return; }","typeGuard":"bool HelperReady(UIManager m) => m != null; // helper set tracked by your init flag","tryCatchPattern":"try { uiManager.OpenUIForm(assetName, groupName); }\ncatch (GameFrameworkException ex) { Log.Fatal($\"OpenUIForm without helper: {ex.Message}\"); }","preventionTips":["Always call SetUIFormHelper right after creating/wiring UIManager in bootstrap","Let UIComponent wire the helper when using UnityGameFramework instead of raw UIManager","Keep a bool 'uiReady' flag checked by all UI-opening code"],"tags":["initialization-order","ui","missing-dependency"],"backgroundTag":"missing-dependency","analyzedSha":"d0c010b05167c58e92350449d04864a91ca13fd2","analyzedAt":"2026-09-15T13:37:15.352Z","contentChangedAt":"2026-09-15T13:37:15.352Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}