EmakiCoreLib
EmakiCoreLib 是 Emaki 系列所有业务插件的共享运行时核心。它本身不提供完整玩法循环，而是提供跨插件复用的底层能力：动作系统、GUI 模板、物品来源、PDC、物品装配、条件、表达式、经济、权重、JavaScript 脚本、调度兼容和 bStats 托管。
分区原则：这里记录“所有插件都能复用”的能力。Attribute、Forge、Strengthen、Cooking、Gem、Skills、Item、Level 等插件自己注册的动作、脚本模块、API、配置字段和玩法流程，放在对应插件文档中说明。
基本信息
| 项目 | 值 |
|---|---|
| 模块版本 | 4.6.3 |
| API Jar | emaki-corelib-api-4.6.3.jar |
| 插件本体 | EmakiCoreLib-4.6.3.jar |
| 主类 | emaki.jiuwu.craft.corelib.EmakiCoreLibPlugin |
| Java | 25 |
| Paper API | 1.21.8-R0.1-SNAPSHOT |
| paper-plugin.yml api-version | 1.21.8 |
| 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，再排查其他模块。
运行兼容性
CoreLib 在启动时输出兼容性报告：Java 25、Paper/Folia 能力缺失会阻止启动；Minecraft 版本低于 1.21.8、无法识别，或达到 1.22.0 及以上时会标记为“未验证”并输出告警，而不会依赖猜测的版本白名单强制拦截。EmakiCoreLibApi.compatibilityReport() 可供依赖插件读取该报告。
安装边界
服务器只安装插件本体 Jar：
plugins/
├── EmakiCoreLib-4.6.3.jar
└── EmakiAttribute-4.6.3.jar / EmakiForge-4.6.0.jar / ...不要把 emaki-corelib-api-*.jar 放进服务器 plugins/。API Jar 只给第三方开发者作为 Maven provided 或 Gradle compileOnly 编译依赖使用。
CoreLib 提供什么
通用动作系统
动作系统允许各插件在 YAML 中执行消息、音效、粒子、命令、经济、经验、临时物品、方块、传送、脚本和动作模板。动作语法、控制前缀、CoreLib 内置动作，以及 /corelib action list|run 管理命令见 动作系统。
业务插件可以向同一个注册表追加自己的动作。例如 Level 的等级经验动作、Attribute 的属性动作、Skills 的技能动作都应在对应插件页面中查参数，不再集中塞在 CoreLib 页面里。
GUI 系统
GUI 系统提供菜单模板、槽位解析、按钮、点击处理、会话管理、物品来源解析和动态渲染基础。业务插件只声明自己的 GUI 文件与流程逻辑。详情见 GUI 系统。
物品来源
物品来源系统统一解析 Vanilla、CraftEngine、ItemsAdder、Nexo、Oraxen、EcoItems、MMOItems、NeigeItems、EmakiItem 等来源，让配方、材料、奖励和 GUI 槽位不依赖显示名或 Lore。详情见 物品来源系统。
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 与动态枚举。
- 权重系统：随机池、品质池、奖励池和保底池的通用工具。
JavaScript 脚本
CoreLib 提供 GraalJS 脚本运行时、runjs 动作、全局脚本扩展、受控服务器 API 和动态模块入口。业务插件启用时可以注册自己的 emaki.module("...") 能力；插件独有方法请阅读对应插件 API 页。详情见 JavaScript 脚本。
推荐阅读顺序
服主 / 配置维护者
- 物品来源系统：先学会如何稳定引用材料和奖励。
- 动作系统：掌握成功、失败、奖励、提示和脚本调用写法。
- 条件系统：配置权限、物品、状态和表达式判断。
- 表达式引擎：编写费用、概率和数值公式。
- GUI 系统：调整菜单布局和按钮交互。
- 对应业务插件页面：配置真正的玩法流程。
第三方开发者
- PDC 服务：了解共享数据写入边界。
- 物品装配系统：了解多模块展示合并规则。
- JavaScript 脚本：了解脚本入口和动态模块。
- 对应插件 [API 与集成] 页面：调用业务 API，不依赖实现类。
默认配置目录
plugins/EmakiCoreLib/
├── config.yml
├── lang/
│ ├── zh_CN.yml
│ └── en_US.yml
└── scripts/
├── global/
├── mythic/
├── extensions/
│ └── global/
├── templates/
└── examples/scripts/ 下自动创建的子目录由 script.paths.create_directories 决定，默认是 global、mythic、extensions/global、templates、examples；script.paths.root 可改变根目录名。release_default_data: false 时不会释放 scripts/examples 下的内置示例脚本。
config.yml 管理语言、GUI 后端、共享玩法事件、动作循环与动作模板、脚本引擎与安全限制，以及全局 Debug；将 debug.global_all 设为 true 会为所有使用 CoreLib DebugLogger 的 Emaki 模块输出 Debug 日志。管理员也可用 /corelib debug all on|off|status 临时切换，CoreLib 重载后会重新采用配置值。lang/ 管理 CoreLib 自身消息；scripts/ 是 CoreLib 脚本运行时目录。业务插件会生成自己的配置目录，不建议把业务配置混放进 CoreLib。