原创 付费 游戏模式 EmakiItem | 自定义物品库 2.7.0

[MD] ### 动作写法迁移 - **动作写法整体换新, 大部分不用你动手。** 首次启动时 CoreLib 会自动把 `plugins/` 下所有 Emaki 插件的配置文件改写成新写法, 只做一次。每个被改过的文件旁边都会留一份 `.legacy-backup` 后缀的原文件备份。万一某一行转换不成功, 插件不会拿这行覆盖你的配置, 而是单独写到一个 `.v2-failed` 文件里、原配置保持不动, 控制台也会列出是哪个文件的哪一行。 - **但 EmakiItem 自己的九个动作必须你手工改名。** 自动改写不认这几个名字, 控制台的迁移报告也不会提到它们 —— 它会安安静静地跳过, 所以别以为报告干净就等于全都改好了。改完之前, 这些动作行在新版里是找不到对应动作的: - `emakiitem_update` → `item_update` - `emakiitem_rerender` → `item_rerender` - `emakiitem_repair_amount` → `item_repair_amount` - `emakiitem_damage` → `item_damage` - `emakiitem_set_damage` → `item_set_damage` - `emakiitem_set_durability` → `item_set_durability` - `emakiitem:component_add` → `item_component_add` - `emakiitem:component_modify` → `item_component_modify` - `emakiitem:component_remove` → `item_component_remove` - 参数名注意区分: `item_repair_amount` 与 `item_damage` 用 `amount`, `item_set_damage` 与 `item_set_durability` 用 `value`。 - 要检查的位置就这六处: `condition.on_pass.actions`、`condition.on_fail.actions`、`repair.on_disabled`、`repair.on_repaired`、`actions.give`、`actions.interact`。 - CoreLib 的通用动作会自动改好, 不用你管, 例如 `sendmessage` → `send_message`、`playsound` → `play_sound`、`sendactionbar` → `send_action_bar`。 - 旧的 `@` 控制前缀会自动改成写在动作前面、用 `|` 隔开的一段, 新写法是 `chance ... | `、`after ... | `、`where ... | `。 - **你自己写过的物品配置里, 动作行上的这四个占位符要加 `var.` 前缀** —— `%item_name%` → `%var.item_name%`、`%item_id%` → `%var.item_id%`、`%item_trigger%` → `%var.item_trigger%`、`%player%` → `%var.player%`。这四个是插件执行动作时塞给你用的, 不加前缀在新写法下读不出来, 会原样打印成 `%item_name%` 这样的字面文字。只需要改动作行, 也就是上面那六处。 - **lore 和条件里的占位符千万不要跟着改。** `lore` 里的属性占位符 (例如 `%physical_attack%`) 和 `condition.expressions` 里的外部占位符 (例如 `%emakilevel_level_main%`) 走的是另一套解析, 跟动作行没关系, 改了反而会坏。 - 随包示例 `items/example_item.yml` 里的动作行与占位符都已经是新写法, 直接用不会有问题, 可以照着看。 ### 物品与套装目录 - **物品和套装配置现在可以按子文件夹分类了**, 新增配置项 `data_directories.max_depth`, 同时作用于 `items/` 与 `sets/` 两个目录。填 `1` 只读取 `items/*.yml`、忽略所有子目录; 填 `2` 额外允许一层子目录, 例如 `items/武器/剑.yml`; 填 `3` 允许两层, 例如 `items/武器/单手剑/铁剑.yml`。最小值是 `1`, 填更小的按 `1` 处理。 - **默认值是 `2`, 这是一处行为变化, 老服要注意。** 此前插件是不限层数、把子目录里的文件全部递归读进来的。升级后如果你的 `items/` 或 `sets/` 里嵌套超过两层, 超出的那些目录不会再被加载, 里面的物品和套装会消失。控制台会点名是哪个目录被跳过了, 照着把 `max_depth` 调大, 或者把文件往上挪一层就行。 ### MythicMobs 物品掉落 - **新增 MythicMobs 集成, 怪物可以直接掉落 EmakiItem 物品**, 不用再把物品复制成 MythicMobs 自己的物品定义。在 MythicMobs 的 `Drops` 里这样写: `emakiitem{id=example_item;amount=1}`, 也可以用短名 `ei_item`。 - 支持三个参数: `id` (必填, 物品 id)、`amount` (数量, 可以是数字或表达式)、`amount_formula` (数量公式, 默认 `%amount% * %drop_amount%`)。公式里可以用 `%amount%`、`%drop_amount%`、`%metadata_amount%`、`%generations%`、`%tick%`、`%id%`、`%drop%`。 - 掉落物走的是和 `/ei give` 完全相同的一套生成流程, 随机变量、物品身份标记、属性、技能绑定与套装归属都会正常写入, 掉出来就是一件完整的 EmakiItem 物品。 - `config.yml` 新增 `mythicmobs.enabled`、`mythicmobs.drops.enabled` 与 `mythicmobs.drops.names` (默认认得 `emakiitem` 和 `ei_item` 两个名字), 默认全部启用。 - MythicMobs 是可选依赖, 没装的话这部分自动跳过, 不影响其他功能。 ### 物品刷新与界面修复 - **修复改了物品的 `lore` 之后, 旧 Lore 不消失反而堆在新 Lore 下面。** 每更新一次就多攒一轮历史 Lore, 越更新越长。原因是重建物品时插件还拿着上一版定义留下的那份 Lore 记录当参照, 基础 Lore 一改这份记录就过期了, 于是新写的 Lore 被当成别的插件插进来的行、旧 Lore 被当成应该恢复的行。现在重建物品时会把 EmakiItem 自己写的展示记录和过期参照一并丢掉, 只以新生成的物品作为唯一基准。Forge、Strengthen、Gem、Cooking 等其他模块写进去的 Lore 行不受影响, 更新后照样保留。 - 套装 Lore 块会在更新后的下一次套装刷新时重建 (进服、切换手持、点击背包等), 极短的时间窗内可能看到套装块暂时缺失。 - **修复修复界面里配置的一部分物品组件不生效**, 影响自定义过 `gui/repair_gui.yml` 的服主。此前界面渲染只认得其中六类组件 (物品名、Lore、物品模型、自定义模型数据、附魔、提示框显示), 你在格子里配的其他组件会被静默丢掉, 填了也看不出效果。现在界面会完整应用你配的全部组件。随包默认的 `repair_gui.yml` 只用到那六类, 所以没改过这个文件的话看不出区别。 - 修复执行 reload 时配置预检报告重复打印两遍。 ### 配置与内容变化 - **旧格式的物品文件依旧能正常读取和使用**, 加载行为没有变化, 你的旧物品定义不会失效。变化的是: 插件不再在启动时自动把这些文件改写成新格式, 也不再为它们生成备份文件。想用新写法就自己改, 不改也能继续跑。 - **原先用 JS 脚本动态注册的物品会直接失效, 没有自动转换的办法。** JS 脚本功能整体取消了, 其中包括用脚本注册物品定义 (`registerDefinition`) 和注册物品工厂 (`registerFactory`) 这两种玩法。这些物品需要你改写成 `items/` 目录下的 YAML 定义。随包示例脚本 `scripts/examples/item_right_click.js` 与 `scripts/examples/item_runtime_definition.js` 一并删除。 ### 开发者相关 - `EmakiItemApiProvider` 已移除, 直接使用 `EmakiItemApi` 的静态方法。 - `EmakiItemApi.available()` 与 `isReady()` 收敛为 `EmakiItemApi.status()` (返回 `ApiStatus`)。 - 原先直接挂在 `EmakiItemApi` 上的 `exists()`、`create()`、`identify()`、`definitionIds()`、`definition()`、`displayName()` 改为分层入口: `catalog()`、`operations()`、`repair()`、`migration()`、`extensions()`。插件未加载时这些入口返回不可用实现, 不再抛异常。 - 物品源体系由内部实现提升为公开契约, 第三方插件可以自行注册物品源类型。**对服主没有配置变化**, `item_sources` 的写法与可用来源都不变。 ### 升级说明 - 需要先把 EmakiCoreLib 升到 `4.7.0`。 - **升级前请备份 `plugins/EmakiItem/` 整个目录。** - 要你自己动手的有四处: - 上面九个动作的改名 (对照清单逐个改)。 - 自己写过的物品配置里, 动作行上的 `%item_name%`、`%item_id%`、`%item_trigger%`、`%player%` 四个占位符加 `var.` 前缀; lore 与条件里的占位符不要动。 - 用 JS 脚本注册的物品改写成 `items/` 里的 YAML 定义。 - 检查 `items/` 与 `sets/` 的子目录层数, 超过两层就把 `data_directories.max_depth` 调大。 - `config.yml` 会自动补齐新的 `data_directories` 与 `mythicmobs` 两个配置块, 不用手工加。 - 建议升级后改一次某个物品定义的 `lore` 并把 `update.version` 加一, 确认旧 Lore 行不再残留。 - 命令与权限没有变化。 [/MD]

[MD] ### 新增 - 新增公开 Bukkit 事件：`EmakiItemCreateEvent`（物品创建时触发）、`ItemRepairEvent`（物品修复时触发，可取消）、`ItemSetBonusChangeEvent`（套装加成变化通知），第三方插件可监听这些事件做联动。 - 新增 JavaScript 脚本扩展：脚本可注册运行时物品定义和自定义物品工厂，用代码方式生成物品，入口 `emaki.module("item")`，并附带示例脚本。 - 新增物品修复被事件取消时的提示文案。 - 通过 CoreLib 统一的物品来源支持，物品现在可识别 Oraxen 自定义物品作为物品来源。 - 接入配置预检：启动和重载时检查 Item 配置并在控制台给出明确提示。 ### 注意事项 - 【破坏性】移除旧套装的自动归一化逻辑：来自更早旧版本遗留的套装物品不再被自动归一化重建。如果你的服务器还有很早以前生成的套装物品，建议更新后检查其套装效果是否正常，必要时重新生成。 [/MD]

[MD] ### 新增 - 新增物品修复 GUI，玩家可以通过界面完成修复流程，维修材料和货币成本的展示更清晰。 - 新增物品别名支持，方便服务器管理员给同一个物品定义多个可识别名称或短写。 - 新增物品分层预览能力，可查看套装、强化、宝石等模块对最终物品展示的影响。 - 新增 Item JavaScript 模块入口，可通过 `emaki.module("items")` 读取模块能力和物品相关信息。 ### 修复 - 修复套装 Lore 和套装效果在物品最终预览中展示不够完整的问题。 - 修复套装效果编辑器中嵌套 Lore 列表的添加按钮容易错位或点击不稳定的问题。 - 修复物品修复、识别、更新和迁移流程中部分表现不够统一的问题。 - 修复复杂物品联动预览时，强化层和宝石层参与最终预览的控制不够清晰的问题。 ### 重构 - 重构 Item API 获取方式，使用静态门面 + Bridge，减少外部调用和插件内部实现的耦合。 - 重构物品修复、物品更新和物品迁移相关流程，让复杂物品维护更稳定。 - 重构套装展示和套装效果编辑表达，将面向配置维护的文案统一到“套装效果”。 - 重构 Item 分层预览服务，使套装、强化和宝石等预览数据通过 CoreLib 统一链路整合。 ### 优化 - 优化物品源、属性、技能、强化和宝石的联动显示，更接近玩家最终看到的物品效果。 - 优化 Web Console 物品编辑器，继续接入 CoreLib 的结构化编辑、预览和历史能力。 - 优化默认物品示例、套装示例和语言文件，使其跟随新版本资源结构。 - 优化复杂物品、套装物品和修复流程的维护体验。 ### 注意事项 - 如果你使用自定义物品定义，建议检查物品别名、修复配置、套装效果和最终预览表现。 - 如果服务器依赖物品修复流程，建议先在测试服确认修复 GUI、材料消耗和货币成本符合预期。 - 更新前建议备份 `items/`、`sets/`、`gui/repair_gui.yml` 和相关物品数据。 - 如果需要完整使用最终物品预览，请同时更新 CoreLib v4.3.0 [/MD]