Snowy 插件文档
Snow Enchantsp

安装与配置

Snow-EnchantSP 的安装、附魔剥离 GUI 用法、三种支付方式与 pricing 价格体系配置。

Snow-EnchantSP

附魔剥离插件。玩家把带附魔的装备放进 GUI，插件列出该装备的每个附魔，点击其中一个即可把它从装备上摘下来变成附魔书，同时按配置扣除金币 / 点券 / 经验。

本手册基于插件当前源码整理，配置字段均以代码实际读取的为准。当前版本 1.0.0。

环境要求

项目要求
服务端Paper 及其衍生（用到 Adventure API）
版本1.21+
硬依赖Vault + 一个经济插件
软依赖PlayerPoints（点券支付，可选）

Vault 与经济服务是启动前提。 插件在 onEnable 里检查 Vault 经济服务，拿不到就打印「Vault 经济服务不可用，插件已自动关闭」并自我禁用。所以只装 Vault 但没装经济插件（如 EssentialsX、CMI）也起不来。

PlayerPoints 是软依赖，没装只是点券支付不可用，插件正常运行。

安装

  1. 装好 Vault 与经济插件（点券支付还需 PlayerPoints）
  2. 把 jar 放进 plugins/
  3. 启动服务器，插件释放 plugins/Snow-EnchantSP/config.yml
  4. 控制台出现 Snow-EnchantSP 加载完成。 即成功

启动日志里还会说明 PlayerPoints 的接入结果：

  • PlayerPoints 已接入，点券支付可用。
  • 未检测到 PlayerPoints，点券支付将不可用。
  • PlayerPoints 接入失败，点券支付将不可用: <原因>

命令与权限

命令作用权限默认
/sesp打开附魔剥离界面SnowEnchantSP.open所有人
/sesp reload重载配置SnowEnchantSP.reloadOP

两个命令都只能玩家执行，控制台执行会提示「该命令仅玩家可用」。

使用流程

打开界面

/sesp，或用菜单插件/命令方块代为执行。

放入装备

把带附魔的装备放到 enchantItemSlot（默认第 5 格，索引 4）。

界面自动列出附魔书

放入后插件延迟 1 tick 刷新，把该装备的每个附魔渲染成一本附魔书，摆在下方区域（槽位 18 ~ 44，一页最多 27 个）。附魔多于一页时用底部 46 / 54 格（索引 45 / 53）的箭头翻页。

点击附魔书付费剥离

三种点击方式对应三种支付组合（见下文）。成功后：装备上的该附魔被移除、一本对应的附魔书进入背包、播放磨石音效、弹出成功标题。

关闭界面

点右上角红色玻璃（第 9 格，索引 8）关闭，会执行 closecommand。直接按 Esc 关闭也会自动返还放在里面的装备。

三种支付方式

同一个附魔可以配多个「方案」（option-1、option-2…），插件按点击方式决定用哪种支付组合，并从上到下找第一个付得起的方案。

点击方式支付组合消耗经验
左键金币是（exp-levels）
右键点券是（exp-levels）
Q（丢弃键）金币 和 点券同时扣否

界面里每本附魔书的 lore 会列出该附魔的全部方案价格，第一行是操作提示（messages.pay-hint）。

Q 键这个组合是「双倍付费换免经验」——同时扣金币和点券，但不扣经验等级。适合给经验金贵的服务器一个替代选项。它要求方案里 money 和 points 都有值，只配了一种的方案会被跳过。Shift 点击被完全禁止，会提示「不支持 SHIFT 点击操作」并弹失败标题。这是为了防止 Shift 快速移动物品把界面里的附魔书/装备搬走导致状态错乱。

config.yml 全部字段

基础

# 关闭按钮执行指令（留空则不执行，玩家名占位符 [Player]）
closecommand: "trmenu open menu [Player]"

# 界面标题，MiniMessage 格式，<price> 会替换成 price 的值
title: "<gradient:#8de4ff:#5db2ff><bold>附魔剥离</bold></gradient> <gray>|</gray> <gold><price></gold><gray>金币/次</gray>"

# 仅用于标题里的 <price> 占位符显示
price: 300.0

# 放入待剥离装备的槽位（0 开始）
enchantItemSlot: 4

# lore 中包含以下内容的物品不可剥离附魔（支持部分匹配）
blocked-lore:
  - "不可剥离"
字段说明
closecommand点关闭按钮后以控制台身份执行，[Player] 替换为玩家名。留空则只关界面
title界面标题，MiniMessage 格式。同时是界面识别依据，见下方警告
price只影响标题里 <price> 的显示，不参与任何实际扣费
enchantItemSlot待剥离装备的槽位，默认 4（第一行第 5 格）
blocked-lore物品 lore 含这些文本时禁止剥离，去色后做部分匹配
price 不是真实价格。 真实扣费全部来自 pricing 一节。price 仅仅是标题里 <price> 占位符的取值——如果你改了 pricing 里的金额却忘了改 price，标题会显示一个与实际不符的数字，玩家会以为你标错价。改价时两处一起改。插件靠「标题完全相同」来判断这是不是自己的界面。 如果服务器上有别的插件打开了标题一模一样的容器，事件也会被拦截；反过来，若 title 里用了会动态变化的内容，界面可能识别失败导致点击无响应。保持 title 为静态文本（<price> 除外）。

GUI 布局

用字符画描述，每行一个字符串，每个字符对应一格：

gui:
  layout:
    - "oooo ooog"
    - "okkkkkkko"
    - "obbbbbbbo"
    - "obbbbbbbo"
    - "obbbbbbbo"
    - "ooooooooo"
  items:
    o:
      material: GRAY_STAINED_GLASS_PANE
      displayName: "<gray>"
    b:
      material: BOOK
    g:
      material: RED_STAINED_GLASS_PANE
      displayName: "<red><bold>点击关闭</bold></red>"
    k:
      material: LIGHT_GRAY_STAINED_GLASS_PANE
      displayName: "<gray>"
  • layout 的行数 × 9 = 界面大小，默认 6 行 = 54 格
  • items 下每个字符定义 material（Bukkit 材质名）与可选的 displayName（MiniMessage）
  • 布局里的空格表示不放东西——默认第一行第 5 格是空格，正好留给 enchantItemSlot: 4
  • items 里没定义的字符会被跳过

这些槽位是硬编码的，改布局时别占用：

槽位（索引）用途
enchantItemSlot（默认 4）放待剥离装备
8关闭按钮
18 ~ 44附魔书列表区（27 格）
45上一页
53下一页

翻页箭头由代码直接写入 45 / 53，会覆盖你在布局里放的任何东西。附魔书区域每次刷新会被填成普通 BOOK，所以布局里那片 b 只是「未放入装备时的占位外观」。

pricing：真正的价格体系

pricing:
  # 所有附魔的默认价格方案
  defaults:
    option-1:
      money: 300
      points: 30
      exp-levels: 30
    option-2:
      money: 500
      points: 50
      exp-levels: 0
    option-3:
      points: 50
      exp-levels: 0
    option-4:
      money: 300
      exp-levels: 0

  # 单独附魔价格配置（key 必须是完整命名空间）
  enchantments:
    minecraft:vanishing_curse:
      option-1:
        points: 50
        exp-levels: 0
字段类型说明
money小数金币价格，走 Vault。不写则该方案不支持左键与 Q
points整数点券价格，走 PlayerPoints。不写则不支持右键与 Q
exp-levels整数额外消耗的经验等级，默认 0。Q 键支付时不扣

方案名任意（option-1 只是习惯写法，改成 cheap、vip 都行），但顺序有意义——插件按配置文件里的出现顺序找第一个付得起的方案。

查找逻辑：先看 pricing.enchantments.<完整附魔ID> 有没有配。有就只用它的方案；没有（或它一条有效方案都没有）才回落到 pricing.defaults。

单独定价是「整体替换」而不是「覆盖合并」。 给某个附魔配了 enchantments 后，defaults 里的方案对它完全失效。默认配置里 minecraft:vanishing_curse 只配了一个纯点券方案，意味着消失诅咒只能右键用点券剥离，左键和 Q 都会提示余额不足。这是有意的（让诅咒类附魔走单一渠道），但你自己加单独定价时要把所有想支持的支付方式都列全。enchantments 下的键必须是完整命名空间 ID，如 minecraft:sharpness、minecraft:unbreaking。写 sharpness 或 DAMAGE_ALL 都不会被匹配到，会静默回落到 defaults。ID 可以用游戏内 /enchant 的补全确认。

一个方案里 money 和 points 都没写会被直接忽略（exp-levels 单独存在没有意义，插件不支持纯经验支付）。

消息自定义

全部文案在 messages 一节，MiniMessage 格式：

messages:
  only-player: "<red>该命令仅玩家可用。</red>"
  usage: "<yellow>用法: /sesp [reload]</yellow>"
  reload-success: "<green>配置重载成功。</green>"
  no-permission: "<red>你没有权限执行此操作。</red>"
  no-permission-open: "<red>缺少权限：SnowEnchantSP.open</red>"
  no-enchant: "<red>物品没有任何可剥离的附魔。</red>"
  separated: "<green>剥离成功：<aqua><enchant> <level></aqua> <gray>消耗: <gold><cost></gold></gray></green>"
  item-back: "<green>你放入的物品已自动返还。</green>"
  dont-shift: "<red>不支持 SHIFT 点击操作。</red>"
  no-affordable-option: "<red>余额/点券/经验不足，无法支付该附魔剥离费用。</red>"
  lore-blocked: "<red>该物品包含不可剥离的 lore 标记。</red>"
  pay-hint: "<gray>左键: 金币+经验 右键: 点券+经验 Q: 金币+点券(无经验)</gray>"

  prev-page: "<yellow><bold>上一页</bold></yellow>"
  next-page: "<yellow><bold>下一页</bold></yellow>"
  page-edge: "<yellow>已经到边界页了。</yellow>"

  title-success: "<green><bold>剥离成功</bold></green>"
  subtitle-success: "<gray>附魔已经拆分为附魔书</gray>"
  title-fail: "<red><bold>剥离失败</bold></red>"
  subtitle-pay-fail: "<gray>请检查金币/点券/经验是否足够</gray>"
  subtitle-dont-shift: "<gray>该界面不支持 Shift 点击</gray>"

可用占位符（仅 separated 一条支持）：

占位符替换为
<enchant>附魔的 key（如 sharpness）
<level>附魔等级
<cost>本次实际花费的纯文本描述，如 300金币+30级经验

messages.subtitle-lore-blocked 在代码里被引用了，但默认配置里没有这个键——被 lore 拦截时会显示代码内置的兜底文本。想自定义就自己加一行：

  subtitle-lore-blocked: "<gray>这件物品被标记为不可剥离</gray>"

禁止剥离特定物品

给物品 lore 加上标记文本即可：

blocked-lore:
  - "不可剥离"
  - "绑定灵魂"
  - "[禁止拆解]"

匹配规则：去掉颜色码后做包含判断。所以 lore 里写 &c&l不可剥离 也能被 不可剥离 匹配到。

放入被拦截的物品时不会列出附魔，点击附魔书也会被拒绝，两处都提示 lore-blocked。

排错

插件启动就自我禁用

控制台会有 Vault 经济服务不可用，插件已自动关闭。。装 Vault 只是第一步，还需要一个真正提供经济服务的插件（EssentialsX、CMI 等）。

点击附魔书提示「余额/点券/经验不足」

按这个顺序查：

  1. 该附魔是否在 pricing.enchantments 里被单独定价了——单独定价会完全替换 defaults，可能不支持你用的那种点击方式
  2. 用的点击方式是否有对应字段：左键要 money，右键要 points，Q 要两者都有
  3. exp-levels 是否超过玩家当前等级（左键/右键会检查，Q 不检查）
  4. 点券支付还要确认 PlayerPoints 已成功接入（看启动日志）

点击界面完全没反应

插件靠标题完全一致识别自己的界面。确认 title 没有被改成含动态内容的文本，且改完执行了 /sesp reload。

装备放进去不列出附魔

  • 装备确实没有附魔
  • 物品 lore 命中了 blocked-lore（会有提示）
  • 放的槽位不是 enchantItemSlot

关闭界面后装备不见了

正常情况会自动返还并提示「你放入的物品已自动返还」。如果背包满了，addItem 无法放入的部分会丢失——这是插件的已知短板，提醒玩家留出背包空间。

Q 键剥离扣了金币但没扣点券

代码在点券扣除失败时会把金币退回。若真出现只扣一边，说明 PlayerPoints 的 take 返回了成功但实际未扣，请检查 PlayerPoints 版本与日志。

更新日志

Snow-Welcome 各版本的变更记录。

更新日志

Snow-EnchantSP 各版本的变更记录。

Copyright © 2026