- 版权类型
- 转载
- 插件中文名
- EmakiLevel | 多轨升级、经验来源与分层缩放
- 插件英文名
- EmakiLevel
- 支持的核心 [服务端]
- Folia
- 语言支持
- 中文(简体)
- 适配Minecraft版本 [Java]
- 1.5
[MD]
# EmakiLevel | 多轨升级、经验来源与分层缩放
EmakiLevel 将长期成长进度与原版经验系统彻底分离。一条主等级加上十余条职业等级各自独立成长，由大量游戏内行为驱动，升级要求通过六优先级分层系统解析，可在全局、权限组、类型或精确等级四个粒度自由调校曲线。等级可向 EmakiAttribute 贡献属性、对外暴露排行榜、同步至 PDC，并与 MythicMobs 联动——全部由 YAML 配置驱动。
所有内容均可自定义：添加、删除、重命名或禁用等级类型；将任意游戏行为路由至任意等级；控制每种类型是自动升级还是需要手动命令触发；设定每次升级的花费与奖励。玩家数据按 UUID 独立存储，新增类型会在下次加载时自动回填。
## 核心亮点
- **13 种内置等级类型** — 主等级，加上战斗、采矿、伐木、采集、农耕、钓鱼、驯养、合成、酿造、冶炼、烹饪与锻造，每种类型拥有独立上限、需求组、自动/手动升级策略及属性贡献配置。
- **九种经验触发器** — 击杀生物、击杀 MythicMobs 生物、破坏方块、收获农作物、钓鱼、合成物品、完成酿造、取出熔炉产物、驯服生物，每种触发器支持匹配字段与经验公式。
- **六级分层缩放** — 需求解析遵循严格优先级链：类型精确值 → 类型公式 → 组精确值 → 组公式 → 全局精确值 → 全局公式。
- **自动与手动升级** — 每种类型独立配置自动升级和手动升级开关，并设有自动升级步数上限，防止单次大量经验触发无限循环。
- **升级花费与奖励** — 可选的经济货币消耗与材料消耗（支持公式），以及按等级匹配的物品奖励（全部 / 单个 / 列表 / 区间），并处理给予或掉落逻辑。
- **属性贡献** — 每种类型可通过按等级公式向 EmakiAttribute 贡献属性，等级变动时自动刷新；未安装 Attribute 插件时自动跳过。
- **排行榜与占位符** — 每种类型拥有独立排行榜，并提供完整的玩家与排名占位符集合。
- **MythicMobs 联动** — 按怪物 ID 配置击杀经验，以及带独立公式的自定义非物理经验掉落。
---
## 功能详解
### 等级类型
每种类型对应一个独立的 YAML 文件，包含 id、enabled、显示名称、描述、主类型标识、起始/最大等级、需求、升级策略、PDC 同步开关与属性贡献配置。
13 种默认类型：
| 类型 | 等级上限 | 说明 |
|---|---|---|
| main | 100 | 主等级，贡献战斗力 |
| combat | 80 | 战斗，贡献物理攻击与暴击率 |
| mining | 60 | 采矿，默认手动升级 |
| logging | 60 | 伐木 |
| gathering | 60 | 采集 |
| farming | 60 | 农耕 |
| fishing | 60 | 钓鱼 |
| taming | 60 | 驯养 |
| crafting | 60 | 合成 |
| brewing | 60 | 酿造 |
| smelting | 60 | 冶炼 |
| cooking | 60 | 烹饪（预留钩子） |
| forging | 60 | 锻造（预留钩子） |
类型可以自由添加、删除、禁用或重命名，但命令、占位符、来源与行为配置中引用的 type id 必须保持一致。
---
### 经验来源与九种触发器
来源文件涵盖战斗、MythicMobs、方块操作（采矿 / 伐木 / 采集 / 农耕）、钓鱼、合成、酿造、冶炼与驯养。
九种触发器：
| 触发器 | 说明 |
|---|---|
| entity kill | 击杀生物，支持最终伤害者与最后命中者归因 |
| MythicMob kill | 按怪物 ID 击杀 MythicMobs 生物 |
| block break | 破坏方块 |
| crop harvest | 收获农作物 |
| player fish | 钓鱼，按钓鱼状态匹配 |
| item craft | 合成物品，按产物来源匹配 |
| brew complete | 完成酿造，归因最后操作玩家 |
| furnace extract | 取出熔炉产物，按产物来源匹配 |
| entity tame | 驯服生物，仅限玩家 |
每条来源规则包含 enabled、type、trigger、include-players、防滥用开关、有序规则列表（首条匹配优先）和经验公式；匹配字段留空表示不限制。
---
### 分层升级需求
需求按六级优先级解析（精确值优先于公式）：
1. 类型精确值
2. 类型公式
3. 组精确值
4. 组公式
5. 全局精确值
6. 全局公式
内置默认组：`global`、`main`、`profession`、`crafting_profession`，每组均可配置公式与精确值。
公式变量包括当前等级、目标等级、最大等级、当前经验与累计经验。可通过 debug 命令查看某条需求实际由哪一层解析。
---
### 自动与手动升级
每种类型独立配置三个开关：`enabled`、`auto-upgrade`、`manual-upgrade`。
- **自动升级**：获得经验后连锁触发升级，受自动升级步数上限约束。
- **手动升级**：通过命令触发，受 `manual-upgrade` 开关控制。
升级流程：累加经验与累计经验 → 触发获得经验行为 → 循环检查所需经验 / 最大等级 / 升级策略 / 经济消耗 / 材料消耗 → 触发成功或失败行为 → 同步 PDC 并刷新属性。
达到最大等级后，累计经验可继续累积，当前等级内经验不再增加。
---
### 升级花费与奖励
**经济花费**（启用时）：提供商（auto / vault / excellenteconomy）、货币类型、基础花费与花费公式。
**材料花费**：物品来源按顺序消耗、基础数量与数量公式。
**物品奖励**：按等级匹配（all / single / list / range），并处理给予背包或掉落至地面的逻辑。
---
### 升级行为（Actions）
获得经验、升级成功、升级失败三个钩子均可执行 CoreLib 行为，上下文包含类型、等级、经验、累计经验、进度与触发原因，支持概率触发、动作栏消息、聊天消息、全服广播与音效。
---
### 排行榜
每种类型提供独立排行榜命令，从当前缓存中取出按累计经验排序的顶级玩家列表。排行榜占位符可读取指定名次玩家的名称、等级与累计经验。
---
### 属性贡献
全局配置提供商 ID 以开启功能；每种类型的 `attributes` 块将属性 ID 映射至公式。在线玩家的贡献在等级变动时刷新；未安装 EmakiAttribute 时自动跳过，不影响其他功能。
---
### PDC 同步与数据存储
PDC 同步支持按事件独立开启（加入服务器 / 经验变动 / 等级变动 / 重载），写入每种类型的等级、经验、累计经验、所需经验与进度。
每位玩家拥有一个按 UUID 命名的数据文件，包含 schema 版本字段；新增类型在下次加载时自动回填；数据在玩家退出或服务器关闭时保存。
---
### 防滥用与 MythicMobs
**防滥用**：追踪玩家放置的方块（先放后破默认不给经验）及最后伤害者（击杀归因在超时前对间接击杀同样有效）。
**MythicMobs**：按怪物 ID 配置击杀经验，以及带独立公式的自定义非物理经验掉落；目标必须解析为玩家。
---
### API、行为与 Web 控制台
- **静态 API 外观类** `EmakiLevelApi`：读取/修改等级与经验，并执行升级操作，返回含成功标志和原因的结果对象。
- **CoreLib 行为**：按类型添加/设置/移除经验与等级，支持目标、原因、自动升级与静默选项。
- **Web 控制台**：提供对配置、需求、类型、来源、GUI 与语言文件的结构化编辑。
---
## 命令
主命令 /emakilevel，别名 /elv、/elevel。
| 命令 | 说明 |
|---|---|
| /elv | 查看所有等级类型 |
| /elv info [type] | 查看某等级类型的详细信息 |
| /elv levelup [type] | 手动升级（别名 up） |
| /elv top [type] | 查看某类型的排行榜 |
| /elv giveexp\|takeexp\|setexp \<player\> \<type\> \<amount\> | 管理经验（管理员） |
| /elv addlevel\|takelevel\|setlevel \<player\> \<type\> \<value\> | 管理等级（管理员） |
| /elv reset \<player\> [type] | 重置数据（管理员） |
| /elv reload | 重载配置 |
| /elv debug requirement \<type\> \<level\> / debug pdc \<player\> | 调试需求解析 / PDC 数据 |
---
## 权限
| 权限节点 | 说明 | 默认 |
|---|---|---|
| emakilevel.use | 基础命令 | 所有玩家 |
| emakilevel.levelup | 手动升级 | 所有玩家 |
| emakilevel.top | 查看排行榜 | 所有玩家 |
| emakilevel.reload | 重载配置 | OP |
| emakilevel.debug | 调试命令 | OP |
| emakilevel.admin | 管理员命令 | OP |
---
## PlaceholderAPI
扩展标识符：`emakilevel`
**玩家占位符**（`<type>` 替换为类型 id）：
| 占位符 | 内容 |
|---|---|
| `%emakilevel_level_<type>%` | 当前等级 |
| `%emakilevel_exp_<type>%` | 当前经验 |
| `%emakilevel_total_exp_<type>%` | 累计经验 |
| `%emakilevel_required_exp_<type>%` | 升级所需经验 |
| `%emakilevel_progress_<type>%` | 进度（0–1） |
| `%emakilevel_progress_percent_<type>%` | 进度百分比（0–100） |
**排行榜占位符**（`<type>` 为类型 id，`<rank>` 为名次）：
| 占位符 | 内容 |
|---|---|
| `%emakilevel_top_<type>_<rank>_name%` | 该名次玩家名称 |
| `%emakilevel_top_<type>_<rank>_level%` | 该名次玩家等级 |
| `%emakilevel_top_<type>_<rank>_total_exp%` | 该名次玩家累计经验 |
整数值输出为整数，非整数保留两位小数。
---
## 兼容性与依赖
| 项目 | 要求 |
|---|---|
| Java | 25 |
| Bukkit API | 1.21 |
| 服务端 | Spigot / Paper 及下游分支 |
| Folia | 支持 |
| 必须依赖 | EmakiCoreLib |
| 可选依赖 | MythicMobs、EmakiAttribute、EmakiCooking、EmakiForge、PlaceholderAPI |
---
## 安装与快速上手
1. 先安装 EmakiCoreLib.jar（必须依赖）。
2. 将 EmakiLevel.jar 放入 `plugins/` 目录。
3. 启动服务器，自动生成默认等级类型、经验来源、升级需求与 GUI 配置文件。
4. 按需配置类型 / 来源 / 缩放 / 奖励，然后执行 /elv reload，并通过 /elv debug requirement 验证需求解析结果。
---
## 相关链接
[Documentation](https://jiuwu02.github.io/Emaki_Series/) | [Discord](https://discord.gg/FV4GFQbvCM) | [QQ Group](https://qm.qq.com/q/GqGrzHp0wU)
[/MD]
# EmakiLevel | 多轨升级、经验来源与分层缩放
EmakiLevel 将长期成长进度与原版经验系统彻底分离。一条主等级加上十余条职业等级各自独立成长，由大量游戏内行为驱动，升级要求通过六优先级分层系统解析，可在全局、权限组、类型或精确等级四个粒度自由调校曲线。等级可向 EmakiAttribute 贡献属性、对外暴露排行榜、同步至 PDC，并与 MythicMobs 联动——全部由 YAML 配置驱动。
所有内容均可自定义：添加、删除、重命名或禁用等级类型；将任意游戏行为路由至任意等级；控制每种类型是自动升级还是需要手动命令触发；设定每次升级的花费与奖励。玩家数据按 UUID 独立存储，新增类型会在下次加载时自动回填。
## 核心亮点
- **13 种内置等级类型** — 主等级，加上战斗、采矿、伐木、采集、农耕、钓鱼、驯养、合成、酿造、冶炼、烹饪与锻造，每种类型拥有独立上限、需求组、自动/手动升级策略及属性贡献配置。
- **九种经验触发器** — 击杀生物、击杀 MythicMobs 生物、破坏方块、收获农作物、钓鱼、合成物品、完成酿造、取出熔炉产物、驯服生物，每种触发器支持匹配字段与经验公式。
- **六级分层缩放** — 需求解析遵循严格优先级链：类型精确值 → 类型公式 → 组精确值 → 组公式 → 全局精确值 → 全局公式。
- **自动与手动升级** — 每种类型独立配置自动升级和手动升级开关，并设有自动升级步数上限，防止单次大量经验触发无限循环。
- **升级花费与奖励** — 可选的经济货币消耗与材料消耗（支持公式），以及按等级匹配的物品奖励（全部 / 单个 / 列表 / 区间），并处理给予或掉落逻辑。
- **属性贡献** — 每种类型可通过按等级公式向 EmakiAttribute 贡献属性，等级变动时自动刷新；未安装 Attribute 插件时自动跳过。
- **排行榜与占位符** — 每种类型拥有独立排行榜，并提供完整的玩家与排名占位符集合。
- **MythicMobs 联动** — 按怪物 ID 配置击杀经验，以及带独立公式的自定义非物理经验掉落。
---
## 功能详解
### 等级类型
每种类型对应一个独立的 YAML 文件，包含 id、enabled、显示名称、描述、主类型标识、起始/最大等级、需求、升级策略、PDC 同步开关与属性贡献配置。
13 种默认类型：
| 类型 | 等级上限 | 说明 |
|---|---|---|
| main | 100 | 主等级，贡献战斗力 |
| combat | 80 | 战斗，贡献物理攻击与暴击率 |
| mining | 60 | 采矿，默认手动升级 |
| logging | 60 | 伐木 |
| gathering | 60 | 采集 |
| farming | 60 | 农耕 |
| fishing | 60 | 钓鱼 |
| taming | 60 | 驯养 |
| crafting | 60 | 合成 |
| brewing | 60 | 酿造 |
| smelting | 60 | 冶炼 |
| cooking | 60 | 烹饪（预留钩子） |
| forging | 60 | 锻造（预留钩子） |
类型可以自由添加、删除、禁用或重命名，但命令、占位符、来源与行为配置中引用的 type id 必须保持一致。
---
### 经验来源与九种触发器
来源文件涵盖战斗、MythicMobs、方块操作（采矿 / 伐木 / 采集 / 农耕）、钓鱼、合成、酿造、冶炼与驯养。
九种触发器：
| 触发器 | 说明 |
|---|---|
| entity kill | 击杀生物，支持最终伤害者与最后命中者归因 |
| MythicMob kill | 按怪物 ID 击杀 MythicMobs 生物 |
| block break | 破坏方块 |
| crop harvest | 收获农作物 |
| player fish | 钓鱼，按钓鱼状态匹配 |
| item craft | 合成物品，按产物来源匹配 |
| brew complete | 完成酿造，归因最后操作玩家 |
| furnace extract | 取出熔炉产物，按产物来源匹配 |
| entity tame | 驯服生物，仅限玩家 |
每条来源规则包含 enabled、type、trigger、include-players、防滥用开关、有序规则列表（首条匹配优先）和经验公式；匹配字段留空表示不限制。
---
### 分层升级需求
需求按六级优先级解析（精确值优先于公式）：
1. 类型精确值
2. 类型公式
3. 组精确值
4. 组公式
5. 全局精确值
6. 全局公式
内置默认组：`global`、`main`、`profession`、`crafting_profession`，每组均可配置公式与精确值。
公式变量包括当前等级、目标等级、最大等级、当前经验与累计经验。可通过 debug 命令查看某条需求实际由哪一层解析。
---
### 自动与手动升级
每种类型独立配置三个开关：`enabled`、`auto-upgrade`、`manual-upgrade`。
- **自动升级**：获得经验后连锁触发升级，受自动升级步数上限约束。
- **手动升级**：通过命令触发，受 `manual-upgrade` 开关控制。
升级流程：累加经验与累计经验 → 触发获得经验行为 → 循环检查所需经验 / 最大等级 / 升级策略 / 经济消耗 / 材料消耗 → 触发成功或失败行为 → 同步 PDC 并刷新属性。
达到最大等级后，累计经验可继续累积，当前等级内经验不再增加。
---
### 升级花费与奖励
**经济花费**（启用时）：提供商（auto / vault / excellenteconomy）、货币类型、基础花费与花费公式。
**材料花费**：物品来源按顺序消耗、基础数量与数量公式。
**物品奖励**：按等级匹配（all / single / list / range），并处理给予背包或掉落至地面的逻辑。
---
### 升级行为（Actions）
获得经验、升级成功、升级失败三个钩子均可执行 CoreLib 行为，上下文包含类型、等级、经验、累计经验、进度与触发原因，支持概率触发、动作栏消息、聊天消息、全服广播与音效。
---
### 排行榜
每种类型提供独立排行榜命令，从当前缓存中取出按累计经验排序的顶级玩家列表。排行榜占位符可读取指定名次玩家的名称、等级与累计经验。
---
### 属性贡献
全局配置提供商 ID 以开启功能；每种类型的 `attributes` 块将属性 ID 映射至公式。在线玩家的贡献在等级变动时刷新；未安装 EmakiAttribute 时自动跳过，不影响其他功能。
---
### PDC 同步与数据存储
PDC 同步支持按事件独立开启（加入服务器 / 经验变动 / 等级变动 / 重载），写入每种类型的等级、经验、累计经验、所需经验与进度。
每位玩家拥有一个按 UUID 命名的数据文件，包含 schema 版本字段；新增类型在下次加载时自动回填；数据在玩家退出或服务器关闭时保存。
---
### 防滥用与 MythicMobs
**防滥用**：追踪玩家放置的方块（先放后破默认不给经验）及最后伤害者（击杀归因在超时前对间接击杀同样有效）。
**MythicMobs**：按怪物 ID 配置击杀经验，以及带独立公式的自定义非物理经验掉落；目标必须解析为玩家。
---
### API、行为与 Web 控制台
- **静态 API 外观类** `EmakiLevelApi`：读取/修改等级与经验，并执行升级操作，返回含成功标志和原因的结果对象。
- **CoreLib 行为**：按类型添加/设置/移除经验与等级，支持目标、原因、自动升级与静默选项。
- **Web 控制台**：提供对配置、需求、类型、来源、GUI 与语言文件的结构化编辑。
---
## 命令
主命令 /emakilevel，别名 /elv、/elevel。
| 命令 | 说明 |
|---|---|
| /elv | 查看所有等级类型 |
| /elv info [type] | 查看某等级类型的详细信息 |
| /elv levelup [type] | 手动升级（别名 up） |
| /elv top [type] | 查看某类型的排行榜 |
| /elv giveexp\|takeexp\|setexp \<player\> \<type\> \<amount\> | 管理经验（管理员） |
| /elv addlevel\|takelevel\|setlevel \<player\> \<type\> \<value\> | 管理等级（管理员） |
| /elv reset \<player\> [type] | 重置数据（管理员） |
| /elv reload | 重载配置 |
| /elv debug requirement \<type\> \<level\> / debug pdc \<player\> | 调试需求解析 / PDC 数据 |
---
## 权限
| 权限节点 | 说明 | 默认 |
|---|---|---|
| emakilevel.use | 基础命令 | 所有玩家 |
| emakilevel.levelup | 手动升级 | 所有玩家 |
| emakilevel.top | 查看排行榜 | 所有玩家 |
| emakilevel.reload | 重载配置 | OP |
| emakilevel.debug | 调试命令 | OP |
| emakilevel.admin | 管理员命令 | OP |
---
## PlaceholderAPI
扩展标识符：`emakilevel`
**玩家占位符**（`<type>` 替换为类型 id）：
| 占位符 | 内容 |
|---|---|
| `%emakilevel_level_<type>%` | 当前等级 |
| `%emakilevel_exp_<type>%` | 当前经验 |
| `%emakilevel_total_exp_<type>%` | 累计经验 |
| `%emakilevel_required_exp_<type>%` | 升级所需经验 |
| `%emakilevel_progress_<type>%` | 进度（0–1） |
| `%emakilevel_progress_percent_<type>%` | 进度百分比（0–100） |
**排行榜占位符**（`<type>` 为类型 id，`<rank>` 为名次）：
| 占位符 | 内容 |
|---|---|
| `%emakilevel_top_<type>_<rank>_name%` | 该名次玩家名称 |
| `%emakilevel_top_<type>_<rank>_level%` | 该名次玩家等级 |
| `%emakilevel_top_<type>_<rank>_total_exp%` | 该名次玩家累计经验 |
整数值输出为整数，非整数保留两位小数。
---
## 兼容性与依赖
| 项目 | 要求 |
|---|---|
| Java | 25 |
| Bukkit API | 1.21 |
| 服务端 | Spigot / Paper 及下游分支 |
| Folia | 支持 |
| 必须依赖 | EmakiCoreLib |
| 可选依赖 | MythicMobs、EmakiAttribute、EmakiCooking、EmakiForge、PlaceholderAPI |
---
## 安装与快速上手
1. 先安装 EmakiCoreLib.jar（必须依赖）。
2. 将 EmakiLevel.jar 放入 `plugins/` 目录。
3. 启动服务器，自动生成默认等级类型、经验来源、升级需求与 GUI 配置文件。
4. 按需配置类型 / 来源 / 缩放 / 奖励，然后执行 /elv reload，并通过 /elv debug requirement 验证需求解析结果。
---
## 相关链接
[Documentation](https://jiuwu02.github.io/Emaki_Series/) | [Discord](https://discord.gg/FV4GFQbvCM) | [QQ Group](https://qm.qq.com/q/GqGrzHp0wU)
[/MD]