架构总览

总体架构图

mermaid

graph TB
    subgraph Runtime["运行时环境"]
        Server["Spigot 1.21+"]
    end

    subgraph Infra["基础设施层"]
        CoreLib["EmakiCoreLib<br/>Action / GUI / ItemSource / Assembly<br/>Structured Presentation / PDC / YAML / Economy"]
    end

    subgraph Business["业务插件层"]
        Attribute["EmakiAttribute<br/>属性 / 战斗 / 伤害流程"]
        Forge["EmakiForge<br/>锻造 / 配方 / 编辑器"]
        Strengthen["EmakiStrengthen<br/>强化 / 星级 / 尝试流程"]
        Gem["EmakiGem<br/>宝石 / 开孔 / 镶嵌 / 升级"]
        Cooking["EmakiCooking<br/>四工位烹饪 / 世界工位状态"]
        Skills["EmakiSkills<br/>主动技能 / 触发器 / 施法模式"]
    end

    subgraph Optional["可选生态"]
        Mythic["MythicMobs"]
        CraftEngine["CraftEngine"]
        ItemsAdder["ItemsAdder"]
        Nexo["Nexo"]
    end

    Attribute --> CoreLib
    Forge --> CoreLib
    Strengthen --> CoreLib
    Gem --> CoreLib
    Cooking --> CoreLib
    Skills --> CoreLib

    Forge -.->|"softdepend"| Attribute
    Strengthen -.->|"softdepend"| Attribute
    Gem -.->|"softdepend"| Attribute
    Skills -.->|"ServicesManager"| Attribute
    Skills -.->|"Mythic API"| Mythic
    Cooking -.->|"Block Bridge"| CraftEngine
    Cooking -.->|"Block Bridge"| ItemsAdder
    Cooking -.->|"Block Bridge"| Nexo

    CoreLib --> Server

架构解读

整套系统分三层：运行时环境（Spigot）、基础设施层（CoreLib）、业务插件层（各玩法模块）。这样分层的核心原因是物品数据的一致性——多个模块都会往同一件物品上写数据（属性、强化等级、宝石槽位等），如果各写各的很容易互相覆盖。CoreLib 作为中间层，统一管理物品的"层快照 → 重建展示"流程，确保各模块的数据互不干扰。

各模块的定位：

EmakiCoreLib 是全局共享的基础设施。除了物品装配和展示渲染，它还包揽了 GUI 框架、动作执行器、物品源解析、消息服务、经济接口等公共能力。
EmakiAttribute 负责属性定义、伤害结算、资源管理和战斗反馈。它同时通过 PdcAttributeApi 和 EmakiAttributeBridge 向其他模块暴露接口，让 Forge、Strengthen、Gem 写入的属性能被正确识别。
EmakiForge / EmakiStrengthen / EmakiGem 都强依赖 CoreLib，软依赖 Attribute。它们各自用独立的 source id 往物品上写入快照和属性负载，CoreLib 负责把这些层合并渲染成最终的物品展示。
EmakiCooking 走的是世界工位路线：四类厨具以方块形式放在世界里，玩家直接右键交互。工位状态会落盘持久化，方块识别则通过 CoreLib 的方块桥接（支持 CraftEngine、ItemsAdder、Nexo 自定义方块）。
EmakiSkills 是技能管理框架，处理解锁来源收集、技能槽位分配、触发器分发和施法模式切换。技能的实际效果由 MythicMobs 执行，Skills 通过 MythicBridge 和 EaBridge 串联整个链路。

共享运行时模式

各业务模块的启动和重载流程高度一致，都遵循这个链路：

初始化 LifecycleCoordinator
装配 RuntimeComponents
加载语言包、配置文件、配方/数据目录
调用 BootstrapService 处理版本化文件和默认资源释放
初始化 GUI、消息服务、物品源、桥接服务和业务 Service
注册命令路由器、事件监听器，暴露服务接口
重载时重新加载配置，刷新在线玩家的物品数据、GUI 会话和运行时状态

这套流程之所以统一，是因为 CoreLib 提供了 LifecycleCoordinator 和 BootstrapService 这两个骨架——业务模块只需要填入自己的组件，启动和重载的编排逻辑由 CoreLib 驱动。

共享基础设施使用矩阵

下表展示了各业务模块对 CoreLib 基础设施的实际使用情况：

CoreLib 组件	Attribute	Forge	Strengthen	Cooking	Gem	Skills
`GuiService`	间接	✅	✅	蒸锅局部	✅	✅
`ActionExecutor`	✅	✅	✅	✅	✅	较少
`ItemSourceService`	间接	✅	✅	✅	✅	间接
`EmakiItemAssemblyService`	名称读取	✅	✅	间接	✅	—
`StructuredPresentationRenderer`	预览	✅	✅	间接	✅	—
`MessageService`	✅	✅	✅	✅	✅	✅
`BootstrapService`	自建	✅	✅	✅	✅	✅
`PdcAttributeGateway`	提供 API	✅	✅	—	✅	—
`EmakiAttributeBridge`	提供服务	—	—	—	—	✅
`AdventureSupport` / `MiniMessages`	✅	✅	✅	✅	✅	✅

表中"间接"表示该模块不直接调用这个组件，但通过 CoreLib 的其他服务间接使用了它。Attribute 的 BootstrapService 标记为"自建"，是因为 Attribute 有自己的启动逻辑，没有复用 CoreLib 的默认实现。

跨模块契约

模块之间的数据交换遵循明确的契约，而不是直接互相调用内部 API：

EmakiAttribute 通过 PdcAttributeApi 暴露属性读写接口（经由 Bukkit ServicesManager 注册），并通过 ServicesManager 注册 EmakiAttributeBridge 供其他模块发现和调用。CoreLib 的 PdcAttributeGateway 负责在调用方侧发现并代理这个 API
EmakiCoreLib 管理 namespace layer 的装配、移除和重建——各模块写入自己 namespace 下的数据，CoreLib 负责把所有层合并成最终物品
EmakiForge / EmakiStrengthen / EmakiGem 各自使用独立的 source id 写入快照和可选的属性负载，互不干扰
EmakiCooking 通过 CustomBlockBridge（CraftEngine / ItemsAdder / Nexo）和 ItemSourceService 识别世界中的工位方块
EmakiSkills 通过触发器分发、MythicBridge 和 EaBridge 串联技能的触发 → 执行 → 属性消耗整条链路

外部生态依赖

CoreLib 可选接入

Vault · ExcellentEconomy · PlaceholderAPI · MMOItems · ItemsAdder · Nexo · NeigeItems · CraftEngine

这些都是软依赖。CoreLib 在启动时检测它们是否存在，有就注册对应的桥接服务（比如 Vault 经济、ItemsAdder 物品源），没有就跳过。不会因为缺少任何一个而报错。

CoreLib 自带库声明

adventure-platform-bukkit · adventure-text-minimessage · adventure-text-serializer-legacy · adventure-text-serializer-plain · exp4j · boosted-yaml

这些通过 plugin.yml 的 libraries 字段声明，服务端启动时自动下载。不需要手动放 jar。

业务模块协作关系

Forge / Strengthen / Gem 都强依赖 EmakiCoreLib，软依赖 EmakiAttribute
Cooking 强依赖 EmakiCoreLib，软依赖 CraftEngine、ItemsAdder、Nexo
Skills 强依赖 EmakiCoreLib，软依赖 MythicMobs、EmakiAttribute、PlaceholderAPI

架构总览 ​

总体架构图 ​

架构解读 ​

共享运行时模式 ​

共享基础设施使用矩阵 ​

跨模块契约 ​

外部生态依赖 ​

CoreLib 可选接入 ​

CoreLib 自带库声明 ​

业务模块协作关系 ​