{"record":{"id":"50245192998e3c2b","repo":"EllanJiang/GameFramework","slug":"you-must-set-entity-helper-first","errorCode":null,"errorMessage":"You must set entity helper first.","messagePattern":"You must set entity helper first\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"critical","filePath":"GameFramework/Entity/EntityManager.cs","lineNumber":617,"sourceCode":"\n        /// <summary>\n        /// 显示实体。\n        /// </summary>\n        /// <param name=\"entityId\">实体编号。</param>\n        /// <param name=\"entityAssetName\">实体资源名称。</param>\n        /// <param name=\"entityGroupName\">实体组名称。</param>\n        /// <param name=\"priority\">加载实体资源的优先级。</param>\n        /// <param name=\"userData\">用户自定义数据。</param>\n        public void ShowEntity(int entityId, string entityAssetName, string entityGroupName, int priority, object userData)\n        {\n            if (m_ResourceManager == null)\n            {\n                throw new GameFrameworkException(\"You must set resource manager first.\");\n            }\n\n            if (m_EntityHelper == null)\n            {\n                throw new GameFrameworkException(\"You must set entity helper first.\");\n            }\n\n            if (string.IsNullOrEmpty(entityAssetName))\n            {\n                throw new GameFrameworkException(\"Entity asset name is invalid.\");\n            }\n\n            if (string.IsNullOrEmpty(entityGroupName))\n            {\n                throw new GameFrameworkException(\"Entity group name is invalid.\");\n            }\n\n            if (HasEntity(entityId))\n            {\n                throw new GameFrameworkException(Utility.Text.Format(\"Entity id '{0}' is already exist.\", entityId));\n            }\n\n            if (IsLoadingEntity(entityId))","sourceCodeStart":599,"sourceCodeEnd":635,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/Entity/EntityManager.cs#L599-L635","documentation":"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.","triggerScenarios":"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.","commonSituations":"Manually constructing EntityManager in tests or non-standard bootstrap without calling SetEntityHelper; Unity scene setup where EntityComponent's helper field was cleared.","solutions":["Call entityManager.SetEntityHelper(new DefaultEntityHelper(...)) (or your helper) during startup before showing entities.","In Unity GameFramework, verify the EntityComponent is present and its entityHelper is assigned/created in Awake.","If constructing EntityManager manually, replicate the full setup: SetResourceManager then SetEntityHelper."],"exampleFix":"// before\nvar em = new EntityManager();\nem.ShowEntity(1, \"Entity\", \"Group\"); // throws\n// after\nvar em = new EntityManager();\nem.SetResourceManager(resourceManager);\nem.SetEntityHelper(new DefaultEntityHelper());\nem.ShowEntity(1, \"Entity\", \"Group\");","handlingStrategy":"try-catch","validationCode":"// verify during bootstrap:\n// entityManager.SetResourceManager(resourceManager);\n// entityManager.SetEntityHelper(entityHelper); // must precede any ShowEntity","typeGuard":"bool IsEntityManagerReady(EntityManager em) => em != null; // assert SetEntityHelper was called in your init code","tryCatchPattern":"try { entityManager.ShowEntity(entityId, assetName, groupName); }\ncatch (GameFrameworkException ex) when (ex.Message.Contains(\"set entity helper first\"))\n{\n    // fail fast / re-run initialization before retrying\n}","preventionTips":["Call SetEntityHelper immediately after SetResourceManager in one init function so order cannot drift.","In Unity GameFramework, rely on EntityComponent.Awake to set the helper; do not create EntityManager manually without it.","Add an init assert/log in bootstrap confirming both manager and helper are set."],"tags":["gameframework","entity","initialization-order","missing-dependency"],"backgroundTag":"missing-dependency","analyzedSha":"d0c010b05167c58e92350449d04864a91ca13fd2","analyzedAt":"2026-09-15T13:37:15.352Z","contentChangedAt":"2026-09-15T13:37:15.352Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}