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

Pass a non-null IEntityGroupHelper implementation (e.g. a component deriving EntityGroupHelper) to AddEntityGroup

EllanJiang/GameFramework · error · GameFrameworkException

Entity group helper is invalid.

Error message

Entity group helper is invalid.

What it means

The EntityGroup constructor throws this when the IEntityGroupHelper argument is null. The helper is required to create/hide entity instance objects, so the group cannot function without it. Thrown right after the name check in the constructor, reached via EntityManager.AddEntityGroup.

Solutions

Pass a non-null IEntityGroupHelper implementation (e.g. a component deriving EntityGroupHelper) to AddEntityGroup
In Unity, assign the helper in the inspector or create one with AddComponent before adding the group
Guard the call: if (helper == null) throw/log before calling AddEntityGroup

Example fix

// before
entityGroupHelper = null;
entityManager.AddEntityGroup("Player", 0, 16, 60, 0, entityGroupHelper, objectPoolManager);
// after
var helper = entityGroupHelper != null ? entityGroupHelper : gameObject.AddComponent<EntityGroupHelper>();
entityManager.AddEntityGroup("Player", 0, 16, 60, 0, helper, objectPoolManager);

Defensive patterns

Strategy: validation

Validate before calling

if (entityGroupHelper == null) throw new ArgumentNullException(nameof(entityGroupHelper), "An IEntityGroupHelper implementation is required");

Type guard

static bool HasValidHelper(IEntityGroupHelper helper) => helper != null;

Try / catch

try { entityManager.AddEntityGroup(name, 0, 16, 60, 0, helper, poolManager); } catch (GameFrameworkException ex) when (ex.Message == "Entity group helper is invalid.") { Log.Error("EntityGroupHelper was null when adding group '{0}'", name); }

Prevention

In Unity, obtain the helper via GetComponent/AddComponent rather than nullable fields
Never pass 'as SomeHelper' results directly without a null check
Wire helpers in one initialization method so missing references surface immediately

When it happens

Trigger: Calling AddEntityGroup passing null for the entityGroupHelper argument, or passing a field/property that was never assigned (e.g. not wired in the Unity inspector).

Common situations: Forgetting to add an EntityGroupHelper component to the GameObject and passing it; constructing the group in pure code and forgetting `new EntityGroupHelper()`; a DI/reference that resolves to null at runtime.

Related errors

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

Appendix: source

Thrown at GameFramework/Entity/EntityManager.EntityGroup.cs:45

            /// 初始化实体组的新实例。
            /// </summary>
            /// <param name="name">实体组名称。</param>
            /// <param name="instanceAutoReleaseInterval">实体实例对象池自动释放可释放对象的间隔秒数。</param>
            /// <param name="instanceCapacity">实体实例对象池容量。</param>
            /// <param name="instanceExpireTime">实体实例对象池对象过期秒数。</param>
            /// <param name="instancePriority">实体实例对象池的优先级。</param>
            /// <param name="entityGroupHelper">实体组辅助器。</param>
            /// <param name="objectPoolManager">对象池管理器。</param>
            public EntityGroup(string name, float instanceAutoReleaseInterval, int instanceCapacity, float instanceExpireTime, int instancePriority, IEntityGroupHelper entityGroupHelper, IObjectPoolManager objectPoolManager)
            {
                if (string.IsNullOrEmpty(name))
                {
                    throw new GameFrameworkException("Entity group name is invalid.");
                }

                if (entityGroupHelper == null)
                {
                    throw new GameFrameworkException("Entity group helper is invalid.");
                }

                m_Name = name;
                m_EntityGroupHelper = entityGroupHelper;
                m_InstancePool = objectPoolManager.CreateSingleSpawnObjectPool<EntityInstanceObject>(Utility.Text.Format("Entity Instance Pool ({0})", name), instanceCapacity, instanceExpireTime, instancePriority);
                m_InstancePool.AutoReleaseInterval = instanceAutoReleaseInterval;
                m_Entities = new GameFrameworkLinkedList<IEntity>();
                m_CachedNode = null;
            }

            /// <summary>
            /// 获取实体组名称。
            /// </summary>
            public string Name
            {
                get
                {
                    return m_Name;

View on GitHub (pinned to d0c010b051)