EllanJiang/GameFramework · error · GameFrameworkException

Sound agent helper is invalid.

Error message

Sound agent helper is invalid.

What it means

The SoundAgent constructor requires a non-null ISoundAgentHelper — the platform-specific audio playback adapter (e.g. Unity sound agent helper). Without it the agent has no playback engine, and it also subscribes ResetSoundAgent on it, so a null value would crash later; construction therefore throws immediately.

Solutions

1. Ensure a concrete ISoundAgentHelper (e.g. Unity SoundAgentHelper attached to a GameObject) is created and passed for each agent.
2. If helpers come from a factory/pool, null-check the returned helper before constructing the agent and treat null as an allocation failure.
3. Verify the sound agent prefab still has the helper MonoBehaviour component after prefab changes.

Example fix

// before
var helper = go.GetComponent<SoundAgentHelper>(); // may be null
var agent = new SoundAgent(group, soundHelper, helper);
// after
var helper = go.GetComponent<SoundAgentHelper>();
if (helper == null) { helper = go.AddComponent<SoundAgentHelper>(); }
var agent = new SoundAgent(group, soundHelper, helper);

var agentHelper = go.GetComponent<SoundAgentHelper>();
if (agentHelper == null) agentHelper = go.AddComponent<SoundAgentHelper>();

ISoundAgentHelper EnsureHelper(GameObject go) => go.GetComponent<SoundAgentHelper>() ?? go.AddComponent<SoundAgentHelper>();

try { var agent = new SoundAgent(group, soundHelper, agentHelper); } catch (GameFrameworkException ex) when (ex.Message.Contains("Sound agent helper is invalid")) { Log.Fatal("Sound agent helper missing on agent GameObject"); throw; }

When it happens

Trigger: Constructing SoundAgent(soundGroup, soundHelper, null) — when an agent is created without a valid agent helper, e.g. custom agent pool code or a factory returning null helpers after a failed asset load.

Common situations: Custom ISoundAgentHelper implementations that fail to instantiate (missing component on prefab, AddComponent failure) and the null result is passed along; modified SoundManager agent-creation loops that skip helper assignment.

Related errors

• Sound group is invalid.
• Sound helper is invalid.
• Asset name is invalid.
• Buffer is invalid.
• Bytes is invalid.

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

Appendix: source

Thrown at GameFramework/Sound/SoundManager.SoundAgent.cs:48

            /// </summary>
            /// <param name="soundGroup">所在的声音组。</param>
            /// <param name="soundHelper">声音辅助器接口。</param>
            /// <param name="soundAgentHelper">声音代理辅助器接口。</param>
            public SoundAgent(SoundGroup soundGroup, ISoundHelper soundHelper, ISoundAgentHelper soundAgentHelper)
            {
                if (soundGroup == null)
                {
                    throw new GameFrameworkException("Sound group is invalid.");
                }

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

                if (soundAgentHelper == null)
                {
                    throw new GameFrameworkException("Sound agent helper is invalid.");
                }

                m_SoundGroup = soundGroup;
                m_SoundHelper = soundHelper;
                m_SoundAgentHelper = soundAgentHelper;
                m_SoundAgentHelper.ResetSoundAgent += OnResetSoundAgent;
                m_SerialId = 0;
                m_SoundAsset = null;
                Reset();
            }

            /// <summary>
            /// 获取所在的声音组。
            /// </summary>
            public ISoundGroup SoundGroup
            {
                get
                {

View on GitHub (pinned to d0c010b051)