宠物 LyPet
LyPet 是一个使用 Adyeshach 创建宠物实体的 Minecraft 插件。插件会读取玩家指定槽位中的物品，根据物品显示名称匹配 pet/ 目录中的宠物配置，再召唤对应实体。
玩家可以通过按键或指令显示、隐藏宠物。宠物会沿玩家移动路径跟随主人，在距离过远、切换世界或目标位置变化时重新定位。启用战斗功能后，宠物还可以追击玩家攻击的目标或攻击玩家的生物，并执行原版攻击、MythicMobs 技能、模型动作和命令。
插件信息
| 项目 | 内容 |
|---|---|
| 插件名 | LyPet |
| 插件版本 | 2.0.1 |
| 作者 | Liyuan |
| 主命令 | /lycw |
| Java 版本 | Java 8 |
| 实体实现 | Adyeshach |
| 配置目录 | plugins/LyPet/ |
| 宠物目录 | plugins/LyPet/pet/ |
| 已确认适配 | 原版攻击代码直接使用 v1_12_R1 NMS 与 CraftBukkit 类，对应 Minecraft 1.12 R1 |
版本说明
项目中的原版攻击实现直接引用 net.minecraft.server.v1_12_R1 和 org.bukkit.craftbukkit.v1_12_R1。当前证据只能确认 Minecraft 1.12 R1，不能据此声明支持其他服务端版本。
玩法说明
- 管理员通过
plugin-slot指定宠物物品所在的背包或装备槽位。 - 每个宠物配置使用
identity定义需要匹配的物品显示名称。 - 玩家将对应物品放入指定槽位后，通过召唤按键或
/lycw common显示宠物。 - 宠物生成后会跟随玩家，并在超过传送距离时移动到目标附近的安全位置。
- 玩家造成伤害或受到生物攻击时，启用自动攻击的宠物会将相关生物设为追击目标。
- 宠物技能可以由鼠标操作、定时检测、战斗事件、DragonCore 按键或 GermPlugin 按键触发。
- 玩家关闭背包时，插件会重新读取槽位，并根据物品变化隐藏或切换宠物。
依赖
plugin.yml 声明了以下软依赖。虽然 Bukkit 将其标记为软依赖，但部分核心功能需要对应插件正常运行。
| 插件 | 使用范围 | 是否需要 |
|---|---|---|
Adyeshach | 创建、显示、移动、传送和交互宠物实体 | 宠物实体功能必需 |
PlaceholderAPI | 注册 %lycw_uuid%、%lycw_name%，解析技能条件、冷却表达式和执行命令中的变量 | 使用变量及相关解析功能时需要 |
MythicMobs | 执行宠物技能和 attack-function 指定的 MythicMobs 技能 | 使用 MythicMobs 技能时需要 |
DragonCore | 读取龙核槽位、注册按键、触发按键技能、绑定模型和播放动作 | 使用龙核功能时需要 |
GermPlugin | 读取萌芽槽位、注册按键和触发按键技能 | 使用萌芽功能时需要 |
插件还包含以下槽位接口。只有在 plugin-slot 选择对应格式时，才需要安装相应插件：
| 槽位来源 | plugin-slot 格式 |
|---|---|
| Minecraft 原版背包 | Minecraft#槽位ID |
| DragonCore | DragonCore#槽位名 |
| GermPlugin | GermPlugin#槽位名 |
| LyInventoryReload | LyInventoryReload#背包#类型 |
| LyInventory | LyInventory#背包#类型 |
| MXSAttributeInventory | MXSAttributeInventory#背包#格子ID |
| PXRPG | PXRPG#类型#背包ID#槽位 |
| APInventory | APInventory#分页ID#槽位ID |
| YeeJewelry | YeeJewelry#背包ID#槽位 |
项目没有使用 MySQL 存储，也没有 LyMySQLCore 接口，因此不需要安装 LyMySQLCore。
功能
宠物识别与召唤
| 功能 | 说明 |
|---|---|
| 指定槽位读取 | 从 plugin-slot 指定的原版背包或第三方背包槽位读取物品。 |
| 显示名称匹配 | 只处理拥有物品显示名称的物品，并使用显示名称匹配宠物。 |
| 精确匹配 | identity-match-contains: false 时，物品显示名称必须与 identity 完全一致。 |
| 关键词匹配 | identity-match-contains: true 时，物品显示名称中包含 identity 即可匹配。 |
| 按键召唤 | DragonCore 或 GermPlugin 启用后，可通过 show-and-hide-key 切换宠物状态。 |
| 指令召唤 | 玩家可通过 /lycw common 执行与召唤按键相同的切换操作。 |
| 背包刷新 | 玩家关闭背包时，插件重新检查槽位中的宠物物品。 |
| 自动切换 | 宠物显示期间，如果槽位匹配到另一份宠物配置，插件会切换当前宠物。 |
| 自动隐藏 | 宠物显示期间，如果槽位不再匹配任何宠物，插件会隐藏当前宠物。 |
跟随与移动
| 功能 | 说明 |
|---|---|
| 路径跟随 | 插件记录玩家或战斗目标的移动路径，宠物依次沿路径点移动。 |
| 动态加速 | 宠物与目标距离增加时会提高移动速度，缩短追赶时间。 |
| 平滑转向 | 宠物移动时会逐步调整身体朝向，攻击时会看向目标。 |
| 待机距离 | 宠物进入 standby-distance 范围后停止继续靠近。 |
| 远距离传送 | 距离超过 teleport-distance 时，宠物会传送到目标附近。 |
| 安全位置查找 | 传送或路径修正时，会向下检查可站立方块和上方空间。 |
| 跨世界处理 | 玩家与宠物不在同一世界时，旧实体会被删除并在玩家所在世界重新创建。 |
| 召唤移动延迟 | 宠物召唤后会短暂延迟移动，用于减少模型刚生成时的动作卡顿。 |
| 刷新频率 | move-update-tick 控制每次移动更新的间隔，最小按 1 tick 处理。 |
自动攻击
| 功能 | 说明 |
|---|---|
| 攻击目标记录 | 玩家攻击生物时，该生物会成为宠物目标。 |
| 防御目标记录 | 玩家受到生物攻击时，攻击者也会成为宠物目标。 |
| 追击范围 | 目标无效、切换世界或离主人超过 track-range 后停止追击。 |
| 攻击距离 | 宠物与目标距离小于 attack-range 时进入攻击状态。 |
| 攻击间隔 | attack-speed 使用 tick 作为单位。 |
| 原版攻击 | attack-function: attack 时，由宠物主人执行 Minecraft 1.12 R1 原版攻击。 |
| 技能攻击 | attack-function 填写其他内容时，将其作为 MythicMobs 技能 ID 执行。 |
| 攻击动作 | 配置 attack-animation-id 后，可在攻击时播放 DragonCore 模型动作。 |
宠物技能
| 功能 | 说明 |
|---|---|
| 左键与右键 | 支持主人左键或右键时触发技能。 |
| 定时技能 | 每秒按照配置概率检查 TIME#概率 技能。 |
| 攻击技能 | 主人造成伤害时，按照 ATTACK#概率 检查技能。 |
| 受伤技能 | 主人受到伤害时，按照 DAMAGED#概率 检查技能。 |
| DragonCore 按键 | 使用 SLOT-DRAGON#按键 监听龙核按键。 |
| GermPlugin 按键 | 使用 SLOT-GERM#按键 监听萌芽按键。 |
| MythicMobs 技能组 | 单次触发可以按顺序执行多个 MythicMobs 技能 ID。 |
| 技能中心 | MythicMobs 技能原点可以选择玩家位置或宠物位置。 |
| 条件判断 | 支持 PlaceholderAPI 变量、四则运算、数值比较、文本相等比较、&& 和 ` |
| 动态冷却 | 冷却单位为秒，可以包含 PlaceholderAPI 变量、括号和四则运算。 |
| 冷却消息 | 支持冷却中提示和冷却结束提示，并替换 {id}、{time}。 |
| 技能动作 | 技能触发时可以播放 DragonCore 模型动作。 |
| 技能命令 | 技能触发后可以使用玩家、临时 OP 或控制台身份执行命令。 |
交互、模型与变量
| 功能 | 说明 |
|---|---|
| Shift 交互 | 玩家潜行并与自己的宠物交互时，可以执行 shift-right-command 中的命令。 |
| 交互冷却 | shift-right-command-cooldown 控制交互命令的触发间隔，单位为毫秒。 |
| DragonCore 模型绑定 | 宠物生成后读取 DragonCore 缓存中的 EntityModel.yml，使用顶层节点的 entity 名称匹配宠物显示名称并绑定模型。 |
| 模型名称匹配 | 模型绑定时会移除颜色后进行包含匹配，第一个匹配的节点生效。 |
| PlaceholderAPI 变量 | 提供当前宠物实体 UUID 和显示名称变量。 |
| 玩家资源清理 | 玩家退出时删除宠物实体，并取消跟随、路径记录等任务。 |
指令
| 指令 | 执行者 | 说明 |
|---|---|---|
/lycw | OP | 显示插件可用指令。非 OP 执行时不会显示帮助内容。 |
/lycw reload | OP | 重载全局配置、按键注册、宠物配置和定时技能任务。 |
/lycw common | 玩家 | 显示或隐藏当前宠物，效果与配置的召唤按键相同。 |
项目没有定义 Bukkit 权限节点。管理功能直接检查执行者是否为 OP，不应配置未经项目定义的权限。
全局配置入口
全局配置文件位于 plugins/LyPet/config.yml。
| 配置项 | 作用 |
|---|---|
plugin-slot | 指定读取宠物物品的槽位来源和槽位参数。 |
show-and-hide-key | 指定 DragonCore 或 GermPlugin 的宠物显示、隐藏按键。 |
register-keys | 注册可以被宠物技能监听的 DragonCore 或 GermPlugin 按键。 |
move-update-tick | 设置宠物移动更新间隔，单位为 tick。 |
默认配置结构：
yaml
plugin-slot: 'Minecraft#8'
show-and-hide-key: 'V'
register-keys:
- 'Z'
move-update-tick: 5完整说明见：全局配置。
宠物配置入口
宠物配置放在 plugins/LyPet/pet/ 下。插件会递归读取目录及其子目录中的所有 .yml 文件。
每份配置必须提供全局唯一的 id。如果多个文件使用相同 ID，后读取到的重复配置不会载入，并会在控制台输出读取失败信息。
| 配置分组 | 主要配置项 |
|---|---|
| 基础识别 | id、identity、identity-match-contains、show-name、entity-type |
| 跟随移动 | follow-speed、teleport-distance、standby-distance |
| 自动攻击 | auto-attack-enable、track-range、attack-range、attack-speed、attack-function |
| 攻击动作 | attack-animation-id、attack-animation-speed |
| Shift 交互 | shift-right-command-cooldown、shift-right-command |
| 宠物技能 | skill 下的事件、条件、冷却、技能、动作、原点和命令配置 |
宠物显示名称 show-name 支持 {player}，生成实体时会替换为宠物主人的玩家名。颜色代码使用 & 编写，读取时会转换为 Minecraft 颜色符号。
PlaceholderAPI 变量
PlaceholderAPI 启用后，插件注册变量前缀 lycw。
| 变量 | 返回内容 |
|---|---|
%lycw_uuid% | 当前宠物实体的标准化 UUID；没有宠物实体时返回空字符串。 |
%lycw_name% | 当前宠物实体的显示名称；没有宠物实体时返回空字符串。 |
变量详情见：插件变量。
运行机制
- 玩家加入服务器时，插件为该玩家创建宠物缓存，初始状态为隐藏。
- 玩家使用召唤按键或
/lycw common后，插件读取plugin-slot指定的槽位。 - 插件检查槽位物品是否存在显示名称，并按精确或包含方式匹配
identity。 - 匹配成功后，插件通过 Adyeshach 创建临时公共实体，设置名称、名称可见状态和随机观察控制器。
- DragonCore 启用时，插件会在宠物生成后尝试根据
EntityModel.yml绑定对应模型。 - 插件启动路径记录与跟随任务，使宠物沿玩家或战斗目标的移动路径前进。
- 玩家攻击生物或受到生物攻击时，插件记录战斗目标；启用自动攻击后，宠物会追击并攻击该目标。
- 技能触发前会依次检查宠物显示状态、触发条件和技能冷却，检查通过后执行动作、MythicMobs 技能与命令。
- 玩家关闭背包时，插件重新匹配槽位；物品移除时隐藏宠物，匹配结果变化时切换宠物配置。
- 玩家退出服务器时，插件删除宠物实体、取消移动任务并移除玩家缓存。
注意事项
entity-type必须是 AdyeshachEntityTypes能识别的名称。填写错误时会在控制台报错，并回退为PIG。- 使用
attack-function: attack时，服务端必须与项目中的 Minecraft 1.12 R1 NMS 实现兼容。 attack-function填写 MythicMobs 技能 ID，或在skills中配置技能时，需要安装并正常启动 MythicMobs。- DragonCore 与 GermPlugin 的按键格式不同。DragonCore 通常填写键盘字符，GermPlugin 使用对应的
KeyType名称。 register-keys只负责注册技能按键；召唤按键由show-and-hide-key单独注册。SLOT-DRAGON#按键和SLOT-GERM#按键使用的按键也应出现在register-keys中。- 宠物物品必须拥有显示名称，否则不会参与
identity匹配。 - 技能条件只实现
>、>=、==、<=、<，没有!=运算符。 - 交互与技能命令会先通过 PlaceholderAPI 解析，再根据命令前缀选择执行身份。
- 插件没有 MySQL 存储功能，不需要安装 LyMySQLCore。
页面索引
| 页面 | 内容 |
|---|---|
| 全局配置 | config.yml 的槽位、召唤按键、技能按键和移动刷新配置 |
| 宠物配置 | 宠物识别、实体、跟随、自动攻击、交互和攻击动作配置 |
| 宠物技能 | 技能事件、概率、条件、冷却、原点、动作、命令和 MythicMobs 技能配置 |
| 插件变量 | PlaceholderAPI 变量及返回值 |
| 常见问题 | 依赖、版本、槽位匹配、召唤、模型、攻击和技能问题排查 |
| 更新日志 | 文档更新记录 |