EmakiCoreLib

CoreLib 的公共能力, 安装方式, 配置目录位置与 config.yml 各键的职责如下

EmakiCoreLib 是 Emaki 系列所有业务插件共用的运行时核心. 它自己不做完整玩法, 只提供各插件都能重复使用的底层能力: 动作系统, GUI 模板, 物品来源, PDC (插件自定义数据, 即物品身上由插件写入的隐藏字段), 物品装配, 条件, 表达式, 经济, 权重, 调度兼容和 bStats 托管

NOTE

分区原则: 这里只记录"所有插件都能重复使用"的能力. Attribute, Forge, Strengthen, Cooking, Gem, Skills, Item, Level 等插件自己注册的动作, API, 配置字段和玩法流程, 放到对应插件的文档里查

基本信息

项目	值
模块版本	4.8.36
API Jar	emaki-corelib-api-4.8.28.jar
插件本体	EmakiCoreLib-4.8.36.jar
主类	emaki.jiuwu.craft.corelib.EmakiCoreLibPlugin
Java	25
Paper API	26.1.2.build.74-stable
paper-plugin.yml api-version	26.1
folia-supported	true
硬依赖	无
软依赖	Vault, ExcellentEconomy, PlaceholderAPI, MMOItems, MythicMobs, ItemsAdder, Nexo, Oraxen, EcoItems, NeigeItems, CraftEngine, PacketEvents
主命令	/emakicorelib (别名 /corelib, /emakicore)
权限	emakicorelib.admin, emakicorelib.reload

CoreLib 必须先加载, 其他业务插件都要靠它提供的服务. 你遇到 CoreLib 启动失败时, 先把 CoreLib 修好, 再去排查其他模块

安装边界

服务器只装插件本体 Jar:

plugins/
├── EmakiCoreLib-4.8.36.jar
└── EmakiAttribute-4.8.7.jar / EmakiForge-4.8.8.jar / ...

不要把 emaki-corelib-api-*.jar 放进服务器的 plugins/. 这个 API Jar 是给第三方开发者当 Maven provided 或 Gradle compileOnly 编译依赖用的, 你装服时用不到它

CoreLib 提供什么

通用动作系统

动作系统让你能直接在 YAML 里执行消息, 音效, 粒子, 命令, 经济, 经验, 临时物品, 方块, 传送和动作模板. 想查动作语法, 控制前缀, CoreLib 内置动作, 以及 /corelib action list|run 管理命令, 看 动作系统; 想看全部 131 个内置段 (source/gate/action) 的分类清单与详情跳转, 看 段 ID 表

业务插件可以往同一个注册表里追加自己的动作. 比如 Level 的等级经验动作, Attribute 的属性动作, Skills 的技能动作, 这些参数要去对应插件页面查, 不在 CoreLib 页面集中列

GUI 系统

GUI 系统提供菜单模板, 槽位解析, 按钮, 点击处理, 会话管理, 物品来源解析和动态渲染基础. 你只要声明自己的 GUI 文件与流程逻辑, 剩下的交给它. 详情见 GUI 系统

物品来源

物品来源系统统一解析 Vanilla, CraftEngine, ItemsAdder, Nexo, Oraxen, EcoItems, MMOItems, NeigeItems, EmakiItem 等来源. 这样一来, 配方, 材料, 奖励和 GUI 槽位就不必依赖显示名或 Lore. 详情见 物品来源系统

物品匹配器

在物品来源之上, 匹配器 (matcher) 再按组件, PDC, Lore, 表达式等条件收窄判断, 用来确定"玩家放进来的物品算不算材料". 全系 9 个模块的输入匹配点共用同一套语法, 详情见 物品匹配器

PDC 与物品装配

CoreLib 把 Bukkit PersistentDataContainer (原版用来给物品, 玩家等附加自定义数据的容器) 统一封装好, 再通过 Assembly 把不同模块写进去的 layer 合成为最终名称和 Lore. Forge, Strengthen, Gem, Item, Attribute 等模块都靠这条链路避免互相覆盖展示. 详情见 PDC 服务, 物品装配系统 和 名称与 Lore 操作

共享玩法事件

CoreLib 把部分 Bukkit / MythicMobs 玩法事件统一整理成配置里用的事件 ID, 供 EmakiLevel 的经验来源和 EmakiCodex 的成就触发器重复使用. 能填哪些 ID 和变量见 共享玩法事件 ID

条件, 表达式, 经济和权重

• 条件系统: 通用条件表达与条件组
• 表达式引擎: 费用, 概率, 等级, 伤害和配置公式
• 经济桥接: Vault / ExcellentEconomy provider 与动态枚举
• 权重系统: 随机池, 品质池, 奖励池和保底池的通用工具

推荐阅读顺序

服主 / 配置维护者

1. 物品来源系统: 先学会怎样稳定地引用材料和奖励
2. 物品匹配器: 在此之上按组件, PDC 等条件收窄输入判断
3. 动作系统: 掌握成功, 失败, 奖励和提示的写法
4. 条件系统: 判断权限, 物品, 状态和表达式
5. 表达式引擎: 写费用, 概率和数值公式
6. GUI 系统: 调整菜单布局和按钮交互
7. 对应业务插件页面: 配置真正的玩法流程

第三方开发者

1. PDC 服务: 了解共享数据的写入边界
2. 物品装配系统: 了解多模块展示的合并规则
3. 对应插件 [API 与集成] 页面: 调用业务 API, 不依赖实现类

默认配置目录

plugins/EmakiCoreLib/
├── config.yml
└── lang/
    ├── zh_CN.yml
    └── en_US.yml

config.yml 管的是语言, GUI 后端, 共享玩法事件, 动作循环与动作模板, 以及全局 Debug. 想让所有使用 CoreLib DebugLogger 的 Emaki 模块都输出 Debug 日志, 把 debug.global_all 设成 true. 管理员也可以用 /corelib debug all on|off|status 临时切换, CoreLib 重载后会重新采用配置值. lang/ 管的是 CoreLib 自己的消息. 业务插件会生成自己的配置目录, 你不要把业务配置混放进 CoreLib

主配置参考

plugins/EmakiCoreLib/config.yml 里不属于其他专页的键列在下面. 其中 gui.* 见 GUI 系统, gameplay_events.* 见 共享玩法事件 ID. 表里"取值范围"只写源码里真实存在的限制, 没做校验的地方记 —

顶层

字段	类型	必填	默认值	取值范围	说明
version	string	否	"4.8.36"	—	资源版本号, 跟模块版本保持同步; 它只作资源标记, 代码不会读取
language	string	否	"zh_CN"	—	对应 lang/<language>.yml, 决定 CoreLib 自己消息用什么语言

debug

字段	类型	必填	默认值	取值范围	说明
debug.global_all	boolean	否	false	true / false	是否让所有使用 CoreLib DebugLogger 的模块默认输出 Debug 日志. 可以用 /corelib debug all on|off|status 在运行时临时覆盖, 重载后恢复成这里的值

minimessage

字段	类型	必填	默认值	取值范围	说明
minimessage.default_no_italic	boolean	否	true	true / false	文本没有写明斜体时, 一律取消斜体 (菜单物品名与 Lore, 菜单标题, 聊天消息, 对话框). 它只改默认值, 显式写了 <i> / <italic> 的仍然生效

vanilla_language

字段	类型	必填	默认值	取值范围	说明
vanilla_language.enabled	boolean	否	false	true / false	是否启用语言表下载与缓存; 第一次缺缓存时会去访问 Mojang 资源索引, 缓存放在 plugins/EmakiCoreLib/lang-cache/, 下载失败时相关的本地化功能就用不了
vanilla_language.locale	string	否	"zh_cn"	原版语言 ID, 如 zh_cn, en_us, zh_tw	原版语言 ID, 跟客户端语言文件名一致. 读取时会规范成小写, 留空就回落到 zh_cn

dialog

字段	类型	必填	默认值	取值范围	说明
dialog.enabled	boolean	否	true	true / false	对话框总开关; 关掉后不加载对话框定义, DialogApi 也用不了
dialog.directory	string	否	"dialogs"	—	定义文件目录, 相对 plugins/EmakiCoreLib/, 插件会加载这个目录里的 .yml 文件; 留空就回落到 dialogs

display

字段	类型	必填	默认值	取值范围	说明
display.backend	string	否	"auto"	bukkit / packet / auto / inherit	展示实体的渲染后端, 供伤害飘字, 工位文本和物品展示等共用. inherit 表示跟随 gui.backend; 填了不认识的值按 auto 处理, packet 用不了时会回退到 bukkit
display.view_distance_blocks	integer	否	48	≥ 1	packet 后端的可见距离, 单位是方块; 小于 1 按 1 处理
display.refresh_interval_ticks	integer	否	20	≥ 1	packet 后端重新计算可见性的间隔, 单位是 1/20 秒 (一个游戏刻); 小于 1 按 1 处理

发货默认值片段:

version: "4.8.36"
language: "zh_CN"
debug:
  global_all: false
minimessage:
  default_no_italic: true
vanilla_language:
  enabled: false
  locale: "zh_cn"
dialog:
  enabled: true
  directory: "dialogs"
display:
  backend: "auto"
  view_distance_blocks: 48
  refresh_interval_ticks: 20

使用示例 (启用原版语言表, 并改用 packet 展示后端):

vanilla_language:
  enabled: true
  locale: "zh_cn"
display:
  backend: "packet"
  view_distance_blocks: 64
  refresh_interval_ticks: 10