插件变量

LyPlaceholder 会向 PlaceholderAPI 注册标识为 lybl 的变量扩展，用于读取玩家变量、服务器变量和刷新规则倒计时。

本页中的变量只有在服务器安装并正常启用 PlaceholderAPI 后才能解析。未安装 PlaceholderAPI 不会影响 LyPlaceholder 保存或刷新变量，但其他插件无法通过本页格式读取变量值。

变量列表

变量	返回内容	是否需要玩家上下文
%lybl_player_变量ID%	当前玩家对应变量的值。	是
%lybl_server_变量ID%	全服共用的服务器变量值。	否
%lybl_countdown_player_规则ID%	玩家刷新规则距离下一次触发的倒计时。	否
%lybl_countdown_server_规则ID%	服务器刷新规则距离下一次触发的倒计时。	否

变量或规则不存在时返回空文本。无法识别的变量格式同样返回空文本。

PlaceholderAPI 扩展标识是 lybl，请勿使用旧格式 %lyplaceholder_...%。

玩家变量

玩家变量为每名玩家分别保存。同一个变量 ID 可以在不同玩家身上保存不同的值。

例如，先使用管理指令设置玩家变量：

/lybl set player Steve 每日积分 20

随后可在支持 PlaceholderAPI 的计分板、菜单、聊天格式或其他插件配置中读取：

%lybl_player_每日积分%

解析结果为当前玩家自己的 每日积分 值，而不是指令示例中固定玩家 Steve 的值。

玩家上下文

%lybl_player_变量ID% 必须由调用方提供玩家上下文。以下情况会返回空文本：

• 变量解析位置没有对应玩家。
• 由控制台直接解析，且调用功能没有指定玩家。
• 当前玩家不存在对应变量。
• 标识未以 player_ 开头或变量格式无法识别。

玩家数据尚未加载完成时，插件管理指令不会修改该玩家的变量。需要玩家变量的其他功能也应在玩家数据加载完成后读取。

服务器变量

服务器变量由全服共用，不区分玩家，也不依赖玩家上下文。

设置服务器变量：

/lybl set server 活动状态 开启

对应的 PlaceholderAPI 变量为：

%lybl_server_活动状态%

只要服务器变量存在，即使变量解析位置没有玩家，也可以返回对应值。

服务器变量适合保存活动状态、全服累计次数、阶段名称等全局数据。

规则倒计时

倒计时变量读取刷新规则距离下一次触发的剩余时间。刷新配置中的顶层节点名称就是规则 ID。

例如，玩家刷新配置包含以下规则：

每日积分刷新:
  trigger-time:
    - '定时:每天 00:00'
  script: |-
    设置值("每日积分", 0)

对应的玩家规则倒计时变量为：

%lybl_countdown_player_每日积分刷新%

服务器规则使用：

%lybl_countdown_server_规则ID%

规则 ID 与变量 ID

规则 ID 和脚本写入的变量 ID 是两个不同概念：

名称	来源	用途
规则 ID	刷新配置的顶层节点名称	标识刷新规则，并组成倒计时变量。
变量 ID	设置值("变量ID", 内容) 的第一个参数	标识实际保存和读取的变量。

例如：

每日积分刷新:
  trigger-time:
    - '定时:每天 00:00'
  script: |-
    设置值("每日积分", 0)
    设置值("今日任务次数", 0)

其中：

• 每日积分刷新 是规则 ID。
• 每日积分 和 今日任务次数 是变量 ID。
• 倒计时使用 %lybl_countdown_player_每日积分刷新%。
• 变量值分别使用 %lybl_player_每日积分% 和 %lybl_player_今日任务次数%。

多个触发时间

同一规则可以配置多个 trigger-time。倒计时变量会比较该规则当前运行的全部触发任务，并返回距离最近一次下一触发点的剩余时间。

活动提醒:
  trigger-time:
    - '定时:每天 12:00'
    - '定时:每天 20:00'
  script: |-
    设置值("活动提醒状态", "已刷新")

对应倒计时：

%lybl_countdown_server_活动提醒%

倒计时格式

倒计时使用中文时间单位，并省略左侧连续为零的单位。

实际剩余时间	返回示例
2 天 3 小时 5 分 8 秒	2天 3时 5分 8秒
3 小时 5 分 8 秒	3时 5分 8秒
5 分 3 秒	5分 3秒

出现以下情况时，倒计时返回空文本：

• 指定作用域中不存在该规则 ID。
• 规则配置了 enable: false，因此没有载入。
• 规则配置校验失败，未替换当前运行任务。
• 对应规则当前没有可用的触发任务。

倒计时变量不需要玩家上下文。玩家规则倒计时表示该规则任务的下一次触发时间，不会为每名玩家返回不同的倒计时。

在刷新配置中读取 PAPI

玩家刷新脚本可以通过 占位符() 读取 PlaceholderAPI 变量，并把结果写入 LyPlaceholder 玩家变量：

玩家等级快照:
  trigger-time:
    - '每隔 30m'
  script: |-
    设置值("等级快照", 数字(占位符("%player_level%")))

写入后可使用以下变量读取保存的快照：

%lybl_player_等级快照%

占位符() 需要 PlaceholderAPI 已启用，并使用当前玩家作为解析上下文。服务器刷新规则没有玩家上下文，不应在脚本中读取需要玩家的 PlaceholderAPI 变量。

如果玩家规则的 condition 使用了 papi: 条件，但 PlaceholderAPI 当前未启用，本次不会消费该玩家的刷新时间。PlaceholderAPI 恢复后，插件仍可重新检测并补偿错过的刷新。

命名限制

变量 ID 与规则 ID 只能包含以下字符：

• 中文。
• 英文字母。
• 数字。
• 下划线 _。
• 短横线 -。

同一作用域内的规则 ID 不可重复。玩家规则与服务器规则属于不同作用域，可以分别使用相同的规则 ID。

变量 ID 会在管理指令和刷新脚本写入时校验。非法变量 ID 会导致对应操作失败；刷新脚本执行时出现非法变量 ID，本次不会写入变量。

常见问题

PlaceholderAPI 未安装时变量会丢失吗？

不会。PlaceholderAPI 是变量输出和部分条件、脚本读取功能的可选依赖。未安装时，LyPlaceholder 仍会按当前存储模式保存和刷新变量，但 %lybl_...% 无法由其他插件解析。

为什么玩家变量返回空文本？

常见原因如下：

• 解析位置没有玩家上下文。
• 当前玩家没有对应变量。
• 变量 ID 与实际保存的 ID 不一致。
• PlaceholderAPI 未安装或未正常启用。
• 使用了错误的旧变量前缀。

正确格式为：

%lybl_player_变量ID%

为什么服务器变量可以正常读取，玩家变量却为空？

服务器变量不需要玩家上下文，玩家变量必须知道正在为哪名玩家解析。请确认调用变量的插件或功能能够提供玩家对象。

为什么倒计时返回空文本？

请确认：

• 使用了正确的玩家或服务器规则作用域。
• 填写的是刷新配置顶层的规则 ID，不是脚本中的变量 ID。
• 规则没有设置 enable: false。
• 刷新配置已经通过 /lybl reload 成功载入。
• 变量使用 %lybl_countdown_player_规则ID% 或 %lybl_countdown_server_规则ID% 格式。

修改变量值后需要重载吗？

不需要。通过 /lybl set、/lybl add、/lybl take 或 /lybl remove 修改变量后会直接更新运行中的数据并异步保存。

只有修改刷新规则配置后，才需要执行：

/lybl reload

MySQL 模式会改变变量格式吗？

不会。YAML、MySQL 和 Redis 只影响变量数据的读取、缓存与持久化方式，不改变 PlaceholderAPI 变量格式。

启用 MySQL 存储时，必须安装并正常启用 LyMySQLCore，并确保数据库成功连接；否则 MySQL 相关功能不会生效，变量系统也无法完成初始化。