定时刷新

LyPlaceholder 可以按固定间隔或指定日期刷新玩家变量与服务器变量。刷新规则分别存放在以下目录：

规则类型	配置目录	作用范围
玩家规则	`plugins/LyPlaceholder/playerPlaceholderRefresh`	每名玩家独立保存和刷新
服务器规则	`plugins/LyPlaceholder/serverPlaceholderRefresh`	全服共用一份变量数据

两个目录都会递归读取子目录中的 .yml 文件，一个文件可以包含多条规则。

插件只会跳过完整文件名为 示例玩家变量刷新配置_不会启用.yml 和 示例系统变量刷新配置_不会启用.yml 的内置示例。其他 .yml 文件即使名称中包含“示例”，也会正常载入。

规则结构

刷新配置的顶层节点名称是规则 ID。实际写入的变量 ID 由 script 中的 设置值() 决定，规则 ID 与变量 ID 不需要相同。

yaml

规则ID:
  enable: true
  trigger-time:
    - '每隔 30m'
  condition: []
  script: |-
    设置值("变量ID", 0)
  message: []
  command: []

配置项	玩家规则	服务器规则	说明
`enable`	可用	可用	是否启用规则，省略时默认为 `true`
`trigger-time`	必填	必填	触发时间列表，至少填写一条
`condition`	可选	忽略	玩家刷新条件，多条条件必须全部满足
`script`	必填	必填	刷新时执行的非空脚本
`message`	可选	可选	每个变量写入后发送的消息列表
`command`	可选	可选	每个变量写入后执行的命令列表

规则 ID 和变量 ID 只能包含中文、字母、数字、下划线或短横线。变量 ID 最长为 128 个字符，规则 ID 最长为 127 个字符。

同一作用域内不能出现重复的规则 ID，包括不同文件或不同子目录中的规则。玩家规则与服务器规则属于不同作用域，可以使用相同的规则 ID。

旧版 value 配置已经移除。规则中出现 value 时会导致重载失败，必须改用脚本中的 设置值()。

玩家规则

玩家规则会为每名玩家分别读取和写入变量，可以通过 condition 限制需要执行刷新的玩家。

yaml

每日积分刷新:
  enable: true
  trigger-time:
    - '定时:每天 00:00'
  condition:
    - 'permission: lyplaceholder.daily'
  script: |-
    设置值("每日积分", 0)
  message:
    - '&a每日积分已刷新为 &f{value}'
  command: []

玩家必须在线且变量数据已经加载完成，规则才会在触发时处理该玩家。

玩家条件

condition 中的条件必须全部满足。条件类型和参数之间必须使用半角英文冒号。

格式	通过条件
`permission: 权限节点`	玩家拥有指定权限
`nopermission: 权限节点`	玩家没有指定权限
`papi: 判断表达式`	PlaceholderAPI 表达式计算结果为真

yaml

condition:
  - 'permission: lyplaceholder.example.enable'
  - 'nopermission: lyplaceholder.example.blocked'
  - 'papi: %player_level% >= 5'

papi: 条件支持比较、数学运算以及逻辑组合，例如：

yaml

condition:
  - 'papi: %player_level% >= 5 && %player_level% < 10'

玩家规则使用 PAPI 条件时，需要服务器已经启用 PlaceholderAPI。如果 PlaceholderAPI 暂时不可用，插件不会将本次触发记录为已经处理，依赖恢复后仍可重新检测和补偿。

服务器规则

服务器规则修改全服共用的服务器变量，不读取、校验或判断 condition。即使配置了 condition，也会直接忽略。

yaml

活动状态刷新:
  enable: true
  trigger-time:
    - '定时:每周 周一 09:00'
  script: |-
    设置值("活动状态", "已开启")
    全服消息("&e本周活动已经开启")
    控制台指令("say 本周活动已经开启")
  message: []
  command: []

服务器脚本没有当前玩家上下文，只能读取服务器变量旧值。不要在服务器脚本中依赖玩家 PlaceholderAPI 变量，也不要使用 玩家消息()、玩家指令() 或 OP指令()。

服务器规则脚本可以使用 全服消息() 和 控制台指令()。其中脚本只执行一次，不需要为在线玩家重复调用。

规则节点中的 message 和 command 属于刷新后的玩家动作。服务器规则执行这些列表时，会遍历全部在线玩家，并针对脚本写入的每个变量分别执行。因此需要全服只执行一次的消息或命令时，优先写在脚本中。

触发时间

trigger-time 是字符串列表，可以填写多条表达式。任意一条到达时间都会触发规则。

固定间隔

写法	说明
`每隔 30s`	每隔 30 秒
`每隔 5m`	每隔 5 分钟
`每隔 2h`	每隔 2 小时
`每隔 1d`	每隔 1 天

每隔 后必须填写正整数和小写单位：

单位	含义
`s`	秒
`m`	分钟
`h`	小时
`d`	天

指定日期

写法	说明
`定时:每天 12:00`	每天指定时间
`定时:每天 12:00:30`	每天指定时间，精确到秒
`定时:每周周一 09:00`	每周指定一天
`定时:每周周一,周三,周五 09:00`	每周指定多天
`定时:每周周一至周五 09:00`	每周指定连续日期范围
`定时:每月 3号 12:00`	每月指定一天
`定时:每月 1号,15号,最后一天 12:00`	每月指定多天或最后一天
`定时:每月 1-5号 12:00`	每月指定连续日期范围
`定时:每年 1月 1日 00:00`	每年指定日期

每天、每周、每月和每年表达式均支持 HH:mm 或 HH:mm:ss。

星期可以使用以下写法：

周一 至 周日、周天
星期一 至 星期日、星期天

列表逗号支持半角 , 和全角 ，。范围分隔符支持 ~、～、至、- 和 －。

定时: 前缀和时间中的冒号必须使用半角英文冒号。时间格式错误会使本次配置重载失败，原有刷新任务继续运行。

刷新脚本

每条规则都必须提供非空的 script 字符串，建议使用 YAML 多行文本 |-。

yaml

script: |-
  设置值("累计次数", 数字(变量值("累计次数")) + 1)
  if (数字(变量值("累计次数")) >= 10) {
    设置值("阶段", "高级")
  } else {
    设置值("阶段", "普通")
  }

脚本只通过 设置值("变量ID", 内容) 创建或更新变量。同一脚本可以写入多个变量；同一个变量被设置多次时，以最后一次设置的值为准。

脚本没有调用 设置值() 时不会修改变量。规则节点中的 message 和 command 也不会执行，因为这两类动作会针对本次脚本实际写入的变量逐个处理。

变量值() 读取的是脚本执行前的变量快照。同一脚本中先调用 设置值()，不会改变后续 变量值() 读取到的旧值。

数据函数

函数	作用
`变量值("变量ID")`	读取刷新前的变量值，不存在时返回空文本
`设置值("变量ID", 内容)`	创建或更新指定变量
`数字(内容)`	转换为数字，空文本或无法转换时得到 `0`
`字符串(内容)`	转换为文本
`占位符("%变量%")`	读取 PlaceholderAPI 变量，主要用于玩家规则
`最大值(数字1, 数字2, ...)`	返回多个数字中的最大值
`最小值(数字1, 数字2, ...)`	返回多个数字中的最小值
`绝对值(数字)`	返回数字的绝对值
`向下取整(数字)`	向下取整
`向上取整(数字)`	向上取整
`四舍五入(数字)`	四舍五入为整数

动作函数

函数	玩家规则	服务器规则	作用
`玩家消息("文本")`	可用	不执行	向当前玩家发送消息，并转换 `&` 颜色代码
`全服消息("文本")`	禁止	可用	向全部在线玩家广播消息
`玩家指令("命令")`	可用	不执行	以当前玩家身份执行命令
`OP指令("命令")`	可用	不执行	临时以当前玩家的管理员身份执行命令
`控制台指令("命令")`	可用	可用	以服务器控制台身份执行命令

命令可以带 /，执行前会自动移除开头的 /。

玩家规则脚本中使用 全服消息() 会在配置重载校验时被拒绝。服务器规则没有玩家上下文，玩家相关动作函数不会执行。

脚本动作函数与规则节点中的 message、command 会同时执行。如果不需要重复发送消息或执行命令，只使用其中一种方式。

运算与判断

脚本支持以下表达式：

类型	写法
数学运算	`+`、`-`、`*`、`/`、`%`
比较运算	`>`、`>=`、`<`、`<=`、`==`、`!=`
逻辑运算	`&&`、`\|\|`、`!`
三元表达式	`条件 ? 成立值 : 不成立值`
条件块	`if`、`else if`、`else`
列表	`[内容1, 内容2, ...]`

yaml

script: |-
  设置值("累计次数", 数字(变量值("累计次数")) + 1)
  if (数字(占位符("%player_level%")) >= 20) {
    设置值("等级奖励", 200)
    设置值("等级称号", "大师")
  } else if (数字(占位符("%player_level%")) >= 10) {
    设置值("等级奖励", 100)
    设置值("等级称号", "高级")
  } else {
    设置值("等级奖励", 50)
    设置值("等级称号", "普通")
  }

三元表达式可以直接作为变量值：

yaml

script: |-
  设置值("阶段", 数字(变量值("累计次数")) >= 10 ? "高级" : "普通")

文本方法

文本方法写在一个表达式后，例如 变量值("变量ID").长度()。

方法	作用
`长度()`	获取文本长度
`包含(内容)`	判断是否包含指定内容
`前缀判断(内容)`	判断是否以指定内容开头
`后缀判断(内容)`	判断是否以指定内容结尾
`替换(旧内容, 新内容)`	替换文本内容
`转小写()`	将英文字母转换为小写
`转大写()`	将英文字母转换为大写
`去空白()`	移除文本首尾空格
`截取(开始位置)`	从指定位置截取到末尾，位置从 `0` 开始
`截取(开始位置, 结束位置)`	截取指定范围，不包含结束位置
`等于(内容)`	判断文本是否完全相同

数字与列表方法

数据类型	可用方法
数字	`绝对值()`、`向下取整()`、`向上取整()`、`四舍五入()`
列表	`长度()`、`读取(位置)`、`包含(内容)`、`为空()`

普通表达式按行执行，可以使用分号结尾。if、else if 和 else 条件块可以跨多行。空行以及以 # 或 // 开头的行会被忽略。

消息与命令

message 和 command 会在脚本成功写入变量后执行，并针对本次写入的每个变量分别处理一次。

yaml

每月等级奖励规则:
  trigger-time:
    - '定时:每月 3号 12:00'
  condition:
    - 'papi: %player_level% >= 5'
  script: |-
    设置值("等级奖励金币", 100)
    设置值("等级奖励次数", 1)
  message:
    - '&7规则 &a{id} &7已将变量刷新为 &f{value}'
  command:
    - '[console]tell %player_name% 规则{id}已经刷新为{value}'
    - '[op]tell %player_name% 规则{id}已经刷新为{value}'
    - 'tell %player_name% 规则{id}已经刷新为{value}'

文本替换

内容	替换结果
`{id}`	当前刷新规则 ID
`{value}`	当前正在处理的变量最终值
PlaceholderAPI 变量	安装并启用 PlaceholderAPI 时按当前玩家解析
`&` 颜色代码	`message` 发送时转换为 Minecraft 颜色代码

脚本一次写入多个变量时，同一条消息或命令会按变量写入顺序执行多次，{value} 每次对应当前变量的值。

命令执行身份

写法	执行方式
`[console]命令`	服务器控制台执行
`[op]命令`	当前玩家临时取得管理员身份后执行
`命令`	当前玩家直接执行

玩家规则中的当前玩家是被刷新的玩家。服务器规则会遍历全部在线玩家执行 message 和 command，因此 [op] 和无前缀命令也会分别以每名在线玩家的身份执行。

离线补偿

玩家规则会按规则 ID 保存最后一次触发时间。玩家变量数据加载完成后，插件会检查该玩家离线期间是否错过规则触发点。

如果 (上次触发时间, 当前时间] 内存在任意触发点，会按玩家当前状态检测条件并补刷新一次。
即使离线期间错过多个触发点，同一规则本次上线也只补刷新一次。
新规则没有历史触发时间时，只会将当前时间设为初始时间，不追溯更早的触发事件。
正常触发时，条件不满足也会记录本次规则触发时间，表示该触发点已经处理。
PAPI 条件当前无法计算时，不会记录触发时间，待 PlaceholderAPI 恢复后仍可再次检测。

刷新时间按规则 ID 保存，不再为脚本写入的每个变量分别保存刷新时间。因此修改规则 ID 会被视为一条新规则。

倒计时变量

安装并启用 PlaceholderAPI 后，可以读取当前规则距离下一次触发的倒计时。

变量	返回内容
`%lybl_countdown_player_规则ID%`	玩家刷新规则下一次触发倒计时
`%lybl_countdown_server_规则ID%`	服务器刷新规则下一次触发倒计时

规则配置多个 trigger-time 时，返回距离当前最近的一次触发。不存在对应规则时返回空文本。

倒计时会省略左侧连续为零的单位，例如 0天 0时 5分 3秒 会显示为 5分 3秒。

重载与错误处理

使用以下指令重新读取全部刷新配置：

指令	权限	说明
`/lybl reload`	`lyplaceholder.admin`	校验并重载玩家规则、服务器规则和自动保存配置

重载时会校验全部已启用规则，包括规则 ID、触发时间、玩家条件和脚本格式。任何文件或规则校验失败时，本次重载失败，当前正在运行的刷新任务会继续保留。

重载成功后，插件会输出实际载入的配置文件和规则 ID。没有载入任何规则时，也会给出对应提示。

以下问题会导致重载失败：

enable 不是布尔值。
同一作用域存在重复规则 ID。
规则 ID 包含非法字符或超过长度限制。
trigger-time 缺失、为空或格式错误。
玩家 condition 前缀、冒号或判断表达式错误。
script 不是字符串、内容为空或语法错误。
配置中继续使用已经移除的 value 节点。
玩家脚本使用只允许服务器规则调用的函数。

脚本执行期间发生除零、未知函数、非法变量 ID 等错误时，本次脚本不会写入变量。该触发点仍会被记录为已经处理，控制台会输出对应规则的刷新失败信息。

定时刷新 ​

规则结构 ​

玩家规则 ​

玩家条件 ​

服务器规则 ​

触发时间 ​

固定间隔 ​

指定日期 ​

刷新脚本 ​

数据函数 ​

动作函数 ​

运算与判断 ​

文本方法 ​

数字与列表方法 ​

消息与命令 ​

文本替换 ​

命令执行身份 ​

离线补偿 ​

倒计时变量 ​

重载与错误处理 ​

定时刷新

规则结构

玩家规则

玩家条件

服务器规则

触发时间

固定间隔

指定日期

刷新脚本

数据函数

动作函数

运算与判断

文本方法

数字与列表方法

消息与命令

文本替换

命令执行身份

离线补偿

倒计时变量

重载与错误处理