EmakiLevel

EmakiLevel 是 Emaki 系列的等级与多经验类型插件。它负责把长期成长从原版经验中独立出来，管理主等级、战斗、挖矿、钓鱼、合成、炼药、冶炼、驯养等多个成长线，并把经验来源、升级需求、升级奖励、属性贡献、PlaceholderAPI、CoreLib Action 和 MythicMobs Drop 统一到一个插件中。

模块信息

项目	当前值
模块版本	`1.4.0`
插件本体	`EmakiLevel-1.4.0.jar`
开发者 API	`emaki-level-api-1.4.0.jar`
主类	`emaki.jiuwu.craft.level.EmakiLevelPlugin`
主命令	`/emakilevel`
别名	`/elv`、`/elevel`
硬依赖	`EmakiCoreLib`
软依赖	`MythicMobs`、`EmakiAttribute`、`EmakiCooking`、`EmakiForge`、`PlaceholderAPI`
主要权限	`emakilevel.use`（默认 true）、`emakilevel.levelup`（true）、`emakilevel.top`（true）、`emakilevel.reload`（op）、`emakilevel.debug`（op）、`emakilevel.admin`（op）
数据存储	`plugins/EmakiLevel/data/<uuid>.yml`
Java / 平台	编译基线 Java 25；`api-version: 1.21.8`；`folia-supported: true`

安装方式

服务器只需要安装运行时插件本体：

text

plugins/
├─ EmakiCoreLib-*.jar
└─ EmakiLevel-1.4.0.jar

不要把 emaki-level-api-*.jar 放进服务器 plugins/ 目录。API Jar 只给第三方开发者作为 Maven provided 或 Gradle compileOnly 编译依赖使用；EmakiLevel 插件本体在打包时已经 shade 了自己的 API。

可选插件按需安装：

可选插件	安装后启用的能力
PlaceholderAPI	注册 `%emakilevel_*%` 占位符。
MythicMobs	读取 MythicMob 击杀来源，并注册 `emakilevel_exp` / `elv_exp` 非实物 Drop。
EmakiAttribute	把等级类型中的 `attributes.values` 转为 Attribute 属性贡献。
EmakiCooking / EmakiForge	可通过 CoreLib Action 在配方、工艺或流程结果中给玩家等级经验。

核心能力

多等级类型：每个 types/*.yml 文件定义一个等级类型，默认包含 main、combat、mining、fishing、crafting、brewing、smelting、taming 等类型。
独立玩家数据：每名玩家一个 YAML 数据文件，保存每个等级类型的 level、exp、total_exp 与更新时间。
分层升级需求：升级所需经验按“类型覆写 → 分组 → 全局”的顺序解析，既支持精确等级值，也支持公式。
自动/手动升级：类型可以独立控制自动升级、手动 /elv levelup、经济消耗、材料消耗、升级奖励和升级动作。
经验来源监听：支持原版击杀、MythicMobs 击杀、方块破坏、成熟作物收获、钓鱼、合成、炼药、冶炼提取和驯养。
防刷机制：可记录玩家放置方块，避免“放置再破坏”刷经验；战斗来源可记录最近造成伤害的玩家。
CoreLib Action：其他 Emaki 插件、脚本或第三方系统可以通过动作增减经验或等级。
PDC 同步：在线玩家实体会同步当前等级、经验、总经验、需求经验和进度，方便其他插件读取。
属性贡献：安装 EmakiAttribute 后，可把等级公式计算出的数值注册为属性贡献。

默认配置目录

首次启动会通过 CoreLib Bootstrap 释放默认资源。运行目录结构如下：

text

plugins/EmakiLevel/
├─ config.yml                 # 主配置：语言、PDC、属性桥接、MythicMobs、防刷、GUI
├─ requirements.yml           # 升级经验需求：全局、分组、精确等级值和公式
├─ types/                     # 等级类型定义
│  ├─ main.yml
│  ├─ combat.yml
│  ├─ mining.yml
│  └─ ...
├─ sources/                   # 经验来源规则
│  ├─ combat.yml
│  ├─ block_actions.yml
│  ├─ mythicmobs.yml
│  └─ ...
├─ gui/
│  ├─ level_gui.yml           # 默认等级 GUI 模板
│  └─ top_gui.yml             # 默认排行榜 GUI 模板
├─ lang/
│  ├─ zh_CN.yml
│  └─ en_US.yml
└─ data/
   └─ <uuid>.yml              # 玩家等级数据

config.yml 中的 release_default_data: true 用于控制缺失默认数据文件时是否释放内置 requirements.yml、types/、sources/ 和 gui/ 文件。服主已经自定义过的文件不会因为普通重启而被直接覆盖。

默认等级类型

类型 ID	显示用途	最高等级	需求分组	默认升级模式	默认属性贡献
`main`	主等级 / 总成长	100	`main`	自动 + 手动	`attribute_power = %level% * 0.5`
`combat`	原版与 MythicMobs 战斗	80	`combat`	自动 + 手动	`physical_attack`、`physical_crit_rate`
`mining`	挖矿	60	`mining`	手动，默认不自动	`mining_power = %level% * 0.2`
`logging`	砍伐原木	60	`logging`	自动 + 手动	默认关闭
`gathering`	采集植物/杂物	60	`gathering`	自动 + 手动	默认关闭
`farming`	成熟作物收获	60	`farming`	自动 + 手动	默认关闭
`fishing`	钓鱼	60	`fishing`	自动 + 手动	默认关闭
`taming`	驯养实体	60	`taming`	自动 + 手动	默认关闭
`crafting`	合成物品	60	`crafting`	自动 + 手动	默认关闭
`brewing`	炼药台完成炼药	60	`brewing`	自动 + 手动	默认关闭
`smelting`	熔炉提取产物	60	`smelting`	自动 + 手动	默认关闭
`cooking`	给烹饪玩法预留	60	`cooking`	自动 + 手动	默认关闭
`forging`	给锻造玩法预留	60	`forging`	自动 + 手动	默认关闭

默认类型只是示例和开箱模板。你可以新增、删除、禁用或改名 types/*.yml 中的类型，但命令、Placeholder、来源规则和 Action 中引用的 type 必须保持一致。

基础工作流

安装并启动 EmakiCoreLib 与 EmakiLevel。
查看 plugins/EmakiLevel/types/，确认需要保留哪些等级类型。
在 requirements.yml 中设置主线和职业等级的经验曲线。
在 sources/*.yml 中配置哪些行为给予哪些类型的经验。
如果需要手动升级消耗，编辑对应 types/<type>.yml > upgrade.cost。
如果安装了 EmakiAttribute，在 types/<type>.yml > attributes.values 中配置等级属性公式。
执行 /elv reload 重载配置。
使用 /elv info、/elv debug requirement <type> <level> 和 PlaceholderAPI 检查结果。

数据与升级行为概览

玩家数据示例：

yaml

schema_version: 1
uuid: "00000000-0000-0000-0000-000000000000"
name: "PlayerName"
levels:
  main:
    level: 1
    exp: 0.0
    total_exp: 0.0
    updated_at: 1730000000000

升级时，插件会按如下顺序处理：

找到等级类型并确认启用。
增加当前等级经验 exp 和总经验 total_exp。
执行 upgrade.actions.gain。
如果允许自动升级，按 level.max_auto_upgrade_steps 限制循环尝试升级。
每次升级检查需求经验、最高等级、手动/自动开关、经济消耗和材料消耗。
升级成功后扣除需求经验、提升等级、发放奖励、执行 upgrade.actions.success。
升级失败时执行 upgrade.actions.failure，并把 failure_reason 放入动作上下文。
同步 PDC，并在 EmakiAttribute 可用时刷新属性贡献。

文档入口

命令与权限：玩家和管理员命令、权限节点、示例。
PlaceholderAPI 占位符：所有 %emakilevel_*% 变量和排行榜占位符。
配置详解：主配置、等级类型、需求曲线、升级消耗、PDC 与属性贡献。
经验来源：sources/*.yml 触发器、匹配字段、公式变量和防刷行为。
MythicMobs 集成：MythicMob 击杀经验与自定义 Drop。
CoreLib 动作：EmakiLevel 注册到 CoreLib ActionRegistry 的动作与参数。
API 与集成：开发者 API、CoreLib Action、静态门面与 Provider 接入。
事件 API：emaki.jiuwu.craft.level.api.event 中的 Bukkit 事件与可取消性。
JavaScript 脚本：emaki.module("level") 门面、经验规则与升级钩子。

EmakiLevel ​

模块信息 ​

安装方式 ​

核心能力 ​

默认配置目录 ​

默认等级类型 ​

基础工作流 ​

数据与升级行为概览 ​

文档入口 ​