What causes "Entity helper is invalid." in EllanJiang/GameFramework?

Create and pass a concrete IEntityHelper instance (e.g. new DefaultEntityHelper().transform as required) before use.

EllanJiang/GameFramework · error · GameFrameworkException

Entity helper is invalid.

Error message

Entity helper is invalid.

What it means

EntityManager.SetEntityHelper rejects a null IEntityHelper argument. The entity helper performs the actual InstantiateObject/CreateEntity work, so without it no entity can be instantiated; the manager throws a GameFrameworkException at configuration time rather than failing later on the first ShowEntity call.

Solutions

Create and pass a concrete IEntityHelper instance (e.g. new DefaultEntityHelper().transform as required) before use.
Ensure the helper GameObject/Component is created if your helper derives from MonoBehaviour and is fetched via GetComponent.
Verify DI/registration code includes the entity helper binding.

Example fix

// before
m_EntityManager.SetEntityHelper(entityHelper); // entityHelper is null

// after
DefaultEntityHelper entityHelper = new GameObject("Entity Helper").AddComponent<DefaultEntityHelper>();
m_EntityManager.SetEntityHelper(entityHelper);

Defensive patterns

Strategy: validation

Validate before calling

IEntityHelper entityHelper = GetComponent<EntityHelperComponent>();
if (entityHelper == null) throw new InvalidOperationException("EntityHelper must be created before entity manager");

Type guard

bool HasEntityHelper(EntityManager em) => em != null && em.EntityHelper != null;

Try / catch

try
{
    entityManager.SetEntityHelper(entityHelper);
}
catch (GameFrameworkException ex)
{
    Debug.LogError($"Entity helper setup failed: {ex.Message}");
}

Prevention

Always instantiate a DefaultEntityHelper (or custom helper) during GameEntry setup.
If the helper is a MonoBehaviour, create its GameObject before injecting.
Include the helper in your DI/registration smoke test.

When it happens

Trigger: Calling EntityManager.SetEntityHelper(null), commonly when a custom EntityHelper class was not instantiated, an assembly/type lookup returned null, or DI setup forgot to register the helper.

Common situations: Forgetting to create the DefaultEntityHelper (or custom helper) instance in GameEntry, custom helper class failing to compile/attach to a GameObject, or refactorings that dropped the helper construction.

Related errors

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

Appendix: source

Thrown at GameFramework/Entity/EntityManager.cs:236

        public void SetResourceManager(IResourceManager resourceManager)
        {
            if (resourceManager == null)
            {
                throw new GameFrameworkException("Resource manager is invalid.");
            }

            m_ResourceManager = resourceManager;
        }

        /// <summary>
        /// 设置实体辅助器。
        /// </summary>
        /// <param name="entityHelper">实体辅助器。</param>
        public void SetEntityHelper(IEntityHelper entityHelper)
        {
            if (entityHelper == null)
            {
                throw new GameFrameworkException("Entity helper is invalid.");
            }

            m_EntityHelper = entityHelper;
        }

        /// <summary>
        /// 是否存在实体组。
        /// </summary>
        /// <param name="entityGroupName">实体组名称。</param>
        /// <returns>是否存在实体组。</returns>
        public bool HasEntityGroup(string entityGroupName)
        {
            if (string.IsNullOrEmpty(entityGroupName))
            {
                throw new GameFrameworkException("Entity group name is invalid.");
            }

            return m_EntityGroups.ContainsKey(entityGroupName);

View on GitHub (pinned to d0c010b051)