原创 付费 游戏模式 EmakiGem | 孔位与共鸣 2.7.0

[MD] ### 宝石升级功能整体取消 - **玩家自己升级宝石这套玩法整体取消了**, 升级台界面、升级动作、升级配置全部不再提供。分等级宝石本身保留, 一颗宝石照样可以有 2 级、3 级、4 级, 只是玩家不能再自己往上升, 高等级宝石改由管理员直接发放。**如果你服的玩法依赖玩家自助升级宝石, 请先想清楚怎么替代再升级。** - 界面模板 `gui/upgrade/default.yml` 已删除, `gui/` 目录下现在只有 `gui/gem/default.yml` 与 `gui/open/default.yml`。自定义过升级界面的话, 这个文件不再被读取, 改了也没有效果。 - `/emakigem gui upgrade` 这条命令没有了, 现在只剩 `/emakigem gui [inlay|open]`, Tab 补全和 `/emakigem help` 的说明都跟着改了。玩家继续输 `upgrade` 会收到参数错误提示。 - config.yml 里整个 `upgrade:` 段被删除, 含 `upgrade.global_success_rates` (原有 2→100.0、3→80.0、4→60.0、5→45.0、6→30.0 五档) 和 `upgrade.global_failure_penalty` (原默认 `none`, 可填 `none` / `downgrade` / `destroy`)。 - 宝石定义文件里各等级的升级用配置也不再起作用: `upgrade.enabled`、`upgrade.gui_template`、`upgrade.failure_penalty`、`upgrade.economy` (含各货币的 `provider` / `currency_id` / `base_cost` / `cost_formula` / `display_name`)、`upgrade.success_rates`, 以及各等级下的 `materials`、`success_rate`、`failure_penalty`、`actions.success` / `actions.failure`。随包的 `gems/example_gem.yml` 已经把这些清掉了。 - **升级后你不会看到任何报错, 这些旧配置是静默失效的**, 请留意这一点。你自己的 config.yml 和宝石文件里留着 `upgrade.success_rates`、`upgrade.economy`、各等级的 `materials` 这些键, 插件照样能正常启动, 配置检查也不会提示, 甚至还会把它们读进来, 但没有任何地方会去用, 填什么数字都没效果。玩家那边的表现就是找不到升级入口: 命令没有升级参数, 界面里也没有升级台。所以升级后请不要因为"没报错"就以为升级功能还在, 想确认的话直接去看玩家能不能打开升级界面。 - **唯一会在控制台留痕的是配置里写了 `emakigem_upgrade_gem_item` 的动作行。** 这个动作已经删了, 那一行不会被自动改写也不会被判成配置错误, 但执行到它时插件找不到这个动作, 会打印一条未知段的提示, 并且把**整条动作序列**丢掉 (不只是这一行), 同一串里后面的动作也不会执行。它不阻断启动, 服务器照常起来。请自己检索配置里的 `emakigem_upgrade_gem_item` 并把这些行删掉。 - `upgrade:` 这个键仍然要保留, 但它现在只管**分等级的显示与效果**, `upgrade.max_level` 是这颗宝石的最高等级, `upgrade.levels.<等级>.display_name` 与 `.effects` 是每一级的名字和效果。想让玩家拿到高等级宝石, 用 `/emakigem give` 或 give 类动作指定等级发放。 - **玩家已有的宝石完全不受影响, 等级也不受影响。** 不管是背包里的散装宝石, 还是已经镶嵌在装备上的宝石, 都不用做任何迁移, 也不会掉级或被清空。原来是 4 级的宝石升级后还是 4 级, 名字和效果照常, `upgrade.levels` 里给这一级配的 `display_name` 与 `effects` 继续生效。删掉的只是"玩家自己往上升"这个途径, 宝石本身的分等级数据一点没动。开孔、镶嵌、取出、共鸣四条链路同样不受影响。 - 升级相关的提示文案也一并删了: `command.upgrade.*` (7 个键)、`gui.upgrade_open_failed`、`gui.upgrade.invalid_gem`、`gui.upgrade.invalid_material`、`gui_text.upgrade.*` (约 26 个键), 以及 `gui_text` 下的 `mode_upgrade`。 - 没有替代功能。如果你想让玩家还能"升级"宝石, 目前只能自己用命令或动作搭一套, 比如收材料后用 give 发一颗更高等级的宝石。 ### 动作写法迁移 - **动作写法整体换新, 大部分不需要你自己动手改。** 首次启动时 CoreLib 会自动把 `plugins/` 下所有 Emaki 插件的配置文件改写成新写法, 只做一次。被改过的文件旁边会留一份 `.legacy-backup` 后缀的原文件备份。万一某一行转换不成功, 插件不会拿它去覆盖你的配置, 而是单独写到 `.v2-failed` 文件里、原配置保持不动, 控制台也会列出是哪个文件的哪一行。 - 自动改写会把动作名字加上下划线分词, 涉及本插件的是 `sendmessage` → `send_message` 和 `playsound` → `play_sound`。出现的位置有: config.yml 里三个开孔器 (`attack_drill`、`defense_drill`、`universal_drill`) 的 `socket_openers.<id>.actions.success` 与 `.failure`, 以及 `gems/example_gem.yml`、`items/example_socket_item.yml`、`resonances/example_resonance.yml`。动作行里的 `%player%` 也会被自动换成 `%caster.name%`。 - **本插件的四个手持物品动作要你手工改名字**, 自动改写不包括它们: - `emakigem_open_socket` → `gem_open_socket` - `emakigem_inlay` → `gem_inlay` - `emakigem_extract` → `gem_extract` - `emakigem_clear_layer` → `gem_clear_layer` - 参数没变, `opener`、`slot`、`bypass`、`bypass_cost` 照原样写就行, 只改前面的名字。 - 旧名字不再保留, 也不在自动改写的名单里。升级后还留着旧名字的话, 那一行不会报配置错误, 但执行到它时插件找不到这个动作, 会在控制台打印 `未知段 emakigem_inlay` 这样的提示并跳过整条动作。请自己检索一遍配置文件里的 `emakigem_` 并改掉。 - 手持升级动作 `emakigem_upgrade_gem_item` 连同它的 `bypass_cost` 参数一起删了, 没有对应的新名字。配置里调用过它的行请直接删除。 - **升级前请备份 `plugins/EmakiGem/` 整个目录**, 尤其是 `gui/` 和 `gems/`。 ### JS 脚本取消 - **原先用 JS 脚本写宝石规则的服主需要重做。** JS 脚本功能整体取消了, 也没有自动转换的办法。具体失效的是两类: - 用 `registerSocketRule` 写的镶嵌规则, 比如"同一件装备上火属性宝石最多 2 颗"这种限制, 以及靠脚本给镶嵌成功率加减的写法。 - 用 `registerSetBonus` 写的套装加成, 比如"镶嵌满 3 颗后给装备加一行说明文字"。 - 镶嵌数量与共存限制可以改用宝石定义里的 `required_gems` / `conflicting_gems` 和各类槽位限制来做, 但脚本里那种自由判断没有一对一的替代。 - 随包的示例脚本 `scripts/examples/gem_status.js` 一并删除。 - 顺带删掉了 `debug.common.action.*` (22 个键)、`debug.common.script.*` 与 `debug.script.trace` 这些语言键, 它们只是 debug 输出文案, 不影响玩法配置。 ### 退款记录与配置检查 - **修复一个坏文件会让所有待补偿记录一起丢失**。插件会把镶嵌、取出、开孔过程中的扣费与退款进度记在 `plugins/EmakiGem/data/operation-journal/` 里, 用来在下次启动时把没退完的钱补给玩家。原先只要这个目录里有一个文件读坏了 (比如服务器崩在写入的一瞬间), 整个目录就会被当成空的, 所有玩家的待补偿记录一起对不上, 该退的钱再也退不回来。现在读不动的文件会被单独挪到 `quarantine` 子目录并在控制台点名, 其余文件照常加载。 - **修复配置有问题时旧配置被冲掉**。原先 `/emakigem reload` 遇到配置读不过, 插件已经把半截新配置装上去了, 结果宝石和界面都不对。现在配置没通过就整份退回原样, 继续用上一份能用的配置, 控制台会说明是哪里的问题。 - **修复控制台报的配置问题数偏大**。此前把"警告"和"提示"也算进失败计数里, 明明只有 1 个真正阻断加载的问题, 却报了七八个。现在失败时只统计真正阻断加载的那些。 - **修复启动时配置检查报告打印两遍**。 ### 开发者相关 - `EmakiGemApiProvider` 已移除, 直接使用 `EmakiGemApi` 的静态方法。 - `EmakiGemApi.available()`、`apiVersion()`、`pluginName()`、`isReady()` 全部移除, 由 `EmakiGemApi.status()` 统一替代 (返回 `ApiStatus`, 提供 `usable()`、`ready()`、版本与插件名字段)。就绪判据是「数据已加载」, 重载期间会返回 `loading`。 - 新增两层公开 API: `EmakiGemApi.catalog()` (宝石与插槽只读查询) 与 `EmakiGemApi.operations()` (镶嵌、取出、开孔、造宝石物品、清宝石层、开界面)。插件未加载时返回空实现, 查询给空答案、操作返回 `EmakiResult.unavailable()`, 不再抛异常。 - `GemOperations` 的返回值统一为 `EmakiResult<T>`: `inlay` 返回 `EmakiResult<GemInlayOutcome>`, `extract` 返回 `EmakiResult<GemExtractOutcome>`, `openSocket` / `createGemItem` / `clearGems` 返回 `EmakiResult<ItemStack>`, `openGui` / `openSocketGui` 返回 `EmakiResult<Unit>`。 - 新增只读视图类型 `GemDefinitionView`、`GemStateView`、`GemSlotView`、`GemResonanceView`、`GemResonanceSlotView`、`GemRelationshipCheck`, 扩展层不再暴露 runtime 内部类型。 - `EmakiGemApi.Bridge` 改为 `@ApiStatus.NonExtendable`, 第三方插件不得实现。 - 事件签名变更: `GemInlayEvent`、`GemExtractEvent`、`GemSocketOpenEvent` 构造器新增首个 `operationId` 参数, `getActor()` 改名为 `getPlayer()`, `GemSocketOpenEvent.getOpenerItem()` 移除。新增 `GemInlayCompletedEvent` 与 `GemExtractCompletedEvent`, 通过 `getOperationId()` 与对应的 pre 事件关联。 - `GemUpgradeEvent` 已移除。 - 事件均为同步事件, 仅在持有对应玩家所有权时触发 (Paper 上是主线程, Folia 上是玩家所在区域线程), 监听器需遵守相同约束。pre 事件在运行时提前拒绝请求时不触发, 且跨线程调用时会被跳过, 依赖 `setSuccessChance` 的监听器不能假设一定会被问到。 - **这是破坏性 API 更新, 第三方代码需要重写; 不提供旧签名、deprecated 过渡或双轨兼容。** 依赖 `emaki-gem-api` 时请用 `provided` (Maven) 或 `compileOnly` (Gradle), 不要打包进自己的 jar。 ### 升级说明 - 需要先把 EmakiCoreLib 升到 `4.7.0`。 - **升级前请备份 `plugins/EmakiGem/` 整个目录。** - 大部分动作写法由插件自动改写, 但下面三处要你自己动手: - 四个手持物品动作要改名 (对照上面的清单)。 - 配置里所有 `emakigem_upgrade_gem_item` 的调用行要删掉。 - 用 JS 脚本写的镶嵌规则与套装加成要改成配置层能做到的写法。 - 确认你服的玩法不依赖玩家自助升级宝石。要发高等级宝石, 用 `/emakigem give` 或 give 类动作指定等级。 - 玩家手上和已镶嵌的宝石、宝石等级、共鸣配置与开孔数据都不受影响, 不需要迁移。 - 升级后建议执行一次 `/emakigem reload`, 看一遍控制台的配置检查与迁移报告, 再验证开孔、镶嵌、取出流程。 [/MD]

[MD] ### 破坏性变更与必要迁移 - 【破坏性】GUI 槽位物品结构改为嵌套组件：原 `item: "<MATERIAL>"` 搭配 `display_name`、`lore`、`hidden_components: [tooltip]`，现改为 `item.source` 搭配 `item.components.custom_name`、`item.components.lore`、`item.components.tooltip_display.hide_tooltip`。自带的 `gui/gem/default.yml`、`gui/open/default.yml`、`gui/upgrade/default.yml` 三个模板均受影响，自定义模板必须迁移。 - 【破坏性】插件描述文件迁移到 `paper-plugin.yml`，其中的 `commands:` 段已移除，必须使用 Paper 系服务端。 - 【移除】浏览器端 Web Console 层整体移除：`web-console.yml`、`web-extensions/` 以及 `web-console/` 前端项目。此前通过浏览器修改配置的服主需要直接编辑 YAML。 ### 新增：宝石关系限制 - 新增此前不存在的宝石关系门禁：`required_gems` 声明镶嵌前装备上必须已存在的宝石，`conflicting_gems` 声明不能共存的宝石，且双向生效。 - 同一个 id 同时出现在两个列表中，或自我引用，会在加载时直接拒绝整个文件。 - 当仍有已镶嵌宝石依赖某颗宝石时，取出该宝石会被拒绝。 - 两个字段默认为空列表，不填写即保持原有行为。 - 新门禁提示与加载校验提示均可本地化。 ### 新增功能 - 新增五个可配置手持物品动作：`emakigem_open_socket`、`emakigem_inlay`、`emakigem_extract`、`emakigem_upgrade_gem_item`、`emakigem_clear_layer`。 - 配置预检文本可本地化，加载类型名称（`gem`、`gem_item`、`resonance`）可翻译。 - 新增对 EmakiItem 的可选软依赖；未安装该插件时，EmakiAttribute 对接会降级运行，不再直接失败。 ### 流程与经济结算可靠性 - 镶嵌、取出与升级改为按记录的阶段推进，因此扣费失败与退款失败可以区分，未完成的退款可以被识别为待补偿。 - 经济扣费失败的处理从「简单退款」改为「回滚加待补偿」：回滚失败不再被当作退款成功。 - 消息前缀更换为新的品牌渐变配色。 ### 修复与兼容性 - `/emakigem reload` 的回复改为在发送者自身的执行域上送达，这是 Folia 上的正确行为所必需的。 - `api-version` 由 `1.21` 提升到 `1.21.8`；构建基座由 spigot-api 改为 paper-api；Java 目标版本仍为 25；`folia-supported: true` 保持不变；权限集保持不变（use/reload/admin/debug）。 - `EmakiGemApi` 源码没有变化，使用方无需改代码，但需要切换编译基座。 ### 升级说明 - 需要 EmakiCoreLib `4.6.0`。 - 升级前请备份 `gui/` 目录与宝石配置，并按上述结构迁移自定义 GUI 模板。 - 升级后建议执行一次 `/emakigem reload`，确认宝石与共鸣配置加载无误，再验证开孔、镶嵌、取出与升级流程。 [/MD]

[MD] ### 新增 - 新增公开 Bukkit 事件：`GemInlayEvent`（镶嵌宝石）、`GemExtractEvent`（取出宝石）、`GemUpgradeEvent`（宝石升级，可改成功率）、`GemSocketOpenEvent`（开孔），均在操作前触发且可取消，第三方插件可监听并介入宝石流程。 - 新增 JavaScript 脚本扩展：可注册宝石套装加成和开孔/镶嵌规则，用脚本动态干预宝石套装效果与开孔逻辑，入口 `emaki.module("gem")`。 - 接入配置预检：启动和重载时检查 Gem 配置并在控制台给出明确提示。 ### 优化 - 优化镶嵌、取出、开孔和升级流程在事件取消或被脚本改写时的一致表现。 [/MD]

[MD] ### 新增 - 新增 Gem JavaScript 模块入口，可通过 `emaki.module("gem")` 判断 Gem 是否可用并读取基础模块信息。 - 新增宝石分层预览对 Item 最终预览的支持，可查看宝石镶嵌后对物品外观、属性和展示内容的影响。 - 新增宝石层预览选项，可在预览中检查是否镶嵌、宝石等级、动作数量，以及共鸣、互斥组和依赖链摘要。 - 新增共享条件系统对接，宝石相关条件配置和其他 Emaki 插件保持一致的写法。 ### 修复 - 修复镶嵌、开孔和升级 GUI 打开时可能自动带入玩家物品，导致操作预期不够清晰的问题。 - 修复无可用宝石时预览区域可能出现无意义数值或空摘要的问题。 - 修复部分宝石默认条件和示例配置没有跟随新版共享条件系统的问题。 ### 重构 - 重构 Gem API 获取方式，使用静态门面 + Bridge，减少外部调用和插件内部实现的耦合。 - 重构 Gem 脚本模块注册与注销逻辑，避免 CoreLib 硬编码业务模块。 - 重构宝石分层预览 Provider，使其通过 CoreLib 的通用物品分层预览接口对外提供数据。 - 重构 Gem Web Console 前端入口，将注册逻辑拆分到独立文件。 ### 优化 - 优化宝石 GUI、开孔 GUI、升级 GUI 和示例配置的显示逻辑，界面行为更一致。 - 优化装备与宝石组合后的最终预览，服务器管理员检查成品物品时更直观。 - 优化 Web Console 宝石编辑页，使其继续复用 CoreLib 的共享编辑器和预览能力。 - 优化默认配置、语言文件和资源结构，后续维护更稳定。 ### 注意事项 - 如果你使用自定义宝石配置，建议检查镶嵌、开孔、升级 GUI 和最终物品预览表现。 - Gem GUI 打开后不再自动替玩家放入目标物品，需要玩家手动放入要操作的装备。 - 更新前建议备份 `gem.yml`、宝石配置、GUI 配置和相关玩家宝石数据。 - 如果需要在 Item 编辑器中预览宝石后的最终物品，请同时更新 CoreLib v4.3.0 [/MD]