XmobiTea Sound

Small Unity audio helper for scene-authored projects. It plays music and SFX through AudioSource, routes new sources through assigned AudioMixerGroups, and loads one SoundSettings asset from Resources.

Need-Based Routing

Choose by current need. Open only the smallest file that answers it.

• AI_USAGE.md: minimal decision guide for playback/volume APIs and normal code generation
• AI_SETUP.md: setup router
• AI_SETUP_SOUND_SETTINGS.md: settings asset, mixer setup, startup clips, and generated constants
• AI_SETUP_SOUND_MANAGER.md: scene manager setup, persistence, and call timing
• AI_API_REFERENCE.md: exact public signatures, return values, fields, and editor menu names
• AI_BEHAVIOR.md: lifecycle, mixer, registry, source ownership, and edge-case behavior
• AGENTS.md: final guardrails for agents working in this package
• runtime/editor source: only when changing package behavior or when docs conflict with observed behavior

Quick Contract

• Namespace: XmobiTea.MiniSound
• Main API: SoundManager : Singleton<SoundManager>
• Host object: scene GameObject with SoundManager
• Settings load path: Resources/XmobiTea SoundSettings
• Default editor-created asset: Assets/Resources/XmobiTea SoundSettings.asset
• Required mixer params: MasterValue, MusicValue, SoundValue
• Startup string key: exact AudioClip.name
• Runtime string key: SoundManager.AddSound(name, clip)
• Auto-created manager: no
• Runtime-created settings: no
• Built-in pause/fade APIs: no

Setup

SoundSettings:

1. Run XmobiTea Tools/Sound/Open Settings.
2. Confirm one XmobiTea SoundSettings.asset exists at the root of a Resources folder. The menu creates Assets/Resources/XmobiTea SoundSettings.asset by default.
3. Assign musicMixerGroup, soundMixerGroup, and masterMixer.
4. Ensure the assigned mixer exposes MasterValue, MusicValue, and SoundValue.
5. Add startup string-played clips to audioClips.

SoundManager scene:

1. Create a boot-scene GameObject named SoundManager.
2. Add the SoundManager component.
3. Add XmobiTea.MiniSingleton.DontDestroy only if later scenes need the same sound host.
4. Keep only one active manager path when using a persistent boot-scene manager.

Call SoundManager APIs from Start() or later unless script execution order guarantees SoundManager.Awake() already ran.

The settings asset existing is not enough; the mixer fields must be assigned before volume/mute and package mixer routing work. Keep only one authoritative settings asset at Resources/XmobiTea SoundSettings so Resources.Load(...) resolves the intended asset.

Detailed setup: AI_SETUP_SOUND_SETTINGS.md and AI_SETUP_SOUND_MANAGER.md.

Basic Usage

using UnityEngine;
using XmobiTea.MiniSound;

public sealed class MenuAudio : MonoBehaviour
{
    [SerializeField] private AudioClip buttonClick;

    private void Start()
    {
        SoundManager.SetVolumeMusicInt(5);
        SoundManager.PlayMusic("MainTheme", true);
    }

    public void PlayButtonClick()
    {
        SoundManager.PlaySound(buttonClick);
    }
}

Prefer direct AudioClip references when available. Use string ids only when the clip is in SoundSettings.audioClips or has been registered with SoundManager.AddSound(name, clip).

Common Calls

SoundManager.PlayMusic("MainTheme", true);
SoundManager.PlaySound("ButtonClick");

SoundManager.StopMusic("MainTheme");
SoundManager.StopAllSound();

SoundManager.SetVolumeMusicInt(5);
SoundManager.SetVolumeSound(-8f);

SoundManager.MuteMusic();
SoundManager.UnmuteMusic();

Runtime-loaded clip:

SoundManager.AddSound("RewardSfx", rewardClip);
SoundManager.PlaySound("RewardSfx");

Target-attached audio:

AudioSource source = SoundManager.Play3DSound(enemy.gameObject, explosionClip);
if (source != null)
{
    source.spatialBlend = 1f;
    source.minDistance = 1f;
    source.maxDistance = 20f;
}

The 3D methods attach or reuse an AudioSource on the target. They do not configure spatial audio settings.

Generated Constants

Run:

XmobiTea Tools/Sound/Generate SoundConstantId.cs

Output:

Assets/XmobiTea-constant/Scripts/SoundConstantId.cs

Generated members are public static readonly string values from SoundSettings.audioClips.

Example: if audioClips contains an AudioClip named MainTheme, generation creates:

public static readonly string MainTheme = "MainTheme";

Then SoundManager.PlayMusic(SoundConstantId.MainTheme, true) is the same lookup as SoundManager.PlayMusic("MainTheme", true).

The field name is normalized with AutoGenerate.GetConstantName(audioClip.name), but the value remains the original clip name. For example, Main Theme becomes SoundConstantId.MainTheme = "Main Theme".

Package Metadata

• Package name: com.xmobitea.changx.mini-sound
• Unity version: 2022.3+
• License: Apache-2.0