快速开始

本页说明从源码或插件包开始，到服务器首次成功加载为止需要做什么。按顺序执行，不要把 API Jar 放进 plugins/。

环境要求

项目	要求
Java	25
服务端	Paper 1.21.8+（最低支持 1.21.8），当前插件声明支持 Folia
构建工具	Maven，多模块聚合工程
必装基础模块	EmakiCoreLib

构建插件

在项目根目录执行：

mvn -DskipTests package

默认聚合出的插件本体模块包括：

• EmakiCoreLib
• EmakiAttribute
• EmakiForge
• EmakiStrengthen
• EmakiCooking
• EmakiLevel
• EmakiCodex

同一次构建还会产出 emaki-*-api 与 emaki-skills-protocol 等编译期构件，它们不是服务器插件。

根 pom.xml 定义了 private-modules profile，其激活条件是根目录存在 .key 文件。该文件存在时会额外聚合：

• EmakiGem
• EmakiSkills
• EmakiItem
• EmakiStorage

由于该 profile 按文件自动激活，通常不需要手动指定；如需显式启用，可执行：

mvn -DskipTests -Pprivate-modules package

构建完成后，每个模块的插件本体 jar 通常位于：

模块名/target/*.jar

只把插件本体 jar 放进服务器 plugins/。不要安装 emaki-*-api-*.jar 和 emaki-skills-protocol-*.jar，它们不是服务器插件。

当前插件与 API Jar 配对

以下版本来自当前 dev 工作区的各模块 pom.xml 与 paper-plugin.yml。服务器服主只安装“插件本体 Jar”；“API Jar”只给第三方开发者作为 provided / compileOnly 编译依赖。

插件本体 Jar	API Jar	当前版本	服务器是否安装 API Jar
EmakiCoreLib-4.6.0.jar	emaki-corelib-api-4.6.0.jar	4.6.0	否
EmakiAttribute-4.6.0.jar	emaki-attribute-api-4.6.0.jar	4.6.0	否
EmakiForge-4.6.0.jar	emaki-forge-api-4.6.0.jar	4.6.0	否
EmakiStrengthen-4.6.0.jar	emaki-strengthen-api-4.6.0.jar	4.6.0	否
EmakiCooking-4.1.0.jar	emaki-cooking-api-4.1.0.jar	4.1.0	否
EmakiLevel-1.4.0.jar	emaki-level-api-1.4.0.jar	1.4.0	否
EmakiCodex-1.0.0.jar	emaki-codex-api-1.0.0.jar	1.0.0	否
EmakiGem-2.6.0.jar	emaki-gem-api-2.6.0.jar	2.6.0	否
EmakiSkills-2.6.0.jar	emaki-skills-api-2.6.0.jar	2.6.0	否
EmakiItem-2.6.0.jar	emaki-item-api-2.6.0.jar	2.6.0	否
EmakiStorage-1.0.0.jar	emaki-storage-api-1.0.0.jar	1.0.0	否

如果你是开发者，只在自己的插件工程里引用对应 API Jar；运行服务器时仍然只把 Emaki 插件本体 Jar 放进 plugins/。

纯协议构件：EmakiSkillsProtocol

emaki-skills-protocol-2.6.0.jar 不是服务器插件，不要放进 plugins/。它没有 paper-plugin.yml，也没有主类，只承载装备技能 PDC 的编解码契约（EquipmentSkillPdcCodec）。CoreLib、Item、Skills、Forge、Gem、Strengthen 在构建时把它嵌入自身 Jar 并 relocate 到各自的运行时包名，因此服主无需单独安装或升级它。

安装顺序

推荐按依赖层级安装：

1. EmakiCoreLib：所有业务模块的基础库，必须先安装。
2. EmakiAttribute：如果你需要属性、战斗、资源或其他模块写入属性，建议安装。
3. 装备线模块：EmakiItem、EmakiForge、EmakiStrengthen、EmakiGem。
4. 成长与玩法线模块：EmakiLevel、EmakiSkills、EmakiCooking、EmakiCodex。
5. 外部生态插件：PlaceholderAPI、Vault / ExcellentEconomy、MythicMobs、CraftEngine、ItemsAdder、Nexo、Oraxen、EcoItems、MMOItems、NeigeItems、PacketEvents 等。

实际加载顺序由服务端和 paper-plugin.yml 决定。CoreLib 是硬依赖，其他多数外部生态是 softdepend，没安装时相关桥接功能会不可用，但插件主体通常仍可加载。

首次启动流程

1. 将需要的 jar 放入服务器 plugins/ 目录。
2. 启动服务器，等待插件生成默认配置。
3. 停服，或至少确认没有玩家正在操作相关系统。
4. 修改 plugins/Emaki*/ 下的配置文件。
5. 再次启动服务器，先看控制台第一条加载错误。
6. 使用各模块的根命令、reload、inspect 或 debug 命令检查功能是否可用。

常见生成目录示例：

plugins/
├── EmakiCoreLib/
│   ├── config.yml
│   └── lang/
├── EmakiAttribute/
│   ├── attributes/
│   ├── conditions/
│   ├── damage_types/
│   ├── lore_formats/
│   └── config.yml
├── EmakiForge/
│   ├── recipes/
│   ├── gui/
│   └── config.yml
├── EmakiLevel/
│   ├── types/
│   ├── sources/
│   ├── requirements.yml
│   └── config.yml
└── EmakiSkills/
    ├── skills/
    ├── resources/
    ├── gui/
    └── data/

验证 CoreLib 是否正常

CoreLib 没有面向玩家的复杂玩法，但它是所有模块的基础。验证方式：

• 控制台没有 EmakiCoreLib 启动异常。
• 业务模块没有提示缺少 CoreLib。
• 使用动作、GUI、物品来源或经济功能的模块能正常初始化。

如果 CoreLib 没有正常加载，先不要排查业务模块。修好 CoreLib 后再看 Attribute、Forge、Skills 等模块。

验证业务模块

建议按模块逐个验证。

Attribute

• 确认控制台没有属性定义加载错误。
• 使用模块根命令查看帮助。
• 修改一个属性定义后重载，检查是否报错。
• 如果启用 PlaceholderAPI，确认占位符能返回数据。

Forge / Strengthen / Gem

• 打开 GUI，确认按钮和槽位正确显示。
• 放入目标装备和材料，测试成功、失败、材料不足等分支。
• 查看装备 Lore 是否被正确刷新。
• 如果依赖 Attribute，确认属性 PDC 没有丢失。

Level

• 使用 /elv info main 确认默认等级类型已加载。
• 使用 /elv debug requirement main 2 检查升级需求来源和值。
• 如果安装 PlaceholderAPI，确认 %emakilevel_level_main% 能返回玩家等级。
• 如果安装 MythicMobs，测试 emakilevel_exp / elv_exp Drop 或 Mythic 击杀来源是否给经验。

Skills

• 确认 MythicMobs 已加载（如果技能需要 MythicMobs 执行效果）。
• 创建一个简单技能，测试主动释放。
• 测试冷却、资源不足、条件不足时是否阻止释放。

Cooking

• 放置或识别对应工位方块。
• 测试砧板、炒锅、研磨机、蒸锅的基础交互。
• 重启服务器，检查工位状态是否持久化。