EllanJiang/GameFramework · error · GameFrameworkException

Entity asset is invalid.

Error message

Entity asset is invalid.

What it means

EntityInstanceObject.Create builds the pooled object that pairs an entity asset with its instance and helper. It throws GameFrameworkException when the entityAsset argument is null, since the pooled object exists to hold that asset reference. Raised during entity show flows when the loaded asset is missing.

Solutions

1. Ensure the entity asset is loaded and non-null before creating the instance object.
2. Check the entity info table: the asset name must exist in your resource package.
3. Verify the asset load completed (load dependency/callback) before showing the entity.
4. Null-check entityAsset if you call Create from custom code.

Example fix

// before
var obj = EntityInstanceObject.Create(name, entityAsset, instance, helper);
// after
if (entityAsset == null) throw new InvalidOperationException("Entity asset not loaded: " + name);
var obj = EntityInstanceObject.Create(name, entityAsset, instance, helper);

if (entityAsset == null) throw new InvalidOperationException("Entity asset not loaded: " + name);
var obj = EntityInstanceObject.Create(name, entityAsset, entityInstance, entityHelper);

bool HasAsset(object entityAsset) => entityAsset != null;

try { var obj = EntityInstanceObject.Create(name, entityAsset, instance, helper); }
catch (GameFrameworkException ex) { Log.Error("Instance object create failed: {0}", ex.Message); }

When it happens

Trigger: Calling EntityInstanceObject.Create(name, null, entityInstance, entityHelper) directly, or ShowEntity flow where the asset loaded from the entity table was null (failed/missing AssetObject).

Common situations: Entity asset name not present in resource/asset configuration; asset load failed but null was propagated instead of surfacing the load error; custom derived EntityManager supplying null assets.

Related errors

• Code is invalid.
• Data provider helper is invalid.
• Data row type is invalid.
• Download manager is invalid.
• Entity helper is invalid.

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

Appendix: source

Thrown at GameFramework/Entity/EntityManager.EntityInstanceObject.cs:32

        /// <summary>
        /// 实体实例对象。
        /// </summary>
        private sealed class EntityInstanceObject : ObjectBase
        {
            private object m_EntityAsset;
            private IEntityHelper m_EntityHelper;

            public EntityInstanceObject()
            {
                m_EntityAsset = null;
                m_EntityHelper = null;
            }

            public static EntityInstanceObject Create(string name, object entityAsset, object entityInstance, IEntityHelper entityHelper)
            {
                if (entityAsset == null)
                {
                    throw new GameFrameworkException("Entity asset is invalid.");
                }

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

                EntityInstanceObject entityInstanceObject = ReferencePool.Acquire<EntityInstanceObject>();
                entityInstanceObject.Initialize(name, entityInstance);
                entityInstanceObject.m_EntityAsset = entityAsset;
                entityInstanceObject.m_EntityHelper = entityHelper;
                return entityInstanceObject;
            }

            public override void Clear()
            {
                base.Clear();
                m_EntityAsset = null;

View on GitHub (pinned to d0c010b051)