Emaki Series

简体中文

English

简体中文

English

Appearance

更新日志阅读说明 ​

本页用于说明当前文档与源码能力的同步重点，并提供升级时的检查路径。完整版本变化仍应结合各模块目录下的 CHANGELOG.md、默认配置文件和发行包说明一起阅读。

CoreLib 4.5.11 / Item 2.5.9：旧版 configured-item 安全迁移 ​

  • CoreLib 共享 GUI 与 EmakiItem items/ 文件会在正式 YAML 解析前自动迁移旧版物品字段。
  • 旧来源、数量、名称、Lore、模型数据、附魔、物品标记和隐藏组件会转换到 item.source、item.amount、item.components；1.21.5+ 的 custom_model_data 与 tooltip_display 映射已覆盖。
  • 现代字段优先，components.raw 节点整体跳过，非目标业务字段保持不变，重复启动不会再次改写。
  • 实际修改前保存原文备份，迁移结果先写临时文件并重新解析；校验成功才替换，失败时保留或恢复原文件。
  • 备份位于各插件数据目录的 migration-backups/configured-item-format/<时间戳>/。正式服升级仍建议先备份完整配置目录。

CoreLib 边界调整：领域协议迁回业务模块 ​

CoreLib 不再持有领域协议与扩展点，二次开发时请改用新归属：

  • 物品层预览 SPI（ItemLayerPreviewProvider、ItemLayerPreviewRequest 等）已从 CoreLib 删除，现由 EmakiItemApi 的 emaki.jiuwu.craft.item.api.preview 持有。
  • 装备技能 PDC key 与编解码现唯一由 EmakiSkillsProtocol 的 EquipmentSkillPdcCodec 持有；CoreLib 的 SkillPdcGateway 已标记 @Deprecated(forRemoval = true)，只作为委托适配器。
  • 属性 PDC 与属性服务契约现唯一权威在 EmakiAttributeApi 的 emaki.jiuwu.craft.attribute.api.PdcAttributeApi 与完整 PdcAttributePayload；CoreLib 的 PdcAttributeGateway 与镜像 PdcAttributeApi 均已 @Deprecated(forRemoval = true)，且镜像无法表达条件、schema 版本与更新时间戳。
  • CoreLib 侧的上述适配器仅为一个同步发行窗口保留，新代码不应再依赖。

当前文档同步重点 ​

本轮文档已按当前源码重新核对命令、权限、配置目录和主要运行能力，并同步以下运行边界与配置结构：

运行边界与配置结构同步重点 ​

  • 平台与调度
    • 各插件 paper-plugin.yml 已声明 Paper 1.21.8+ 与 Folia 支持；CoreLib 新增 Folia 调度适配，业务模块的延迟任务、异步任务、GUI 回主线程刷新和显示实体刷新应通过统一调度入口运行。
    • 文档中的环境要求已同步为 Paper 1.21.8+，并同步当前 Folia 支持声明。
  • GUI 与物品展示
    • GUI 槽位以 item 作为当前结构化字段；动态信息槽、确认槽、预览槽优先尊重模板中的 item、display_name、lore 和组件配置。
    • EmakiGem 镶嵌、开孔、升级界面打开时不再自动从玩家主手或背包补入目标物品，目标装备与材料需要玩家手动放入。
    • EmakiSkills 技能面板、触发器选择界面以及 EmakiStrengthen 的预览/确认类动态槽位已对齐上述 GUI 模板优先规则。
  • 属性与 PDC
    • Attribute 支持区间随机值，Lore 与 PDC 解析可识别百分比和整数区间，快照会保留区间贡献的最小值、最大值与实际取值。
    • variables 与 ea_attributes 语义边界更清晰：变量用于文本与占位符上下文，真实属性输出应写入显式 ea_attributes。
    • 近期清理了 ea_attribute_meta 相关逻辑，材料、宝石、物品和强化配置不应再依赖该字段作为属性元数据入口。
  • Cooking 配方
    • 配方结果统一使用 result.<branch>.outputs/actions 结构；成功、提前、过度、欠熟、过熟、非法等分支都按同一模型描述。
    • 新增配方完成条件系统，配方可以在产出前检查条件；操作台默认交互按键也按当前源码重新整理。
    • 工位悬浮文本展示、展示实体后端和刷新配置已进入当前配置线。
  • Level
    • 新增 EmakiLevel / EmakiLevelApi 等级系统模块，提供多等级类型、经验来源、升级需求、PDC、PlaceholderAPI、CoreLib Action、MythicMobs Drop 和 EmakiAttribute 属性贡献桥接。
    • VitePress 已新增详细 Level 模块文档，并在快速开始、项目介绍和架构总览中补充等级成长模块。
  • Forge / Gem / Strengthen / Item / Skills
    • Forge 材料效果只显示当前效果类型自己的参数，quality_modify 使用 tier，capacity_bonus 使用 value。
    • Gem 宝石物品会在获取、重载和 GUI 复刻时按当前定义刷新名称、Lore、模型和等级展示。
    • Skills、Strengthen、Forge、Gem、Item 的技能效果统一使用 es_skills 列表写法，不再把旧单值字段作为当前文档推荐写法。

新增和补充 ​

  • Attribute
    • 新增配置目录说明，补充 config.yml、attribute_balance.yml、attributes/、damage_types/、conditions/、lore_formats/ 的职责。
    • 新增属性衰减曲线页面，说明 logarithmic、sqrt、piecewise_linear 三类衰减规则。
    • 伤害系统补充 synthetic_hit_feedback，说明接管原版伤害后的击退与受伤音效反馈。
  • Gem
    • 新增开孔器系统页面，说明 socket_openers、开孔器材料、插槽类型和失败反馈。
    • 更新镶嵌成功率，改为当前 inlay_success 配置结构。
    • 补充宝石升级全局成功率和失败惩罚。
  • Skills
    • 新增技能状态栏页面，说明 actionbar 模板、刷新间隔和施法模式展示。
    • 补充脚本引擎全局限制，包括每阶段动作行数和单动作目标数量。
    • 补充 combo_attack 被动触发器和被动触发器全局设置。
  • Cooking
    • 命令与权限补充 /ec debug、烤炉、榨汁机、发酵桶权限。
    • 工位系统补充展示实体后端、展示距离、刷新间隔、炒锅翻炒动画和烫伤机制。
  • Forge
    • 新增锻造历史记录页面，用于说明锻造行为追踪、自动保存和排查用途。
    • 品质系统保留品质池、保底、品质物品元数据和确定性算法说明。
  • Strengthen
    • 分支树页面补充分支配方文件和强化转移设计要点。
  • Item
    • 命令页面补充 /ei debug 和 emakiitem.debug 权限。

删除和修正 ​

  • Gem 命令修正
    • 清理已不属于当前命令路由的旧管理入口。
    • 当前命令统一为 /emakigem gui [inlay|open|upgrade]、reload、inspect、clearstate、debug。
    • 权限改为 emakigem.use、emakigem.reload、emakigem.admin、emakigem.debug。
  • Skills 命令修正
    • 技能界面入口统一为 /eskills gui。
    • 清理已不属于当前命令路由的旧触发器管理入口。
    • 补充 /eskills clearslot <player> <slot>。
    • castmode 明确为 /eskills castmode <on|off|toggle>。
  • Cooking 权限修正
    • 榨汁机盛取权限使用 emakicooking.station.juicer.collect。
    • 发酵桶开始权限使用 emakicooking.station.fermentation_barrel.start。
    • 工位权限统一采用 emakicooking.station.* 形式。

模块版本线说明 ​

当前源码中各模块版本并不完全相同，应以各模块 src/main/resources/config.yml 和 pom.xml 为准：

模块当前默认配置版本
EmakiCoreLib4.6.0
EmakiAttribute4.6.0
EmakiForge4.6.0
EmakiStrengthen4.6.0
EmakiCooking4.1.0
EmakiLevel1.4.0
EmakiCodex1.0.0
EmakiGem2.6.0
EmakiSkills2.6.0
EmakiItem2.6.0
EmakiStorage1.0.0

纯协议构件 emaki-skills-protocol 当前为 2.6.0。它不是服务器插件，也没有独立的默认配置，随各 runtime 模块一起分发。

不同模块的版本号代表各自发行节奏，不表示功能重要性。升级时应按实际安装模块分别比对默认配置。

推荐阅读顺序 ​

  1. 阅读目标模块首页，确认模块职责和依赖关系。
  2. 阅读命令与权限页面，先完成权限组规划。
  3. 阅读配置目录或核心功能页面，确认默认目录和文件用途。
  4. 阅读具体功能页，例如宝石开孔、技能触发器、属性衰减、锻造品质、烹饪工位。
  5. 修改配置后使用对应模块的 reload、inspect、debug 或 lint 命令验证。
  6. 正式服升级前，在测试服导入真实装备与玩家数据进行抽样验证。

升级前检查清单 ​

  • 备份整个 plugins/Emaki*/ 配置目录。
  • 备份玩家数据、装备数据、Cooking 工位数据和经济数据。
  • 不要直接覆盖旧配置；先用默认配置对比新增字段，再逐项合并。CoreLib 4.5.11 / Item 2.5.9 的 configured-item 自动迁移不能替代完整备份。
  • 检查命令和权限是否按当前文档修正。
  • 检查 Attribute 是否启用 hard_lock_damage，并确认环境伤害映射符合服务器预期。
  • 检查 Gem 是否合并 socket_openers、inlay_success、upgrade 全局配置。
  • 检查 Skills 是否合并 actionbar、script_engine、passive_trigger_settings。
  • 检查 Cooking 是否合并 oven、juicer、fermentation_barrel 工位、GUI 和权限。
  • 检查 Forge 品质、历史记录和条件失败策略是否符合当前玩法。
  • 检查 Item 自动更新和修复配置是否会影响旧物品。

排查建议 ​

  • 配置加载失败时，先看控制台首个 YAML 解析错误，通常后续错误都是连锁结果。
  • 物品属性异常时，先确认 CoreLib 装配层是否重建，再检查 Attribute PDC 输出。
  • GUI 无法操作时，优先检查权限、槽位配置、模板 ID 和物品来源。
  • 成功率、品质、强化等随机玩法异常时，先检查公式变量、保底计数和失败处理策略。
  • 涉及跨模块效果时，按 CoreLib → Attribute/Skills → 业务模块的顺序排查。