From faba10b33efe9bc7ad06f96f49db41821ade8585 Mon Sep 17 00:00:00 2001
From: Oliver Wong <htw128@live.com>
Date: Thu, 4 Jun 2026 19:10:50 +0800
Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md | 19 +++++++++++++++++++
 guide.md  | 12 ++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 1311737..8c5f77d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -170,6 +170,25 @@ SfxSystem manages: throttle (`ThrottleCount`), min interval (`MinInterval`), pri
 - `HapticSystem.Instance.Stop(uint? hapticId = null)` — stops current haptic playback
 - Supports four `HapticType`s: `Preset`, `Emphasis`, `Constant`, `Advance` (`.haptic` file)
 
+#### Device capability & fallback
+
+`HapticController.Play()` (`Lofelt/.../HapticController.cs:350`) uses a three-tier decision chain:
+
+1. **Advanced device** (`DeviceCapabilities.meetsAdvancedRequirements`) → full `.haptic` playback via `LofeltHaptics`
+2. **Gamepad** (`GamepadRumbler.CanPlay()`) → gamepad rumble
+3. **Basic OS support** (`DeviceCapabilities.isVersionSupported`) → **always falls back to a Preset**
+4. None of above → silent no-op
+
+**Advance (`.haptic` file) fallback is Preset-only** — it never degrades to Emphasis or Constant. The fallback Preset is configured via `HapticObject.FallbackPreset` in the data table.
+
+| HapticType | Advanced | Android basic | iOS basic |
+|------------|----------|---------------|-----------|
+| **Advance** | Full `.haptic` | → Preset | → Preset |
+| **Emphasis** | JSON clip | 50ms max-amplitude pulse | → amplitude-mapped Preset |
+| **Constant** | JSON clip with modulation | max-amplitude for `duration` | → hardcoded `HeavyImpact` |
+
+Emphasis and Constant have their own internal fallback chains (template-based JSON clips on advanced, raw motor patterns or Presets on basic), but these are independent direct-invoke paths — they are never used as fallback targets for Advance.
+
 ---
 
 ## Interactive Music System
diff --git a/guide.md b/guide.md
index 78a3bef..eec0074 100644
--- a/guide.md
+++ b/guide.md
@@ -72,6 +72,18 @@ AudioSystem.Instance.SetState(MyCustomEnum.SomeState);  // 需先通过 StateGro
 - 游戏启动时的首次状态设置**必须放在 `Start` 内**，晚一点可以，早了容易出问题。
 - 若需在其他位置进行首次初始化，请注释掉 `AudioSystem.Start()` 中的相关代码。
 
+### 开关
+
+```csharp
+AudioSystem.Instance.SetMusicVolume(float tatgetVolume) //设置音乐音量 （-80～0）
+AudioSystem.Instance.SetSFXVolume(float tatgetVolume) //设置音效音量 （-80～0）
+
+AudioSystem.Instance.SetMusicState(bool enable) // 启用/禁用音乐
+AudioSystem.Instance.SetSFXState(bool enable) // 启用/禁用音效
+
+HapticSytem.Instance.EnableHaptic(bool enable) // 启用/禁用触感系统
+```
+
 ### Inspector 参数
 
 | 字段 | 说明 |