0.0.9

更新日期：2026/10/4。

• 修复 onAttack 的目标传递：Chance、All、Repeat 等控制流下未指定目标的子动作继承外层 target: Entity，显式 target: Self 仍作用于施法者。没有命中生物时，Entity 技能直接跳过，不再错误地作用于自己。
• 修复 Folia 1.21.11 测试日志中的跨区域调用：每秒常驻 BUFF 在玩家所属区域执行；Delay / Repeat、GUI 刷新、上线提示与禁飞恢复等延迟任务跟随相关实体。施法者与目标在延迟期间分属不同区域时，该次子动作跳过。
• 本次构建及 58 项自动测试通过；Folia 改动依据实际日志修复，仍需在服务器复测其他交互与跨区域场景。

0.0.8

更新日期：2026/10/1。

• Enchant 奖励支持 var: "v+2" 等表达式，以当前附魔等级 v 一次提升多级；仍可用固定 level 或省略 var 保持每次 +1。拆卸按实际变化回退。
• 宝石配置新增 Removable: false，允许镶嵌但禁止拆卸；装备可通过 config.yml 中的 DismantleProtection.Lore 或 snowygems:no_dismantle PDC BYTE 标记禁止拆卸全部宝石。
• 拆卸台对受保护宝石显示说明，点击时在扣费前再次校验；游戏内编辑器字段及动作参数增加用途描述，并可切换 Removable。
• 宝石配置有附魔与 BUFF 二级强化示例；查看与拆卸说明保护设置。

0.0.7

更新日期：2026/9/26。

• 修复随机点券兑换券因表达式产生小数而被 PlayerPoints 拒绝的问题。Point 只求值一次，交易前向零取整，提示与实际到账整数一致；Internal 与 PlayerPoints 使用相同奖励数额。旧随机配置无需修改，版本保持 0.0.7。
• 取整为 0、非有限数或超出点券范围的 Point 奖励不生效；只有这条奖励的兑换券保留。100+2900*$RANDOM() 实际发放 100～2999 点券，包含 3000 可改为 100+2901*$RANDOM()。
• 修复极小随机数写成科学计数法时漏读指数的问题，避免随机奖励偶发超出配置范围；表达式支持 1.0E-7 等数值。
• Chance、If、All、Repeat、Reward、RewardSwitch 等嵌套技能及 Conditional 嵌套奖励可用 then 对象或列表编写；内置技能示例已转换。
• /sgem migrate 会递归转换可验证等价的旧嵌套技能，并保留触发器与目标；嵌套执行加入解析缓存。
• Switch 的两个形态可写成 from / to。
• 拆卸计价与成功率集中到 dismantle/*.yml，金币、点券、经验可分别计算并组合。
• 编辑器改为全 GUI 操作，可按分类创建、编辑、删除宝石和符文配方；修复边框覆盖返回、添加与翻页图标的问题。
• 新增 gui/editor.yml，可配置编辑器标题、图标和按钮位置。
• /sgem dismantle 改为放入装备的拆卸台；右侧逐颗显示实时价格并支持翻页，界面可在 gui/dis.yml 自定义。
• /sgem debug all 与指定 tag 的指令现在会直接开启控制台日志；编辑器保存触发的配置重载不再关闭本次运行期间的调试。
• Rewards 与 Skills 新增 YAML 对象式动作，旧函数行仍兼容。
• 新增 /sgem editor 和管理员权限 snowygems.migrate、snowygems.edit。

详见技能配置与迁移说明。

0.0.6（修订构建）

文档同步日期：2026/9/18。此节对应当前 0.0.6 工作区与已交付修订包，不表示 GitHub 已发布新 Release；旧 0.0.6 构建未必包含以下改动。

新增

• 玩家只读图鉴 /sgem catalog 与 snowygems.catalog 权限。
• 管理员 /sgem history <玩家名> 与 snowygems.history 权限；独立的轮换操作日志。
• Embed 数量限制正式生效，新增 ExclusiveGroup 与 TrackApplied。

修复与行为变更

• 只有全部实际奖励可安全撤销才允许拆卸返还，修复石等纯一次性效果不再生成新的可拆卸实例。
• 无限耐久、ItemFlag 和技能隐藏补充撤销凭据；隐藏技能仍能触发并读取动态等级。
• 技能 Slot 生效，主动 / 定时技能共用成功施放冷却；同 ID BUFF 每轮最多成功施放一次。
• 潜行左键同 tick 去重，发射物快照缺失不再借用当前主手；嵌套与延迟任务使用共享预算。
• PlayerPoints 不可用时暂停交易，不再回退到另一套内置余额。
• 重复 ID、加载异常和关键引用错误拒绝加载；strict 对配置错误拒绝加载。失败重载恢复旧注册表，首次启动失败停用插件。

图鉴与历史显示修订

• 修复 catalog 忽略 Texture 导致头颅显示为 PAPER；恢复头颅纹理和 Glow。
• history 每次显示最新 5 条，一行包含本地时间、操作、物品名称和结果；不向聊天直接输出 UUID、制表符、内部键值和扣费中间记录。
• 物品名称去色、清除混淆 / 控制字符并限制长度；磁盘完整诊断信息仍保留。

验证与升级

本次修订插件构建成功，40 项自动测试通过；不等同于全部目标服务端、经济插件与真实背包交互已验证。更新前备份装备与配置，同名配置文件不会强制覆盖。旧记录缺少必要凭据时可能无法拆卸；详见升级检查清单与图鉴及操作记录。

0.0.5

更新日期：2026/9/11

新增

• 更新可以将方块标记为符文锻造台的功能

0.0.4

更新日期：2026/9/10

Paper 物品数据兼容修复（Issue #1）

• 宝石标识、镶嵌与拆卸历史、属性累计和隐藏 Lore 改存 Bukkit PDC，移除插件对 TabooLib NMS ItemTag 的调用与模块依赖。
• 通过 Paper 公共物品序列化接口导入旧 NBT；保留空数据记录，避免拆卸后旧标签再次出现。
• 修复默认属性保留标记可能被后续 ItemMeta 写入覆盖的问题。
• 增加旧版与现代 NBT、压缩格式、长历史和损坏数据的回归测试。未完成 Paper 26.2 实服验证，升级与降级说明见排错与调试。

符文锻造

• 新增 /sgem rune、材料数量预览、二次确认和分页；新增 snowygems.rune 玩家权限与 RUNE_FORGE 菜单按钮。
• 新增 10 条可配置配方：碎片合成四色一级符文，红蓝绿升级为二级，二级回收为碎片。
• 扣料和产物空间统一规划，缺料或空间不足时保持背包原样；执行前重查，旧菜单与重载后的点击失效。
• 补充 10 个锻造规划回归测试，覆盖满背包、跨格扣料、堆叠上限与材料守恒。详见符文锻造与升级。

功能与交互

• 默认一、二级符文使用可拆卸的 Lore 标记，便于 SX 等外部属性插件读取；示例本身不直接提供对应属性或技能效果。
• 统一默认镶嵌台、符文镶嵌台和分解台的装饰、引导与操作入口；确认预览显示符文槽名称，替代难理解的内部格子编号。
• 当前默认符文槽仍按配置关键词匹配颜色；需要严格区分时，可配置 GEM:物品ID 或 CATEGORY:分类，未引入独立的符文颜色类型。
• 补齐四色符文示例、符文镶嵌台确认预览、未镶嵌符文分解为碎片的配方。
• 新增 CONFIRM_EMBED 与 CLOSE，支持跳转后返还输入；保留旧菜单 Shift+右键装备的批量入口。
• 宝石分类浏览支持分页，领取仅响应左键与 Shift+左键。
• 统一装备单件限制、符文槽规则、Gui 限制与执行前预检。

修复

• 修正矛的分类和技能说明：矛是突刺/蓄力近战武器，不属于 RANGED，示例不再使用不存在的 onLaunch:SPEAR / onHit:SPEAR 投掷流程。
• 防止双击带走装饰图标、拖拽/数字键/副手交换绕过槽位限制，普通取回装备不会误触镶嵌。
• 菜单持有布局快照，重载与正常停用前回收投入物品；关窗后停止无效刷新。
• 直接使用先预留一颗宝石再发奖，修复失败消耗不一致和礼包奖励被手持回写覆盖。
• Eat: true 的消耗类宝石可由食用事件处理，支持副手，取消原版吃喝避免二次消耗；原版食物、药水效果和空瓶产物不执行。
• 新镶嵌逐颗记录实际成功的奖励及撤销数据，拆卸只移除最近的一颗同 ID，并处理失败退款。
• 点券扣除检查实际交易结果，拒绝非法金额；随机池忽略非正权重并避免整数总权重溢出。
• 修复 none: 命令提示无法静默、方块主副手重复打开、被取消的挖掘清除工作台标记等问题。

配置与文档

• 菜单加载检查行列、槽位字符、类型、数量和重复菜单名。
• 配置自检增加未知奖励、无效奖池和不存在的 Gui 引用。
• 新增启动与重载后的配置健康检查；缺失的核心配置文件会自动尝试以非覆盖方式补回，仍缺失的路径会在控制台明确列出。
• config.yml 与语言文件启用迁移支持，新节点尽量补入旧文件；菜单、宝石和技能文件的自定义内容保留并提示手动合并。
• 补齐三语操作提示，更新语言目录、标记入口、权限、费用取整和旧装备限制说明。
• 已有 gui/gui.yml、gui/rune.yml 不会自动替换，请按工作台升级步骤合并。

验证范围

• 24 项回归测试通过，覆盖奖励撤销、符文锻造规划、PDC 编解码和旧 NBT 导入。
• 19 个 YAML、168 个宝石、3 个菜单、3 种语言（各 179 个键）、10 条符文配方校验通过。

升级注意

• 更新前备份插件目录、世界和玩家数据。新物品与后续写入使用 PDC，旧构建无法读取新数据，不宜直接降级。
• 符文新配置文件缺失时会释放；已有 GUI 请手动合并确认按钮、锻造入口与符文槽规则。
• 默认符文只写 Lore 标记，需在外部属性插件中配置对应效果。

项目提供自动回归测试和配置检查。构建及测试结果以本次交付记录为准。0.0.9 已根据 Folia 1.21.11 的实服报错修复对应区域调度，修订构建仍需复测；真实 Vault/PlayerPoints 账户和全部目标版本尚未完成联机验证。

旧装备无法补回历史上丢失的重复强化次数或数值，详见旧装备的边界。

以下 0.0.1–0.0.3 内容合并自指定的历史更新日志，描述对应版本的情况；当前功能与兼容性限制以 0.0.6 修订说明和各功能页面为准。

0.0.3

更新日期：2026/9/8

修复

• 修复新版宝石礼包使用后无效果的问题

0.0.2

更新日期：2026/8/26

新增

• 增加镶嵌台标记功能，使用 /sgem mark 即可将准星所指的方块变为镶嵌台。右键即可打开镶嵌台
• 可在 config.yml 文件中的 tagged-blocks 字段中修改可被标记成镶嵌台的方块
• 语言文件大改，增加多语言功能，内置简体中文，繁体中文与英语

修复

• 修复材质为食物的宝石可以食用的漏洞
• 修复材质为末影之眼的宝石可以扔出的漏洞
• 修复普通物品宝石可以被分解或参与合成的漏洞

配置变动

• 语言文件迁移至 \lang 文件夹中
• 新增 MarkedBlocks.yml 文件来记录被标记成镶嵌台的方块

破坏性变更

• 现语言文件不支持热加载，切换语言或更改文本内容之后请执行 /sgem reload 指令

0.0.1

初始先行版（历史记录）

核心系统

• 宝石镶嵌：把宝石镶到装备上获得属性、附魔、常驻 BUFF 与主动技能
• 三种宝石类型：镶嵌类（默认）、PlayerGem（右键直接生效）、RandomGem（开箱抽奖）
• 奖励函数体系：Attribute Enchant LoreAdd LoreVar Conditional 等，支持表达式与叠加上限
• 技能引擎：绑定装备 lore 文本触发，支持触发标记、条件、概率、延迟、重复与形态切换
• 常驻 BUFF 引擎：每秒扫描装备 lore 标记施加效果
• 自定义工作台菜单：字符网格布局，五种槽位类型
• 内置宝石镶嵌台 /sgem embed

查看与拆卸

• /sgem inspect 只读查看装备上已镶嵌的宝石
• /sgem dismantle 拆卸宝石，可配置费用（金币/点券/经验）与损坏概率
• 拆卸时真正撤销属性修饰符与附魔等级，而非仅跑 $onRemove
• 镶嵌属性宝石前先固化装备原生属性，避免护甲/韧性等自带属性消失

多版本兼容

• 支持 1.21.4 → 26.x，同一份配置跨版本通用
• 启动时读服务端注册表建快照，不按版本号硬编码
• 七个可开关的版本功能模块（Mace Spear CopperEquipment 等），默认 auto
• 1.21.11 矛（七种材质）与其专属附魔「突进」lunge 的完整支持
• 旧名兼容：DURABILITY、GENERIC_MAX_HEALTH 等老配置无需修改
• /sgem compat 版本能力报告与配置自检，区分「版本不支持」与「写错了」

权限

• 13 个细粒度权限节点，两个伞节点 snowygems.user（默认所有人）与 snowygems.admin（默认 OP）

版本更新与公告

• 服务器启动完成后异步检测一次，本地版本与官方不一致即提示
• 公告拉取，控制台与管理员上线时展示
• 遵循 JVM 系统代理，可完全关闭

经济对接

• 金币走 Vault，点券支持内置账户或 PlayerPoints
• 兑换券类宝石发放后主动告知玩家获得数额

排错

• 20 个 debug tag，可按范围过滤日志
• 全部玩家可见文案集中在 lang.yml（134 个节点），热重载生效

版本记录约定

发布新版本时，在上方按这个格式追加：

## 0.1.0

**新增**
- 我是功能

**修复**
- 我是问题

**配置变动**
- 我是变动

**破坏性变更**
- 我是变更