EllanJiang/GameFramework · error · GameFrameworkException

You must set sound helper first.

Error message

You must set sound helper first.

What it means

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.

Solutions

  1. Call SetSoundHelper with a valid ISoundHelper before any AddSoundAgentHelper call
  2. Enforce an initialization order: resource manager, sound helper, groups, then agent helpers
  3. Assert m_SoundHelper != null in your bootstrap before sound setup

Example fix

// before
soundManager.AddSoundAgentHelper("Music", agentHelper); // helper not set yet
// after
soundManager.SetSoundHelper(soundHelper);
soundManager.AddSoundGroup("Music", false, false, 1f, groupHelper);
soundManager.AddSoundAgentHelper("Music", agentHelper);
Defensive patterns

Strategy: try-catch

Validate before calling

if (soundManager.GetSoundGroup(soundGroupName) == null) throw new InvalidOperationException("Group missing; also ensure SetSoundHelper was called");

Type guard

bool SoundManagerReady(SoundManager sm) => sm.HasSoundGroup(soundGroupName);

Try / catch

try { soundManager.AddSoundAgentHelper(groupName, agentHelper); }
catch (GameFrameworkException ex) { Log.Error("Sound init incomplete: " + ex.Message); }

Prevention

When it happens

Trigger: Calling AddSoundAgentHelper before SetSoundHelper was ever invoked; constructing SoundManager fresh and immediately adding agent helpers; partial initialization after an earlier SetSoundHelper(null) call threw.

Common situations: Bootstrap scripts that add sound agents before helper injection; scene reload logic skipping the SetSoundHelper step; DI container missing a registration.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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

Appendix: source

Thrown at GameFramework/Sound/SoundManager.cs:296

                Mute = soundGroupMute,
                Volume = soundGroupVolume
            };

            m_SoundGroups.Add(soundGroupName, soundGroup);

            return true;
        }

        /// <summary>
        /// 增加声音代理辅助器。
        /// </summary>
        /// <param name="soundGroupName">声音组名称。</param>
        /// <param name="soundAgentHelper">要增加的声音代理辅助器。</param>
        public void AddSoundAgentHelper(string soundGroupName, ISoundAgentHelper soundAgentHelper)
        {
            if (m_SoundHelper == null)
            {
                throw new GameFrameworkException("You must set sound helper first.");
            }

            SoundGroup soundGroup = (SoundGroup)GetSoundGroup(soundGroupName);
            if (soundGroup == null)
            {
                throw new GameFrameworkException(Utility.Text.Format("Sound group '{0}' is not exist.", soundGroupName));
            }

            soundGroup.AddSoundAgentHelper(m_SoundHelper, soundAgentHelper);
        }

        /// <summary>
        /// 获取所有正在加载声音的序列编号。
        /// </summary>
        /// <returns>所有正在加载声音的序列编号。</returns>
        public int[] GetAllLoadingSoundSerialIds()
        {
            return m_SoundsBeingLoaded.ToArray();

View on GitHub (pinned to d0c010b051)