AudioSystem/AGENTS.md

AGENTS.md — AudioSystem (OCES)

Project

Unity 2022.3.62f3, URP, C#. Custom audio & haptic middleware under the namespace OCES.

Architecture

Assets/Scripts/OCES/
├── Audio/
│   ├── Generated/       ← AUTO-GENERATED, do not edit
│   └── HandWritten/     ← hand-written runtime code
│       ├── LongAudio/   ← music & ambience systems
│       └── Editor/      ← AudioImportTool
├── Haptic/
│   ├── Generated/       ← AUTO-GENERATED, do not edit
│   └── Handwritten/     ← hand-written runtime code
├── Metronome.cs         ← demo/test helper
├── PlaySoundBind.cs     ← UI bind helpers
├── SetStateBind.cs
└── SetPropertyBind.cs

Generated code boundary — critical

Everything under Assets/Scripts/OCES/*/Generated/ is auto-generated from Excel data tables. Every file has the header comment: auto generated by tools(注意:千万不要手动修改本文件).

• Generated files: data classes (AudioObject, AudioGroup, MusicSegment, etc.), config loader tables, AudioConsts.cs (Cues IDs, NameDictionaries, Parameters enums), FileManager.cs
• If you need to change data: edit the source .xlsx in DataTables/, then re-run the ExcelTool to regenerate .bytes configs + C# classes
• Partial class pattern: AudioObject.cs and config classes exist in both Generated/ (serialization) and HandWritten/ (runtime logic like switch resolution). Add runtime methods to the HandWritten/ partial, never to Generated/

Data pipeline

DataTables/*.xlsx   (gitignored, source of truth for game data)
       ↓  ExcelTool
Resources/AudioData/*.bytes   ← binary configs loaded at runtime via AudioConfigLoader
Resources/HapticData/*.bytes
       ↓  also generates
Assets/Scripts/OCES/*/Generated/*.cs   ← C# data classes + AudioConsts

Tools/ and DataTables/ are gitignored. The Excel tool and source spreadsheets live outside version control.

Duplicate types — intentional

FileManager and IBinarySerializable exist independently in both OCES.Audio and OCES.Haptic namespaces. They are not shared. When adding haptic code, use OCES.Haptic.IBinarySerializable; for audio, use OCES.Audio.IBinarySerializable.

AudioMixer group paths

The mixer hierarchy is hard-referenced by path strings. These must match exactly:

• Master/Regular/SFX — default SFX group
• Master/Regular/Voice — voice group
• Master/SFX_Accent — accent SFX
• Master/Regular/Music — music pool
• Master/Regular/SFX/Ambience — ambience pool

API conventions

• AudioSystem.Instance.Play(uint audioId) is the primary API. Use Cues.Play_* constants from AudioConsts.cs.
• Play(string) is [Obsolete] — string-based lookup is ambiguous for shared/duplicate names.
• AudioSystem.Instance.SetState<TEnum>(TEnum state) drives music/ambience switching. New state enums must be registered via StateGroupRegistry.Register<TEnum>(typeId) in Parameters.EnumIds.RegisterAllGameState().
• HapticSystem.Instance.Play(uint hapticId) is typically called automatically by SfxSystem when an AudioObject.Haptic field is set; direct calls are for debugging only.

Editor tools

• AudioImportTool: batch-applies import settings (sample rate, compression, load type) to all audio files in Resources/Audios/. Menu: Tools/Audio/Apply Audio Import Settings. CLI entry: OCES.Audio.AudioImportTool.RunCli.
• ExcelTool (commented out menu item): Assets/Editor/ExcelTool.cs — invokes external shell script to regenerate data from Excel. Currently disabled ([UnityEditor.MenuItem] is commented out).

Third-party dependencies

• DOTween (Assets/Scripts/DG/DOTween/) — used for low-pass filter tweening and cross-fades
• NiceVibrations / Lofelt (Assets/Scripts/Lofelt/NiceVibrations/) — haptic feedback with native plugins per platform (Assets/Plugins/{Android,iOS,macOS,Windows}/)

Audio file naming conventions

• au_sfx_* — sound effects
• au_bgm_* — background music
• au_music_* — music segments (used by the interactive music system)
• au_stream.ogg — streaming audio

Resources paths

• Audio clips: Resources/Audios/ (loaded via Resources.Load<AudioClip>)
• Audio configs: Resources/AudioData/ (loaded via AudioConfigLoader.Load<T>)
• Haptic configs: Resources/HapticData/
• Haptic clips: Resources/Haptics/ (.haptic files for advanced haptic playback)