等级 LyGalaxyLevel

MySQL 前置要求

启用 MySQL 存储时，必须安装 LyMySQLCore，并确认它已成功连接数据库。否则本插件的 MySQL 数据读取、保存、同步或相关记录不会生效。

LyGalaxyLevel 是一个支持多个独立等级节点的 Minecraft 等级系统。每个节点可以单独配置等级上限、升级经验、经验来源、每日经验上限、升级条件、升级指令、经验加成、等级称号、称号属性和经验瓶。

玩家可以通过原版经验球、普通怪物掉落、MythicMobs Drops、管理指令或 API 获取经验。等级数据支持保存到 YAML 文件或 MySQL，并可通过 PlaceholderAPI 提供等级、经验、今日经验、全服倍率和等级称号变量。

插件信息

项目	内容
插件名	`LyGalaxyLevel`
中文名	等级
插件版本	`1.1.0`
作者	离渊
主命令	`/lgl`
命令权限	`lgl.admin`
默认权限类型	OP
Bukkit 接口版本	`1.13`

支持版本

项目内提供了以下 Minecraft 服务端 NMS 适配模块：

Minecraft 版本	适配模块
1.7.10	`V1_7_R4`
1.8.8	`V1_8_R3`
1.11.2	`V1_11_R1`
1.12.2	`V1_12_R1`
1.13.2	`V1_13_R2`
1.14.4	`V1_14_R1`
1.15.2	`V1_15_R1`
1.16.5	`V1_16_R3`
1.17.1	`V1_17_R1`
1.18.2	`V1_18_R2`
1.19.2	`V1_19_R1`
1.19.4	`V1_19_R3`
1.20.1	`V1_20_R1`
1.20.2	`V1_20_R2`
1.20.3	`V1_20_R3`

项目证据未列出其它 Minecraft 版本的 NMS 适配模块。经验瓶配置说明明确标注兼容 1.7.10 和 1.12.2。

依赖与兼容

组件	用途	是否必须
`PlaceholderAPI`	解析经验公式、升级条件、经验加成变量和插件变量	使用相关功能时需要
`LyMySQLCore`	提供 MySQL 数据连接	启用 MySQL 存储时必须
`MythicMobs`	读取 MythicMobs Drops 中的 `lexp` 经验内容	使用 MythicMobs 经验时需要
`SX-Attribute`	提供 SX-Attribute 2.x 或 3.x 的等级称号属性适配	使用对应属性插件时需要
`AttributePlus`	提供等级称号属性来源	使用对应属性插件时需要
`ItemLoreOrigin`	通过虚拟物品 Lore 提供等级称号属性	使用对应属性插件时需要
`AttributeCompatibleAPI`	注册并提供兼容属性来源	使用对应属性插件时需要
`AttributeSystem`	提供等级称号属性来源	使用对应属性插件时需要

plugin.yml 中声明的软依赖为 PlaceholderAPI、LyMySQLCore、SX-Attribute、AttributePlus、ItemLoreOrigin、AttributeCompatibleAPI 和 AttributeSystem。插件会检测 MythicMobs 是否启用，并根据其主版本选择对应监听器。

启用 MySQL 后需要重启服务器。只有 LyMySQLCore 已安装并成功连接数据库时，MySQL 数据读写、跨节点数据保存和相关记录才会生效。

主要功能

功能	说明
多等级节点	每个节点拥有独立 ID、等级上限、经验公式、消息、升级指令、升级条件和经验瓶设置。
等级与经验管理	支持增加、扣除和设置指定节点的经验或等级。设置等级时当前经验归零。
经验公式	升级所需经验支持固定等级、等级区间、PlaceholderAPI 变量、`{level}` 和四则运算。
原版经验球	可为每个等级节点设置原版经验球倍率。
普通怪物经验	通过 `mobExp` 目录中的 YAML 文件按怪物 ID 或名称匹配经验。
MythicMobs 经验	支持从 MythicMobs Drops 读取 `lexp` 内容，并指定经验值和等级节点。
玩家经验加成	节点可以读取 PlaceholderAPI 变量作为玩家专属经验加成。
全服经验倍率	可为指定节点开启限时全服经验倍率。
每日经验上限	每个节点可以单独设置每日经验上限，每天零点刷新。
等级上限	可设置节点最高等级，并控制满级后是否继续获得经验。
升级条件	可以为指定等级配置多个条件，条件不满足时阻止升级并发送提示。
升级指令	支持每级执行、指定等级执行和等级区间执行的控制台指令。
等级称号	可按达到的等级匹配称号，并通过 PlaceholderAPI 返回当前称号。
称号属性	可将多个等级节点当前生效的称号属性同步到支持的属性插件。
原版经验条同步	可将指定等级节点同步到玩家原版等级和经验条。
经验瓶	可将玩家当前经验按比例转换为经验瓶。该功能由等级节点单独控制。
YAML 存储	默认使用玩家独立 YAML 文件保存等级数据。
MySQL 存储	可将玩家等级数据保存到 MySQL，但必须先安装并连接 `LyMySQLCore`。
旧数据转换	支持转换 `LyLevelPlus` 的旧版 YAML 数据或 MySQL 数据。
自动保存	支持按固定间隔保存，以及检测到玩家数据变化后进行加强型自动保存。
Debug 模式	可开关调试输出，用于查看等级和经验数据变化。

指令

所有 /lgl 管理指令使用 lgl.admin 权限。该权限在 plugin.yml 中默认授予 OP。插件指令处理还会对部分管理操作检查发送者的 OP 状态。

指令	说明
`/lgl`	当发送者为 OP 时显示指令帮助。
`/lgl reload`	重载插件配置和等级节点。
`/lgl debug`	开关 Debug 模式，默认关闭。
`/lgl addexp [玩家] [节点ID] [经验值]`	为玩家增加指定节点的经验，并应用经验加成。
`/lgl addexp [玩家] [节点ID] [经验值] -n`	为玩家增加经验，但不应用经验加成。
`/lgl takeexp [玩家] [节点ID] [经验值]`	扣除玩家指定节点的经验。
`/lgl setexp [玩家] [节点ID] [经验值]`	设置玩家指定节点的当前经验。
`/lgl addlevel [玩家] [节点ID] [等级]`	增加玩家指定节点的等级，当前经验归零。
`/lgl takelevel [玩家] [节点ID] [等级]`	扣除玩家指定节点的等级，当前经验归零。
`/lgl setlevel [玩家] [节点ID] [等级]`	设置玩家指定节点的等级，当前经验归零。
`/lgl expitem [玩家] [节点ID] [经验值] [转换率]`	抽取玩家当前经验，按转换率生成经验瓶。需要先在对应节点启用经验瓶功能。
`/lgl multiple [节点ID] [加成百分比] [持续分钟]`	开启指定节点的全服经验倍率。持续时间使用分钟，填写 `-1` 停止该节点的倍率。
`/lgl load-old-data [mysql/yaml]`	转换旧版 `LyLevelPlus` 的 MySQL 或 YAML 数据。

经验值格式

addexp、takeexp、setexp 和经验瓶相关指令支持以下经验值格式：

格式	说明
`a`	使用固定值。
`a-b`	在最小值 `a` 和最大值 `b` 之间随机取值。
`a%`	按当前经验的百分比计算。
`a-b%`	按当前经验的随机百分比计算。

经验瓶指令中的转换率范围为 1-100，表示抽取后经验瓶保留的经验比例。

数据与机制

等级节点

等级节点由独立 YAML 文件配置，节点 ID 必须全局唯一。玩家数据中会为每个节点维护以下内容：

数据	说明
`level`	当前等级，默认从 `0` 级开始。
`now-exp`	当前经验。
`today-exp`	当天已获得的经验。

节点达到 max-level 后不能继续升级。max-level-can-get-max-exp 用于控制满级后是否仍然允许获得经验；配置为 -1 时禁止满级后继续获得经验。

经验计算

节点的升级经验由 level-exp-set 决定。插件会按等级匹配单个等级或等级区间，然后依次处理 PlaceholderAPI 变量、{level} 和四则运算。

获得经验时，插件会处理以下内容：

原版经验球倍率 exp-orb。
节点专属玩家经验加成。
全服经验倍率。
exp-addition-formula 经验加成公式。
exp-formula 最终经验公式。
每日经验上限和经验增加事件。

使用 addexp 的 -n 参数时，最终经验公式中的加成按 0 计算。

每日经验上限

节点的 every-day-max-exp 控制玩家每天可以获得的有效经验数量：

设置为 -1 时不限制每日经验。
设置为非负数时，超过剩余额度的部分不会计入经验。
每日经验在每天晚上 0 点刷新。
经验增加事件调整后的有效经验仍然受每日上限限制。

全服经验倍率

/lgl multiple 可以为指定节点开启全服经验倍率。倍率值按百分比填写，并与玩家自身经验加成按照 exp-addition-formula 合并计算。

倍率开始和结束时会广播节点消息中的 MULTIPLE-EXP-START 与 MULTIPLE-EXP-END。倍率到期后自动结束；持续时间填写 -1 时停止已有倍率。全服倍率仅作用于当前运行本插件的服务器实例。

普通怪物经验

插件会监听普通怪物死亡事件，并读取 mobExp 目录中的 YAML 配置。每个怪物配置可以填写条件和多个等级节点的经验：

yaml

离渊大牛马:
  condition:
    - 'permission:{exp.离渊大牛马}'
    - 'papi:{%player_level% >= 0}'
  exp:
    default: 5
    exp2: 10

怪物经验支持固定值和随机区间。怪物 ID 与名称均可能参与匹配；如果两者相同，同一配置可能触发两次经验发放，因此应避免使用重复匹配值。

only-check-customnpc-name 用于限制怪物掉落经验的检测方式。

MythicMobs Drops 经验

启用 mythic-drops-exp-enable 后，插件支持读取 MythicMobs Drops 中的 lexp 内容：

yaml

Drops:
  - 'lexp 123-578'
  - 'lexp 789 节点ID'

lexp 支持固定经验、随机经验区间以及指定等级节点。该功能需要安装并正常启用 MythicMobs。插件会根据 MythicMobs 主版本选择对应监听器。

等级称号与属性

节点可以为不同等级配置称号文本和属性文本。玩家当前等级会匹配不高于当前等级的最高称号等级，并通过 %lgl_节点ID_tag% 返回对应称号。

当配置了 attribute-plugin 后，插件会汇总玩家所有等级节点当前生效的称号属性，并同步到选定的属性插件。支持的配置值包括：

配置值	属性适配
`AttributePlus`	AttributePlus
`SX-Attribute2`	SX-Attribute 2.x
`SX-Attribute3`	SX-Attribute 3.x
`ItemLoreOrigin`	ItemLoreOrigin 虚拟物品 Lore
`AttributeCompatibleAPI`	AttributeCompatibleAPI
`AttributeSystem`	AttributeSystem

原版经验条同步

当 sync-minecraft-exp-bra 填写有效的节点 ID 时，该节点的等级和当前经验会同步到玩家原版经验条：

原版等级显示该节点等级。
原版经验进度显示当前经验占下一级所需经验的比例。
配置为空或节点不存在时不进行同步。
anti-enchant 用于控制附魔系统对原版等级和经验的扣除处理。

经验瓶

经验瓶功能由节点配置中的 exp-item-enable 控制，项目配置说明标注该功能兼容 1.7.10 和 1.12.2。

经验瓶可以配置以下内容：

配置键	说明
`exp-item.item`	经验瓶物品类型和数据值。
`exp-item.display-name`	经验瓶显示名称。
`exp-item.lore`	经验瓶 Lore。

插件管理员可以使用 /lgl expitem 为指定玩家抽取当前经验并生成经验瓶。经验瓶会受到每日经验上限影响，玩家不能自行执行该转换操作。

数据保存

插件支持 YAML 和 MySQL 两种玩家数据存储方式：

存储方式	数据位置或组件	说明
YAML	`plugins/LyGalaxyLevel/data/<UUID>.yml`	每名玩家使用独立 YAML 文件保存。尖括号内容表示占位符。
MySQL	`LyMySQLCore`	需要启用配置并成功连接数据库，否则 MySQL 数据读写不会生效。

插件支持按固定间隔自动保存发生变动的玩家数据，也支持开启加强型自动保存。修改存储方式后需要重启服务器。

旧数据转换

/lgl load-old-data [mysql/yaml] 用于转换 LyLevelPlus 的旧数据：

参数	读取来源
`mysql`	旧版 MySQL 数据，旧表名为 `LyLevelPlus`。
`yaml`	`plugins/LyLevelPlus/playerdata/` 目录中的旧版 YAML 数据。

转换旧数据前应先备份原有数据，避免数据覆盖或转换失败造成数据丢失。

API

插件提供 LyLevelAPI 接口，供其它插件读取和修改玩家等级数据。公开方法包括：

API 方法	作用
`refreshTodayExp(Player)`	将玩家所有等级节点的今日经验清零。
`addExp(Player, String, long, String)`	为指定节点增加经验，并根据来源处理经验球倍率、经验加成和每日上限。
`takeExp(Player, String, long)`	扣除指定节点的当前经验。
`setExp(Player, String, long)`	设置指定节点的当前经验。
`setLevel(Player, String, long, boolean)`	设置指定节点的等级，当前经验归零；最后一个参数控制是否继续处理经验状态。
`getExp(Player, String)`	获取指定节点的当前经验。
`getNextExp(Player, String)`	获取指定节点升级到下一级所需的经验。
`getLevel(Player, String)`	获取指定节点的等级。
`getTodayExp(Player, String)`	获取指定节点当天已获得的经验。

插件提供以下事件：

事件	触发时机
`LyGalaxyLevelExpAddEvent`	经验增加处理过程中触发。
`LyGalaxyLevelLevelUpEvent`	玩家完成升级后触发，并包含升级前后的等级信息。

API 调用需要使用有效的玩家对象和等级节点 ID。玩家数据、等级节点或玩家节点缓存不存在时，读取类方法返回 0，修改类方法不会执行对应修改。

文档索引

页面	内容
配置说明	主配置、数据库、自动保存、经验公式、等级节点、经验瓶和消息配置。
经验来源与机制	普通怪物经验、MythicMobs Drops、经验加成、每日上限、升级条件和原版经验条同步。
插件变量	PlaceholderAPI 变量、等级称号变量和全服倍率变量。
常见问题	经验不增加、MySQL 不生效、每日上限、原版同步、属性称号和旧数据转换问题。

等级 LyGalaxyLevel ​

插件信息 ​

支持版本 ​

依赖与兼容 ​

主要功能 ​

指令 ​

经验值格式 ​

数据与机制 ​

等级节点 ​

经验计算 ​

每日经验上限 ​

全服经验倍率 ​

普通怪物经验 ​

MythicMobs Drops 经验 ​

等级称号与属性 ​

原版经验条同步 ​

经验瓶 ​

数据保存 ​

旧数据转换 ​

API ​

文档索引 ​