ResidenceRPGDash

为 Luminol/Paper 1.21.11 与 Residence 6.0.1.8 编写的 Folia 兼容空手 F 键冲刺插件。

功能

• 仅在明确开启 rpgdash Flag 的 Residence 领地内生效。
• 玩家主手与副手均为空时按一次 F，向视线水平方向跳跃冲刺。
• 任一只手有物品时不会冲刺，也不会取消原版主副手交换；副手物品可正常使用。
• 领地外、无权限或状态不符合要求时，F 保持原版行为。
• 默认冷却 5 秒，可在配置文件中修改。
• 冷却中空手按 F 时，动作栏显示向上取整的剩余秒数。
• 冷却结束后，动作栏显示美化的就绪提示。
• 冲刺力度、音效、云雾粒子、烟花火星粒子和全部玩家文字均可配置。
• 不监听跳跃或修改玩家飞行权限，不会与服务器飞行功能冲突。

环境要求

• Java 21
• Luminol/Paper API 1.21.11
• Residence 6.0.1.8 或保持相同 API 契约的后续版本

Residence 是硬前置，缺少时插件不会加载。LuckPerms 不是代码前置，只用于管理 Bukkit 权限节点。

安装与启用

1. 将 ResidenceRPGDash-1.0.0.jar 放入服务器的 plugins 目录。
2. 确认服务器已经安装 Residence。
3. 完整重启服务器。
4. 为需要启用的领地执行：

/resadmin set <领地名> rpgdash true

关闭功能：

/resadmin set <领地名> rpgdash false

未设置 rpgdash 的领地默认关闭，不会自动启用。

权限

residencergpdash.use
residencergpdash.admin

两个权限在 plugin.yml 中都设置为 default: op，默认仅管理员拥有。residencergpdash.use 控制冲刺使用权，residencergpdash.admin 控制帮助与热加载命令。

使用 LuckPerms 授权普通玩家：

/lp user <玩家名> permission set residencergpdash.use true

为权限组授权：

/lp group <权限组> permission set residencergpdash.use true

管理命令

/rrd help
/rrd reload

/rrd help 显示管理帮助；/rrd reload 异步读取 config.yml，并原子热加载冲刺参数及全部语言文字。加载失败时插件会继续使用旧配置，不会留下半更新状态。

配置

首次启动后生成 plugins/ResidenceRPGDash/config.yml。配置文件包含完整中文注释，主要选项如下：

dash:
  cooldown-seconds: 5
  horizontal-power: 1.25
  vertical-power: 0.55

动作栏文字支持 MiniMessage。冷却文字中的 {seconds} 会替换为向上取整后的剩余秒数，因此冷却尚未结束时不会显示 0 秒。无效的 MiniMessage 会在启动时回退为默认美化文本并输出中文警告。

修改后执行 /rrd reload 即可热加载配置与语言。这里的热加载只重读本插件配置，不会卸载或重新加载插件本体；仍不建议使用第三方插件管理器强制热重载整个插件。

Folia 说明

• Folia 在插件启用早期只检测一次，结果会被缓存。
• 业务代码不直接调用旧版 BukkitScheduler。
• 玩家、位置、速度、粒子、音效和动作栏均在玩家所属 Entity/Region 上下文访问。
• Entity/Region 延迟最少为 1 tick。
• 共享状态使用并发集合，且只保存 UUID、时间戳和可取消任务句柄。
• 玩家离开资格区域、死亡、退出或插件停用时会取消任务并清理状态。
• 插件不监听目标 Folia 1.21.11 中不可用的世界切换、传送、重生和世界加载/卸载事件。

folia-supported: true 只表示允许加载，不单独证明线程安全。当前实现针对 Luminol 1.21.11 与 Paper API 1.21.11-R0.1-SNAPSHOT 进行静态编译验证；升级服务端核心或 Residence 后应重新验证。

构建

项目默认从以下位置读取 Residence 编译依赖：

D:/Users/Administrator/Desktop/fwq/xw/plugins/Residence6.0.1.8.jar

其他环境可以覆盖路径：

gradle clean test build -PresidenceJar='D:/server/plugins/Residence.jar'

Residence 仅作为 compileOnly 依赖，不会被打包进本插件 JAR。

许可证

Copyright (C) 2026 xWtree

本项目使用 GNU General Public License v3.0 开源。完整条款见 LICENSE。

• 作者：xWtree
• 网站：https://github.com/mcxyd