原创 开源 游戏模式 EmakiForge | 图纸锻造 4.8.0

[MD] ### 新增 - 新增 `/forge convert-legacy` 迁移入口，可预览并转换旧 `recipes.materials[].item` 与 `blueprint_requirements[].item` 配置。 - 转换流程保留备份，并报告冲突与无法转换的规则；使用 `confirm` 或 `--apply` 后才会写入。 ### 重构 - 锻造材料与图纸资格判定统一改用 CoreLib `matcher`，可组合物品源、组件、Lore、PDC 和逻辑条件。 - `item_sources` 继续承担材料计数、成品构造、显示和锻造物品审计身份等非判定职责；matcher 身份与刷新链路保持一致。 ### 破坏性变更 - 自定义材料和图纸的资格判定需要迁移到 matcher；不要删除仍承担计数、构造或审计职责的 `item_sources`。 ### 升级说明 - 升级前备份 `plugins/EmakiForge/`，先预览转换结果，再核对 `matcher`、`item_sources`、数量、材料键和成品刷新结果。 - 宽 matcher 可能提前命中物品，请先写更具体的规则，并在测试服验证图纸、必需材料、可选材料、容量加成、品质保底和失败返还。 [/MD]

[MD] ### 动作写法迁移 - **动作写法整体换新, 但大部分不需要你动手改。** 首次启动时 CoreLib 会自动把 `plugins/` 下所有 Emaki 插件的配置文件改写成新写法, 只做一次, 之后不再重复。每个被改过的文件旁边都会留一份 `.legacy-backup` 后缀的原文件备份。万一某一行转换不成功, 插件不会拿这行去覆盖你的配置, 而是单独写到一个 `.v2-failed` 文件里、原配置保持不动, 控制台也会列出是哪个文件的哪一行, 方便你自己看一眼。 - **锻造的三个刷新动作要你手工改名字**, 自动改写不包括它们。去掉开头的 `emaki`: - `emakiforge_refresh_held` → `forge_refresh_held` - `emakiforge_refresh_player` → `forge_refresh_player` - `emakiforge_refresh_all` → `forge_refresh_all` - 旧名字不再保留, 升级后还写旧名字的话, 控制台会提示找不到这个动作。 - **锻造自己的变量占位符要加 `var.` 前缀。** 配方和 config.yml 里凡是用到锻造变量的地方都要改, 例如 `%forge_result_item_name%` → `%var.forge_result_item_name%`、`%forge_failure_reason%` → `%var.forge_failure_reason%`。品质广播里那个老写法 `<show_item>` 也换成了 `%var.forge_show_item%`, 新的 config.yml 已经是新写法了。GUI 文案和 `%player%` 这类玩家占位符不在改动范围内, 不用管。 - 动作名本身的下划线分词由插件自动改写, 比如 `sendmessage` → `send_message`、`playsound` → `play_sound`、`broadcastmessage` → `broadcast_message`, 随包的 `recipes/example_recipe.yml` 已经是改好的样子, 可以对照看。 - **原先用 JS 脚本改成功率或发奖励的配方需要重写。** JS 脚本功能整体取消了, 也没有自动转换的办法。原先脚本能做的两件事现在都有配置层的做法: 改成功率用配方里的 `success_rate` 和 `failure_outcomes`, 锻造前后发奖励用配方 `actions` 段下的 `pre`/`success`/`failure` 以及 `result.success.actions`。随包的示例脚本 `scripts/examples/forge_success.js` 一并删除。 ### 锻造界面与材料清单 - **锻造容量那一格现在会列出这个配方要哪些材料、你放了多少。** 新增占位符 `%blueprint_requirements%`, 写在 `gui/forge_gui.yml` 的 `capacity_display` 槽位 lore 里, 一项材料占一行, 凑够的打勾、没凑够的打叉, 后面跟着「已放入的量/需要的量」。注意这个数量看的是你已经放进锻造界面的量, 不是背包里的量。 - 清单挂在容量那一格而不是图纸格, 是因为图纸格放上图纸以后, 占位物品就被真图纸替换掉了, 清单反而会被藏起来。 - **一张图纸被多个配方共用时, 清单会按配方分组列出**, 每组前面带配方名, 最多展开 3 组, 剩下的折叠成一行「还有 N 个配方」。这里刻意不做合并: 甲配方要铁、乙配方要金, 合起来会显示两样都缺, 而实际上凑齐任意一个就能锻造。同一格还能用 `%recipe_count%` 拿到候选配方的个数。 - 还没放图纸、或者放的图纸对不上任何配方时, 这一行显示「配方会按图纸物品源自动匹配」。 - 上面这些提示语都能改, 文案在语言文件的 `gui.blueprint.*` 下面: `no_recipe`、`recipe_group_header`、`requirement_satisfied`、`requirement_missing`、`more_recipes`。 - **顺带一说, lore 里整行只写一个占位符时, 值有几条就展开成几行。** 这是清单能一行一项显示的前提, 所以 `%blueprint_requirements%` 要单独占一行, 别和别的文字挤在同一行。 ### 配方与界面模板 - **配方可以指定自己的锻造界面模板了。** 在配方里加一个 `gui_template` 键, 填 `gui/` 目录下模板的文件名 (不带 `.yml`), 这个配方开出来的界面就用指定的那份。不填就还是用 `forge_gui`, 沿用旧配方文件不受影响。 ### 控制台输出 - **配方里动作写错时, 控制台报错从内部代号变成了看得懂的话。** 原先某一行动作插件读不下去时, 控制台只会甩出一个内部代号, 根本看不出是哪里写错了。现在会直接说明问题是什么、出在哪个位置、以及可能想写的是什么, 后面照旧跟着出问题的文件、配方 id 和动作所在的阶段与行号。这些文案跟着语言文件走, 换语言也能用。 - **配置预检的问题行现在按严重程度整行上色**, 错误和致命是整行红色, 警告是整行黄色, 提示保持原来的灰色。新增 `console.config_precheck_issue_warn` 和 `console.config_precheck_issue_error` 两个文案键, 旧语言文件缺这两个键时会退回原来的样式, 不会打印出裸的键名。 - 启动和重载时的六条控制台日志由白色改成灰色, 和其他 Emaki 插件的输出保持一致。 ### 开发者相关 - `EmakiForgeApiProvider` 已移除, 直接使用 `EmakiForgeApi` 的静态方法。 - `EmakiForgeApi.available()`、`apiVersion()`、`pluginName()`、`isReady()` 全部移除, 由 `EmakiForgeApi.status()` 统一替代 (返回 `ApiStatus`)。 - 新增三层公开 API: `EmakiForgeApi.catalog()` (配方与材料只读查询, 含 `matchRecipe`、`validate`、`previewResult`、`mastery`、`accepting`)、`EmakiForgeApi.operations()` (`forgeAsync`、`openForgeGui`、`openRecipeBook`、`viewingRecipeBook`、`refreshItem`、`refreshPlayer`)、`EmakiForgeApi.extensions()` (预留层, 当前无成员)。插件未加载时返回降级实现, 不再抛异常。 - 返回值统一为 `EmakiResult`: 「插件不可用」与「业务失败」分开表达, 配 `FailureKind` 区分子系统被关闭与插件未安装。 - 新增模型类型 `ForgeInputs`、`ForgeOutcome`、`ForgeRecipeView`、`ForgeMaterialView`、`ForgeBlueprintView`、`ForgeValidation`。 - `ForgeStartEvent`、`ForgeCompletedEvent` 补齐线程语义说明: 均为同步事件, 仅在运行时持有对应区域所有权时触发, 监听器需遵守相同的 Paper/Folia 线程约束。 - `EmakiForgeApi.Bridge` 与 `ForgeExtensions` 标记为 `@ApiStatus.NonExtendable`, 第三方插件不得实现。 - **这是破坏性 API 更新, 第三方代码需要重写, 不提供旧签名或过渡兼容。** ### 升级说明 - 需要先把 EmakiCoreLib 升到 `4.7.0`。 - **升级前请备份 `plugins/EmakiForge/` 整个目录**, 特别是 `recipes/` 和 `gui/`。 - 大部分动作写法由插件自动改写, 但下面三处要你自己动手: - 三个刷新动作要去掉开头的 `emaki` (对照上面的清单)。 - 锻造自己的变量占位符要加 `var.` 前缀。 - 用 JS 脚本改成功率或发奖励的配方要改成用配方里的 `success_rate`、`failure_outcomes` 和 `actions` 实现。 - 想让锻造界面显示材料清单的话, 需要在 `gui/forge_gui.yml` 的 `capacity_display` 槽位 lore 里加一行 `%blueprint_requirements%`。沿用旧 GUI 文件不加也能正常锻造, 只是不显示清单。 - 配方结构、图纸、玩家的锻造熟练度数据都没变, 不需要迁移。 - 升级后建议跑一次 `/emakiforge reload` 与 `/emakiforge debug stats`, 确认配方注册数量和预期一致, 再打开锻造界面看一眼材料清单。 [/MD]

[MD] ### 破坏性变更与必要迁移 - 【破坏性】配方 `result` 结构调整且不再兼容旧格式：原 `result.item_sources`、`result.meta_actions.name_actions`、`result.meta_actions.lore_actions`、`result.actions` 需改写为 `result.success.outputs[].item_sources` 以及 `result.success.name_actions`、`result.success.lore_actions`、`result.success.actions`。插件只读取 `success`；缺失时该配方不会报错，但也不会产出任何物品，所有自定义配方必须迁移。 - 【破坏性】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/*.yml` 必须迁移。 - 【破坏性】插件描述文件从 `plugin.yml` 迁移到 `paper-plugin.yml`，其中的 `commands:` 段已移除（命令改为运行时注册）。不再支持纯 Spigot，必须使用 Paper 或 Paper 分支。 - 【移除】浏览器端 Web Console 层整体移除：`web-console.yml`、`web-extensions/` 以及 `web-console/` 前端项目。此前通过浏览器修改配置的服主需要直接编辑 YAML。 - 【移除】管理端配方编辑器模板 `gui/editor_gui.yml` 已删除，它唯一的入口就是被移除的网页编辑器。 ### 新增功能 - 新增三个可配置动作，可用于任意动作链：`emakiforge_refresh_held`、`emakiforge_refresh_player`、`emakiforge_refresh_all`。 - 新增 `/emakiforge debug stats`（别名 `status`），输出运行时与配方加载报告：generation、文件数/解析数/跳过数/注册数/重复数、问题与警告、耗时、来源状态。 - 配置预检与配方加载诊断（目录创建失败、id 为空、id 重复、加载失败）现已可本地化；玩家可见的运行时状态提示（重载中、无可用配方、加载失败、能力缺失、索引未就绪、已关闭、会话过期）同样可本地化。 - 新增对 EmakiItem 的可选软依赖；未安装该插件时，EmakiAttribute 对接会降级运行，不再直接失败。 ### 重载与结算可靠性 - 重载改为原子操作：候选运行时在后台构建，只有在不存在阻断性问题时才整体安装。失败时继续由原运行时提供服务；被后续重载取代的重载会被报告为已过期。 - 重载汇总数字改为取自本次重载自身的结果，并发重载不会再报出混合的计数。 - 锻造结算加入明确的提交边界，已过期的完成流程不会二次返还已消耗的输入。 - 配方书绑定打开时取得的运行时快照，重载期间翻页不会混用不同 generation 的数据。 - GUI 模板由独立加载器读取，并纳入重载候选校验。 - 消息前缀更换为新的品牌渐变配色。 ### 修复 - `/emakiforge reload` 此前无条件回报成功并吞掉失败，现在会回报失败并附带详情（`general.reload_fail` 消息键此前存在但从未被发送）。 - 重载回复改为在发送者自身的执行域上送达，这是 Folia 上的正确行为所必需的。 ### 运行环境与兼容性 - `api-version` 由 `1.21` 提升到 `1.21.8`，仅支持 1.21.8 及以上版本。 - 构建基座由 spigot-api 改为 paper-api，使用本插件 API 的开发者需要同步切换编译基座。 - Java 目标版本仍为 25，`folia-supported: true` 保持不变，权限集保持不变（use/book/reload/debug/admin）。 - 移除了跨插件的强制 API 版本门禁，混用小版本略有差异的 Emaki 插件不再在启动阶段被阻止。 ### 升级说明 - 需要 EmakiCoreLib `4.6.0`。 - 升级前请备份 `recipes/` 与 `gui/` 目录，并按上述结构迁移全部自定义配方与 GUI 模板。 - 升级后建议执行一次 `/emakiforge reload` 与 `/emakiforge debug stats`，确认配方注册数量与预期一致，再验证锻造 GUI 和配方书流程。 [/MD]

[MD] ### 新增 - 新增公开 Bukkit 事件：`ForgeStartEvent`（锻造开始时触发，可取消）和 `ForgeCompletedEvent`（锻造完成时触发，含成功与否、结果物品、品质等信息，适合做统计与播报），第三方插件可监听这些事件做联动。 - 新增 JavaScript 脚本扩展：可注册锻造结果钩子和锻造规则，用脚本动态干预锻造流程，入口 `emaki.module("forge")`，并附带示例脚本。 - 接入配置预检：启动和重载时检查 Forge 配置并在控制台给出明确提示。 ### 优化 - 加固锻造预备缓存：取用预览物品时进行复制，避免缓存中的物品被外部引用篡改。 [/MD]

[MD] ### 新增 - 新增 Forge JavaScript 模块入口，可通过 `emaki.module("forge")` 判断 Forge 是否可用并读取基础模块信息。 - 新增 Forge 默认脚本示例由 Forge 自己释放，不再由 CoreLib 代管业务示例。 - 新增 Forge Web Console 扩展注册结构，配方、GUI 和主配置更适合在网页端编辑。 - 新增共享条件系统对接，Forge 配方可以使用和其他 Emaki 插件一致的条件配置风格。 ### 修复 - 修复部分 Forge 默认配置和条件写法没有跟随新版共享条件系统的问题。 - 修复锻造物品来源识别在跨插件物品源显示时不够统一的问题。 - 修复旧 API 获取方式对外部插件开发者不够稳定的问题。 - 修复 Web Console 中 Forge 配置字段说明和编辑入口不够完整的问题。 ### 重构 - 重构 Forge API 获取方式，使用静态门面 + Bridge，第三方插件不再依赖实现类实例。 - 重构 Forge Assembly 层命名空间注册方式，由 Forge 自己注册自己的锻造层。 - 重构 Forge 脚本模块注册与注销逻辑，避免 CoreLib 硬编码业务模块。 - 重构 Forge Web Console 前端入口，将注册逻辑拆分到独立文件。 - 重构配方加载和物品识别服务，使配方匹配和物品来源判断更清晰。 ### 优化 - 优化 Forge 默认配置和语言文件版本，示例更接近当前推荐写法。 - 优化 Web Console 里 Forge 模块图标、文件标题和字段说明展示。 - 优化 Forge 与 CoreLib 共享物品来源显示名链路，非原版物品源更容易显示友好名称。 - 优化 Forge 与脚本、物品来源、条件系统的集成一致性。 ### 注意事项 - 如果你使用了自定义 Forge 配方，建议检查条件节点、物品来源匹配和质量/容量相关字段。 - 如果第三方插件调用 Forge API，建议确认已经切到新的静态门面调用方式。 - 建议与 CoreLib v4.3.0 一起更新。 [/MD]