插件变量
LyDispatch 提供 PlaceholderAPI 变量扩展，变量标识为 lypq。服务器必须安装并成功加载 PlaceholderAPI，变量扩展才会注册并生效。
变量使用目标玩家的数据进行解析，只能在存在玩家上下文的位置使用。控制台或没有玩家对象的解析环境会返回空文本。
变量总览
| 变量 | 返回内容 | 无对应数据时 |
|---|---|---|
%lypq_global% | 玩家全部派遣任务的综合状态文本 | 玩家数据未加载时返回空文本；数据已加载但没有派遣任务时返回 global-nothing-text |
%lypq_status_派遣id% | 指定派遣的状态数字 | 返回 0 |
%lypq_surplustime_派遣id% | 指定派遣剩余时间的格式化结果 | 返回空文本 |
%lypq_endtime_派遣id% | 指定派遣结束时间的格式化结果 | 返回空文本 |
将变量中的 派遣id 替换为派遣配置文件顶层的 id。例如，派遣配置中的 ID 为 宠物出行 时，变量写法如下：
text
%lypq_status_宠物出行%
%lypq_surplustime_宠物出行%
%lypq_endtime_宠物出行%派遣 ID 必须与配置中的原始 ID 一致，包括中文、英文和大小写。插件查找指定派遣时不会自动修正错误的 ID。
全局状态
| 变量 | 返回内容 |
|---|---|
%lypq_global% | 根据玩家全部派遣任务，返回当前优先级最高的状态文本 |
插件会遍历已加载的派遣配置，并按以下规则确定返回内容：
- 存在已经结束、可以领取奖励的派遣时，返回完成状态文本。
- 没有可领奖派遣，但存在仍在进行的派遣时，返回进行中状态文本。
- 玩家数据已加载，但没有任何派遣任务时，返回无任务状态文本。
- 玩家数据尚未加载时，返回空文本。
全局状态文本由 config.yml 中的以下配置控制：
| 状态 | 配置项 | 默认内容 |
|---|---|---|
| 有任务可领奖 | global-finish-text | 您有派遣任务已完成 快去领取奖励吧 |
| 有任务进行中 | global-starting-text | 您有派遣任务进行中 请耐心等待 |
| 没有任务 | global-nothing-text | 您暂未开启派遣任务 快去开启吧 |
这些文本支持使用 & 颜色代码。变量返回前，插件会将 & 转换为 Minecraft 颜色代码。
yaml
global-starting-text: '您有派遣任务进行中 请耐心等待'
global-nothing-text: '您暂未开启派遣任务 快去开启吧'
global-finish-text: '您有派遣任务已完成 快去领取奖励吧'如果玩家同时存在进行中的派遣和已结束的派遣，已结束派遣的完成状态优先返回。
指定派遣状态
| 变量返回值 | 含义 |
|---|---|
0 | 玩家数据中没有该派遣任务，或玩家数据尚未加载 |
1 | 派遣正在进行，当前时间尚未到达结束时间 |
2 | 派遣已经结束，可以领取奖励 |
示例：
text
%lypq_status_宠物出行%插件会根据玩家保存的派遣结束时间实时判断状态：
- 结束时间晚于当前时间时返回
1。 - 当前时间已经到达或超过结束时间时返回
2。 - 玩家领取奖励后，该派遣状态会被移除，变量重新返回
0。
时间变量
剩余时间
text
%lypq_surplustime_派遣id%该变量读取指定派遣保存的结束时间，计算结束时间减去当前时间的结果，然后交给 time-format 配置项进行格式化。
当派遣已经结束时，剩余时间会先限制为 0，再进行格式化。变量返回的是日期格式化结果，不是直接返回秒数，也不是独立的“天、小时、分钟”倒计时。
结束时间
text
%lypq_endtime_派遣id%该变量读取指定派遣保存的结束时间，并使用 time-format 配置项格式化，适合显示预计归来日期和时间。
时间格式
两个时间变量都使用 config.yml 中的 time-format：
yaml
time-format: 'MM/dd HH:mm:ss'该配置会直接作为 Java 日期格式使用。常见字段如下：
| 格式 | 含义 |
|---|---|
MM | 月份 |
dd | 日期 |
HH | 24 小时制小时 |
mm | 分钟 |
ss | 秒 |
修改 time-format 后，%lypq_surplustime_派遣id% 和 %lypq_endtime_派遣id% 都会使用新的格式。
派遣 ID 限制
变量参数通过下划线 _ 分隔，插件读取第一个下划线后的内容作为派遣 ID。因此，派遣配置中的 id 不应包含下划线。
可以正常使用的 ID：
yaml
id: '宠物出行'不建议使用的 ID：
yaml
id: '宠物_出行'对于 宠物_出行，变量 %lypq_status_宠物_出行% 会被拆分为 status、宠物 和 出行，插件只会读取第一个参数 宠物，无法匹配完整的 宠物_出行。
玩家数据加载
变量依赖玩家派遣数据完成加载。玩家刚进入服务器、插件尚未完成初始化或数据尚未读取完成时，变量可能返回空文本或 0。
| 情况 | %lypq_global% | %lypq_status_派遣id% | 时间变量 |
|---|---|---|---|
| 玩家数据尚未加载 | 空文本 | 0 | 空文本 |
| 玩家没有指定派遣 | 根据全部派遣任务返回状态文本 | 0 | 空文本 |
| 指定派遣进行中 | 返回进行中文本，若存在可领奖派遣则返回完成文本 | 1 | 返回格式化结果 |
| 指定派遣已结束 | 返回完成状态文本 | 2 | 剩余时间按 0 格式化，结束时间保持不变 |
| 奖励已经领取 | 重新计算全部派遣任务状态 | 0 | 空文本 |
MySQL 存储说明
启用 config.yml 的 MySQL 存储后，玩家派遣数据会从数据库读取并保存。
使用 MySQL 存储时必须同时满足以下条件：
- 安装 LyMySQLCore。
- LyMySQLCore 成功连接数据库。
- LyDispatch 成功完成玩家数据加载。
只有 LyMySQLCore 已安装并成功连接数据库，相关玩家数据加载完成后，PlaceholderAPI 变量才会正确反映数据库中保存的派遣状态。数据库未连接或玩家数据尚未加载时，变量可能返回空文本或 0。
变量生效条件
| 条件 | 说明 |
|---|---|
| PlaceholderAPI | 必须安装并成功加载，否则 lypq 变量扩展不会注册 |
| 玩家上下文 | 变量需要目标玩家对象，控制台解析可能返回空文本 |
| 玩家数据 | 指定派遣状态和时间变量依赖玩家数据加载完成 |
| 派遣 ID | 必须与派遣配置顶层 id 完全一致，且不应包含下划线 |
| MySQL 存储 | 必须安装 LyMySQLCore，并确保数据库连接成功 |