常见问题

LyPet 是如何识别宠物的

LyPet 会读取 config.yml 中 plugin-slot 指定的槽位，然后根据槽位物品的显示名称匹配宠物配置。

必须同时满足以下条件：

1. 玩家已经进入服务器并创建了玩家缓存。
2. plugin-slot 格式正确。
3. 对应槽位插件已经安装并正常启用。
4. 目标槽位中存在物品。
5. 物品具有显示名称。
6. 显示名称符合宠物配置中的 identity。
7. 宠物配置中的 id 没有重复。

identity-match-contains 决定名称匹配方式：

配置值	匹配规则
false	物品显示名称必须与 identity 完全一致，包括颜色代码产生的颜色
true	物品显示名称中包含 identity 即可

没有匹配到宠物时，召唤会提示“槽位不存在宠物, 无法召唤!”。

宠物召唤不出来

按以下顺序检查：

1. 确认玩家已经进入服务器。插件会在玩家加入时创建玩家缓存。
2. 如果插件重载后已有在线玩家无法正常召唤，先让玩家重新进入服务器。
3. 检查 plugin-slot 是否使用了正确格式。
4. 确认对应的背包或槽位插件已经安装并启用。
5. 确认目标槽位内存在物品，且物品具有显示名称。
6. 确认物品显示名称与宠物配置中的 identity 匹配。
7. 确认宠物配置中的 id 没有与其他宠物重复。
8. 检查控制台是否出现宠物配置读取失败、实体类型错误或前置插件未启动的信息。

如果宠物当前已经显示，再次使用召唤键或执行 /lycw common 会隐藏宠物。

plugin-slot 应该怎么填写

plugin-slot 使用 # 分隔槽位来源和参数。

槽位来源	格式
原版背包	Minecraft#槽位编号
DragonCore	DragonCore#槽位名
GermPlugin	GermPlugin#槽位名
LyInventoryReload	LyInventoryReload#背包#类型
LyInventory	LyInventory#背包#类型
MXSAttributeInventory	MXSAttributeInventory#背包#格子编号
PXRPG	PXRPG#类型#背包ID#槽位
APInventory	APInventory#分页ID#槽位编号
YeeJewelry	YeeJewelry#背包ID#槽位

原版背包槽位编号直接传入 Bukkit 背包槽位编号。配置示例中的 Minecraft#8 表示读取原版背包的 8 号槽位。

使用扩展背包槽位时，对应插件必须存在并提供可用接口，否则 LyPet 无法读取槽位物品。

更换宠物物品后没有刷新

LyPet 会在玩家关闭背包时重新读取 plugin-slot。

如果宠物当前处于显示状态：

• 槽位中不再存在可匹配的宠物时，宠物会被隐藏。
• 槽位中的物品匹配了另一份宠物配置时，缓存中的宠物数据会切换。

如果外部背包插件修改物品时没有触发原版背包关闭事件，可以先关闭一次背包，再重新召唤宠物。

按键没有反应

先确认使用的是 DragonCore 还是 GermPlugin。两者的按键格式不同：

客户端	常见格式
DragonCore	Z、X、C、V
GermPlugin	KEY_Z、KEY_X、KEY_C、KEY_V

召唤和隐藏宠物的按键由 show-and-hide-key 设置。技能按键除了写入宠物技能的 event，还必须加入 register-keys。

修改键位后执行：

/lycw reload

重载时，插件会重新注册 register-keys 中的技能键和 show-and-hide-key 中的召唤键。控制台会显示每个键位注册成功或失败的信息。

还需要检查：

• DragonCore 或 GermPlugin 是否已经正常启动。
• show-and-hide-key 是否使用了当前客户端对应的格式。
• 技能事件是否使用 SLOT-DRAGON#键位 或 SLOT-GERM#键位。
• 宠物是否已经召唤。技能按键只对当前显示中的宠物生效。

能否不用客户端按键召唤宠物

可以。玩家执行以下指令即可切换宠物显示状态：

/lycw common

宠物隐藏时，该指令会尝试召唤宠物；宠物显示时，该指令会隐藏宠物。

/lycw 有哪些指令

插件验证通过并加载核心后，管理员直接执行 /lycw 可以查看帮助信息。

指令	执行者	作用
/lycw	管理员	查看重载和召唤帮助
/lycw reload	管理员	重载配置、宠物文件和键位
/lycw common	玩家	切换宠物显示和隐藏状态

项目中的 plugin.yml 只声明了 lycw 命令，没有声明独立的命令权限节点。管理员指令通过 Bukkit 的管理员状态判断。

插件验证通过前，命令处理器只提供重载功能，并提示更多指令将在验证通过后显示。验证所需的服务器地址、端口和用户信息不在项目配置文件中提供。

重载后配置没有生效

管理员执行：

/lycw reload

重载会执行以下操作：

• 重新读取 config.yml。
• 递归扫描 plugins/LyPet/pet 目录下的 .yml 文件。
• 清空并重新载入宠物数据。
• 重新注册 DragonCore 和 GermPlugin 键位。
• 重启技能定时任务。

检查控制台输出：

• “读取宠物成功”表示对应配置已载入。
• “读取宠物失败”表示该文件存在错误，或宠物 id 重复。
• 相同 id 的宠物只会载入一份，重复配置会被跳过。
• 键位注册成功或失败会分别输出日志。

重载后已有在线玩家出现异常时，可以让玩家重新进入服务器，使玩家缓存重新创建。

控制台提示实体类型错误

检查宠物配置中的 entity-type。

该值必须能被 Adyeshach 的 EntityTypes.valueOf 识别。填写错误时，插件会在控制台输出错误，并将实体类型回退为 PIG，但仍应修正配置中的实体类型。

控制台提示 Adyeshach 未启动

宠物实体通过 Adyeshach 的公共临时实体管理器创建。Adyeshach 未正常启动时，宠物实体功能无法正常工作。

检查：

• Adyeshach 是否已经安装并成功启用。
• 当前 Adyeshach 是否提供 LyPet 调用的实体 API。
• LyPet 是否在 Adyeshach 启动后完成加载。

plugin.yml 将 Adyeshach 声明为软依赖，但宠物创建和实体管理代码直接调用了 Adyeshach API，因此软依赖不代表可以完全不安装。

控制台提示 MythicMobs 未启动

以下功能会调用 MythicMobs：

• 宠物配置中的 skills。
• attack-function 中除 attack 以外的技能 ID。

MythicMobs 未启动时，这些功能无法正常释放。检查 MythicMobs 是否已经安装并启用，并确认填写的技能 ID 存在。

宠物不跟随玩家

检查宠物配置中的以下项目：

配置项	作用
follow-speed	宠物基础跟随速度
standby-distance	宠物与目标小于该距离时停止跟随
teleport-distance	宠物与目标超过该距离时传送
move-update-tick	宠物移动任务的刷新间隔，最小按 1 tick 处理

宠物召唤后会固定等待 20 tick 再开始移动，用于减少模型刚出现时的动作卡顿。这一秒内没有立即跟随属于正常行为。

插件会记录玩家或攻击目标的移动路径，让宠物沿路径点移动。玩家切换世界后，插件会删除旧实体，并在玩家当前世界重新创建宠物。

宠物距离过远却没有正确传送

确认 teleport-distance 大于 standby-distance，并避免将传送距离设置得过小。

传送时，插件会尝试：

1. 根据目标位置和 standby-distance 计算偏移位置。
2. 将位置向上调整一格。
3. 向下检查最多两格，寻找可站立且上方两格为空的位置。

围栏、墙、活板门、压力板、按钮、空气和透明或非实体方块不会被视为安全落点。如果附近没有找到安全位置，宠物可能直接使用计算出的目标位置。

宠物不攻击

检查以下配置：

配置项	检查内容
auto-attack-enable	必须为 true
track-range	目标与主人的距离不能超过该范围
attack-range	宠物与目标的距离必须小于该值
attack-speed	达到攻击距离后的攻击间隔，单位为 tick
attack-function	使用 attack 进行原版攻击，其他值会作为 MythicMobs 技能 ID

宠物不会主动搜索附近实体。目标通过战斗事件设置：

• 主人攻击一个生物时，该生物会成为宠物目标。
• 主人被一个生物攻击时，攻击者会成为宠物目标。

目标失效、切换世界或距离主人超过 track-range 后，插件会清除该目标。

建议让 track-range 不大于 teleport-distance，避免追击范围和传送范围相互冲突。

attack-function: attack 无法使用

原版攻击实现直接调用了 CraftBukkit 和 NMS 的 v1_12_R1 类。

如果服务器内部版本不兼容，执行原版攻击时可能出现类不存在或类型转换错误。可以检查当前服务端是否兼容 v1_12_R1，或者将 attack-function 改为已经存在的 MythicMobs 技能 ID。

宠物攻击时没有播放模型动作

检查：

• attack-animation-id 是否为空。
• DragonCore 是否已经启用。
• 动画 ID 是否存在于当前模型配置中。
• attack-animation-speed 是否填写了模型所需的速度值。

攻击动画仅在 DragonCore 启用时发送。无论动画是否配置，宠物仍会尝试执行 attack-function。

DragonCore 宠物模型没有绑定

召唤宠物后，插件会读取 DragonCore 缓存中的 EntityModel.yml，并使用其中各节点的 entity 值匹配宠物显示名称。

匹配时会移除颜色代码，并判断宠物显示名称是否包含 entity 对应的名称。检查：

• DragonCore 是否已经启用。
• DragonCore 是否已经加载 EntityModel.yml。
• 模型节点中是否存在 entity 配置。
• entity 对应的名称是否包含在宠物的 show-name 中。
• 替换 {player} 后的宠物名称是否仍能匹配模型识别名称。

插件找到第一个匹配节点后会停止继续查找，因此应避免多个模型使用相互包含的识别名称。

技能没有触发

首先确认宠物处于显示状态，然后检查 event 的格式。

事件	触发条件
LEFT	主人左键点击空气或方块
RIGHT	主人右键点击空气或方块
TIME#几率	每秒按照 0 至 100 的几率检测一次
DAMAGED#几率	主人受到实体伤害时按几率触发
ATTACK#几率	主人对实体造成伤害时按几率触发
SLOT-DRAGON#键位	按下对应的 DragonCore 键位
SLOT-GERM#键位	松开对应的 GermPlugin 键位

ATTACK 和 DAMAGED 必须带 #几率。例如：

event: 'ATTACK#30'

如果使用按键事件，还要将对应键位加入 register-keys 并重载插件。

技能还必须满足以下条件：

• 宠物处于显示状态。
• trigger-conditions 全部通过。
• 技能不在冷却中。
• 触发事件对应的前置插件已经启用。

TIME 技能触发频率不正确

时间技能每秒检测一次。TIME#几率 中的数值是每次检测的触发概率，不是固定间隔。

例如：

event: 'TIME#20'

表示每秒进行一次约 20% 概率的触发检测。即使概率检测成功，技能仍会受到条件和冷却限制。

技能条件始终不通过

trigger-conditions 会先通过 PlaceholderAPI 替换变量，再进行条件判断。

支持的比较符号：

符号	作用
>	大于
>=	大于或等于
==	数值或文本相等
<=	小于或等于
<	小于

数值表达式支持 +、-、*、/ 和括号。条件还支持：

• &&：同组条件全部满足。
• ||：任意一组条件满足。

检查 PlaceholderAPI 是否已经安装，并确认变量替换后得到的是可计算的数字或可比较的文本。每一条 trigger-conditions 内容都必须通过，技能才会继续释放。

技能冷却不正确

cd 的基础单位为秒。插件会先替换 PlaceholderAPI 变量，计算四则运算表达式，再转换为毫秒保存。

例如：

cd: '5'

冷却按“玩家 + 宠物 ID + 技能 ID”分别记录。不同宠物使用相同技能编号时不会共用同一条冷却记录。

冷却期间再次触发技能时，只会发送 cd-msg.on-cd，不会执行技能或命令。冷却结束后，定时任务会发送一次 cd-msg.over-cd。

冷却消息支持：

内容	替换结果
{id}	当前宠物技能编号
{time}	剩余冷却秒数，仅用于冷却中的消息

将消息设为空字符串可以关闭对应提示。

MythicMobs 技能没有释放

检查：

1. MythicMobs 是否已经正常启动。
2. skills 中填写的技能 ID 是否真实存在。
3. trigger-conditions 是否全部满足。
4. 技能是否还在冷却中。
5. 宠物是否仍处于显示状态。

skill-origin-loc 决定技能 Origin 坐标：

配置值	Origin 坐标
true	主人当前位置
false	宠物当前位置

技能的施法实体仍是玩家。需要围绕 Origin 选择目标时，应在 MythicMobs 技能中使用适合 Origin 的目标选择方式。

如果技能 ID 不存在，插件会直接结束该技能调用，不会自动创建技能，也不会向玩家发送错误消息。技能命令仍会继续按照技能配置处理。

技能命令没有执行

技能命令只有在条件通过且技能不处于冷却时执行。

支持的执行方式：

前缀	执行身份
[op]	临时以管理员身份让玩家执行
[console]	控制台执行
无前缀或 [player]	玩家执行

命令内容支持 PlaceholderAPI 变量，并会将 {id} 替换为当前技能编号。命令中不要填写开头的 /。

即使 skills 列表中的 MythicMobs 技能不存在，代码仍会继续处理该技能配置中的命令。

技能动画没有播放

技能动画由以下配置控制：

animation-id: ''
animation-speed: 0

检查 DragonCore 是否启用、动画 ID 是否存在，以及宠物是否已成功创建。技能动画会发送给宠物所在世界内的玩家。

动画播放失败时，控制台会输出“播放模型动画错误”及异常信息，但技能命令和后续处理仍可能继续执行。

Shift 加右键宠物没有反应

该交互监听的是 Adyeshach 宠物实体交互事件，并要求玩家处于潜行状态。

检查：

• 玩家是否按住 Shift 后右键自己的宠物。
• 宠物是否由当前玩家召唤。
• shift-right-command 是否包含有效命令。
• shift-right-command-cooldown 是否仍在冷却中。
• Adyeshach 是否正常提供实体交互事件。

交互冷却单位为毫秒，默认值为 500。

Shift 加右键命令如何执行

执行方式与技能命令相同：

前缀	执行身份
[op]	临时以管理员身份让玩家执行
[console]	控制台执行
无前缀	玩家执行

命令支持 PlaceholderAPI 变量。命令中不要填写开头的 /。

PlaceholderAPI 变量返回空内容

LyPet 只会在 PlaceholderAPI 已启用时注册变量扩展。

当前提供：

变量	内容
%lycw_uuid%	当前宠物实体的标准化 UUID
%lycw_name%	当前宠物实体的显示名称

以下情况会返回空字符串：

• 请求变量时没有玩家对象。
• 玩家缓存不存在。
• 玩家当前没有已创建的宠物实体。

未知的 LyPet 变量会返回错误内容。

宠物名称中的 {player} 没有替换

{player} 只在创建宠物实体时用于 show-name，会替换为主人的真实玩家名。

它不是 PlaceholderAPI 变量，也不会在所有配置项中通用替换。技能命令、交互命令和条件需要使用 PlaceholderAPI 提供的变量格式。

玩家退出后宠物还在

玩家正常退出时，插件会：

• 删除宠物实体。
• 停止跟随任务和路径记录任务。
• 清除当前攻击目标。
• 移除玩家缓存。

如果服务器异常停止、插件被强制卸载或 Adyeshach 删除实体过程报错，可能留下异常显示。重新进入服务器或重启相关插件后再检查实体状态。

玩家切换世界后宠物消失或重新生成

这是当前机制的一部分。跟随任务发现宠物与主人不在同一世界时，会删除旧宠物，并在主人当前世界重新创建实体，同时清除旧路径和攻击目标。

DragonCore 模型会在重新创建宠物后再次尝试同步。

宠物追击了错误的目标

每当主人攻击生物，或主人被生物攻击时，缓存中的当前目标都会更新为对应生物。

插件不会维护仇恨列表，也不会比较多个目标的优先级。后发生的有效战斗事件可能覆盖之前的目标。目标失效、跨世界或距离主人超过 track-range 后会被清除。

关闭自动攻击后宠物仍朝目标移动

将 auto-attack-enable 设为 false 后，路径记录任务不会继续按照攻击目标更新位置，宠物会恢复跟随主人。

如果刚刚修改配置，需要执行：

/lycw reload

然后重新召唤宠物，使当前玩家缓存使用新载入的宠物配置。

是否需要 MySQL 或 LyMySQLCore

LyPet 项目中未发现 MySQL 存储、数据库配置或 LyMySQLCore 接口。

当前宠物配置来自：

• config.yml
• plugins/LyPet/pet 目录下的 YAML 文件

玩家运行状态保存在服务器内存缓存中。因此，LyPet 当前不涉及 MySQL 存储，也不能确认需要安装 LyMySQLCore；与 MySQL 数据库连接成功并不是本项目已确认的生效条件。

LyPet 声明了哪些前置插件

plugin.yml 中声明的软依赖如下：

前置插件	主要用途
Adyeshach	创建、管理和交互宠物实体
PlaceholderAPI	技能条件、技能命令、交互命令和 LyPet 变量
MythicMobs	宠物技能和非 attack 类型的攻击技能
GermPlugin	GermPlugin 槽位、按键和技能事件
DragonCore	DragonCore 槽位、按键、宠物模型和动画

其中，Adyeshach 的实体 API 会被宠物创建逻辑直接调用；PlaceholderAPI、MythicMobs、GermPlugin 和 DragonCore 则根据具体功能按需使用。