原创 工具 娱乐 CharmPlugin —— 根据权限节点给予永久药水buff的护符系统 1.0

简介​

CharmPlugin2 是一款专为 Spigot / Paper 1.21.4 设计的轻量级护符插件。它允许服主通过权限节点为玩家绑定永久的药水效果（如速度、力量、夜视等），并且玩家可以随时使用指令 开关 这些效果，所有开关状态会持久化存储于 MySQL 数据库中。
本插件特别适合RPG服务器或生存服务器，作为玩家成长或氪金奖励的一环。

---

功能特性​

• 权限驱动：每个护符对应一个权限节点，拥有权限即代表玩家“拥有”该护符。
• 永久药水效果：护符提供的药水效果是永久持续的（直到玩家主动关闭或管理员收回）。
• 玩家自主开关：玩家可使用 /charm toggle <护符> 自由开启/关闭已拥有的护符效果。
• 状态持久化：玩家的开关状态保存在 MySQL 数据库中，重启服务器后依然保留。
• 死亡自动禁用（可选）：可配置玩家死亡后自动禁用所有护符，增加生存难度。
• 冷却机制：切换护符状态有冷却时间（可单独配置），防止高频切换。
• 管理员命令：支持在线给予/移除玩家护符权限，无需手动修改权限文件。
• 高度自定义：每个护符可单独配置药水效果、等级、显示名称、冷却时间。
• 轻量高效：定时任务周期检查并应用效果，资源消耗低。

---

命令列表​

玩家命令（需要 charm.use 权限）：

• /charm list
  说明：列出所有可用护符及当前状态（启用/禁用/无权限）
• /charm toggle <护符>
  说明：开启或关闭指定护符的效果（需拥有该护符权限）
• /charm reload
  说明：重载配置文件（额外需要 charm.admin 权限）

管理员命令（需要 charm.admin 权限）：

• /charmadmin reload
  说明：重载配置文件
• /charmadmin give <玩家> <护符>
  说明：给予指定玩家某个护符的权限（并自动设为启用状态）
• /charmadmin take <玩家> <护符>
  说明：移除指定玩家的某个护符权限（同时删除状态记录）

---

权限节点（纯文本）​

• charm.use
  描述：允许玩家使用 /charm 命令
  默认值：true（所有玩家）
• charm.admin
  描述：允许使用 /charmadmin 命令及 /charm reload
  默认值：op（管理员）
• charm.bypass
  描述：绕过切换护符的冷却时间
  默认值：op
• 护符权限节点：
  每个护符的权限节点 = 配置文件中定义的护符键名（例如 speed、strength、jump 等）。
  您需要在权限插件中为玩家授予对应节点，玩家才拥有该护符。

​

护符权限：每个护符的权限节点即为配置中定义的 charmKey（例如 speed、strength）。你需要在权限插件（如 LuckPerms）中给玩家授予相应权限，玩家才会拥有该护符。

支持的药水效果类型​

插件支持所有原版 PotionEffectType，常见的有：

• SPEED（速度）
• STRENGTH（力量）
• JUMP_BOOST（跳跃提升）
• NIGHT_VISION（夜视）
• FIRE_RESISTANCE（防火）
• INCREASE_DAMAGE（自动映射为 STRENGTH）
• JUMP（自动映射为 JUMP_BOOST）

提示：如果你不确定某个效果名称，可以使用 PotionEffectType 枚举中的名称（如 HEALTH_BOOST、HASTE 等）。

点击展开...

---

安装与使用​

1. 下载插件：将 CharmPlugin2.jar 放入服务器的 plugins 文件夹。
2. 配置 MySQL：编辑 config.yml，填写正确的数据库连接信息（需要提前创建好数据库）。
3. 启动服务器：插件会自动创建数据表（charm_players 和 charm_charms）。
4. 配置权限：在权限插件中为玩家添加对应护符的权限节点（如 speed）。
5. 重载或重启：执行 /charm reload 或重启服务器使配置生效。
6. 玩家使用：拥有权限的玩家输入 /charm list 查看护符，使用 /charm toggle &lt;护符&gt; 开启/关闭效果。

---

数据库结构​

• charm_players：存储玩家 UUID 和最后已知名称。
• charm_charms：存储玩家每个护符的启用状态（enabled 布尔值）。

所有数据在玩家离开服务器后依然保留，保证状态持久化。

---

注意事项​

1. 药水效果冲突：本插件在应用效果时，会移除该玩家身上同类型的药水效果再重新添加，以确保护符效果是唯一的。如果你有其他插件也在给玩家添加同类型效果，可能会出现覆盖问题，请留意。
2. 权限同步：玩家是否拥有护符完全取决于其权限节点。如果管理员通过 /charmadmin give 给予权限，插件会自动记录状态；但如果直接通过权限插件添加权限，玩家需要手动切换一次（或重进服务器）才会生效。
3. 冷却机制：切换护符的冷却时间仅针对“切换操作”本身，不影响效果持续时间（因为是永久）。
4. MySQL 依赖：本插件必须使用 MySQL，不支持 SQLite。请确保数据库服务正常运行。
5. 版本兼容：插件基于 1.21.4 API 构建，但在 1.20、1.19、1.18、1.17、1.6版本也可能运行（未全面测试）。

---

常见问题​

Q：玩家拥有权限但护符没有生效？
A：请确认玩家是否通过 /charm toggle 开启了该护符（状态默认为启用，但若通过管理员给予则自动启用）。也可以尝试重进服务器或使用 /charm reload。

Q：如何添加新的护符？
A：在 config.yml 的 charms 下按照格式添加新的条目，然后重载配置。之后给玩家对应的权限即可。

Q：可以设置护符为默认启用吗？
A：默认情况下，玩家首次获得护符权限时，状态为启用（enabled=true）。如果你希望默认禁用，可在数据库中手动修改，或稍后我们会考虑添加配置选项。

Q：插件支持 PlaceholderAPI 吗？
A：当前版本暂不支持，但未来可能会添加。

配置文件详解​

yaml
# MySQL 数据库配置
database:
host: 127.0.0.1
port: 3306
database: CharmPlugin
username: root
password: "你的密码"
table-prefix: charm_ # 表前缀，可避免与其他插件冲突
ssl: false

# 护符效果配置
charms:
speed: # 护符唯一标识（同时也是权限节点）
display-name: "&a速度护符" # 显示名称，支持颜色代码
type: "SPEED" # 药水效果类型（见下文支持列表）
level: 2 # 等级（实际效果等级 = level）
cooldown: 5 # 切换冷却时间（秒）
strength:
display-name: "&c力量护符"
type: "INCREASE_DAMAGE" # 自动映射为 STRENGTH
level: 2
cooldown: 5
# ... 可继续添加更多护符

# 系统设置
settings:
check-interval: 3 # 每隔几秒检查并应用效果（建议 3~5）
message-prefix: "&6[护符] &f" # 消息前缀
disable-on-death: false # 玩家死亡后是否自动禁用所有护符（true/false）