PlaceholderAPI 占位符

EmakiLevel 在安装 PlaceholderAPI 时注册扩展标识符 emakilevel。占位符适用于计分板、菜单、聊天格式、BossBar、ActionBar、其他插件文本模板，以及支持 PlaceholderAPI 的 GUI 插件。

如果 PlaceholderAPI 未安装，EmakiLevel 本体仍然可以正常运行，只是不会注册 %emakilevel_*% 外部占位符。

玩家等级占位符

玩家等级占位符需要有玩家上下文，例如计分板里的当前玩家、菜单拥有者或 PlaceholderAPI 请求传入的玩家。

占位符	返回值
%emakilevel_level_<type>%	当前等级。
%emakilevel_exp_<type>%	当前等级内经验。
%emakilevel_total_exp_<type>%	总经验。
%emakilevel_totalexp_<type>%	总经验，兼容无下划线写法。
%emakilevel_total_<type>%	总经验，短写法。
%emakilevel_required_exp_<type>%	升到下一级所需经验。
%emakilevel_requiredexp_<type>%	需求经验，兼容无下划线写法。
%emakilevel_required_<type>%	需求经验，短写法。
%emakilevel_progress_<type>%	当前等级进度，范围 0 到 1。
%emakilevel_progress_percent_<type>%	当前等级进度百分比，范围 0 到 100。

示例：

%emakilevel_level_main%
%emakilevel_exp_main%
%emakilevel_required_exp_main%
%emakilevel_progress_percent_main%
%emakilevel_level_combat%
%emakilevel_total_exp_mining%

如果 <type> 不存在，或者玩家数据无法加载，占位符会返回空字符串。

排行榜占位符

排行榜来自插件当前缓存的玩家等级数据。在线玩家和已加载过的数据会出现在缓存中；它不是数据库级全服离线扫描排行榜。

占位符	返回值
%emakilevel_top_<type>_<rank>_name%	指定名次的玩家名。
%emakilevel_top_<type>_<rank>_level%	指定名次的等级。
%emakilevel_top_<type>_<rank>_total_exp%	指定名次的总经验。
%emakilevel_top_<type>_<rank>_totalexp%	总经验，兼容无下划线写法。
%emakilevel_top_<type>_<rank>_total%	总经验，短写法。

示例：

%emakilevel_top_main_1_name%
%emakilevel_top_main_1_level%
%emakilevel_top_main_1_total_exp%
%emakilevel_top_combat_3_name%

排行榜占位符解析格式固定为 top_<type>_<rank>_<field>。默认类型 ID 都不包含下划线；如果你自定义了包含下划线的类型 ID，玩家等级占位符可以正常解析，但排行榜占位符建议改用不含下划线的类型 ID，以避免歧义。

数值格式

EmakiLevel 会把数值格式化为适合展示的字符串：

• 整数值输出整数，例如 120。
• 非整数值保留两位小数，例如 12.50。
• progress 是 0 到 1 的小数。
• progress_percent 是 0 到 100 的百分比数值，但不会自动附带 % 符号。

示例计分板文本：

主等级: Lv.%emakilevel_level_main%
主经验: %emakilevel_exp_main%/%emakilevel_required_exp_main%
进度: %emakilevel_progress_percent_main%%
战斗等级: Lv.%emakilevel_level_combat%
排行榜第一: %emakilevel_top_main_1_name% Lv.%emakilevel_top_main_1_level%

%emakilevel_progress_percent_main%% 中第一个 %emakilevel_progress_percent_main% 是占位符，最后一个 % 是显示给玩家看的百分号。

常见用法

菜单 Lore

lore:
  - "<gray>主等级: <yellow>Lv.%emakilevel_level_main%</yellow>"
  - "<gray>经验: <green>%emakilevel_exp_main%</green>/<green>%emakilevel_required_exp_main%</green>"
  - "<gray>进度: <aqua>%emakilevel_progress_percent_main%%</aqua>"

条件插件

%emakilevel_level_combat% >= 20
%emakilevel_progress_percent_mining% >= 75

聊天/称号展示

[Lv.%emakilevel_level_main%] %player_name%: %message%

与内部动作变量的区别

PlaceholderAPI 占位符是给外部插件读取的 %emakilevel_*% 变量。EmakiLevel 自己在 types/<type>.yml > upgrade.actions.* 中提供的是动作上下文变量，例如 %level%、%new_level%、%amount%、%failure_reason%。两者写法都使用 %key% 风格，但作用域不同。

升级动作变量详见 配置详解。