EllanJiang/GameFramework · critical · GameFrameworkException

You must set UI form helper first.

Error message

You must set UI form helper first.

What it means

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.

Solutions

1. Call uiManager.SetUIFormHelper(new DefaultUIFormHelper(...)) (or your custom helper) during initialization
2. If using UnityGameFramework's UIComponent, let it wire the helper instead of using a raw UIManager
3. Verify initialization completes before any UI opening code runs

Example fix

// before
uiManager.OpenUIForm("BattleHud"); // helper never set
// after
uiManager.SetUIFormHelper(new DefaultUIFormHelper());
uiManager.OpenUIForm("BattleHud");

if (!uiInitialized) { Log.Error("UIManager helper not set yet"); return; }

bool HelperReady(UIManager m) => m != null; // helper set tracked by your init flag

try { uiManager.OpenUIForm(assetName, groupName); }
catch (GameFrameworkException ex) { Log.Fatal($"OpenUIForm without helper: {ex.Message}"); }

When it happens

Trigger: Calling OpenUIForm when m_UIFormHelper is null — i.e. SetUIFormHelper was never invoked, or was invoked on a different UIManager instance.

Common situations: 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.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• You must set resource manager first.
• Resource helper is invalid.
• Setting helper is invalid.
• You can not use VerifyResourcePack at this time.
• You must set download manager first.

AI-assisted analysis of EllanJiang/GameFramework@d0c010b051 (2026-09-15). Data as JSON: /api/errors/e6101c86f8326d70. Report an issue: GitHub.

Appendix: source

Thrown at GameFramework/UI/UIManager.cs:732

        /// <summary>
        /// 打开界面。
        /// </summary>
        /// <param name="uiFormAssetName">界面资源名称。</param>
        /// <param name="uiGroupName">界面组名称。</param>
        /// <param name="priority">加载界面资源的优先级。</param>
        /// <param name="pauseCoveredUIForm">是否暂停被覆盖的界面。</param>
        /// <param name="userData">用户自定义数据。</param>
        /// <returns>界面的序列编号。</returns>
        public int OpenUIForm(string uiFormAssetName, string uiGroupName, int priority, bool pauseCoveredUIForm, object userData)
        {
            if (m_ResourceManager == null)
            {
                throw new GameFrameworkException("You must set resource manager first.");
            }

            if (m_UIFormHelper == null)
            {
                throw new GameFrameworkException("You must set UI form helper first.");
            }

            if (string.IsNullOrEmpty(uiFormAssetName))
            {
                throw new GameFrameworkException("UI form asset name is invalid.");
            }

            if (string.IsNullOrEmpty(uiGroupName))
            {
                throw new GameFrameworkException("UI group name is invalid.");
            }

            UIGroup uiGroup = (UIGroup)GetUIGroup(uiGroupName);
            if (uiGroup == null)
            {
                throw new GameFrameworkException(Utility.Text.Format("UI group '{0}' is not exist.", uiGroupName));
            }

View on GitHub (pinned to d0c010b051)