配置说明

LyPlaceholder 的配置分为主配置与变量刷新规则。主配置控制自动保存、操作提示和存储连接；刷新规则分别控制玩家变量与服务器变量的定时修改。

类型	文件或目录	用途
主配置	plugins/LyPlaceholder/config.yml	自动保存、操作提示、Redis、MySQL
玩家刷新规则	plugins/LyPlaceholder/playerPlaceholderRefresh	按玩家分别执行的变量刷新规则
服务器刷新规则	plugins/LyPlaceholder/serverPlaceholderRefresh	全服共用的服务器变量刷新规则

玩家与服务器刷新目录会递归读取子目录中的 .yml 文件。执行 /lybl reload 会重新读取主配置和全部刷新规则，但 Redis、MySQL 的开关或连接参数发生变化时必须重启服务器。

主配置

默认 config.yml 内容如下：

# 自动保存仅在变量数据发生变化时异步执行，最低 10 秒。
auto-save-seconds: 60

# 变量修改指令成功后的提示。
message:
  set: '&7已将 &a{target} &7的变量 &6{id} &7设置为 &b{value}'
  add: '&7已将 &a{target} &7的变量 &6{id} &7增加 &b{amount}&7，当前值为 &b{value}'
  take: '&7已将 &a{target} &7的变量 &6{id} &7减少 &b{amount}&7，当前值为 &b{value}'
  remove: '&7已删除 &a{target} &7的变量 &6{id}'

# Redis 前置缓存。
redis:
  enable: false
  host: 127.0.0.1
  port: 6379
  username: default
  password: ''
  database: 0

# MySQL 关闭时使用 YAML 持久化。
mysql:
  enable: false
  databasename: mc2
  username: mc2
  password: mc1234
  port: 3306
  ip: 127.0.0.1

自动保存

配置项	默认值	说明
auto-save-seconds	60	检查并异步保存已发生变化的数据，单位为秒，不能小于 10。

auto-save-seconds: 60

自动保存只处理与最近一次成功保存快照不同的数据。数据没有变化时，不会写入 Redis、MySQL 或 YAML。

将该值设置为小于 10 的数字会导致配置重载失败，不会自动改为 10。重载失败时，原有刷新任务和自动保存任务继续运行。

除定时自动保存外，插件还会在以下时机保存相关变量：

• 使用管理指令修改变量后。
• 玩家退出或被踢出服务器时。
• 插件正常关闭时。

操作提示

message 控制管理指令修改变量成功后向指令发送者显示的提示。

配置项	触发操作	默认用途
message.set	set	设置玩家或服务器变量成功
message.add	add	增加数字变量成功
message.take	take	减少数字变量成功
message.remove	remove	删除变量成功

提示文本支持 & 颜色代码和以下替换内容：

内容	说明
{target}	玩家变量为玩家名，服务器变量固定为“系统”
{id}	本次操作的变量 ID
{value}	操作完成后的变量值
{amount}	add 或 take 提供的增减数量

message:
  set: '&7已将 &a{target} &7的变量 &6{id} &7设置为 &b{value}'
  add: '&7已将 &a{target} &7的变量 &6{id} &7增加 &b{amount}&7，当前值为 &b{value}'
  take: '&7已将 &a{target} &7的变量 &6{id} &7减少 &b{amount}&7，当前值为 &b{value}'
  remove: '&7已删除 &a{target} &7的变量 &6{id}'

节点留空或删除后，对应操作成功时不会发送提示。get 查询结果、错误提示和指令帮助不由这些节点控制。

修改操作提示后可以执行 /lybl reload 生效，不需要重启服务器。

存储组合

mysql.enable 决定持久化层使用 MySQL 还是本地 YAML，redis.enable 独立决定是否增加 Redis 前置缓存。

MySQL	Redis	启动读取	保存位置
关闭	关闭	YAML	YAML
开启	关闭	MySQL	MySQL
关闭	开启	同时读取 Redis 与 YAML，选择版本较新的快照	Redis 与 YAML
开启	开启	同时读取 Redis 与 MySQL，选择版本较新的快照	Redis 与 MySQL

Redis 与持久化层同时存在数据时，插件会比较快照版本并采用较新的数据。版本相同时优先采用 MySQL 或 YAML 中的数据，并使用选出的快照同步较旧的一侧。

保存时不会使用旧版本快照覆盖存储层中已经存在的更新版本。Redis 读取期间如果检测到快照版本变化，会等待后重试，避免读取到正在更新的半份数据。

切换存储方式

切换 YAML 与 MySQL 持久化方式前，需要自行迁移已有变量数据。插件不会自动把旧持久化方式中的全部历史数据迁移到新数据库。

Redis

Redis 是可选的前置缓存，可以与 YAML 或 MySQL 持久化组合使用。

redis:
  enable: false
  host: 127.0.0.1
  port: 6379
  username: default
  password: ''
  database: 0

配置项	默认值	说明
redis.enable	false	是否启用 Redis 前置缓存
redis.host	127.0.0.1	Redis 服务器地址，不能为空
redis.port	6379	Redis 端口，范围为 1 至 65535
redis.username	default	Redis ACL 用户名
redis.password	空文本	Redis 密码；为空时不设置用户名和密码认证
redis.database	0	Redis 数据库编号，不能小于 0

启用 Redis 后，插件会在初始化时建立连接并执行连通性检查。连接失败、地址为空、端口无效或数据库编号无效时，变量系统不会继续初始化。

以下 Redis 配置发生变化后必须重启服务器：

• redis.enable
• redis.host
• redis.port
• redis.username
• redis.password
• redis.database

如果修改后直接执行 /lybl reload，重载会被拒绝，原有运行配置保持不变。

MySQL

必须安装 LyMySQLCore

启用 MySQL 模式时，服务器必须安装并成功启用 LyMySQLCore，且数据库连接必须成功。只填写 MySQL 连接信息不能替代此前置插件。

mysql:
  enable: false
  databasename: mc2
  username: mc2
  password: mc1234
  port: 3306
  ip: 127.0.0.1

配置项	默认值	说明
mysql.enable	false	是否使用 MySQL 持久化；关闭时使用本地 YAML
mysql.databasename	mc2	数据库名称，需要提前创建
mysql.username	mc2	数据库登录用户名，不能为空
mysql.password	mc1234	数据库登录密码，可以为空
mysql.port	3306	MySQL 端口，范围为 1 至 65535
mysql.ip	127.0.0.1	MySQL 服务器地址，不能为空

数据库名称只能包含字母、数字、下划线或短横线。变量数据表和版本表由插件自动创建，数据库本身需要提前创建，并确保填写的用户拥有建表及读写权限。

MySQL 模式只有在 LyMySQLCore 已启用并且 LyPlaceholder 成功连接数据库后才会生效。数据库或已启用的 Redis 尚未准备完成时，插件会拒绝玩家进入，避免玩家变量在存储未就绪时被错误加载或覆盖。

以下 MySQL 配置发生变化后必须重启服务器：

• mysql.enable
• mysql.databasename
• mysql.username
• mysql.password
• mysql.port
• mysql.ip

玩家刷新规则

玩家变量刷新规则位于：

plugins/LyPlaceholder/playerPlaceholderRefresh

规则按玩家分别读取和保存。触发时会对每名在线且变量数据已经加载完成的玩家检测条件，然后执行脚本。

每日权限刷新规则:
  enable: true
  trigger-time:
    - '定时:每天 12:00'
  condition:
    - 'permission: lyplaceholder.example.enable'
    - 'nopermission: lyplaceholder.example.blocked'
  script: |-
    设置值("每日刷新状态", "每日已刷新")
  message:
    - '&7规则 &a{id} &7已经刷新变量为 &f{value}'
  command:
    - '[console]tell %player_name% 规则{id}已经刷新为{value}'

服务器刷新规则

服务器变量刷新规则位于：

plugins/LyPlaceholder/serverPlaceholderRefresh

服务器变量由整个服务器共用一份。服务器规则没有玩家脚本上下文，不读取或判断 condition，即使配置该节点也会直接忽略。

每日状态重置规则:
  enable: true
  trigger-time:
    - '定时:每天 00:00'
  script: |-
    设置值("每日重置状态", "今日已重置")
  message:
    - '&7规则 &a{id} &7已经刷新服务器变量为 &f{value}'
  command:
    - '[console]bc 规则{id}已经刷新为{value}'

刷新文件读取规则

规则	说明
文件格式	只读取扩展名为 .yml 的文件，扩展名不区分大小写
子目录	会递归读取刷新目录中的全部子目录
读取顺序	按文件绝对路径排序后读取
单文件规则数	一个文件可以包含多条顶层规则
规则 ID	顶层节点名称就是规则 ID
重复限制	同一作用域中的规则 ID 不能重复，即使位于不同文件
禁用规则	设置 enable: false；省略时默认启用
内置示例	只跳过两个完整文件名匹配的内置示例

插件只会跳过以下两个完整文件名：

• 示例玩家变量刷新配置_不会启用.yml
• 示例系统变量刷新配置_不会启用.yml

其他 .yml 文件即使名称中包含“示例”，也会正常读取和执行。

规则 ID 只能包含中文、字母、数字、下划线或短横线，长度不能超过 127 个字符。脚本中使用的变量 ID 允许相同字符，长度不能超过 128 个字符。

刷新规则配置项

每个顶层节点代表一条刷新规则。

配置项	类型	必填	说明
enable	布尔值	否	是否启用规则，省略时默认为 true
trigger-time	文本列表	是	规则触发时间，至少填写一条
condition	文本列表	否	玩家规则的触发条件；服务器规则忽略此项
script	多行文本	是	触发后执行的变量脚本，必须为非空字符串
message	文本列表	否	每个变量写入后向对应玩家发送的消息
command	文本列表	否	每个变量写入后执行的命令

旧版 value 节点已经移除。规则中出现 value 会导致重载失败，变量必须通过 script 中的 设置值() 写入。

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

触发时间

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

trigger-time:
  - '每隔 30s'
  - '每隔 5m'
  - '每隔 2h'
  - '每隔 1d'
  - '定时:每天 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'

类型	格式	说明
固定间隔	每隔 正整数s	按秒触发
固定间隔	每隔 正整数m	按分钟触发
固定间隔	每隔 正整数h	按小时触发
固定间隔	每隔 正整数d	按天触发
每天	定时:每天 HH:mm	每天指定时间触发
每周	定时:每周 星期 HH:mm	支持单日、列表或连续范围
每月	定时:每月 日期 HH:mm	支持单日、列表、范围和 最后一天
每年	定时:每年 M月 d日 HH:mm	每年指定日期和时间触发

时间支持 HH:mm 和 HH:mm:ss。定时: 以及时间中的冒号必须使用半角英文冒号。

星期支持以下写法：

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

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

触发时间格式错误会阻止配置重载，旧刷新任务继续运行。

玩家条件

condition 只对玩家变量规则生效。同一规则中的全部条件都满足后才会执行脚本。

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

条件前缀	说明
permission:	玩家必须拥有指定权限
nopermission:	玩家必须没有指定权限
papi:	使用 PlaceholderAPI 结果进行判断

条件前缀后的冒号必须使用半角英文冒号。papi: 条件支持比较、数学运算、&& 和 ||。

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

服务器规则不会读取、校验或执行 condition。

刷新脚本配置

script 必须是非空的多行字符串，建议使用 YAML 的 |- 写法。每次调用 设置值("变量ID", 内容) 都会创建或更新一个变量，一条规则可以写入多个变量。

script: |-
  设置值("累计次数", 数字(变量值("累计次数")) + 1)
  设置值("每日状态", "已刷新")

脚本没有调用 设置值() 时不会修改变量，规则节点中的 message 和 command 也不会执行。同一个变量在一段脚本中被多次设置时，以最后一次设置的值为准。

脚本支持读取当前作用域的旧变量值、数字与文本转换、数学运算、比较、逻辑运算、三元表达式、多行 if、else if、else 条件块、数组以及文本、数字和列表方法。

玩家规则可以通过 占位符() 读取当前玩家的 PlaceholderAPI 变量。服务器规则没有玩家上下文，不应调用需要玩家的占位符或玩家动作。

脚本格式会在重载时校验。脚本格式错误会使本次重载失败并保留旧任务；脚本实际执行时发生除零、未知函数或非法变量 ID 等错误，本次不会写入变量。

刷新消息

刷新规则中的 message 是文本列表。脚本每成功写入一个变量，都会为该变量依次发送列表中的消息。

message:
  - '&7规则 &a{id} &7已执行'
  - '&7当前写入值：&f{value}'

内容	说明
{id}	当前刷新规则 ID
{value}	当前写入变量的最终值
PlaceholderAPI 变量	安装并启用 PlaceholderAPI 时按目标玩家解析
& 颜色代码	发送前转换为 Minecraft 颜色代码

如果一段脚本写入多个变量，消息会针对每个变量分别发送。服务器规则会对每名在线玩家执行消息，因此同一条服务器规则写入多个变量时，每名玩家都会分别收到对应消息。

刷新命令

刷新规则中的 command 是文本列表，与 message 相同，会在每个变量写入后分别执行。

command:
  - '[console]tell %player_name% 规则{id}已经刷新为{value}'
  - '[op]give %player_name% diamond 1'
  - 'spawn'

写法	执行身份
[console]命令	服务器控制台
[op]命令	临时给予目标玩家管理员身份后执行
无前缀	目标玩家本人

命令文本支持 {id}、{value}。安装并启用 PlaceholderAPI 时，也会按目标玩家解析 PAPI 变量。

服务器规则会遍历全部在线玩家执行 message 和 command。因此服务器规则中的无前缀命令与 [op] 命令仍以每名在线玩家为执行者；只需要执行一次的全服操作应使用 [console]，并注意脚本写入多个变量时命令仍会按变量数量重复执行。

重载规则

执行以下指令重新读取主配置与刷新文件：

/lybl reload

可以直接重载的内容包括：

• auto-save-seconds
• message 操作提示
• 玩家刷新规则文件
• 服务器刷新规则文件

必须重启服务器的内容包括：

• Redis 开关与全部连接参数
• MySQL 开关与全部连接参数
• YAML 与 MySQL 持久化方式切换

重载会先完整读取并校验候选配置。任一文件或规则出现格式错误、重复规则 ID、无效触发时间、无效条件、空脚本或脚本语法错误时，本次重载失败，当前正在运行的刷新任务和自动保存任务保持不变。

重载成功后，插件会在指令反馈和控制台中列出实际载入的玩家规则、服务器规则、来源文件与规则 ID。