90 lines
4.4 KiB
Markdown
90 lines
4.4 KiB
Markdown
# 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)
|