{"record":{"id":"afa21c8fccfd7b39","repo":"EllanJiang/GameFramework","slug":"you-must-set-sound-helper-first","errorCode":null,"errorMessage":"You must set sound helper first.","messagePattern":"You must set sound helper first\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/Sound/SoundManager.cs","lineNumber":296,"sourceCode":"                Mute = soundGroupMute,\n                Volume = soundGroupVolume\n            };\n\n            m_SoundGroups.Add(soundGroupName, soundGroup);\n\n            return true;\n        }\n\n        /// <summary>\n        /// 增加声音代理辅助器。\n        /// </summary>\n        /// <param name=\"soundGroupName\">声音组名称。</param>\n        /// <param name=\"soundAgentHelper\">要增加的声音代理辅助器。</param>\n        public void AddSoundAgentHelper(string soundGroupName, ISoundAgentHelper soundAgentHelper)\n        {\n            if (m_SoundHelper == null)\n            {\n                throw new GameFrameworkException(\"You must set sound helper first.\");\n            }\n\n            SoundGroup soundGroup = (SoundGroup)GetSoundGroup(soundGroupName);\n            if (soundGroup == null)\n            {\n                throw new GameFrameworkException(Utility.Text.Format(\"Sound group '{0}' is not exist.\", soundGroupName));\n            }\n\n            soundGroup.AddSoundAgentHelper(m_SoundHelper, soundAgentHelper);\n        }\n\n        /// <summary>\n        /// 获取所有正在加载声音的序列编号。\n        /// </summary>\n        /// <returns>所有正在加载声音的序列编号。</returns>\n        public int[] GetAllLoadingSoundSerialIds()\n        {\n            return m_SoundsBeingLoaded.ToArray();","sourceCodeStart":278,"sourceCodeEnd":314,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/Sound/SoundManager.cs#L278-L314","documentation":"Thrown by SoundManager.AddSoundAgentHelper when the sound helper has not yet been set via SetSoundHelper. This is an initialization-order invariant: SoundManager requires ISoundHelper before sound agents can be created. The method then also validates that the target sound group exists.","triggerScenarios":"Calling AddSoundAgentHelper before SetSoundHelper was ever invoked; constructing SoundManager fresh and immediately adding agent helpers; partial initialization after an earlier SetSoundHelper(null) call threw.","commonSituations":"Bootstrap scripts that add sound agents before helper injection; scene reload logic skipping the SetSoundHelper step; DI container missing a registration.","solutions":["Call SetSoundHelper with a valid ISoundHelper before any AddSoundAgentHelper call","Enforce an initialization order: resource manager, sound helper, groups, then agent helpers","Assert m_SoundHelper != null in your bootstrap before sound setup"],"exampleFix":"// before\nsoundManager.AddSoundAgentHelper(\"Music\", agentHelper); // helper not set yet\n// after\nsoundManager.SetSoundHelper(soundHelper);\nsoundManager.AddSoundGroup(\"Music\", false, false, 1f, groupHelper);\nsoundManager.AddSoundAgentHelper(\"Music\", agentHelper);","handlingStrategy":"try-catch","validationCode":"if (soundManager.GetSoundGroup(soundGroupName) == null) throw new InvalidOperationException(\"Group missing; also ensure SetSoundHelper was called\");","typeGuard":"bool SoundManagerReady(SoundManager sm) => sm.HasSoundGroup(soundGroupName);","tryCatchPattern":"try { soundManager.AddSoundAgentHelper(groupName, agentHelper); }\ncatch (GameFrameworkException ex) { Log.Error(\"Sound init incomplete: \" + ex.Message); }","preventionTips":["Always call SetSoundHelper before adding sound agents","Follow the documented init sequence: helper, groups, agents","Wrap sound subsystem bootstrap in one ordered method"],"tags":["gameframework","sound","initialization-order"],"backgroundTag":"missing-dependency","analyzedSha":"d0c010b05167c58e92350449d04864a91ca13fd2","analyzedAt":"2026-09-15T13:37:15.352Z","contentChangedAt":"2026-09-15T13:37:15.352Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}