EllanJiang/GameFramework · error · GameFrameworkException

Can not attach entity when child entity status is

Error message

Can not attach entity when child entity status is '{0}'.

What it means

AttachEntity rejects a child whose lifecycle status has reached EntityStatus.WillHide or beyond (e.g. WillHide/WillDelete). Entities already scheduled to hide or be deleted cannot be re-parented, so the library throws with the current status in the message.

Solutions

  1. Check child status (or your own flag) before attaching and cancel if >= WillHide
  2. Avoid HideEntity/DeleteEntity and AttachEntity racing: sequence them explicitly
  3. Defer the attach until the child is shown and stable

Example fix

// before
entityManager.AttachEntity(childId, parentId, userData);
// after
if (child.Status < EntityStatus.WillHide) entityManager.AttachEntity(childId, parentId, userData);
Defensive patterns

Strategy: validation

Validate before calling

var info = entityManager.GetEntity(childEntityId); if (info == null || info.Status >= EntityStatus.WillHide) return;

Try / catch

try { entityManager.AttachEntity(childId, parentId, userData); }
catch (GameFrameworkException ex) { /* child busy hiding/deleting; retry later or skip */ }

Prevention

When it happens

Trigger: Calling AttachEntity on a child that is in the process of being hidden, deleted, or otherwise transitioning (status >= WillHide) — often from an async callback that raced with a HideEntity call.

Common situations: Animation-complete handlers firing after HideEntity was requested; pooled entities recycled while a delayed attach was pending; attaching during scene unload.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

Thrown at GameFramework/Entity/EntityManager.cs:922

        /// <param name="childEntityId">要附加的子实体的实体编号。</param>
        /// <param name="parentEntityId">被附加的父实体的实体编号。</param>
        /// <param name="userData">用户自定义数据。</param>
        public void AttachEntity(int childEntityId, int parentEntityId, object userData)
        {
            if (childEntityId == parentEntityId)
            {
                throw new GameFrameworkException(Utility.Text.Format("Can not attach entity when child entity id equals to parent entity id '{0}'.", parentEntityId));
            }

            EntityInfo childEntityInfo = GetEntityInfo(childEntityId);
            if (childEntityInfo == null)
            {
                throw new GameFrameworkException(Utility.Text.Format("Can not find child entity '{0}'.", childEntityId));
            }

            if (childEntityInfo.Status >= EntityStatus.WillHide)
            {
                throw new GameFrameworkException(Utility.Text.Format("Can not attach entity when child entity status is '{0}'.", childEntityInfo.Status));
            }

            EntityInfo parentEntityInfo = GetEntityInfo(parentEntityId);
            if (parentEntityInfo == null)
            {
                throw new GameFrameworkException(Utility.Text.Format("Can not find parent entity '{0}'.", parentEntityId));
            }

            if (parentEntityInfo.Status >= EntityStatus.WillHide)
            {
                throw new GameFrameworkException(Utility.Text.Format("Can not attach entity when parent entity status is '{0}'.", parentEntityInfo.Status));
            }

            IEntity childEntity = childEntityInfo.Entity;
            IEntity parentEntity = parentEntityInfo.Entity;
            DetachEntity(childEntity.Id, userData);
            childEntityInfo.ParentEntity = parentEntity;
            parentEntityInfo.AddChildEntity(childEntity);

View on GitHub (pinned to d0c010b051)