坐骑配置

坐骑文件放在插件目录的 ride/ 目录中，所有扩展名为 .yml 的文件都会被递归加载。每个文件代表一个坐骑，坐骑通过物品名称匹配配置中的 match-name。

重新加载插件时，示例坐骑文件会被覆盖为插件内置版本。请勿直接在 ride/示例坐骑.yml 中保存自定义配置，建议复制为新的坐骑文件后再修改。

基础结构

id: '示例'
type: 'pig'
match-name: '&6神驹·赤兔'
name: '&6神驹·赤兔'
fly: false
move-speed: 0.4
jump-power: 1
jump-tick: 5
jump-count: 2
rise-power: 2

配置	类型	说明
id	字符串	坐骑唯一 id。插件指令和 API 使用此值定位坐骑。
type	字符串	坐骑实体类型。目前支持 pig 和 dragon。
match-name	字符串	物品显示名称匹配文本。物品显示名称包含该文本时，判定为对应坐骑。支持 & 颜色代码。
name	字符串	坐骑显示名称，可用于模型名称匹配。支持 & 颜色代码。
fly	布尔值	是否启用飞行模式。飞行模式和陆行模式使用不同的移动逻辑。

type 会按不区分大小写的方式读取。当前项目为 v1_7_R4 和 v1_12_R1 提供了坐骑实体适配；其它 CraftBukkit 版本没有对应的适配实现。

如果需要套用模型，通常使用 pig。项目原配置说明指出，dragon 可能存在朝向问题。

匹配坐骑物品

插件从 config.yml 的 ride-slot 指定槽位读取物品名称，再与每个坐骑文件的 match-name 进行包含匹配。

match-name 匹配的是物品显示名称，不是物品类型或物品 id。多个坐骑的匹配文本发生重叠时，实际使用哪个坐骑取决于坐骑文件加载顺序，不建议配置重叠的匹配文本。

移动和跳跃

move-speed: 0.4
jump-power: 1
jump-tick: 5
jump-count: 2
rise-power: 2

配置	类型	说明
move-speed	小数	坐骑基础移动速度。最终速度还会根据 config.yml 中的移速属性配置和公式计算。
jump-power	小数	跳跃强度。跳跃期间使用该值计算垂直移动速度。
jump-tick	整数	跳跃持续时间，单位为 tick。最低有效值为 1。
jump-count	整数	单次骑乘允许的连续跳跃次数。陆行模式下，只有满足移动输入且当前跳跃状态结束时才会增加跳跃次数。
rise-power	整数	陆行模式自动攀升的最大检测高度。用于通过前方的台阶或低矮障碍。

骑乘期间，插件读取玩家的前进、后退、左移、右移和跳跃输入。陆行模式支持连续跳跃；飞行模式下，按住跳跃键会持续触发上升处理。

飞行参数

down-power:
  -20: -0.5
  -70: -1

up-power:
  20: 0.5
  70: 1

配置	类型	说明
down-power	键值映射	飞行模式低头时的下降力度。键名为视角角度阈值，值为对应的垂直移动力度。
up-power	键值映射	飞行模式抬头时的上升力度。键名为视角角度阈值，值为对应的垂直移动力度。

down-power 仅在 fly: true 时生效，用于视角向下时下降。up-power 仅在 fly: true 时生效，用于视角向上时上升。

飞行上升会受到 config.yml 中 world-fly-limit 的限制。配置了对应世界的高度后，坐骑达到该 Y 轴高度时会停止继续上升。

骑乘属性和伤害

riding-attribute:
  - '物理伤害10'

ride-can-damaged: false
ride-or-player-damaged-end-riding: true
player-attack-end-riding: true

配置	类型	说明
riding-attribute	字符串列表	骑乘开始时给玩家添加的属性，结束骑乘时移除。具体属性格式由所选属性插件决定。
ride-can-damaged	布尔值	坐骑是否可以受到伤害。设为 false 时，坐骑受到的伤害会被取消。
ride-or-player-damaged-end-riding	布尔值	玩家或坐骑受到伤害时是否结束骑乘。坐骑免疫伤害时，坐骑伤害事件会被取消，因此通常只有玩家受伤会触发结束骑乘。
player-attack-end-riding	布尔值	骑乘中的玩家造成伤害时是否结束骑乘。

riding-attribute 只有在 config.yml 正确选择并连接对应属性插件时才会生效。项目支持的属性插件名称为 AttributePlus2、AttributePlus3、SX-Attribute2 和 SX-Attribute3。

骑乘动作

riding-animation:
  - '动作1:1500'
  - 'delay:2000'
  - '动作2:1200'

配置	类型	说明
riding-animation	字符串列表	骑乘期间循环播放的玩家动作列表。插件按列表顺序播放，播放完成后从头循环。

动作支持以下格式：

格式	说明
动作名	播放动作，并使用默认的循环间隔。
动作名:毫秒	播放动作指定的毫秒数后继续下一项。
delay:毫秒	不播放动作，仅延迟指定的毫秒数后继续下一项。

动作会根据已启用的模型插件自动发送：启用 GermPlugin 时向附近玩家发送萌芽动作；否则在启用 DragonCore 时发送龙核玩家动作。

如果只需要循环一个动作，可以只配置一项：

riding-animation:
  - '动作1:1500'

技能触发时，骑乘循环动作会暂停约 1 秒，技能动作结束后从列表开头继续播放。

骑乘技能

坐骑技能写在坐骑文件的 event 节点下。每个子节点代表一个技能配置，子节点名称只是该技能在配置中的标识，不作为指令或变量使用。

event:
  骑乘技能示例:
    trigger-type: 'start-riding'
    chance: 0.5
    cooldown: 1000
    mythic-skill: ''
    success-message:
      - '你触发了示例技能'
    fail-message:
      - '你没有触发示例技能'
    success-command:
      - '[console]tell %player_name% 成功时执行这条指令'
    fail-command:
      - '[console]tell %player_name% 失败时执行这条指令'
    ride-action: ''
    player-action: ''

技能字段

配置	类型	默认值	说明
trigger-type	字符串	无	技能触发条件。必须使用支持的触发类型。
chance	小数	1	触发成功概率，通常填写 0 到 1 之间的值。插件使用随机数判断是否成功。
cooldown	整数	1000	技能冷却时间，单位为毫秒。触发检测后立即进入冷却，无论本次成功还是失败。
mythic-skill	字符串	空字符串	触发成功时由玩家释放的 MythicMobs 技能。留空或删除时不释放。
success-message	字符串列表	空列表	技能触发成功时发送给玩家的消息。支持 & 颜色代码。
fail-message	字符串列表	空列表	技能随机判定失败时发送给玩家的消息。支持 & 颜色代码。
success-command	字符串列表	空列表	技能触发成功时执行的指令。
fail-command	字符串列表	空列表	技能随机判定失败时执行的指令。
ride-action	字符串	空字符串	技能触发成功时播放的坐骑实体动作。支持 动作名 或 动作名:毫秒。
player-action	字符串	空字符串	技能触发成功时播放的玩家动作。支持 动作名 或 动作名:毫秒。

技能配置中的消息和指令只在对应的成功或失败分支执行。mythic-skill、消息、指令和动作均可单独留空。

触发类型

trigger-type	触发时机
start-riding	开始骑乘时。
end-riding	结束骑乘时。
fly-up	飞行模式上升时。
fly-down	飞行模式下降时。
fly-move	飞行模式水平移动时。
rising	陆行模式自动攀爬时。
forward	玩家按住前进方向开始移动时。
cease	玩家松开移动输入、坐骑停止移动时。
damaged	坐骑受到伤害并触发坐骑伤害事件时。
second	骑乘期间每秒触发一次检测时。可配合 cooldown 控制检测间隔。
right	骑乘中的玩家右键点击时。
left	骑乘中的玩家左键点击时。

部分移动类触发器由骑乘实体按时间间隔检测，因此并不是每个游戏 tick 都会执行技能。技能是否实际执行，还会受到 chance 和 cooldown 影响。

技能指令

技能指令支持以下执行前缀：

前缀	执行身份
[console]	使用控制台身份执行。
[op]	临时给予玩家 OP 后执行，执行完成后恢复原 OP 状态。
[player]	使用玩家身份执行。
无前缀	默认使用玩家身份执行。

指令会先处理 PlaceholderAPI 变量，并支持以下数值表达式：

表达式	说明
eval:{表达式}	计算表达式并输出结果。
ceil:{表达式}	计算表达式并向上取整。
floor:{表达式}	计算表达式并向下取整。

表达式可以在右花括号前追加格式，例如 eval:{1/3~%.2f}。指令中的 & 会转换为 Minecraft 颜色符号。

重载行为

执行插件重载后，插件会：

• 重新读取 config.yml。
• 重新读取 ride/ 目录下的所有 .yml 文件。
• 强制结束当前所有玩家的骑乘状态。
• 重新注册召唤坐骑按键。
• 重新读取 ride-slot。
• 重新加载 ProtocolLib 的坐骑移动数据包监听。

重载坐骑文件前，请确认 id 不重复，并确保 down-power、up-power 等映射节点存在且格式正确。