SkyPVP 2.4.0
完整使用教程

01 · DEPLOY

首次安装

1. 安装 Java 21，准备干净的 Paper 1.21.8 服务端。
2. 停止服务器，把 SkyPVP-Core.jar 放入 plugins/。
3. 把免费扩展和已购买的 Explosives／CombatFX JAR 放入 plugins/SkyPVPCore/plugins/；没有该目录时可先启动一次核心再停止服务器。
4. 需要幸运方块自定义头颅时安装 HeadDatabase；需要变量时安装 PlaceholderAPI。
5. 启动服务器并执行 /skypvp，确认 Core 2.4.0 与附属状态正常。

plugins/
├─ SkyPVP-Core.jar
└─ SkyPVPCore/
   ├─ config.yml
   ├─ addons/
   └─ plugins/
      ├─ SkyPVPKits.jar
      ├─ SkyPVPLuckyBlock.jar
      ├─ SkyPVPProgression.jar
      ├─ SkyPVPWorldGuard.jar
      ├─ SkyPVP-Explosives-1.0.0.jar  # 付费可选
      └─ SkyPVP-CombatFX-1.1.0.jar    # 付费可选

02 · UPGRADE

升级到 2.4.0

1. 执行 save-all flush，再执行 stop。
2. 完整备份 plugins/SkyPVPCore/。
3. 替换 plugins/SkyPVP-Core.jar；免费扩展只有版本变化时才需要替换。
4. 移走遗留的 *.jar1、*.jar2 或嵌套的 Addon.zip，避免重复加载。
5. 不要覆盖现有 config.yml、addons/ 与玩家数据；2.4 会迁移旧配置并保留备份。
6. 完整启动服务器并逐项验证状态页、Dialog、职业、幸运方块、等级和世界保护。

03 · LICENSE V2

获取与热更新 V2 授权

1. 使用邮箱验证码登录授权中心；未购买账户也可按冷却时间领取免费试用。
2. 选择 Core 或 Explosives，再填写服务器实际对外 IPv4。
3. Core 执行 /skypvp license apply <授权码>；Explosives 执行 /skypvp explosives license apply <授权码>，均可在运行中热应用。
4. 30 分钟试用每 3 天可领取一次，3 天试用每 14 天可领取一次；到期后插件会停止受授权保护的功能。

一个账户对每个产品只能绑定一个 IP。V2 使用 Ed25519 离线验签并在本地检查到期时间；远程不可用不影响本地有效授权，联网时会同步撤销状态。

04 · NATIVE DIALOG

游戏内配置与 YAML

管理员执行 /skypvp admin 打开 Core 2.4 原生 Dialog。界面可查看授权状态、模块状态，并进入幸运方块、职业包、世界状态、经验和消息配置。保存后按界面提示重载对应模块。

需要批量编辑时，先停止服务器并备份 plugins/SkyPVPCore/，使用 UTF-8 编辑 YAML。只修改值，不要破坏缩进；字符串含冒号、井号或颜色代码时加引号。启动后先观察控制台 YAML 报错，再用 Dialog 检查迁移后的最终值。

05 · CORE

核心命令

可重载的扩展名：SkyPVPKits、SkyPVPLuckyBlock、SkyPVPProgression、SkyPVPWorldGuard、SkyPVPExplosives。

05 · KITS

职业模块

职业名会规范化为小写字母、数字、下划线或短横线。职业发放时若背包已满，放不下的物品会掉落在玩家脚下。

06 · LUCKY BLOCK

幸运方块模块

管理命令权限为 skypvp.admin.luckyblock，并兼容旧拼写 skypvp.admin.luckblock。概率可输入小数或百分比。set 需要有效 HeadDatabase ID；heal 只扫描已加载区块，每轮最多修复 4 个。

/skypvp luckyblock add default 25%
/skypvp luckyblock set default 300 <HDB-ID>
/skypvp luckyblock list default

非空奖池会按权重抽取；空奖池仍会触发既定事件与经验逻辑。管理 GUI 还可以配置彩色标题、倒计时、左旋或右旋以及旋转速度。

07 · PROGRESSION 2.2.0

成长模块

Progression 2.2.0 增加彩色等级阶段、经验/升级/阶段提升音效、连续经验提示合并、玩家个人开关和经验审计。升级时保留 players.yml，旧版 level-prefix.ranges 会自动迁移，不会重置玩家数据。

管理命令权限为 skypvp.admin.exp。执行 /skypvp admin，进入“经验与成长”，即可编辑每级经验、经验来源、防刷、等级区间、消息和音效；音效支持在保存前立即试听。

等级区间

level-tiers:
  beginner:
    min-level: 0
    max-level: 9
    display: 新手
    color: '&7'
    format: '%color%Lv.%level% %symbol%'
    symbol: '⭐'
  legend:
    min-level: 75
    max-level: -1
    display: 传奇
    color: '&6&l'
    format: '%color%[%tier%] Lv.%level% %symbol%'
    symbol: '★'

max-level: -1 表示没有上限。格式支持 %color%、%level%、%tier%、%tier_id% 和 %symbol%。

经验与升级音效

settings:
  sounds:
    experience-gain:
      enabled: true
      sound: ENTITY_EXPERIENCE_ORB_PICKUP
      volume: 0.55
      pitch-mode: BY_AMOUNT
      minimum-pitch: 0.8
      maximum-pitch: 1.6
      cooldown-millis: 150
    level-up:
      enabled: true
      sound: ENTITY_PLAYER_LEVELUP
      volume: 1.0
      pitch: 1.15
    tier-up:
      enabled: true
      sound: UI_TOAST_CHALLENGE_COMPLETE
      volume: 1.0
      pitch: 1.0

音效名可写传统 Bukkit 名称，也可写 minecraft:entity.player.levelup。无效名称会安全跳过并在控制台提示，不会使附属停止运行。

连续经验提示与审计

settings.actionbar.merge-window-ticks 控制经验合并窗口。击杀经验和连杀奖励在短时间内同时出现时会汇总为一条提示。每次经验变化都会写入 plugins/SkyPVPCore/addons/SkyPVPProgression/experience-audit.csv，可用于定位经验来源和异常变动。

可用 PlaceholderAPI 变量：

08 · WORLD PROTECTION

世界保护模块

所需权限：skypvp.admin.worldguard。修改后用实际玩家测试放置、破坏和交互行为。

09 · EXPLOSIVES · ¥4.99

战术 TNT 与火焰弹

Explosives 是独立付费扩展。TNT 用于近战清图，火焰弹用于远程打击；爆炸事件始终取消方块破坏和点火，只手动计算玩家伤害与击退。

1. 管理员执行 /skypvp explosives admin。
2. 在配置档中分别设置自己/他人的伤害、水平和垂直击退、半径、冷却与距离衰减。
3. 用权限与优先级把玩家分配到 default、vip 或自建配置档。
4. 在效果页预览轨迹粒子、命中音效与爆炸音效，再保存配置。
5. 用 give 发放测试物品；只有插件标记的道具会触发能力，普通 TNT 与火焰弹不受影响。

10 · COMBATFX 1.1.0 · ¥4.99

云墨战迹 · 战斗特效与击败消息

CombatFX 读取最终战斗结果，播放粒子、声音与伤害读数，并按击败方式展示可配置消息；它不修改伤害、击退、攻击冷却、无敌帧或死亡判定。

1. 将 JAR 放入 plugins/SkyPVPCore/plugins/，移除旧 SkyPVPEffects，避免双重播放。
2. 使用产品标识 skypvp-combatfx 的独立授权码热应用；Core 或 Explosives 授权码不能替代。
3. 玩家执行 /skypvp combatfx，在 Dialog 中调整显示、声音和低配模式，再用箱子菜单左键装备、右键预览。
4. 管理员执行 /skypvp combatfx admin，编辑 8 套主题、6 个频道、击败消息、动画步骤、世界范围与粒子预算。
5. 高峰期优先降低可见距离和每 Tick 粒子预算；详细 YAML 与权限见完整 Wiki。

11 · DEFEAT MESSAGES

按击败方式显示消息

1.1.0 内置近战、弹射物、爆炸、火焰、岩浆、摔落、虚空、魔法、窒息、自杀和其他共 11 类消息。每类都可以填写多条文案，触发时随机选择一条。

defeat-messages:
  enabled: true
  causes:
    melee:
      - "&e%victim% &7被 &c%killer% &7正面击败"
    projectile:
      - "&e%victim% &7没能躲开 &c%killer% &7的远程攻击"
    void:
      - "&e%victim% &7被 &c%killer% &7击落虚空"
    suicide:
      - "&e%victim% &7结束了自己的战斗"
    other:
      - "&e%victim% &7离开了战场"

可用变量：%killer%、%victim%、%weapon%、%world%、%distance%、%killer_health%、%killer_level%、%victim_level%。

11 · PERMISSIONS

权限汇总

11 · MAINTENANCE

维护与排错

• 只改配置：使用对应模块的重载命令；Explosives 使用 /skypvp explosives reload。
• 更新 JAR：执行 save-all flush 与 stop，替换文件后完整启动。
• 幸运方块异常：先用 list 确认登记，再用 heal 修复已加载区块，必要时开启 debug。
• 爆炸物异常：确认扩展授权属于 skypvp-explosives、玩家拿的是插件发放道具，并检查所用权限配置档。
• 绝对不要使用 Bukkit/Paper 全局 /reload，它会造成监听器、任务和插件状态不一致。