概览
Prop 快捷道具模块概览，客户端按键绑定、手持右键触发、冷却消耗与临时属性加成
概览
模块简介
Prop（快捷道具）模块为 ArcartX 客户端 MOD 生态提供一套完整的快捷道具系统。服务器管理员通过 YAML 文件定义道具（Prop），每个道具绑定一组效果（命令、消息、药水、属性加成等）与使用条件。玩家可以通过两种方式触发道具：
- 手持右键：将任意物品通过管理命令绑定为指定道具后，右键即可使用
- 客户端按键：通过 ArcartX 客户端按键系统将道具槽位绑定到键盘按键（如 Z/X/C），按下即触发
道具支持冷却组、消耗、权限校验、PlaceholderAPI 条件判断，以及 AttributePlus / MythicLib / Symphony 三套属性插件的临时属性加成。属性加成在持续时间到期后自动移除，玩家下线时也会自动清理。
| 属性 | 值 |
|---|---|
| 模块 ID | prop |
| 模块名称 | Prop |
| 当前版本 | 1.4.4 |
| 主类 | xuanmo.arcartxsuite.prop.PropModule |
| 配置文件 | config.yml |
| 消息文件 | messages.yml |
| 数据目录 | data/prop/ |
| 命令 ID | prop |
| EventBus 主题 | axs.prop.prop_used |
| 存储模式 | 无持久化存储（纯内存运行） |
功能特性
| 特性 | 说明 |
|---|---|
| 客户端按键绑定 | 通过 ArcartX 客户端按键系统将道具槽位绑定到键盘按键，按下即触发使用 |
| 手持右键使用 | 将任意物品绑定为指定道具后，玩家手持右键即可触发 |
| 多槽位支持 | 支持配置多个快捷道具槽位（Slot1/Slot2/Slot3...），每个槽位独立绑定按键 |
| 冷却组 | 同一冷却组内的多个道具共享冷却时间，避免重复使用 |
| 物品消耗 | 使用后可选消耗一个物品（remove: true）或保留物品（remove: false） |
| 权限控制 | 每个道具可配置使用权限节点，留空表示无限制 |
| 使用条件 | 支持 PlaceholderAPI 条件判断（等级、余额、世界、职业等），全部满足才可使用 |
| 效果系统 | 支持 10 种效果类型：命令、消息、饱食度、生命值、经验、百分比生命、药水、AttributePlus、MythicLib、Symphony |
| 临时属性加成 | 通过 AttributePlus / MythicLib / Symphony 附加临时属性，持续时间结束后自动移除 |
| 药水兼容 | 兼容 1.20.2+ 药水效果重命名（如 SLOW → SLOWNESS），旧名自动映射 |
| 原版物品名解析 | 使用宿主 VanillaItemNameBridge 解析物品显示名，用于冷却与提示消息 |
依赖关系
| 类型 | 依赖 | 说明 |
|---|---|---|
| 必需 | ArcartX 客户端 MOD | 提供客户端按键绑定、额外槽位、物品 PDC 持久化等能力 |
| 必需 | ArcartXSuite 宿主 | 提供 PropBridgeAPI、AttributeBridgeRegistry、EventBusCapability 等基础设施 |
| 可选 | AttributePlus | ap 效果类型，附加临时属性词条 |
| 可选 | MythicLib | ml / mythiclib 效果类型，附加临时属性 modifier |
| 可选 | Symphony | sy / symphony 效果类型，附加临时属性修改 |
| 可选 | PlaceholderAPI | 使用条件中的 PAPI 变量解析 |
属性桥接的启用由宿主
config.yml的attribute-bridges节统一管理。即使服务器安装了对应插件，若此处设为false，Prop 模块也无法使用其属性功能。
道具机制
道具定义与 ID
道具定义存放在 data/prop/props/ 目录下的 YAML 文件中。加载器（PropDefinitionLoader）递归扫描该目录，以文件相对路径（去除扩展名、小写归一化）作为道具 ID。例如 props/技能/火球术.yml 的道具 ID 为 技能/火球术（小写）。
物品绑定
通过管理命令 /axs prop set <道具ID> 将玩家主手物品绑定为指定道具。绑定过程通过 PropBridgeAPI.writePropId() 将道具 ID 写入物品的 PersistentDataContainer（PDC），同时通过 setCooldownTag() 写入冷却组标签。绑定后物品即可通过手持右键触发。
按键触发
按键映射在 data/prop/key.yml 中配置。每个绑定定义了默认按键（如 Z）和关联的道具槽位（如 Slot1）。模块启动时通过 PropBridgeAPI.registerClientKeyBind() 向 ArcartX 客户端注册按键绑定，按下时读取对应槽位的物品，解析道具 ID 后触发使用。
使用流程
无论是手持右键还是按键触发，使用流程一致：
- 解析物品中的道具 ID（PDC 读取）
- 查找道具定义，同步冷却组标签
- 检查冷却（按冷却组共享）
- 检查使用方式限制（
hand/key开关） - 检查权限（
permission节点） - 检查使用条件（
conditions列表，AND 逻辑） - 设置冷却时间
- 消耗物品（如
remove: true） - 执行效果列表
- 发布
axs.prop.prop_used事件到 EventBus
效果执行
效果以 type|payload 格式编写，模块按行解析并分类执行。属性类效果（ap / ml / sy）会聚合后批量提交给对应属性服务，在 Duration 秒后自动移除。其他效果（命令、消息、药水等）立即执行。
冷却机制
冷却以冷却组为单位管理。同一冷却组内的多个道具共享一个冷却计时器，使用任一道具后整组进入冷却。冷却时间存储在客户端标签中（PropPlayerHandle.setTagCooldown()），按键触发时若冷却未结束会同步槽位缓存到客户端。