跟随、骑乘与战斗
每宠主动攻击开关、跟随与骑乘、战斗规则及兼容说明。
每只宠物的主动攻击开关
潜行空手右键自己的已召唤宠物，在管理菜单点击“主动攻击”即可切换。每只宠物独立保存，旧宠物和新宠物默认开启；召回、玩家重进与正常重启后保留选择。
关闭后清除当前目标，停止自动索敌、主人攻击援助、主人或宠物受击后的自动反击、原版自主仇恨、普通攻击与自动战斗技能，宠物继续跟随。开启仍遵守管理员物种配置和区域限制，不能绕过 behavior.auto-attack.enabled: false。
手动 /lipet skills cast <1|2|3> 继续使用原有冷却与合法目标校验；需要目标的技能没有合法目标时仍不可施放。详见 2.2.4 更新说明。
本页从 LiPet
0.27.20-SNAPSHOT完整 Wiki 同步整理；需要连续查阅全部功能时，请返回 LiPet 完整 Wiki。
0.27.20 玩家重进主人恢复
玩家未手动收回宠物便退出时，如果重进时活动实体仍存在，LiPet 会在宠物实体所属线程按档案中的主人 UUID 恢复狼、猫等原版驯服关系。区块重新载入和热重载使用同一恢复路径。鹦鹉继续不绑定原版主人，避免再次进入肩部数据。
0.27.15 快乐恶魂移动修复
成年快乐恶魂使用恶魂飞行控制器，但通用 Pathfinder 可能接受一条它无法稳定执行的地面路径。新版跟随与战斗会先停止快乐恶魂的旧路径，再由飞行速度接管；其他宠物仍保留原有寻路策略。
成年实体高 4 格，跟随与召回脚底目标改为主人上方 3 格，减少贴地和碰撞。骑乘任务还会同步快乐恶魂的身体 yaw，原地转向、持续前进后转头和多层模型座位继续每 tick 使用玩家当前视角。
0.27.12 Folia 名牌跨区安全刷新
宠物跨区域移动时，名牌刷新先检查实体是否属于当前区域线程；处于迁区临界点则交给宠物实体调度器在下一 tick 重试。异常分支不再调用 getPassengers() 或继续修改实体，因此不会把第二次 owning-region 异常抛出实体任务。
上马事件会立即记录隐藏状态，下马后一 tick 按最终乘客树校正；行为循环把已确认的骑乘结果直接传给名牌服务，仍兼容多层模型座位。已有 nameplate.hide-while-ridden 设置及下马恢复行为不变。
0.27.11 战斗经验结算
战斗宠物连续击杀时，同一只宠物在数据库写入期间积压的经验会合并为下一批保存；不同玩家各自保持操作顺序。回收和关服保存排在经验批次之后，revision 冲突会读取最新数据库记录后重试。保存失败会写控制台警告并通知在线主人，便于区分宠物币已到账与经验未保存。
0.27.10 最终移动速度
地面与飞行实体属性、跟随导航和战斗追击统一读取“基础速度 + 敏捷 + 速度技能”。成长加点后的属性刷新会重新应用技能速度，避免迅捷技能被覆盖；GUI 与 %lipet_active_speed% 也显示同一结果，最多保留三位小数。
8. 宠物类型
宠物类型的行为与骑乘参数默认继承 pet-types.yml -> defaults，不同项写在 宠物/ 目录的独立 YML；顶层 nameplate 与 riding 保存名牌和骑乘血条设置。
示例：
types:
wolf:
entity-type: "WOLF"
display-name: "狼"
enabled: true
owner-limit: 1
model:
provider: "NATIVE"
id: ""
hide-base-entity: true
override-hitbox: true
behavior:
follow-enabled: true
follow-distance: 10.0
stop-distance: 3.0
teleport-distance: 30.0
说明：
entity-type必须是当前 Paper 版本存在的 Bukkit 实体类型。owner-limit当前固定用于“一种宠物只能拥有一只”的限制。model.provider支持NATIVE、MODEL_ENGINE、CRAFT_ENGINE。model.hide-base-entity仅在外部模型提供器中生效；ModelEngine/MEG 建议保持true，它只隐藏原版载体外观，不会关闭宠物 AI。model.override-hitbox控制 ModelEngine 是否使用模型蓝图碰撞箱；它与隐藏原版外观是两个独立选项。auto-register-vanilla: true时会自动注册可生成的原版实体宠物类型。follow-distance是开始追赶距离，stop-distance是停止追赶距离；后者必须更小，避免宠物在临界点反复启停。- 超过
teleport-distance时只会在主人落地且未飞行、未滑翔时安全回传；回传带有短冷却，避免异步传送失败时连续刷传送。 - 鹦鹉等飞行宠物安全回传前会先清理双行 TextDisplay 名牌，异步传送完成或失败后立即在宠物当前位置恢复，避免宠物移动后文字停在旧地点。
- 原生寻路连续拒绝路径时，宠物会在主人安全落地后回传，不会停在原地，也不会使用速度强拖穿过障碍。
ModelEngine / MEG 模型
给宠物使用 ModelEngine 模型时，至少填写：
model:
provider: "MODEL_ENGINE"
id: "你的模型ID"
hide-base-entity: true
override-hitbox: true
hide-base-entity: true 会通过 ModelEngine 的载体可见性接口隐藏脚下的原版生物，同时继续使用该实体承载 LiPet 的 AI、寻路、属性与碰撞。不要用隐身药水代替这个选项。重复召唤、区块重新加载和宠物运行状态恢复都会复用已有同 ID 模型，不会再次叠加；修改模型配置后执行 /lipet reload，当前已召唤宠物也会在其实体线程刷新。若将 id 改成另一个模型，插件会先卸载本轮运行期记录的旧模型再挂载新模型。
ModelEngine 的显示版本同为 R4.1.0 时，不同构建支持的 NMS 版本仍可能不同。Paper 26.x 必须安装包含 Java 25 / 26.x NMS 适配层的更新构建；若控制台出现 Unsupported NMS Version: 26.1.2 或类似错误，是当前 ModelEngine 构建不支持服务端版本，应先升级 ModelEngine。LiPet 不会把 ModelEngine 打进自身 Jar。
双行宠物名牌
召唤后的宠物默认使用两行头顶文字：第一行是宠物名称，第二行是主人玩家名。配置位于 pet-types.yml 顶层：
nameplate:
enabled: true
owner-line: "<gradient:#7DD3FC:#C4B5FD>主人：</gradient><white><owner_name></white>"
vertical-offset: 0.55
view-range: 1.0
line-width: 200
text-opacity: 255
shadowed: true
see-through: false
default-background: false
background-color: "#00000000"
# true：骑乘时对所有玩家隐藏；false：骑乘时保留名牌显示。下马后恢复。
hide-while-ridden: true
riding:
hide-boss-bar-while-ridden: true
owner-line支持 MiniMessage、RGB、渐变和<owner_name>占位符。enabled: false使用原版单行名称；单行回退也遵守骑乘隐藏规则。hide-while-ridden: true对骑手和其他玩家统一隐藏双行名牌，同时清空载体原版名称；false保留显示。下马或关闭隐藏并重载后恢复，普通上下马复用同一个 TextDisplay，不反复删除重建。riding.hide-boss-bar-while-ridden独立控制 Boss 血条，下坐骑后恢复；它不能代替名牌隐藏开关。- 修改后执行
/lipet reload，已召唤宠物会在下一轮行为刷新时自动应用新样式。 - 升级保留管理员已有的隐藏开关与注释。完整配置及转向说明见 0.27.7 骑乘名牌与视角转向。
- 名牌使用独立 PDC 关联宠物实体；区块重新载入时会校验并恢复，传送导致挂载脱离时会自动重建，死亡、收回和放生时会同步删除，不写入宠物数据库。
18. 骑乘
方式：
- 空手右键自己的已召唤宠物。
- 使用
/lipet mount。 - 使用信号棒骑乘模式。
0.27.7 起，上马立即启动每 tick 控制，使用骑手当前视角与按键，不再等待按键状态改变才更新朝向。不按移动键也可原地转头，持续按住前进键时转向会跟随最新视角；飞行骑乘同时使用当前俯仰。下马、退出或失效骑乘会清理控制任务，避免旧任务继续影响宠物。
0.27.9 起，每 tick 同时读取疾跑键。地面和飞行骑乘按 riding-sprint-multiplier 放大水平速度，飞行俯仰产生的升降速度使用同一倍率。宠物基础速度、敏捷成长和技能速度加成也会写入实体支持的 FLYING_SPEED；不具备该属性的实体会安全跳过。
骑乘期间临时关闭载体 aware，暂停原版 LookControl / MoveControl，避免下一 tick 把视角方向拉回或把俯仰清零。hasAI、坐下状态、实体物理和动作保持不变；下马、退出、异常或换骑后在实体区域恢复之前的感知状态。恢复会核对骑乘关系，旧任务不会在新一轮骑乘开始后误恢复。跟随、战斗和延迟回传也在实际执行前检查包含模型嵌套座位的骑乘状态，不覆盖骑手方向。
如果管理员在骑乘中主动调整 AI 或坐下状态，会保留新选择；恢复时不会强制写回旧快照。/lipet reload 同样检查真实骑乘关系，保留仍在骑乘宠物的坐下状态，不重新开启原版感知；名牌样式及隐藏开关仍可正常刷新。
末影龙的翅膀、头部和身体属于独立部件，LiPet 会循环解析回龙本体，因此空手右键骑乘和潜行右键管理都可正常使用。0.26.17+ 将末影龙稳定在 HOVER 阶段，避免原版阶段 AI 飞向末地传送门；飞行骑乘按视角俯仰升降，跳跃键主动爬升。
骑乘参数写在公共 defaults.behavior 或对应的 宠物/**/*.yml 差异配置中；Boss 血条隐藏总开关位于 pet-types.yml：
behavior:
riding-speed: 0.35
# 按住疾跑键后的倍率，允许 1.0-3.0。
riding-sprint-multiplier: 1.5
jump-velocity: 0.5
20. 兼容说明
宠物 AI 与坐下状态
宠物每次召唤都会恢复原版 AI、Mob 感知和站立状态。非骑乘宠物的行为循环会修复被外部模型插件或旧实体数据意外关闭的 AI；玩家主动切换为“坐下”时暂停，切回“跟随”时恢复。骑乘期间则保留 hasAI，临时关闭 aware 以停用原版方向控制，避免与骑手输入竞争；下马后恢复原感知状态。
狼、猫等可驯服实体在收回前会先解除原版主人、驯服和坐下状态，再移除世界实体，避免原版驯服数据把实体继续保留下来。鹦鹉使用 LiPet 自己的主人标记，不再绑定原版主人，因此新召唤的鹦鹉不会自动飞到玩家肩上。
对于升级前已经停留在肩上的鹦鹉，/lipet store、管理菜单收回、信号棒收回和玩家退出流程都会同时检查左右肩。肩部数据会在发起保存时先安全摘除；若数据库保存失败，插件会把原肩部实体恢复，保存成功后才彻底清理。因此不会再出现聊天提示“已收回”但肩上仍有鹦鹉的情况。
跟随逻辑每 10 tick 更新一次：宠物超过 follow-distance 后启动原生寻路，进入 stop-distance 后停止；两者之间保持已有路径，避免来回启停。超过 teleport-distance，或原生寻路连续四次拒绝路径时，只有主人已落地且没有飞行或滑翔才会安全回传；主人仍在空中时宠物会等待。
召唤时会为宠物安装高优先级移动与目标控制 Goal，原版闲逛、逃跑和自动仇恨不能再反向覆盖插件路径。全部地面宠物都由服务端原生 Pathfinder 绕开方块：跟随每 10 tick 更新落点，战斗每 10 tick 刷新路径、每 2 tick 检查攻击距离；路径不可达时会停止旧路径，不会把宠物直线拖过障碍。快乐恶魂因成年原生导航与飞行控制器组合不稳定，固定使用平滑飞行速度；其他飞行类在运行端确实没有可用路径时使用同一兜底。骑乘时快乐恶魂额外同步身体朝向；实际伤害仍由统一属性与攻击冷却计算。
文本样式
LiPet 会在最终写入前统一移除聊天消息、ActionBar、悬浮文本、GUI 标题与图标、捕捉球、技能书、信号棒和宠物名称的斜体装饰。根组件、嵌套组件和悬浮提示都会递归处理；即使旧配置使用 &o 或斜体标签，显示时也会强制转换为非斜体。
双行宠物名牌同样通过统一 MiniMessage 组件生成，宠物名和“主人”行都不会使用斜体。
Paper 26.1.2 / 26.2
LiPet 当前使用 Java 21 字节码构建，运行端推荐 Java 25。调度逻辑封装在 PlatformScheduler，业务层不直接散落调度调用。
活动宠物实体由加载索引维护。SQLite / MySQL 完成回调只读取线程安全状态，再把生命读取、属性刷新、召回和移除交给实体调度器；不会再从数据库线程调用区块实体查询。
0.26.11-SNAPSHOT 的 80 项自动测试已在默认兼容构建与 Paper 26.2 Profile 全部通过。同一 Java 21 成品 Jar 已在 Paper 26.1.2 Build 70 与 Paper 26.2 Build 111 使用 Java 25 完成真实启动、/lipet status、配置补全和安全关闭；26.1.2 还验证了 shop.yml 从 enabled: false 热重载为 true 后，帮助页商城入口立即恢复。
0.26.9-SNAPSHOT 同一通用 Jar 已在 Paper 26.1.2 Build 70 与 Paper 26.2 Build 111 搭配 CraftEngine 26.8-SNAPSHOT 完成真实运行探针：CE 物品 default:topaz_pickaxe 被识别为完整自定义 ID，同底材原版物品独立识别为 minecraft:golden_pickaxe，并成功命中 pet-types.yml 食物规则；72 项自动测试全部通过。
0.26.8-SNAPSHOT 同一通用 Jar 已在 Paper 26.1.2 Build 70 与 Paper 26.2 Build 111 完成真实启动及 ModelEngine R4.1.0 更新构建运行探针；真实 magecat 模型验证了原版载体不可见、重复挂载只有一份模型、卸载后载体恢复可见，68 项自动测试全部通过。0.26.7-SNAPSHOT 另已验证旧版 GUI/商城 Lore 自动迁移和优雅关服，管理员自定义 Lore 保持不变。
0.26.6-SNAPSHOT 同一通用 Jar 已在 Paper 26.1.2 Build 70 与 Paper 26.2 Build 111 完成真实启动、rewards.yml 加载、奖励表建表、每日指令注册、PlaceholderAPI 2.12.3 挂钩和优雅关服检查；SQLite 奖励事务另行验证了首次到账、同日防重、次日重置和余额同步，58 项自动测试全部通过。0.26.5-SNAPSHOT 已验证旧 messages.yml 中文名称节点增量补全和中文变量解析。0.26.4-SNAPSHOT 的 TextDisplay 双行主人名牌实体测试已验证实际生成、玩家名文本、重命名复用、透明背景和收回即时删除。0.26.3-SNAPSHOT 的历史验证包含旧版在线换库；2.2.2 起已改为数据库连接变更正常重启，不能再依照历史行为执行在线换库。
默认交付包使用最低兼容 API 构建，以便同一 Jar 继续运行于 Paper 26.1.2。项目提供锁定 26.2.build.111-stable 的 26.2 编译检查 profile：
mvn -Ppaper-26.2 clean package
plugin.yml 的 api-version 刻意保留为 1.21.11，它表示最低可加载版本，并不表示只支持 1.21.11；改成 26.2 会让 Paper 26.1.2 拒绝加载同一 Jar。
捕捉仪式的音效和粒子使用 Bukkit Registry 解析。配置既可继续填写 ENTITY_PLAYER_LEVELUP、ENCHANT，也可填写 minecraft:entity.player.levelup、minecraft:enchant；不存在的键会记录中文警告并回退到安全默认值，不会因此禁用插件。
0.25.7 起新写入的宠物背包使用 Bukkit ItemStack 字节格式。旧版本保存的对象流数据仍可读取，并会在宠物背包下次保存时自然迁移，不需要手工转换数据库。
外部依赖
Vault、PlaceholderAPI、ModelEngine、CraftEngine 等为软依赖或 provided 依赖，不会打入 LiPet Jar。CraftEngine 喂食识别只调用其官方稳定 bukkit.api 包中的 CraftEngineItems#getCustomItemId，不缓存物品实例，因此 CraftEngine 重载配置后仍会读取当前物品 ID。
SQLite / MySQL 驱动由运行时依赖管理器按配置下载到插件数据目录，不直接塞进成品 Jar。