EllanJiang/GameFramework · critical · GameFrameworkException

You must set entity helper first.

Error message

You must set entity helper first.

What it means

EntityManager.ShowEntity throws "You must set entity helper first." when m_EntityHelper is null. The entity helper (IEntityHelper, e.g. DefaultEntityHelper in Unity) is responsible for actually instantiating the entity object, so it must be injected via SetEntityHelper before ShowEntity can run. Like the resource-manager check, this is an initialization-order failure.

Solutions

  1. Call entityManager.SetEntityHelper(new DefaultEntityHelper(...)) (or your helper) during startup before showing entities.
  2. In Unity GameFramework, verify the EntityComponent is present and its entityHelper is assigned/created in Awake.
  3. If constructing EntityManager manually, replicate the full setup: SetResourceManager then SetEntityHelper.

Example fix

// before
var em = new EntityManager();
em.ShowEntity(1, "Entity", "Group"); // throws
// after
var em = new EntityManager();
em.SetResourceManager(resourceManager);
em.SetEntityHelper(new DefaultEntityHelper());
em.ShowEntity(1, "Entity", "Group");
Defensive patterns

Strategy: try-catch

Validate before calling

// verify during bootstrap:
// entityManager.SetResourceManager(resourceManager);
// entityManager.SetEntityHelper(entityHelper); // must precede any ShowEntity

Type guard

bool IsEntityManagerReady(EntityManager em) => em != null; // assert SetEntityHelper was called in your init code

Try / catch

try { entityManager.ShowEntity(entityId, assetName, groupName); }
catch (GameFrameworkException ex) when (ex.Message.Contains("set entity helper first"))
{
    // fail fast / re-run initialization before retrying
}

Prevention

When it happens

Trigger: Calling ShowEntity before SetEntityHelper was called; in Unity, the EntityComponent not finding/creating the helper (e.g. missing component setup), or custom code creating EntityManager manually without setting a helper.

Common situations: Manually constructing EntityManager in tests or non-standard bootstrap without calling SetEntityHelper; Unity scene setup where EntityComponent's helper field was cleared.

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

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

Appendix: source

Thrown at GameFramework/Entity/EntityManager.cs:617

        /// <summary>
        /// 显示实体。
        /// </summary>
        /// <param name="entityId">实体编号。</param>
        /// <param name="entityAssetName">实体资源名称。</param>
        /// <param name="entityGroupName">实体组名称。</param>
        /// <param name="priority">加载实体资源的优先级。</param>
        /// <param name="userData">用户自定义数据。</param>
        public void ShowEntity(int entityId, string entityAssetName, string entityGroupName, int priority, object userData)
        {
            if (m_ResourceManager == null)
            {
                throw new GameFrameworkException("You must set resource manager first.");
            }

            if (m_EntityHelper == null)
            {
                throw new GameFrameworkException("You must set entity helper first.");
            }

            if (string.IsNullOrEmpty(entityAssetName))
            {
                throw new GameFrameworkException("Entity asset name is invalid.");
            }

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

            if (HasEntity(entityId))
            {
                throw new GameFrameworkException(Utility.Text.Format("Entity id '{0}' is already exist.", entityId));
            }

            if (IsLoadingEntity(entityId))

View on GitHub (pinned to d0c010b051)