常见问题

插件启动失败怎么办？

先检查服务端版本。当前项目提供 1.7.10、1.12.2、1.20.1 的 NMS 适配实现，原页面确认当前版本会识别 1.7.10、1.12.2、1.20.1，其它版本可能停止启用。

再检查控制台中的前置插件提示。PlaceholderAPI、Vault 和 PlayerPoints 在插件描述中属于软依赖，但不同功能对前置的实际要求不同：

前置	影响功能
`PlaceholderAPI`	派遣条件中的 `papi:{...}`、变量、奖励动作中的玩家变量，以及全局变量相关功能
`Vault`	经济相关功能的软依赖入口
`PlayerPoints`	点券相关功能的软依赖入口
`LyMySQLCore`	启用 MySQL 存储时必须安装，并且必须成功连接数据库

如果服务端版本、前置插件或许可证验证存在问题，应优先查看启动控制台日志。

`/lypq` 没有显示帮助或没有反应怎么办？

插件注册的主命令是 /lypq。帮助信息和部分管理指令只会在发送者为 OP 时显示或执行。

当前项目中可以确认的指令如下：

指令	使用条件	功能
`/lypq`	OP	显示帮助信息
`/lypq open`	玩家	打开派遣总览界面
`/lypq open <派遣ID>`	玩家	打开指定派遣界面
`/lypq open <玩家> <派遣ID>`	OP	为指定在线玩家打开指定派遣界面
`/lypq force <玩家> <派遣ID>`	OP	强制结束指定在线玩家的派遣并结算奖励
`/lypq reload`	OP	重载插件配置

<派遣ID> 必须与派遣文件中的 id 完全一致。open <玩家> <派遣ID> 和 force <玩家> <派遣ID> 只能处理在线玩家。

`/lypq open` 没有派遣任务怎么办？

按以下顺序检查：

检查插件目录下的 dispatch/ 文件夹中是否存在扩展名为 .yml 的派遣文件。
确认文件内容可以被 YAML 正常读取。
确认每个派遣文件都有 id。
确认所有派遣文件的 id 全局唯一。
检查主配置中的 load-default-config。该选项为 true 时读取默认示例配置，为 false 时不读取默认示例配置。
执行 /lypq reload 后重新打开界面；如果修改了数据库开关，应重启服务器而不是只重载配置。

派遣文件会递归扫描 dispatch/ 目录及其子目录，但只读取 .yml 文件。

派遣文件加载了，但界面中看不到任务怎么办？

检查派遣文件中的界面字段：

title：派遣界面标题。
main-gui-id：总览界面中的显示物品。
main-gui-name：总览界面中的显示名称。
main-gui-lore：总览界面中的说明文本。
dispatch.time-and-reward：派遣时长和奖励按钮配置。

如果文件的 id 重复，或者派遣文件存在 YAML 格式错误，可能导致该文件无法正确加载。启动或重载时应查看控制台中的派遣配置加载日志。

物品放不进去怎么办？

派遣物品槽只允许放入一个物品。放入数量大于 1 的物品时，会发送 message.put-item-fail。

如果配置了 dispatch.match-item，放入的物品必须满足其中任意一条匹配条件：

写法	匹配方式
`name:{文本}`	完全匹配物品显示名，忽略大小写
`lore:{文本}`	完全匹配任意一行 Lore，忽略大小写
`contain_name:{文本}`	物品显示名包含指定文本
`contain_lore:{文本}`	任意一行 Lore 包含指定文本

颜色代码会将 & 转换为 Minecraft 颜色符号后再比较。使用 name:{...} 或 lore:{...} 时，文本、颜色和空格都应与物品实际显示内容保持一致；需要关键词匹配时使用 contain_name:{...} 或 contain_lore:{...}。

如果没有配置 dispatch.match-item，只有在派遣槽为空时才会被视为匹配；放入物品反而不会通过匹配。

部分时长节点还可以配置自己的 match-item，但当前数据加载逻辑主要读取派遣级别的 dispatch.match-item，排查时应优先检查派遣级别配置。

额外物品提示“此额外物品无法使用在该派遣中”怎么办？

额外物品按 extra-item 下的节点名称匹配物品显示名，并且是完全匹配。检查以下内容是否一致：

颜色代码。
空格。
大小写和实际显示文本。
物品是否存在显示名。

额外物品槽同样只允许放入一个物品。放入数量大于 1 时，会发送 message.put-item-fail；未匹配到 extra-item 节点时，会发送全局配置中的 message.extra-item-fail。

take-extra-item 决定领取奖励时是否扣除额外物品。额外物品可以通过 action 修改派遣时间、增加奖励组几率，并参与奖励动作结算。

派遣无法开始怎么办？

开始派遣时会依次检查派遣条件、派遣物品和额外物品。常见原因如下：

condition 条件不满足。
派遣物品没有命中 dispatch.match-item。
当前玩家已经有该派遣的进行中状态。
permission:{权限节点} 条件不满足。
nopermission:{权限节点} 条件不满足，因为玩家实际拥有该权限。
papi:{表达式} 判断结果为假，或 PlaceholderAPI 没有加载。

一个条件列表中的所有条件都必须满足。papi:{...} 支持 PlaceholderAPI 替换后的数值比较、字符串比较、布尔判断，以及 && 和 || 逻辑表达式。

派遣时间支持固定值和范围值。例如 1 表示固定派遣 1 分钟，1-5 表示在 1 至 5 分钟之间随机派遣。权限加成组按配置从上到下检查，第一次满足条件的组生效。

权限加成没有生效怎么办？

检查 permission-addition 下的组配置。每个组包含以下字段：

配置项	说明
`condition`	该组需要满足的全部条件
`time`	时间计算公式，使用 `{time}` 代表原始派遣毫秒数
`message`	该组生效时发送给玩家的提示

权限加成组按 YAML 配置顺序从上到下匹配，第一个满足全部条件的组生效。公式支持数字、括号以及 +、-、*、/ 运算。例如：

yaml

permission-addition:
  '组1':
    condition:
      - 'permission:{vip.1}'
    time: '{time}*0.9'
    message: '&a本次派遣时间减少10%！'

如果同时使用额外物品的 time:{...} 动作，额外物品时间修改会在权限加成计算后继续作用。

派遣进行中为什么不能再次放入物品或修改界面？

同一个派遣 ID 同时只能存在一个派遣状态。派遣进行中，派遣物品槽和额外物品槽不能继续修改，点击未完成的派遣按钮也不会重复开始任务。

派遣状态包含：

派遣 ID。
派遣时长配置键。
派遣物品。
额外物品。
结束时间。

玩家退出或被踢出服务器时，当前状态会保存；重新进入后会继续读取该状态。

派遣完成后不能领取奖励怎么办？

先检查奖励节点中的 slot。领取时，玩家背包可用空位必须不少于该值；空间不足会发送 message.empty-slot，状态不会正常结算。

再检查以下内容：

派遣时长配置是否仍然存在。
当前状态记录的时长是否与 dispatch.time-and-reward 下的配置键一致。
reward-group 的 chance 是否在预期范围内。
奖励动作中的物品库、物品 ID 和数量格式是否正确。
奖励动作中涉及的前置插件是否已安装。

奖励组会分别按几率判断，多个奖励组可以同时触发。额外物品中的 reward_chance:{奖励组ID#增加值} 会对对应奖励组进行加法增加。

如果奖励动作包含 giveitem，支持的物品库标识为：

标识	物品来源
`mm`	MythicMobs
`ni`	NeigeItems
`si`	SX-Item

为什么派遣物品被扣除了？

时长奖励节点中的 take-item 决定是否启用扣除判定，take-item-chance 决定扣除几率。扣除发生时，会发送 message.take-item。

配置示例：

yaml

dispatch:
  time-and-reward:
    10:
      take-item: true
      take-item-chance: 0.1

额外物品是否扣除由对应节点的 take-extra-item 决定。该设置只影响额外物品，不等同于派遣物品的 take-item。

奖励动作不生效怎么办？

先确认动作前缀和格式。项目中已实现的奖励动作包括：

动作	功能
`charge:<数值>`	调用离渊充能接口为派遣物品充能；物品必须存在 Lore
`lore_match_mode:contain`	后续 Lore 查找使用包含匹配
`lore_match_mode:equls`	后续 Lore 查找使用完整匹配
`lore_match_mode:start`	配置中可使用该模式标识，但当前实现对非 `contain` 值按非包含匹配处理
`lore_remove:<文本>`	删除匹配到的 Lore
`lore_replace:<原文本>:<新文本>`	替换匹配到的 Lore
`lore_add_next:<原文本>:<新增文本>`	在匹配 Lore 后插入一行
`lore_add_last:<原文本>:<新增文本>`	在匹配 Lore 前插入一行
`name_set:<文本>`	设置物品显示名
`name_replace:<原文本>:<新文本>`	替换物品显示名中的文本
`name_add_start:<文本>`	在物品显示名前追加文本
`name_add_end:<文本>`	在物品显示名后追加文本
`command_console:<指令>`	以控制台身份执行指令
`command_op:<指令>`	以 OP 身份执行指令
`command:<指令>`	以玩家身份执行指令
`message_server:<文本>`	向在线玩家发送全服消息
`message:<文本>`	向当前玩家发送消息
`giveitem:<物品库>:<物品ID>:<数量>`	从支持的物品库发放物品

奖励动作中的玩家变量会通过 PlaceholderAPI 处理。使用包含冒号的文本时，应注意动作解析本身也使用冒号分隔字段。

`charge` 动作无法使用怎么办？

charge:<数值> 只会处理存在物品元数据且带有 Lore 的派遣物品。物品为空、没有 ItemMeta 或没有 Lore 时，该动作不会继续处理。

同时需要确保对应的充能方案存在；如果没有可用的充能方案，该功能不会生效。

开始指令或结束指令没有执行怎么办？

指令写在派遣文件的以下位置：

yaml

dispatch:
  start-command:
    - '[console]某条控制台指令'
    - '[op]某条OP指令'
    - '某条玩家指令'
  end-command:
    - '[console]某条控制台指令'
    - '[op]某条OP指令'
    - '某条玩家指令'

前缀含义如下：

前缀	执行身份
`[console]`	控制台
`[op]`	临时以 OP 身份执行的玩家
无前缀	当前玩家

指令会先经过 PlaceholderAPI 替换。当前项目的数据加载代码读取结束指令时使用的是 dispatch.start-command 路径，因此如果 end-command 没有按预期生效，应先确认结束指令配置，并注意当前版本实现中的该读取行为。

变量不显示怎么办？

确认 PlaceholderAPI 已加载，并确认变量 ID 使用 lypq。当前配置文件中记录的变量如下：

变量	返回内容
`%lypq_status_<派遣ID>%`	指定派遣状态：未派遣为 `0`，已派遣等待回归为 `1`，已回归可领奖为 `2`
`%lypq_surplustime_<派遣ID>%`	指定派遣剩余工作时间，单位为秒
`%lypq_endtime_<派遣ID>%`	指定派遣工作结束时间，单位为秒
`%lypq_global%`	根据全局派遣状态返回对应文本

全局变量使用以下配置文本：

配置项	使用场景
`global-starting-text`	存在进行中的派遣任务
`global-nothing-text`	没有开启派遣任务
`global-finish-text`	存在已完成但未领取奖励的派遣任务

例如派遣文件中配置 id: '宠物出行'，对应状态变量为：

text

%lypq_status_宠物出行%

派遣 ID 包含特殊字符时，变量中的 ID 也必须与配置完全一致。

时间显示不正确怎么办？

检查主配置中的 time-format。该值会传给日期格式化器，用于显示派遣结束时间。

yaml

time-format: 'MM/dd HH:mm:ss'

{time} 在不同位置代表不同内容：

位置	`{time}` 含义
`dispatching-item-name`、`dispatching-item-lore`	格式化后的结束日期时间
`after-returning-item-name`、`after-returning-item-lore`	派遣时长文本
`time-and-reward.item-name`、`item-lore`	当前派遣时长配置键
`permission-addition.time`	原始派遣时间的毫秒数

派遣完成后没有提示怎么办？

玩家在线且到达结束时间后，插件会发送派遣文件中的 message.can-reward，并播放主配置中的 dispatch-end-sound。

检查以下配置：

yaml

dispatch-end-sound: 'ENTITY_EXPERIENCE_ORB_PICKUP'

不同版本的音效名称不同：1.12 使用 ENTITY_EXPERIENCE_ORB_PICKUP，1.7 使用 ORB_PICKUP。如果音效名称不被当前服务端识别，控制台会提示音效错误，但不影响派遣状态本身。

玩家离线期间不会收到在线提示；重新进入服务器后会读取已保存的派遣状态。

关闭界面后物品不见了怎么办？

正常关闭派遣界面时，尚未开始派遣的派遣物品会尝试返还到玩家背包。背包空间不足时，无法返还的物品会掉落在玩家当前位置附近，并发送“包满了，东西掉你脚下了！！”提示。

开始派遣后，物品属于当前派遣状态，不能通过关闭界面取回；需要等待派遣完成并领取奖励。

重载后配置没有变化怎么办？

确认修改的是插件实际读取的文件，并执行：

text

/lypq reload

重载只适用于配置重新读取。mysql.enable 的注释明确要求修改后重启服务器，不能只依靠重载切换存储方式。

如果派遣文件加载失败或字段缺失，应查看控制台中的配置加载日志。派遣文件的 id、title、dispatch.match-item、dispatch.time-and-reward 等字段会直接影响界面和派遣逻辑。

切换 MySQL 后数据异常怎么办？

使用 MySQL 存储必须同时满足以下条件：

安装 LyMySQLCore。
LyMySQLCore 成功连接数据库。
主配置中的 mysql.enable 设置为 true。
修改后重启服务器。
检查 mysql.databasename、mysql.username、mysql.password、mysql.port 和 mysql.ip。

示例配置：

yaml

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

只有安装 LyMySQLCore 且成功连接数据库后，MySQL 相关功能才会生效。数据库连接失败时，插件会输出连接失败日志；数据库未连接完成时，玩家登录可能被阻止。

切换存储方式前建议备份原有数据。YAML 存储的数据位于插件目录的 data/ 文件夹中，每名玩家使用一个以 UUID 命名的 .yml 文件；安全保存逻辑还会生成 .bak 备份文件。

YAML 数据损坏怎么办？

YAML 玩家数据使用 UTF-8 读取。插件会检查主文件中的异常内容；主文件损坏时会尝试读取对应的 .bak 备份文件并恢复主文件。

如果主文件和备份文件都损坏，插件会返回空配置，玩家原有的派遣状态可能无法恢复。处理前应停止继续修改文件，并保留原始文件和备份文件供排查。

强制结束派遣失败怎么办？

/lypq force <玩家> <派遣ID> 需要满足以下条件：

执行者是 OP。
目标玩家在线。
目标玩家已经加载 LyDispatch 数据。
目标玩家存在该派遣 ID 的进行中状态。
该派遣 ID 仍存在于当前加载的派遣配置中。
目标玩家背包有足够的空位领取奖励。

强制结束会按当前派遣时长配置结算奖励，并执行结束指令。若当前状态记录的时长配置已经被删除，插件会提示当前时间数据不存在，并移除该派遣状态。

常见问题 ​

插件启动失败怎么办？ ​

/lypq 没有显示帮助或没有反应怎么办？ ​

/lypq open 没有派遣任务怎么办？ ​

派遣文件加载了，但界面中看不到任务怎么办？ ​

物品放不进去怎么办？ ​

额外物品提示“此额外物品无法使用在该派遣中”怎么办？ ​

派遣无法开始怎么办？ ​

权限加成没有生效怎么办？ ​

派遣进行中为什么不能再次放入物品或修改界面？ ​

派遣完成后不能领取奖励怎么办？ ​

为什么派遣物品被扣除了？ ​

奖励动作不生效怎么办？ ​

charge 动作无法使用怎么办？ ​

开始指令或结束指令没有执行怎么办？ ​

变量不显示怎么办？ ​

时间显示不正确怎么办？ ​

派遣完成后没有提示怎么办？ ​

关闭界面后物品不见了怎么办？ ​

重载后配置没有变化怎么办？ ​

切换 MySQL 后数据异常怎么办？ ​

YAML 数据损坏怎么办？ ​

强制结束派遣失败怎么办？ ​

常见问题

插件启动失败怎么办？

`/lypq` 没有显示帮助或没有反应怎么办？

`/lypq open` 没有派遣任务怎么办？

派遣文件加载了，但界面中看不到任务怎么办？

物品放不进去怎么办？

额外物品提示“此额外物品无法使用在该派遣中”怎么办？

派遣无法开始怎么办？

权限加成没有生效怎么办？

派遣进行中为什么不能再次放入物品或修改界面？

派遣完成后不能领取奖励怎么办？

为什么派遣物品被扣除了？

奖励动作不生效怎么办？

`charge` 动作无法使用怎么办？

开始指令或结束指令没有执行怎么办？

变量不显示怎么办？

时间显示不正确怎么办？

派遣完成后没有提示怎么办？

关闭界面后物品不见了怎么办？

重载后配置没有变化怎么办？

切换 MySQL 后数据异常怎么办？

YAML 数据损坏怎么办？

强制结束派遣失败怎么办？