refactor: 重构 Transition 查询逻辑，移除 PathId 改用 ContainerId 匹配

2026-04-28 15:30:01 +08:00
parent 2fa3fa49d7
commit 8ea862b546
13 changed files with 204 additions and 78 deletions
@@ -0,0 +1,89 @@
+# 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)