EllanJiang/GameFramework · error · GameFrameworkException

Sound group helper is invalid.

Error message

Sound group helper is invalid.

What it means

Thrown by the SoundGroup constructor when the soundGroupHelper argument is null. A sound group needs an ISoundGroupHelper to function (e.g. for priority/avoid-replacement behavior), so GameFramework rejects null helpers at construction time.

Solutions

1. Create or obtain a valid ISoundGroupHelper and pass it to the constructor
2. Ensure the helper component is attached/initialized before adding sound groups
3. Null-check the helper at the call site before constructing the group

Example fix

// before
var group = new SoundGroup("Music", null);
// after
ISoundGroupHelper helper = GetComponent<SoundGroupHelper>();
var group = new SoundGroup("Music", helper);

if (soundGroupHelper == null) throw new ArgumentNullException(nameof(soundGroupHelper));
var group = new SoundGroup(name, soundGroupHelper);

bool HasHelper(ISoundGroupHelper h) => h != null;

try { var group = new SoundGroup(name, helper); }
catch (GameFrameworkException ex) { Log.Error(ex.Message); }

When it happens

Trigger: new SoundGroup(name, null); passing a helper field that was never assigned; failing to create/obtain the concrete SoundGroupHelper before building groups.

Common situations: Forgetting to add the SoundHelper/SoundGroupHelper component to the Unity Sound component; initialization order issues where the helper is created after groups; a factory returning null.

Related errors

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

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

Appendix: source

Thrown at GameFramework/Sound/SoundManager.SoundGroup.cs:40

            private bool m_AvoidBeingReplacedBySamePriority;
            private bool m_Mute;
            private float m_Volume;

            /// <summary>
            /// 初始化声音组的新实例。
            /// </summary>
            /// <param name="name">声音组名称。</param>
            /// <param name="soundGroupHelper">声音组辅助器。</param>
            public SoundGroup(string name, ISoundGroupHelper soundGroupHelper)
            {
                if (string.IsNullOrEmpty(name))
                {
                    throw new GameFrameworkException("Sound group name is invalid.");
                }

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

                m_Name = name;
                m_SoundGroupHelper = soundGroupHelper;
                m_SoundAgents = new List<SoundAgent>();
            }

            /// <summary>
            /// 获取声音组名称。
            /// </summary>
            public string Name
            {
                get
                {
                    return m_Name;
                }
            }

View on GitHub (pinned to d0c010b051)