# 自动下马 / 取消变形（Auto Dismount）技术总结

## 功能概述

骑乘或变形状态下尝试施法时，自动取消坐骑 / 变形 buff，使下次施法直接生效。

## 检测架构（三层）

### 第 1 层 — 错误消息匹配

监听 `UI_ERROR_MESSAGE` 事件：

| 方式 | 说明 |
|---|---|
| 哈希表精确匹配 | `ERR_ATTACK_MOUNTED`, `ERR_NOT_WHILE_MOUNTED`, `ERR_MOUNT_SHAPESHIFTED` 等标准全局变量 |
| 关键词模糊匹配 | `mounted`, `shapeshifted`, `坐骑`, `骑乘`, `变形`, `形态`（兜底自定义错误消息） |

> Turtle WoW 使用自定义错误 `"你正在骑乘状态"`，不在标准全局变量中，通过关键词 `"骑乘"` 命中。

### 第 2 层 — Dismount() API

客户端若提供 `Dismount()` 函数则先调用（`pcall` 包裹），**不 early return**，继续 buff 扫描作为后备。

### 第 3 层 — Buff 扫描（0-39）

遍历玩家 buff，逐个按优先级检测：

| 优先级 | 检测方式 | 目标 | 示例 |
|---|---|---|---|
| 1 | 变形图标匹配 | 德鲁伊 / 萨满形态 | `ability_druid_catform`, `spell_nature_spiritwolf` |
| 2 | 坐骑图标模式 | 坐骑 buff 图标 | `ability_mount_*`, `inv_pet_speedy` |
| 3 | Tooltip 速度文本 | 坐骑速度描述（多语言） | `"又慢又稳"`, `"Increases speed by"` |
| 4 | Buff 名称关键词 | Tooltip 首行含坐骑关键词 | `"骑乘"`, `"riding"` |

### 猎人守护跳过

猎人的猎豹 / 豹群守护使用 `ability_mount_*` 图标，需特殊跳过以免误取消。

## 调试关键发现

### Tooltip 扫描在 Turtle WoW 中失效

`GameTooltip:SetPlayerBuff(index)` 对所有 buff 均返回 **0 行**。
即使重新 `SetOwner`、尝试 `GetPlayerBuff` 返回的 buffId，结果相同。

**影响**：tooltip 检测路径完全失效，必须依赖图标模式匹配。

### 非标准坐骑图标

| 坐骑 | 实际图标纹理 |
|---|---|
| 骑乘乌龟 | `inv_pet_speedy`（不匹配 `ability_mount_*`） |
| 标准坐骑 | `Ability_Mount_*` |
| AQ 坐骑 | `inv_misc_qirajicrystal_*` |

## 完整图标模式清单

```lua
-- 坐骑
mountIconPatterns = {
    "ability_mount_",
    "inv_misc_qirajicrystal",
    "inv_pet_speedy",
}
-- 变形
shapeshiftIcons = {
    "ability_racial_bearform",     -- 熊形态
    "ability_druid_catform",       -- 猫形态
    "ability_druid_travelform",    -- 旅行形态
    "spell_nature_forceofnature",  -- 枭兽形态
    "ability_druid_aquaticform",   -- 水栖形态
    "spell_nature_spiritwolf",     -- 幽魂之狼
    "ability_druid_treeoflife",    -- 生命之树
    "ability_druid_stagform",      -- 鹿形态
    "ability_druid_flightform",    -- 飞行形态
}
-- 猎人守护（跳过）
hunterAspectIcons = {
    "ability_mount_jungletiger",   -- 猎豹守护
    "ability_mount_packhorse",     -- 豹群守护
}
```

## 扩展方法

遇到新坐骑无法自动下马时：
1. 在 `InitAutoDismount` 中将 `_debug` 设为 `true`
2. 骑上坐骑施法，查看聊天窗口中的 `[Nanami-DBG] buff[x]=` 输出
3. 将新坐骑的图标关键字添加到 `mountIconPatterns`