Update AGENTS.md

2026-05-14 20:23:29 +08:00
parent 6cd802ba3a
commit 10fa82bdce
1 changed files with 291 additions and 31 deletions
@@ -4,31 +4,76 @@

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

+---
+
 ## Architecture

 ```
 Assets/Scripts/OCES/
+├── ResourceLoader.cs       ← 资源缓存与同步/异步加载
+├── Metronome.cs            ← demo/test helper
+├── PlaySoundBind.cs        ← UI bind helpers
+├── SetStateBind.cs         ← 状态切换 bind
+├── SetPropertyBind.cs      ← 属性控制 bind
+│
 ├── Audio/
-│   ├── Generated/       ← AUTO-GENERATED, do not edit
-│   └── HandWritten/     ← hand-written runtime code
-│       ├── LongAudio/   ← music & ambience systems
-│       └── Editor/      ← AudioImportTool
+│   ├── Generated/          ← AUTO-GENERATED, do not edit
+│   │   ├── AudioObject.cs     ← AudioObject + AudioObjectConfig（数据类 + 加载表）
+│   │   ├── AudioGroup.cs      ← AudioGroup + AudioGroupConfig
+│   │   ├── AudioConsts.cs     ← Cues.Play_* 常量, NameDictionaries, Parameters(GameState enum + EnumIds)
+│   │   ├── MusicSegment.cs    ← MusicSegment + MusicSegmentConfig
+│   │   ├── MusicContainer.cs  ← MusicContainer + MusicContainerConfig
+│   │   ├── MusicPath.cs       ← MusicPath + MusicPathConfig
+│   │   ├── MusicTransition.cs ← MusicTransition + MusicTransitionConfig
+│   │   ├── AmbiencePath.cs    ← AmbiencePath + AmbiencePathConfig
+│   │   ├── AmbienceTransition.cs ← AmbienceTransition + AmbienceTransitionConfig
+│   │   └── FileManager.cs     ← FileManager (OCES.Audio 命名空间, IBinarySerializable + 字节读取)
+│   │
+│   └── HandWritten/        ← hand-written runtime code
+│       ├── AudioSystem.cs           ← 主入口：持有 SfxSystem + MusicSystem，对外暴露 Play / SetState / SetLowpass
+│       ├── SfxSystem.cs             ← 音效系统：节流/并发/优先级/打断、连续容器播放、ActiveSound 管理
+│       ├── AudioSourcePool.cs       ← AudioSource 对象池
+│       ├── AudioObject.cs           ← partial: AudioObjectConfig 的 Switch 解析逻辑
+│       ├── AudioExtendSettings.cs   ← 集中配置 ScriptableObject（路径/Mixer组/导入参数/淡出淡入曲线等）
+│       ├── HandWrittenDefinitions.cs ← 枚举定义（KillMode, MixingType, ContainerType, AlignMode, CallbackFlags, 等）+ IBinarySerializable 接口 + IPathEntry/ITransitionConfig 接口
+│       ├── DebugInfoCollector.cs    ← 运行时调试信息收集（仅在 UNITY_EDITOR || DEVELOPMENT_BUILD 编译）
+│       ├── VolumeStepResolver.cs    ← 音量阶梯变化（VolumeStep）计算
+│       ├── PitchStepResolver.cs     ← 音高阶梯变化（PitchStep）计算
+│       ├── LongAudio/               ← interactive music & ambience systems
+│       │   ├── MusicSystem.cs               ← 音乐/环境音总控，持有 MusicChannelPlayer + AmbienceChannelPlayer，由 AudioSystem 驱动
+│       │   ├── MusicStateRouter.cs           ← 基于路径规则的全量状态匹配路由 + StateGroupRegistry 注册表
+│       │   ├── MusicChannelPlayer.cs         ← 音乐通道：Transition 切换、节拍对齐、淡入淡出
+│       │   ├── AmbienceChannelPlayer.cs      ← 环境音通道：Transition 切换、淡入淡出（无节拍对齐）
+│       │   ├── LongAudioContainerPlayer.cs    ← Container 递归播放引擎，被两个 Channel 共用
+│       │   ├── ChannelFader.cs               ← 音量淡入淡出 + SyncPoint 同步点管理
+│       │   ├── BeatClock.cs                  ← 节拍/小节/Grid 定时回调
+│       │   ├── AudioContainerSelector.cs     ← SFX Container 的随机/顺序选择（含 LimitRepetition）
+│       │   ├── MusicSegment.cs               ← partial: MusicSegment.IsOffBeat + MusicSegmentConfig.Validate()
+│       │   └── MusicContainer.cs             ← partial: MusicContainerConfig 的 GetBeatsPerBar/Validate
+│       └── Editor/                ← Editor-only tools
+│           ├── AudioImportTool.cs            ← 批量音频导入设置
+│           └── AudioExtendSettingsProvider.cs ← Project Settings 面板 "Audio Extend"
+│
 ├── 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/          ← AUTO-GENERATED, do not edit
+│   │   └── HapticObject.cs    ← HapticObject + HapticObjectConfig（数据类 + 加载表）
+│   │
+│   └── Handwritten/        ← hand-written runtime code
+│       ├── HapticSystem.cs           ← 触感反馈主系统（Preset / Emphasis / Constant / Advance 四种模式）
+│       ├── HapticSystemSettings.cs   ← 触感配置 ScriptableObject（资源路径）
+│       └── HandwrittenDefinitions.cs ← IBinarySerializable 接口 + FileManager + HapticType 枚举
 ```

+---
+
 ## 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`
+- **Generated files**: data classes (`AudioObject`, `AudioGroup`, `MusicSegment`, `MusicContainer`, `MusicPath`, `MusicTransition`, `AmbiencePath`, `AmbienceTransition`, `HapticObject`), config loader tables (`*Config` classes), `AudioConsts.cs` (Cues IDs, NameDictionaries, Parameters enums), `FileManager.cs` (in `OCES.Audio` namespace)
 - **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/`
+- **Partial class pattern**: `AudioObject.cs`, `AudioObjectConfig`, `MusicSegment`, `MusicSegmentConfig`, `MusicContainer`, `MusicContainerConfig` exist in both `Generated/` (serialization) and `HandWritten/` (runtime logic). Add runtime methods to the `HandWritten/` partial, never to `Generated/`.
+- **Generated data protocols**: Generated `MusicPath` and `AmbiencePath` classes have their `ITransitionConfig` / `IPathEntry` interface implementations added via `HandWrittenDefinitions.cs` using `partial class` declarations.

 ## Data pipeline

@@ -43,37 +88,227 @@ Assets/Scripts/OCES/*/Generated/*.cs   ← C# data classes + AudioConsts

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

+## Configuration: AudioExtendSettings
+
+`AudioExtendSettings` is a **ScriptableObject singleton** that centralises all configurable parameters for the audio system. It replaces hardcoded path strings and magic numbers.
+
+- **Asset location**: `Assets/Settings/AudioExtendSettings.asset`
+- **Editor entry**: `Project Settings > Audio Extend` (via `AudioExtendSettingsProvider`)
+- **Creation**: `Tools/Audio/Create AudioExtendSettings Asset` (menu item)
+- **Runtime injection**: `AudioSystem.Awake()` reads the `[SerializeField]` inspector reference and assigns it to `AudioExtendSettings.Instance`
+
+### Configured parameters
+
+| Section | Key fields |
+|---------|-----------|
+| Resource Paths | `audioConfigPath`, `audioResourcePath`, `audioMixerPath` |
+| AudioMixer Groups | `sfxGroupPath`, `voiceGroupPath`, `accentSfxGroupPath`, `musicGroupPath`, `ambienceGroupPath` |
+| Lowpass Filter | `lowpassParamName`, `lowpassEnabledCutoff` (440Hz), `lowpassDisabledCutoff` (22000Hz), `lowpassTweenDuration` |
+| Audio Import | `compressionFormat`, `sfxSampleRate` (22050), `musicSampleRate` (44100), `musicQuality`, `sfxQuality`, `decompressThreshold` (5s), `streamingThreshold` (15s) |
+| Fade | `defaultFadeOutEase` (InSine), `defaultFadeInEase` (OutSine) |
+
+**All code must read mixer group paths from `AudioExtendSettings.Instance.*GroupPath`** — do not hardcode path strings.
+
 ## 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`.
+`FileManager` and `IBinarySerializable` exist independently in both `OCES.Audio` and `OCES.Haptic` namespaces. They are not shared.

-## AudioMixer group paths
+- **Audio**: `OCES.Audio.IBinarySerializable` and `OCES.Audio.FileManager` are defined in `Audio/Generated/FileManager.cs`
+- **Haptic**: `OCES.Haptic.IBinarySerializable` and `OCES.Haptic.FileManager` are defined in `Haptic/Handwritten/HandwrittenDefinitions.cs`

-The mixer hierarchy is hard-referenced by path strings. These must match exactly:
+When adding haptic code, use `OCES.Haptic.*`; for audio, use `OCES.Audio.*`.

- `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
+## ResourceLoader
+
+`OCES.ResourceLoader` at the OCES root is a shared resource caching layer used by both `AudioSystem` and `HapticSystem`. It provides:
+
+- `LoadSync<T>(string path)` — cached synchronous load via `Resources.Load<T>`
+- `LoadAsync<T>(string path, Action<T> onComplete)` — async load with callback deduplication (concurrent requests for the same path share one load operation)
+- Injected into `AudioSystem` and `HapticSystem` during `Awake()`
+
+Both `AudioConfigLoader` and `HapticConfigLoader` use `ResourceLoader` to load `TextAsset` config bytes.

 ## 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.
+### AudioSystem — primary entry point
+
+```csharp
+// Core playback — prefer uint overloads
+AudioSystem.Instance.Play(uint audioId);                // via Cues.Play_* constants
+AudioSystem.Instance.Play(int audioId);                 // convenience, casts to uint
+AudioSystem.Instance.Play(AudioObject audioObject);     // direct object (resolves Switch containers)
+
+// State-driven music/ambience switching
+AudioSystem.Instance.SetState<TEnum>(TEnum state);      // drives MusicStateRouter → channel switching
+
+// Lowpass filter
+AudioSystem.Instance.SetLowpass(bool enable);           // tweens mixer lowpass via DOTween
+
+// Music sync callbacks (subscribed via events)
+AudioSystem.Instance.OnBeat += containerId => { };
+AudioSystem.Instance.OnBar  += containerId => { };
+AudioSystem.Instance.OnGrid += containerId => { };
+```
+
+- `Play(string)` is `[Obsolete]` — string-based lookup is ambiguous for shared/duplicate names. It survives for backward compatibility only.
+- `SetState<TEnum>` updates the `MusicStateRouter` which matches `MusicPath` / `AmbiencePath` tables and switches the appropriate Container via `MusicChannelPlayer` / `AmbienceChannelPlayer`.
+- **New state enums**: register via `StateGroupRegistry.Register<TEnum>(typeId)` in `Parameters.EnumIds.RegisterAllGameState()` (generated in `AudioConsts.cs`).
+
+### SfxSystem — internal SFX runtime
+
+`SfxSystem` is held by `AudioSystem` and not exposed publicly, but its methods are accessible via `AudioSystem` internally:
+
+- `Stop(uint audioId)` — stop all active instances of a given audio ID
+- `SetVolume(uint audioId, float targetVolume)` — live volume adjustment
+- `SetPitch(uint audioId, float targetPitch)` — live pitch adjustment
+
+SfxSystem manages: throttle (`ThrottleCount`), min interval (`MinInterval`), priority preemption (`KillMode`), concurrent instance tracking, continuous container playback, and haptic auto-trigger.
+
+### HapticSystem
+
+- `HapticSystem.Instance.Play(uint hapticId)` — called automatically by SfxSystem when `AudioObject.Haptic` is set; direct calls log a warning (debug-only).
+- `HapticSystem.Instance.Stop(uint? hapticId = null)` — stops current haptic playback
+- Supports four `HapticType`s: `Preset`, `Emphasis`, `Constant`, `Advance` (`.haptic` file)
+
+---
+
+## Interactive Music System
+
+### State-driven routing
+
+1. `AudioSystem.SetState<TEnum>(state)` → forwards to `MusicSystem.OnStateChanged(state)`
+2. `MusicStateRouter.SetState()` stores the state, then performs full-match against `MusicPath` and `AmbiencePath` tables
+3. Path format: `TypeID1,子状态|TypeID2,子状态…` — all conditions must be met (AND logic). Priority field selects the best match when multiple paths satisfy.
+4. Best-matched `ContainerId` is dispatched to `MusicChannelPlayer.SwitchTo()` and `AmbienceChannelPlayer.SwitchTo()`
+
+Key class: `MusicStateRouter` — maintains `ActiveStates` dictionary, exposes `LastMusicPathId` / `LastAmbiencePathId` for Transition lookup.
+
+### StateGroupRegistry
+
+Programmer-maintained enum-to-TypeId mapping. Usage:
+
+```csharp
+// In Parameters.EnumIds.RegisterAllGameState() (generated):
+StateGroupRegistry.Register<Parameters.GameState>(1);
+```
+
+The integer `1` must match the TypeId values in the MusicPath/AmbiencePath Excel tables.
+
+### Transition system
+
+- `MusicChannelPlayer` handles music Transitions with **beat-aligned switching** (supports `AlignMode.Immediate` / `Beat` / `Bar`)
+- `AmbienceChannelPlayer` handles ambience Transitions with **simple cross-fade** (no beat alignment)
+- Both use `ChannelFader` for volume ramping via DG.Tweening `DOFade`
+- Transition resolution: matches `SourceContainerId → DestinationContainerId` with `-1` wildcard support; highest-ID exact match wins
+- `SyncPoint.SameAsCurrentSegment` allows new music to start at the same playback position as the outgoing track
+
+### BeatClock
+
+Drives music-sync callbacks (`OnBeat`, `OnBar`, `OnGrid`) using `AudioSettings.dspTime`:
+
+- Parses BPM from `MusicContainer.Bpm` (falls back to inherited BPM from parent Container)
+- Parses time signature from `MusicContainer.TimeSig` (e.g. `"4/4"`)
+- Grid interval from `MusicContainer.Grid` (in bars)
+- Automatically disables callbacks when Blend containers have multiple divergent BPMs
+
+### Container playback
+
+`LongAudioContainerPlayer` recursively plays a `MusicContainer` tree and supports:
+
+- **Container types**: `Random`, `Sequence`, `Blend`
+- **Random mode**: shuffle (不放回) with optional no-repeat history
+- **Sequence mode**: global step cursor per container
+- **Blend mode**: simultaneous playback of all child segments
+- **Off-beat detection**: `MusicSegmentConfig.Validate()` checks `StartOffset`/`EndOffset` against actual clip lengths
+- Returns `ContainerPlayHandle` for external stop/fade control
+
+---
+
+## SFX Runtime Logic
+
+### Container playback
+
+AudioObject supports container types (`ContainerType`):
+
+| Type | Behavior |
+|------|----------|
+| `Random` | Random selection from child clips, with `LimitRepetition` and `RandomType` (Standard / Shuffle 不放回) |
+| `Sequence` | Step-through in order |
+| `Blend` | (reserved for long audio) |
+| `Switch` | State-driven selection via `SwitchGroupId` — resolved by `AudioObjectConfig.PreParseSwitchMappings()` |
+
+`ContainerPlayMode`:
+- `false` (Step): play one clip at a time
+- `true` (Continuous): play all clips in sequence with gap, supports Random/Sequence
+
+### Selection helpers
+
+- `AudioContainerSelector` — manages random histories, sequence cursors, `LimitRepetition` queues. Shared across all SFX instances.
+- `PitchStepResolver` — incremental pitch shifting per `PitchStep` (+ semitones) within `PitchStepThreshold` (ms), clamped by `PitchStepLimit`
+- `VolumeStepResolver` — incremental volume adjustment per `VolumeStep` (dB) within `VolumeStepThreshold` (ms)
+
+### Priority & preemption (KillMode)
+
+When `ThrottleCount` or `Group` limits are exceeded:
+
+- `KillMode.Oldest` — evict the oldest playing instance
+- `KillMode.Newest` — silence the newest (incoming) instance
+
+### Mixing groups (MixingType)
+
+| Enum | Mixer path (from AudioExtendSettings) |
+|------|--------------------------------------|
+| `Sfx` | `sfxGroupPath` |
+| `Voice` | `voiceGroupPath` |
+| `Accented` | `accentSfxGroupPath` |
+
+### ActiveSound
+
+Tracks each playing sound instance: `AudioSource`, `AudioObject`, `StartTime`, `CurrentLoopCount`, `Coroutine`, `Pitch`, `Volume`, `State` (`Pending` / `Playing` / `Finished`).
+
+---

 ## 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).
+### AudioImportTool
+
+Batch-applies import settings to all `.wav`/`.ogg` files in the audio resources directory. Now fully configuration-driven via `AudioExtendSettings`.
+
+- **Menu**: `Tools/Audio/Apply Audio Import Settings`
+- **CLI entry**: `OCES.Audio.AudioImportTool.RunCli` (via `-executeMethod`)
+- **Classification**: Auto-detects Music/SFX/Voice by checking `MusicSegment` table → `AudioObject` table `MixingType` → filename heuristics
+- **Import rules** (all from `AudioExtendSettings`):
+  - SFX/Voice: `sfxSampleRate`, DecompressOnLoad (or Streaming if ≥ `streamingThreshold`)
+  - Music: `musicSampleRate`, DecompressOnLoad (≤ `decompressThreshold`), Streaming (≥ `streamingThreshold`), CompressedInMemory (between)
+  - Files referenced by `AudioObject.Haptic` force `preloadAudioData = true`
+
+### AudioExtendSettingsProvider
+
+Provides a custom Project Settings tab (`Project Settings > Audio Extend`) for editing `AudioExtendSettings.asset` with full serialized property inspection.
+
+### ExcelTool
+
+`Assets/Editor/ExcelTool.cs` — invokes external shell script to regenerate data from Excel. Currently disabled (`[UnityEditor.MenuItem]` is commented out).
+
+---
+
+## Debugging
+
+`DebugInfoCollector` (compiled only under `UNITY_EDITOR || DEVELOPMENT_BUILD`):
+
+- Displays current active states, clip concurrent counts, and active sound list to a `UI.Text` component
+- Updated every frame by `SfxSystem.Update()` and `MusicStateRouter.SetState()`
+- Singleton pattern, accessed via `DebugInfoCollector.Instance`
+
+---

 ## Third-party dependencies

- **DOTween** (`Assets/Scripts/DG/DOTween/`) — used for low-pass filter tweening and cross-fades
+- **DOTween** (`Assets/Scripts/DG/DOTween/`) — used for low-pass filter tweening (`DOTween.To`), fade-in/fade-out curves (`AudioSource.DOFade`)
 - **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
@@ -81,9 +316,34 @@ The mixer hierarchy is hard-referenced by path strings. These must match exactly
 - `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)
+All paths are configured via `AudioExtendSettings` at runtime. The defaults are:
+
+| Resource | Path | Access |
+|----------|------|--------|
+| Audio clips | `Resources/Audios/` | `ResourceLoader.LoadSync<AudioClip>` |
+| Audio configs | `Resources/AudioData/` | `AudioConfigLoader.Load<T>` (file-based) or `HapticConfigLoader.Load<T>` (Resources-based) |
+| Haptic configs | `Resources/HapticData/` | `HapticConfigLoader.Load<T>` |
+| Haptic clips | `Resources/Haptics/` | `.haptic` files for advanced haptic playback |
+| AudioMixer | `Resources/Audios/Master` | `Resources.Load<AudioMixer>` |
+
+---
+
+## Key enums (defined in `HandWrittenDefinitions.cs`)
+
+| Enum | Values | Purpose |
+|------|--------|---------|
+| `KillMode` | `Oldest`, `Newest` | Priority preemption strategy |
+| `MixingType` | `Sfx`, `Voice`, `Accented` | Output mixer group routing |
+| `ContainerType` | `Random`, `Sequence`, `Blend`, `Switch` | Container playback strategy |
+| `BlendCrossFadeType` | `Exponential`, `Linear`, `Logarithmic` | (reserved) |
+| `AlignMode` | `Immediate`, `Beat`, `Bar` | Music transition timing |
+| `CallbackFlags` | `MusicSyncBeat`, `MusicSyncBar`, `MusicSyncGrid` | (reserved) |
+| `ActiveSoundState` | `Pending`, `Playing`, `Finished` | Playback lifecycle |
+| `SyncPoint` | `Start`, `SameAsCurrentSegment` | Crossfade sync mode |
+| `SyncSegment` | `Start`, `LastPlayedSegment` | (reserved) |
+
+`Parameters.GameState` (generated in `AudioConsts.cs`) is the default game state enum: `Home`, `Game`, `Win`, `Lose`, `TestA`, `TestB`.