项目介绍
Emaki Series 是一组面向 Minecraft 1.21.8+ 的 RPG 插件模块。它不把所有玩法塞进一个插件，而是把公共能力放进 CoreLib，把属性、装备、强化、宝石、等级、技能、烹饪和图鉴拆成可组合模块。
如果你的服务器需要下面这些能力，按模块选择安装即可：
- 装备应该有稳定 ID、名称、Lore、属性、套装和技能绑定。
- 属性系统需要支持物理、法术、投射物、暴击、防御、穿透、资源等数值。
- 装备成长需要锻造、强化、宝石、品质、材料、失败惩罚和展示刷新。
- 玩家成长需要多等级类型、经验来源、升级需求、排行榜、PDC 和 PlaceholderAPI 展示。
- 技能需要主动释放、被动触发、冷却、资源消耗、等级参数和外部技能引擎联动。
- 玩法系统需要世界工位、交互流程、输入材料、产物发放和状态持久化。
- 收集与目标引导需要原版成就页、节点触发器和完成奖励动作。
- 所有模块需要共享动作、GUI、物品来源、经济、PDC 和配置加载能力。
后续文档会按模块说明配置目录、命令、权限、核心 YAML 字段和验证方式。
技术基线
| 项目 | 当前基线 |
|---|---|
| 服务端 | Paper 1.21.8+（最低支持 1.21.8） |
| API | paper-api:1.21.8-R0.1-SNAPSHOT |
| Java | 25 |
| paper-plugin.yml api-version | 1.21.8 |
| 构建方式 | Maven 多模块聚合 |
插件仅面向 Minecraft 1.21.8 及以上版本开发，不兼容更低版本；
api-version声明为1.21.8，低于该版本的服务器会被 Paper 拒绝加载。当前插件描述文件也声明了 Folia 支持。
模块定位
| 模块 | 版本线 | 聚合 | 定位 |
|---|---|---|---|
| EmakiCoreLib | 4.6.0 | 默认 | 公共基础库，所有业务模块都依赖它。 |
| EmakiAttribute | 4.6.0 | 默认 | 属性、资源、伤害、条件、PDC 属性 API。 |
| EmakiForge | 4.6.0 | 默认 | 锻造、图纸要求、材料贡献、品质和配方书。 |
| EmakiStrengthen | 4.6.0 | 默认 | 装备强化、星级阶段、保护、失败惩罚和刷新。 |
| EmakiCooking | 4.1.0 | 默认 | 世界工位式烹饪玩法。 |
| EmakiLevel | 1.4.0 | 默认 | 多等级类型、经验来源、升级需求、PDC、Placeholder 和 MythicMobs 经验 Drop。 |
| EmakiCodex | 1.0.0 | 默认 | 原版成就图鉴、成就页配置和 CoreLib 动作触发。 |
| EmakiGem | 2.6.0 | private-modules | 宝石、插槽、开孔、镶嵌、提取和升级。 |
| EmakiSkills | 2.6.0 | private-modules | 主动/被动技能、触发器、资源消耗、MythicMobs 桥接。 |
| EmakiItem | 2.6.0 | private-modules | 自定义物品、套装、触发器和自动更新。 |
| EmakiStorage | 1.0.0 | private-modules | 分页 GUI 仓库、单槽大额存量、容量档位与付费解锁。 |
private-modules是根pom.xml中定义的 profile，当根目录存在.key文件时自动激活，用于额外聚合 EmakiSkills、EmakiGem、EmakiItem 和 EmakiStorage。
除上述服务器插件外，工程还包含若干仅供编译期使用的构件：各模块的 emaki-*-api，以及纯协议模块 emaki-skills-protocol（2.6.0，持有装备技能 PDC 编解码契约）。它们都不是服务器插件，不要放进 plugins/；emaki-skills-protocol 由 CoreLib、Item、Skills、Forge、Gem、Strengthen 在构建时嵌入并 relocate 到各自的运行时包名。
为什么需要 CoreLib
CoreLib 是 Emaki Series 的“基础设施层”。很多插件都会遇到相同问题，例如：
- 如何在 YAML 中执行奖励、提示、扣费、命令、粒子、音效？
- 如何统一打开 GUI、处理按钮点击、保护交互状态？
- 如何识别 Vanilla、MMOItems、ItemsAdder、Nexo、Oraxen、EcoItems、CraftEngine 等来源的物品？
- 如何把不同模块写入的装备状态保存到 PDC，且不互相覆盖？
- 如何把锻造、强化、宝石、物品基础信息组合成最终展示？
- 如何写条件表达式、概率、延迟动作、经济扣费？
如果每个模块都自己实现一套，最终会难以维护。CoreLib 把这些能力统一起来，业务模块只需要关注自己的玩法逻辑。
常见组合方式
只做属性和战斗
安装：
- EmakiCoreLib
- EmakiAttribute
- 可选：PlaceholderAPI、MythicMobs、MMOItems
适合：只想做 RPG 属性、伤害类型、资源状态、PAPI 展示和外部怪物技能联动。
做装备成长
安装：
- EmakiCoreLib
- EmakiAttribute
- EmakiItem
- EmakiForge
- EmakiStrengthen
- EmakiGem
适合：做一条完整装备线，例如基础装备由 Item 生成，Forge 改造品质，Strengthen 提升星级，Gem 提供插槽与宝石属性，Attribute 负责最终数值计算。
做等级成长
安装：
- EmakiCoreLib
- EmakiLevel
- 可选：PlaceholderAPI、MythicMobs、EmakiAttribute、EmakiCooking、EmakiForge
适合：制作主等级、战斗等级、采集等级、生活职业等级等多条成长线，并把经验来源接入原版事件、MythicMobs Drop 或其他 Emaki 插件的 Action。
做技能系统
安装：
- EmakiCoreLib
- EmakiSkills
- MythicMobs
- 可选：EmakiAttribute、PlaceholderAPI、EmakiItem、EmakiLevel
适合：让装备、权限、等级、配置或外部来源解锁技能，由 Skills 处理冷却、资源消耗和触发，再交给 MythicMobs 执行实际技能效果。
做生活玩法
安装：
- EmakiCoreLib
- EmakiCooking
- 可选：EmakiLevel、CraftEngine、ItemsAdder、Nexo
适合：制作砧板、炒锅、研磨机、蒸锅等世界工位，让玩家通过方块交互完成烹饪流程；如果需要厨艺/生活职业成长，可通过 EmakiLevel 或 CoreLib Action 给予经验。
做成就图鉴
安装：
- EmakiCoreLib
- EmakiCodex
- 可选：PacketEvents、PlaceholderAPI、MythicMobs
适合：用 advancements/*.yml 把玩法目标做成原版成就页，由击杀、合成、钓鱼、破坏方块等 CoreLib 共享 gameplay 事件触发节点，并在节点完成时执行 CoreLib 动作发放奖励。安装 PacketEvents 时可额外注入成就树坐标。