[MD]
# ⚔️ 鲸鱼御剑 | JYSwordComing
> **售前一句话**：让玩家骑上飞剑自由翱翔天际，支持多武器配置、按键技能释放、DragonCore 动作与模型联动。
***
## 1. 产品定位
| 项目 | 内容 |
| ---- | ------------------------------------------ |
| 插件名称 | **JYSwordComing /** 鲸鱼御剑 |
| 适配版本 | **Minecraft 1.12.2** |
| 标准价格 | **19.9RMB** |
| 核心价值 | 让 RPG 服务器拥有仙侠风格的御剑飞行体验，支持多武器差异化飞行参数与空中技能释放 |
***
## 2. 适用场景
- **仙侠 RPG 服务器**：玩家手持飞剑即可御剑飞行，配合 DragonCore 模型实现视觉沉浸感。
- **修仙练级体系**：不同等级飞剑拥有不同飞行速度、高度和距离限制，形成成长目标。
- **空中战斗玩法**：飞行中释放 MythicMobs 技能，实现空战、空中 Boss 战等玩法。
- **活动与探索**：利用飞行高度和距离限制，设计限时探索、竞速等趣味活动。
***
## 3. 功能全景
| 功能模块 | 可以怎么讲 | 给服主带来的价值 |
| ---------------- | ---------------------------------- | ------------------------ |
| ⚔️ 御剑飞行 | 玩家手持匹配武器输入指令即可骑乘飞剑自由飞行 | 打造仙侠核心体验，提升玩家沉浸感 |
| 🎮 按键操控 | WASD 控制方向，空格上升，Shift 下降，视角决定飞行朝向 | 操作直观流畅，无需额外学习成本 |
| 🔫 空中技能 | 飞行中按鼠标左/右键或自定义按键释放 MythicMobs 技能 | 实现空中战斗、技能连招等进阶玩法 |
| 🗡️ 多武器配置 | 每把飞剑可独立配置速度、高度、距离、碰撞、偏移等参数 | 武器差异化，低级剑慢且受限，高级剑快且自由 |
| 🔑 权限与条件 | 支持权限节点和 PlaceholderAPI 条件表达式限制武器使用 | 灵活接入等级、经济、声望等体系 |
| 🎭 DragonCore 联动 | 支持站立/坐姿飞行模式，通过 DragonCore 动作冻结玩家动画 | 飞行姿态自然，模型展示精准 |
| 🛡️ 安全机制 | 受伤自动收剑、超出高度/距离自动收剑、免疫摔落伤害 | 防止滥用，保障玩法平衡 |
| 🔄 悬停修正 | 无输入时自动修正漂移，保持悬停位置稳定 | 飞行手感丝滑，不会"溜车" |
| 🧹 残留清理 | 玩家上线时自动检测并清理残留的飞剑实体 | 服务器崩溃/强制关闭后不会出现"卡在空中"的问题 |
***
## 4. 前置插件
> - **DragonCore**（必须）— 提供按键注册、槽位读取、动作播放和模型显示支持
> - **MythicMobs**（必须）— 提供技能释放接口，飞行中的技能由 MM 施放
> - **PlaceholderAPI**（可选）— 支持在武器配置中使用 PAPI 变量条件表达式
***
## 5. 配置文件
### 5.1 主配置文件 (config.yml)
<details>
<summary>点击展开/收起主配置文件</summary>
```yaml
# ===================================================
# JYSwordComing 主配置文件
# ===================================================
# ---------------------------------------------------
# 武器识别来源
# ---------------------------------------------------
# HAND: 检测玩家手中拿着的物品
# SLOT: 检测 DragonCore 指定槽位中的物品
# ---------------------------------------------------
weapon-source: HAND
# 如果 weapon-source 设置为 SLOT，则需要填写 DragonCore 槽位标识符
# 该标识符需要与 DragonCore 配置文件中的槽位 ID 保持一致
dragoncore-slot: "weapon_slot"
# ---------------------------------------------------
# 默认飞行参数
# ---------------------------------------------------
# 当某个武器在 weapons.yml 中没有配置 fly 段时，
# 将使用这里的默认值。
# ---------------------------------------------------
default-fly:
speed: 0.5 # 最大飞行速度 (格/tick)
collision-enabled: true # 是否启用碰撞检测
max-height: 80 # 最大飞行高度 (绝对 Y 坐标)，0 表示不限制
max-distance: 120 # 最大飞行距离 (从起飞点算起的水平距离)，0 表示不限制
weapon-offset: 0.4 # 武器模型向后偏移量 (格)，使玩家站在武器中间
# ---------------------------------------------------
# 飞行模式
# ---------------------------------------------------
# STAND: 站立飞行 (玩家站在武器上)
# SIT: 坐着飞行 (通过 DragonCore 动作实现坐姿)
# ---------------------------------------------------
flight-mode: STAND
# 坐着飞行时播放的 DragonCore 动作名称
# 仅在 flight-mode 为 SIT 时生效
# 动作名称需要与资源包中定义的动作一致
sit-animation: "sit"
# 站立飞行时播放的 DragonCore 动作名称
# 仅在 flight-mode 为 STAND 时生效
# 用于冻结玩家手脚摆动动画，使角色保持静止站立姿态
# 动作名称需要与资源包中定义的动作一致
# 若留空或动作不存在，则不播放动画（手脚会摆动）
stand-animation: "stand"
# ---------------------------------------------------
# 全局行为设置
# ---------------------------------------------------
# 受到伤害时是否自动收起飞剑 (如果武器单独配置了，则优先使用武器配置)
auto-unequip-on-damage: true
# 御剑飞行时是否免疫摔落伤害
prevent-fall-damage: true
# 调试模式：输出详细日志用于排查问题
debug: false
# ---------------------------------------------------
# 提示消息 (支持颜色代码 &)
# ---------------------------------------------------
messages:
no-permission: "&c你没有权限使用该武器"
requirement-fail: "&c你不满足使用该武器的条件"
weapon-not-found: "&c未找到匹配的武器配置"
equip-success: "&a你已踏上飞剑！"
unequip-success: "&a你已收起飞剑"
reload-success: "&a配置文件已重新加载"
out-of-range: "&c已超出飞行距离，飞剑自动收起"
out-of-height: "&c已超出飞行高度限制，飞剑自动收起"
```
</details>
### 5.2 武器库配置 (weapons.yml)
<details>
<summary>点击展开/收起武器库配置文件</summary>
```yaml
# ===================================================
# JYSwordComing 武器库配置
# ===================================================
# 本文件用于定义所有可用的飞剑武器。
# 每个武器都是一个独立的配置单元，以任意不重复的英文/数字名称作为 key。
# ===================================================
weapons:
# -------------------------------------------------
# 示例武器 1 - 初级飞剑
# -------------------------------------------------
sword_1:
# -------------------------------------------------
# 【必填】匹配文本
# -------------------------------------------------
# 插件会检测物品的显示名称(name)或任意一行描述(lore)
# 是否【包含】此文本 (不区分大小写)。
# 支持颜色符号 &，会自动转换为标准颜色代码 §。
# -------------------------------------------------
match: "测试模型1"
# -------------------------------------------------
# 【可选】显示名称
# -------------------------------------------------
# 在提示消息中使用的武器名称，若不填写则显示 match 的值。
# -------------------------------------------------
display: "&b初级飞剑"
# -------------------------------------------------
# 【可选】权限节点
# -------------------------------------------------
# 玩家需要拥有此权限才能使用该武器。
# 若不填写或留空，则不需要任何权限。
# -------------------------------------------------
permission: "jianlai.weapon.sword_1"
# -------------------------------------------------
# 【可选】PAPI 条件表达式
# -------------------------------------------------
# 使用 PlaceholderAPI 变量编写的条件表达式。
# 只有当表达式结果为 true 时，玩家才能使用该武器。
# 若不填写或留空，则不进行条件判断。
#
# 示例：
# "%player_level% >= 10" 等级大于等于10
# "%player_health% > 10 && %vault_eco_balance% > 1000"
# -------------------------------------------------
requirement: "%player_level% >= 10"
# -------------------------------------------------
# 【可选】飞行属性
# -------------------------------------------------
# 若不填写整个 fly 段，则使用 config.yml 中的默认飞行参数。
# 若只填写部分属性，则未填写的属性将使用默认值。
# -------------------------------------------------
fly:
speed: 0.8
collision-enabled: true
max-height: 60
max-distance: 150
weapon-offset: 0.5
# -------------------------------------------------
# 【可选】技能按键绑定
# -------------------------------------------------
# 按下指定按键时，会以飞剑实体为施法者释放对应的 MythicMobs 技能。
# 支持的按键：
# LEFT : 鼠标左键
# RIGHT : 鼠标右键
# A ~ Z 中的任意字母键 (除了 W A S D 用于飞行控制)
# -------------------------------------------------
# 如果整个 skills 段不存在或留空，则按下任何按键都不会释放技能。
# -------------------------------------------------
skills:
LEFT: "FireBall" # 鼠标左键释放 FireBall 技能
RIGHT: "Heal" # 鼠标右键释放 Heal 技能
Q: "Teleport" # 按下 Q 键释放 Teleport 技能
X: "LaunchProjectile" # 按下 X 键释放 LaunchProjectile 技能
# -------------------------------------------------
# 【可选】行为开关
# -------------------------------------------------
# 若不填写整个 behavior 段，则使用 config.yml 中的全局设置。
# -------------------------------------------------
behavior:
# 受到伤害时是否自动收起飞剑
auto-unequip-on-damage: true
# -------------------------------------------------
# 示例武器 2 - 高级飞剑 (省略部分可选配置)
# -------------------------------------------------
sword_2:
match: "&6高级飞剑"
display: "&6高级飞剑"
# 没有配置 permission，表示不需要权限
# 没有配置 requirement，表示不需要 PAPI 条件
fly:
speed: 1.2
collision-enabled: true
max-height: 100
weapon-offset: 0.6
skills:
LEFT: "IceBolt"
F: "SpeedBoost"
# 没有配置 behavior，将使用全局设置 (auto-unequip-on-damage = true)
# -------------------------------------------------
# 示例武器 3 - 最简配置 (只有必填的 match)
# -------------------------------------------------
sword_3:
match: "普通木剑"
# 其他所有设置均使用默认值或留空
```
</details>
***
## 6. 飞行操控说明
| 按键 | 功能 |
| ---------- | ---------------- |
| W | 向视角方向前进 |
| S | 向视角方向后退 |
| A | 向左平移 |
| D | 向右平移 |
| 空格 (Space) | 上升 |
| Shift | 下降 |
| 鼠标视角 | 控制飞行朝向（飞剑模型自动跟随） |
> 飞行时松开所有按键将自动悬停，不会漂移。同时按下相反方向键（如 W+S）输入会互相抵消，保持悬停。
***
## 7. 插件指令
| 指令 | 说明 |
| ----------------- | -------- |
| `/jysword on` | 召唤飞剑开始飞行 |
| `/jysword off` | 收起飞剑结束飞行 |
| `/jysword reload` | 重载配置文件 |
| `/jysword help` | 显示帮助菜单 |
> 指令别名：`/jys`、`/jianlai`
***
## 8. 插件指令权限
| 权限节点 | 说明 | 默认值 |
| --------------------- | ------------------------------ | --- |
| jysword.reload | 重载配置文件命令 | op |
| jianlai.weapon.<武器ID> | 使用指定武器飞行的权限（在 weapons.yml 中配置） | 无 |
***
## 9. 武器匹配机制
插件通过以下方式匹配玩家手中的武器：
1. **获取物品**：根据 `weapon-source` 配置，从玩家主手或 DragonCore 指定槽位获取物品
2. **提取文本**：提取物品的显示名称（优先使用 DragonCore 的 `ItemUtil.getName`，回退到 Bukkit 的 `displayName`）和 Lore 描述
3. **模糊匹配**：将武器配置中的 `match` 文本与物品名称/Lore 进行**包含匹配**（不区分大小写，忽略颜色代码）
4. **匹配成功**：返回第一个匹配到的武器配置
> 示例：`match: "飞剑"` 可以匹配名称为 `&b极品飞剑` 的物品，也可以匹配 Lore 中包含 `飞剑` 的物品。
***
## 10. 技能释放机制
飞行中的技能释放流程：
1. **按键触发**：玩家按下绑定的按键（鼠标左/右键或自定义字母键）
2. **施法者**：以飞剑实体（ArmorStand）作为 MythicMobs 技能的施法者
3. **施法位置**：以飞剑实体当前位置作为技能释放位置
4. **冷却时间**：内置 500ms 技能冷却，防止频繁触发
5. **按键注册**：飞行控制键（WASD/Space/Shift）在插件启动时注册；技能按键在玩家装备武器时动态注册，卸下武器时动态注销
> W/A/S/D 按键仅用于飞行控制，不可绑定为技能键。
[ATTACH]140569[/ATTACH]
[/MD]
