EmakiCoreLib 总览

EmakiCoreLib 是 Emaki 插件体系的基础库。其他所有功能模块都建立在它之上——从 GUI 渲染、动作执行到物品管理和数据持久化，CoreLib 把这些通用的底层能力收拢在一起，让上层模块不必重复造轮子。

基本信息

属性	值
模块 ID	emaki-corelib
版本	3.4.0
主类	net.pekocraft.emaki.corelib.EmakiCoreLib
命令	无
软依赖	Vault, ExcellentEconomy, PlaceholderAPI, CraftEngine, ItemsAdder, NeigeItems, MMOItems, Nexo

CoreLib 做了什么

简单来说，CoreLib 把 Emaki 体系中各模块都会用到的功能抽成了公共服务：

• GUI 框架 — 用 YAML 模板定义箱子界面，支持异步渲染和声音反馈
• 动作系统 (Action) — 一套动作执行管线，可以串联条件判断、概率触发、延迟执行等控制逻辑
• 物品来源 (ItemSource) — 跨插件的物品获取抽象，不管是原版物品还是 CraftEngine、ItemsAdder 等第三方插件的物品，都用同一套格式引用
• 装配系统 (Assembly) — 物品名称和 Lore 的分层渲染引擎，多个模块可以各自往同一件物品上叠加展示层
• PDC 服务 — 基于 PersistentDataContainer 的分区化数据存储，把不同模块的数据隔离在各自的命名空间下
• 经济桥接 (Economy) — 对接 Vault / ExcellentEconomy 等经济插件，上层模块不需要关心底层用的是哪个
• 条件系统 (Condition) — 比较运算符 + 逻辑组合的条件判断，主要配合动作系统的 @if 前缀使用
• 表达式引擎 (Expression) — 基于 exp4j 的数学表达式求值，还内置了多种随机分布
• 引导加载 (Bootstrap) — 管理模块的生命周期和服务注册顺序
• 技能 PDC 网关 (SkillPdcGateway) — 在物品 PDC 中读写技能 ID 列表，供 Forge、Strengthen、Gem 模块在产物上标记技能
• 自定义方块桥接 (CustomBlockBridge) — CraftEngine、ItemsAdder、Nexo 三种自定义方块插件共用的方块识别接口，供 Cooking 等模块判断世界中的方块是不是自定义方块工位
• PDC 属性网关 (PdcAttributeGateway) — 通过 Bukkit ServicesManager 发现并调用 EmakiAttribute 的 PDC 属性 API，供 Forge、Strengthen、Gem 等模块向物品写入属性负载

服务注册表

CoreLib 通过 EmakiServiceRegistry 管理所有服务实例。各模块启动时把自己的服务注册进去，其他模块需要时直接从注册表里取。

这种设计的好处是模块之间不需要互相持有引用，降低了耦合度。

已注册服务列表

CoreLib 一共注册了 17 个服务：

#	服务接口	说明
1	ActionService	动作解析与执行
2	GuiService	GUI 模板加载与会话管理
3	ItemSourceService	物品来源解析与获取
4	AssemblyService	物品装配与结构化渲染
5	PdcService	PDC 持久化数据存储
6	EconomyService	经济操作桥接
7	ConditionService	条件表达式求值
8	ExpressionService	数学表达式求值
9	PlaceholderService	占位符解析
10	SoundService	声音播放
11	TemplateService	动作模板管理
12	CooldownService	冷却时间管理
13	LanguageService	多语言文本管理
14	ConfigService	配置文件管理
15	NamespaceRegistry	装配命名空间注册
16	CacheService	缓存管理
17	SignatureService	数据签名与校验

获取服务的方式很简单：

ActionService actionService = EmakiServiceRegistry.get(ActionService.class);

提示

所有服务在 CoreLib 的 onEnable 阶段就注册完了。如果你的模块依赖 CoreLib，记得在 plugin.yml 的 softdepend 或 depend 里声明 EmakiCoreLib，确保加载顺序正确。

自动加载库

CoreLib 启动时会自动加载以下库，其他模块不需要重复引入：

库	用途
adventure-api / adventure-platform-bukkit	MiniMessage 与 Component 文本处理
exp4j	数学表达式解析与求值
boosted-yaml	增强型 YAML 配置读写

配置文件

config.yml

# 配置文件版本，请勿手动修改
config_version: 3

# 动作模板定义
action:
  templates:
    # 模板名称 -> 动作列表
    notify_and_sound:
      - "sendmessage message=<green>操作成功！"
      - "playsound sound=entity.experience_orb.pickup volume=1.0 pitch=1.2"

    reward_basic:
      - "givemoney amount=100"
      - "giveexp amount=50"
      - "sendmessage message=<gold>你获得了基础奖励！"

注意

config_version 由插件自动管理，用于配置格式迁移。手动改这个值可能导致配置被覆盖或迁移出错。

动作模板

在 action.templates 下定义的模板，可以在任何动作列表中通过 usetemplate 引用，避免到处复制粘贴相同的动作序列。详见 动作系统。

语言系统

CoreLib 用基于文件的多语言系统管理文本，语言文件放在 lang/ 目录下：

plugins/EmakiCoreLib/
├── config.yml
└── lang/
    ├── zh_CN.yml    ← 默认语言
    ├── en_US.yml
    └── ...

• 默认语言是 zh_CN（简体中文）
• 语言文件是标准 YAML 格式，键是消息 ID，值是 MiniMessage 格式的文本
• 其他模块可以通过 LanguageService 注册和查询自己的语言键

# lang/zh_CN.yml 示例
messages:
  prefix: "<gray>[<gradient:gold:yellow>Emaki</gradient>]</gray> "
  no_permission: "{prefix}<red>你没有权限执行此操作。"
  player_only: "{prefix}<red>该命令只能由玩家执行。"
  reload_success: "{prefix}<green>配置已重新加载。"

提示

语言文件完整支持 MiniMessage 格式，渐变色、悬浮文本、点击事件这些富文本特性都可以用。