配置说明

2.3.2 主动攻击名称与旧默认文案迁移

宠物设置按钮、默认说明及开启、关闭和保存失败提示统一为“主动攻击”。原官方默认名称和消息按完整字符串匹配迁移，按钮说明按完整列表匹配；任一行被修改则保留整份自定义说明。缺失项继续补齐，服主自定义文字与颜色不会批量替换。

pet-auto-attack-enabled 旁的旧官方说明注释在忽略空行后仍须逐字匹配，管理员注释文字保留。忽略空行只适用于该注释，不用于按钮 lore 或消息值。

配置键 manage.actions.auto-attack、behavior.auto-attack.enabled、动作、变量与 pet-auto-attack-* 消息键继续沿用，不修改数据库结构或每宠开关选择。详见 2.3.2 迁移与升级说明。

2.3.1 模型主驾驶与换乘

2.3.1 不新增骑乘配置项，保留管理员的等级、速度、模型和权限设置。多模型宠物使用 ModelEngine 指定的主驾驶管理器；完全没有驾驶骨时继续使用原版载体骑乘。有驾驶骨但主驾驶关系缺失、主座位拒绝上马，或旧模型座位未释放时，LiPet 会拒绝此次挂载。

ModelEngine 使用虚拟座位，Bukkit getVehicle() 为空是正常实现方式。MM 直接触发模型上马时同样检查未解除的旧模型关系。配置及升级边界见 2.3.1 更新说明。

2.3.0 MythicMobs 双向集成

MM 技能现在可用 @LipetOwner 选择施法宠物的主人，以 lipetExperience{amount=25} @self 给宠物提交经验奖励，并通过 <lipet.level>、<lipet.damage>、<lipet.max_health>、四维属性与品质 ID 读取 LiPet 档案。未安装 MCPets 时同时提供 @PetOwner 和 petExperience{exp=25} 兼容名称。

现有 mythic-skills 的等级解锁、trigger 和 power 保持原行为；MM 使用 <skill.power> 获取传入值。MM damage 默认还会自动乘一次 power，显式引用它时需设 poweraffectsdamage=false 避免重复。伤害数值不等于 <pet.damagemodifier> 倍率，其他 MCPets 专属机制仍需按包核对。详见 双向集成指南 和 2.3.0 更新说明。

2.2.5 GUI 标题支持 PlaceholderAPI 变量

宠物主菜单、商城、仓库、信息、管理、放生确认及独立背包的标题，统一支持 PlaceholderAPI 的 %变量% 与原有 LiPet <变量>。例如管理菜单标题可写成 <gold><pet_name></gold> · %player_name%；PAPI 按打开菜单的玩家解析，查看他人宠物时也是查看者上下文。

保留原有 MiniMessage 颜色、<font:命名空间:字体> 与 Unicode 字符；未安装 PAPI、变量未知或解析异常时保留原文并继续打开菜单。现有标题配置不被覆盖，修改配置后执行 /lipet reload 并重新打开菜单；升级 Jar 仍需正常重启。

详见 2.2.5 GUI 标题变量说明。

主动攻击开关（2.2.4 起提供）

玩家在宠物管理菜单调整的是每只宠物的存档设置，默认开启，SQLite / MySQL 会分别保存。GUI 按钮外观位于 gui.yml 的管理菜单，状态和操作提示使用 messages.yml；缺失项按原机制补齐，2.3.2 另迁移精确匹配的旧默认文案；现有自定义值与注释保留。

物种的 behavior.auto-attack.enabled 仍由管理员控制。玩家开启主动攻击不能绕过禁用的物种主动索敌，也不能越过主人、友方及区域保护。详见 2.2.4 行为与升级说明。

死亡惩罚（0.27.24）

config.yml 新增 death-penalty.enabled（布尔，默认 true）、levels-lost（整数 0-10000，默认 1）、minimum-level（整数 1-10000，默认 1）。修改后 /lipet reload 生效。实际掉级会清空当前级经验并扣回相应属性点，见 完整配置示例和边界。

本页从 LiPet 0.27.20-SNAPSHOT 完整 Wiki 同步整理；需要连续查阅全部功能时，请返回 LiPet 完整 Wiki。

0.27.20 喂食冷却配置

feeding:
  # 同一只宠物两次成功喂食之间的冷却秒数，支持小数，取值范围 0-60。
  # 设为 0 可关闭；修改后执行 /lipet reload 生效。
  cooldown-seconds: 1.0

冷却提示位于 messages.yml -> pet-feed-cooldown，支持 <seconds> 剩余秒数变量。旧配置只补缺失节点和中文注释，不覆盖管理员已有值。

0.27.14 原版专属食物

新安装会按 Paper 26.2 原版食物标签生成专属物品。主要修正为：CAMEL_HUSK -> RABBIT_FOOT、PIGLIN/PIGLIN_BRUTE -> COOKED_PORKCHOP、SULFUR_CUBE -> SLIME_BALL、WOLF -> COOKED_BEEF、ZOMBIE_HORSE -> RED_MUSHROOM、ZOMBIE_NAUTILUS -> PUFFERFISH。狼模板用熟牛肉和熟鸡肉；猫模板用生鳕鱼和生鲑鱼。

旧服的 growth.foods 被视为管理员配置，不会自动改名或删除。请备份对应宠物文件，手动替换节点并执行 /lipet reload。完整表格见 0.27.14 更新日志。

0.27.13 默认喂食经验

官方普通食物、CraftEngine 案例、狼猫模板、原版商城模板和新生成原版宠物的 growth.foods.*.experience 默认统一为 4。默认最弱目标的战斗经验约为 6，20 点生命目标为 15。升级不覆盖旧服已有食物数值；需要采用本次平衡时手动改为 4 并执行 /lipet reload。

0.27.11 原版宠物食物与失败提示

官方原版宠物文件完全缺少 growth.foods 时会按物种补全。例如烈焰人生成启用的 BLAZE_POWDER，并把继承的 COOKED_BEEF 设为 enabled: false。已有 growth.foods 和自定义宠物不修改。

messages.yml 会补入以下根节点，现有自定义文本保留：

# 战斗经验未成功写入数据库时提示在线主人。
pet-combat-experience-save-failed: "<red>宠物战斗经验暂时无法保存，请联系管理员检查数据库。</red>"

0.27.9 商城、飞行骑乘与回收配置

messages.yml 新增三个根节点。旧文件只补缺失项和中文注释，已有文本及空字符串保留：

# 宠物道具商城余额不足；宠物商城继续使用 shop-insufficient-funds。
item-shop-insufficient-funds: "<red>余额不足，无法购买该道具。</red>"
# 回收超过 100 tick 时仅提示一次；设为空字符串可关闭。
pet-store-pending: "<yellow>正在保存并回收宠物，请稍候，无需重复操作。</yellow>"
# 只说明结果提示异常，需重新打开仓库确认实际状态。
pet-store-feedback-failed: "<yellow>宠物回收结果提示异常，请重新打开仓库确认状态，并联系管理员查看后台日志。</yellow>"

pet-types.yml -> defaults.behavior 新增疾跑倍率，单宠物文件可覆盖，范围 1.0-3.0：

behavior:
  riding-speed: 0.35
  # 按住疾跑键后的速度倍率。
  riding-sprint-multiplier: 1.5

0.27.8 召唤等待与异常提示

以下是 plugins/LiPet/messages.yml 的根节点，合并到原文件即可，不要放到 config.yml，也不要复制出一个额外的 messages: 父节点：

# 未完成超过 100 tick（正常 TPS 下约 5 秒）时仅提示一次；设为 "" 可关闭。
# 支持 MiniMessage。此提示不会取消召唤、提前解除状态锁或重复生成宠物。
pet-call-pending: "<yellow>正在召唤宠物，请稍候，无需重复操作。</yellow>"
# 原有召唤业务失败消息；管理员已自定义的内容保留。
pet-call-failed: "<red>宠物召唤失败，请稍后重试。"
# 仅说明结果文本或反馈发送异常，宠物可能已成功生成，应先检查实际状态。
pet-call-feedback-failed: "<yellow>召唤结果提示异常，请先检查宠物状态，并联系管理员查看后台日志。</yellow>"

普通快速召唤不增加等待提示。旧配置只补缺失节点和中文注释，自定义文本与空字符串不会覆盖；完成换用 0.27.8 Jar 并重启后，后续修改文本可执行 /lipet reload。旧版本的重载不会清除已经卡住的玩家操作队列，升级与根因见 召唤无响应修复。

0.27.5 新增配置与行为

新增 model.levels 等级模型、capture.yml -> vanilla-random-attributes 捕捉四属性范围，以及 shop.yml -> item-entries.*.item.capture-ball 捕捉球商品。旧固定模型和普通商品仍兼容；缺失配置会自动补齐。

完整示例见 等级模型、随机属性与捕捉球商店。

3. 配置文件

文件	用途
config.yml	存储、服务器 ID、群组、依赖下载、喂食冷却、内置货币与三种货币显示名称
pet-types.yml	defaults 公共默认值、宠物目录、原版自动注册、名牌、骑乘和背包全局设置；兼容旧 types 节点
宠物/**/*.yml	每只宠物的身份与差异项；递归读取，目录、子目录和文件名均可用中文，也可直接读取 MCPets 单宠物格式
shop.yml	商城总开关、宠物商城和宠物道具商城
gui.yml	GUI 标题、尺寸、槽位、留白/边框、图标、点击动作与音效
capture.yml	捕捉球、捕捉概率、捕捉仪式、音效、粒子、实体映射
skills.yml	技能书、技能等级、技能效果
items.yml	宠物信号棒等 LiPet 功能物品
rewards.yml	每日、战斗、升级、捕捉宠物币奖励与反馈效果
messages.yml	所有玩家提示文本

所有文本建议使用 MiniMessage 格式。插件会自动补全新增配置节点，不会覆盖已有自定义值。

主菜单“我的宠物”入口

gui.yml 的 main.buttons.warehouse.name 默认显示“我的宠物”，main.buttons.warehouse.lore 的最后一行显示“➥ 点击打开宠物列表”：

main:
  buttons:
    warehouse:
      name: "<gradient:#FFB74D:#FFF59D><bold>我的宠物</bold></gradient>"
      lore:
        - "<gradient:#FFD180:#FFF59D>➥ 点击打开宠物列表</gradient>"

点击后仍进入 nav:warehouse 宠物列表，列表页面标题继续使用“宠物仓库”。升级时插件只精确迁移官方旧按钮名称和完整旧 Lore；服主自定义文本不会被覆盖。

仓库四键操作

仓库宠物图标的四种操作可分别配置，默认值为：

warehouse:
  pet-item:
    actions:
      LEFT: "call:<pet_id>"
      RIGHT: "info:<pet_id>"
      SHIFT_LEFT: "store"
      SHIFT_RIGHT: "delete-request:<pet_id>"

对应含义为左键召唤、右键管理、潜行左键收回当前宠物、潜行右键打开放生确认。升级只迁移官方旧 Lore、注释和旧默认动作；服主自定义值保持不变。

默认 warehouse.pet-item.lore 将两条潜行操作显示为绿色，并在空行后独立显示红色永久删除警告：

- "<green>潜行左键</green><gray> · 召回宠物</gray>"
- "<green>潜行右键</green><gray> · 放生宠物</gray>"
- ""
- "<red>⚠放生会永久删除全部数据</red>"

已有活动宠物时再次召唤使用 messages.yml 的 pet-already-active：

pet-already-active: "<yellow>已达最大召唤数量，请将已召唤的休息后再召唤！</yellow>"

升级时会自动迁移历次官方默认值和 Bukkit 自动折行后的旧文本；服主自己修改过的内容不会被覆盖。

管理二级面板返回按钮

从宠物管理页进入“完整属性”或“成长与加点”时，属性面板使用 gui.yml 的 info.navigation.manage：

info:
  navigation:
    manage:
      enabled: true
      slot: 49
      slots: []
      material: "CHEST"
      name: "<aqua>返回管理界面</aqua>"
      lore:
        - "<dark_gray>◆ 界面导航</dark_gray>"
        - "<gray>返回 <white><pet_name></white> 的管理界面</gray>"
        - ""
        - "<aqua>➥ 点击返回管理界面</aqua>"
      action: "manage-return:<entity_id>"

从仓库或指令打开属性面板时继续使用 info.navigation.warehouse。两个按钮均可独立修改材质、位置、名称、Lore 和动作；旧服只会自动补充缺失的管理返回节点，不覆盖已有配置。

货币显示名称（0.27.6）

shop.yml 中的 INTERNAL、VAULT、PLAYERPOINTS 是支付提供器 ID，请继续保留这些英文 ID。宠物商城和道具商城的 <currency> 显示文字统一由 config.yml 配置：

# config.yml：只合并货币显示设置，保留现有其他配置。
# 显示名称只影响文字，不改变支付提供器、余额或商品价格。
currency:
  # 对应 shop.yml 的 currency: INTERNAL。
  internal:
    # 非空单行文本，支持 MiniMessage；默认显示“宠物币”。
    display-name: "宠物币"
  # 对应 shop.yml 的 currency: VAULT，需安装 Vault 和经济插件。
  vault:
    # 非空单行文本，支持 MiniMessage；默认显示“金币”。
    display-name: "金币"
  # 对应 shop.yml 的 currency: PLAYERPOINTS，需安装 PlayerPoints。
  playerpoints:
    # 非空单行文本，支持 MiniMessage；默认显示“点券”。
    display-name: "点券"

例如商品使用 price: 100.0、currency: "PLAYERPOINTS" 时，默认显示 100.00 点券；本次更新只修复名称，价格仍保留两位小数，PlayerPoints 仍要求整数金额。若自定义 Lore 直接写死了 PlayerPoints，请把那段文字改成 <currency>。

名称配置不会替代前置插件：提供器未挂钩、不可用或 ID 未知时，商城继续显示大写 ID 供管理员排查，购买仍会被拒绝。

首次升级需要停服、换入 LiPet-0.27.6-SNAPSHOT.jar 后重启一次。此后修改上述名称，执行 /lipet reload 并等待成功，再关闭并重新执行 /lipet shop 或 /lipet itemshop 即可看到新名称；原来已经打开的菜单不会自动重绘。内置货币名称也会同步到余额指令和奖励提示。

只有候选主配置验证通过、普通配置重载和数据库处理成功后才应用新名称；配置错误、数据库重载失败或并发重载被拒绝时保留旧名称。旧文件只补缺失的名称节点和注释，管理员已有自定义值不覆盖。server.id、服务器群组 server.group 和 currency.internal.initial-balance 仍按启动时读取，名称热更不会改变这些设置，数据库继续遵守原有热切换规则。

capture.yml、skills.yml、items.yml、shop.yml 与 gui.yml 的物品 material 均可填写 CraftEngine 完整 ID。全部入口、失败回退与自检方法见 CraftEngine 完整物品挂钩。

0.27.4 起默认配置直接提供两个安全关闭的 CE 案例：

# capture.yml
balls:
  craftengine_example:
    enabled: false
    material: "yourpack:pet_capture_ball"

# pet-types.yml
defaults:
  growth:
    foods:
      craftengine_example:
        enabled: false
        item-id: "yourpack:pet_food"
        display-name: "灵契宠物粮"
        experience: 4
        healing: 8.0

把 yourpack:* 改为真实的 CE 完整 ID，再将 enabled 改为 true 并执行 /lipet reload。关闭的节点会在校验占位 ID 前跳过，未安装 CraftEngine 的服务器也能保留案例；升级只补缺失节点，不覆盖管理员已有物品和数值。

8. 宠物类型

pet-types.yml 使用以下全局目录设置：

type-files:
  enabled: true
  directory: "宠物"
  include-subdirectories: true

目录中可放多个 .yml 或 .yaml，默认递归读取子目录。新服会为默认捕捉规则允许的全部原版生物生成 宠物/原版宠物/<中文名>.yml，并生成 宠物/自定义宠物/正义工作室/龙骑/龙骑-普通.yml。已有类型、文件、数值和注释不会覆盖；仅存在旧官方 宠物类型/ 时会安全迁移为 宠物/，新旧目录同时存在时不会擅自合并。

所有宠物相同的配置统一写一次：

defaults:
  attributes:
    base-health: 20.0
    base-damage: 3.0
    movement-speed: 0.25
  behavior:
    follow-distance: 10.0
    stop-distance: 3.0
    teleport-distance: 30.0
    mountable: true
    mount-type: "AUTO"
  inventory:
    size: 54

宠物/原版宠物/狼.yml 只写不同部分：

types:
  wolf:
    inherit-defaults: true
    entity-type: "WOLF"
    display-name: "狼"
    legacy-ids:
      - "wolf"
      - "minecraft:wolf"
      - "vanilla_wolf"
    attributes:
      base-health: 30.0

说明：

• 单宠节点深层覆盖 defaults；只改 base-health 不会丢掉其他公共属性。
• inherit-defaults: false 可关闭继承；显式空节点如 mythic-skills: {} 可清空公共段。
• 合并只发生在内存中，不会把公共值展开写回每只宠物的文件。
• 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 时只会在主人落地且未飞行、未滑翔时安全回传；回传带有短冷却，避免异步传送失败时连续刷传送。
• 原生寻路连续拒绝路径时，宠物会在主人安全落地后回传，不会停在原地，也不会使用速度强拖穿过障碍。

MCPets 自定义宠物

MCPets 单宠物 YML 可以不改结构，直接复制到中文子目录：

plugins/MCPets/Pets/justice_studios/dragon_mounts/dragon-mounts-normal.yml
→ plugins/LiPet/宠物/自定义宠物/正义工作室/龙骑/龙骑-普通.yml

Id: pet_dragon_mounts
Enabled: true
MythicMob: dragon-mounts-red
EntityType: PHANTOM
Mountable: true
MountType: flying
Distance: 6
ComingBackRange: 15
Icon:
  Name: "龙骑"

• 当前主要直接执行 Id、Enabled、MythicMob、EntityType、Name / Icon.Name、Mountable、MountType、Distance 和 ComingBackRange。
• MythicMob 通过 MythicMobs 生成；MountType: flying 使用飞行骑乘，walking 使用地面骑乘。
• SpawnRange 会被读取保留，但本版仍在主人位置生成，不按该半径随机偏移。
• Permission、Signals、Skins、DismountOnDamaged、DespawnOnDismount、AutoRide 暂不执行，但原文件无需删除这些节点。
• 适配只在内存中进行，不改写复制进来的 MCPets 文件。

MythicMobs 等级技能

技能放在对应宠物类型节点内，例如 宠物/原版宠物/狼.yml 的 types.wolf：

mythic-skills:
  level-10-bite:
    enabled: true
    skill: "LiPetWolfBite"
    trigger: "PET_ATTACK"
    unlock-level: 10
    chance: 0.35
    cooldown-seconds: 8.0
    power: 1.0
    power-per-level: 0.05

• skill 必须与 MythicMobs 中的内部技能名完全一致。
• unlock-level 不能超过该宠物的 growth.maximum-level。
• trigger 支持 PET_ATTACK、PET_DEFEND、OWNER_ATTACK、OWNER_DEFEND、INTERACT、PASSIVE、INTERVAL。
• 最终 power = power + max(0, 等级 - unlock-level) × power-per-level。
• PASSIVE 与 INTERVAL 至少配置 0.5 秒冷却；其他触发器允许 0，但仍有短暂递归保护。
• MythicMobs 未安装时 LiPet 正常运行，/lipet status 会同时显示挂钩状态、含启用规则的宠物类型数和启用规则总数。
• 冷却判断先于概率抽取；PASSIVE 与 INTERVAL 每轮合并为一次扫描。
• MM 返回 false 时保留配置冷却，零冷却失败技能至少退避 1 秒；错误日志按技能名分别限频，避免错误配置刷屏。
• 反射挂钩兼容实例或静态 getAPIHelper()，以及 float / double power 七参数 API。
• 旧类型文件只补入带中文注释且默认关闭的示例，不覆盖自定义值；修改后执行 /lipet reload。

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 关联宠物实体；区块重新载入时会校验并恢复，传送导致挂载脱离时会自动重建，死亡、收回和放生时会同步删除，不写入宠物数据库。

9. 属性与成长

核心属性：

• 力量：增加攻击伤害
• 体质：增加生命与恢复
• 防御：增加伤害减免
• 敏捷：增加移动速度，并影响闪避等衍生属性

衍生属性：

• 最大生命
• 攻击伤害
• 伤害减免
• 暴击率
• 暴击伤害
• 闪避
• 击退抗性
• 吸血
• 生命恢复

成长配置位置：

growth:
  maximum-level: 50
  base-experience: 100
  experience-per-level: 25
  attribute-points-per-level: 3

宠物可通过喂食和战斗获得经验。升级后获得自由属性点，玩家可在 GUI 中加点。

属性与宠物状态的中文名称位于 messages.yml：

labels:
  unknown-pet: "未知宠物"
  attributes:
    strength: "力量"
    vitality: "体质"
    defense: "防御"
    agility: "敏捷"
  pet-states:
    stored: "已收回"
    active: "已召唤"
    transferring: "转移中"
    dead: "复活冷却"
    disabled: "已禁用"

属性加点消息可使用完整上下文变量，常用变量包括 <pet_name>、<attribute>、<attribute_key>、<previous_value>、<value>、<previous_points>、<points>、<strength>、<vitality>、<defense> 和 <agility>。<attribute> / <attribute_name> 是中文显示名，<attribute_key> 保留 STRENGTH 等稳定英文键，适合动作和外部插件。

0.27.19 新增 pet-attribute-no-points 与 pet-attribute-invalid-action。属性按钮继续使用 attribute:<pet_id>:STRENGTH，属性键不区分大小写；错误 UUID、缺少参数和未知属性会被安全拒绝。

10. 喂食

食物配置在对应的 宠物类型/*.yml 中；旧 pet-types.yml 写法继续支持：

foods:
  # 旧版 Bukkit Material 写法继续支持。
  COOKED_BEEF:
    display-name: "熟牛肉"
    experience: 4
    healing: 6.0
    attribute-points: 0
    minimum-level: 1
    maximum-level: 0

  # CraftEngine 物品必须填写完整 namespace:item_id。
  # 节点名只是管理员自定别名；使用 item-id 后也完整支持含点号的合法 ID。
  pet-biscuit:
    item-id: 'my.pack:pet.food'
    display-name: "灵宠饼干"
    experience: 4
    healing: 8.0
    attribute-points: 0
    minimum-level: 1
    maximum-level: 0

规则：

• 玩家手持配置的原版或 CraftEngine 食物右键自己的宠物即可喂食。
• 官方默认 experience 为 4，低于默认战斗经验；自定义食物仍可填写其他非负数。
• CraftEngine 物品按完整自定义 ID 精确识别；即使多个物品都以 PAPER 为底材，也只会匹配配置的那一个。
• 简单 CE ID 可直接作为节点名，例如 'default:pet_biscuit':；ID 含 . 时请使用普通节点别名并填写 item-id。
• CraftEngine 是可选软依赖。未安装时原版食物仍可使用，CE 食物配置会保留但不会匹配。
• 修改食物规则后执行 /lipet reload 即可生效；CraftEngine 自身重载物品后无需重启 LiPet，因为插件不会缓存物品实例。
• 不符合等级限制时不会消耗食物。
• 没有产生回血、经验或属性点效果时不会消耗食物。
• 数据保存失败时会退还食物。

11. 捕捉系统

管理员发放捕捉球：

/lipet captureball <类型> [数量] [玩家]

玩家手持捕捉球右键野生生物触发捕捉。

捕捉配置在 capture.yml：

ritual:
  enabled: true
  duration-ticks: 50
  pulse-interval-ticks: 10
  particle: "ENCHANT"
  sounds:
    start: "BLOCK_BEACON_ACTIVATE"
    pulse: "BLOCK_AMETHYST_BLOCK_CHIME"
    success: "ENTITY_PLAYER_LEVELUP"
    failure: "ENTITY_ITEM_BREAK"

兼容处理：

• 无效 Sound / Particle 不会禁用插件，会自动回退安全默认值。
• 疣猪兽、猪灵等跨维度僵尸化实体会做宠物保护。
• 怕阳光生物作为宠物时会防止白天自动燃烧。
• 缺少原版攻击 AI 的宠物会使用统一追击与近战攻击兜底。
• 同一种宠物默认只能拥有一只。

12. 宠物商城

商城总开关

shop.yml 顶层节点同时控制两个商城：

# 商城总开关。true=开放宠物商城和宠物道具商店；false=全部关闭。
# 关闭后 /lipet shop、/lipet itemshop、GUI 导航和已打开界面的购买操作都会被拒绝。
# 修改后执行 /lipet reload 即可立即生效，取值只能是 true 或 false。
enabled: true

• true：开放宠物商城和宠物道具商城。
• false：禁用商城指令、帮助入口、GUI 导航动作和已打开界面的购买操作。
• 修改后执行 /lipet reload 即时生效，不需要重启服务器。
• 旧配置缺少该节点时只补入 enabled: true 与中文注释，不覆盖商品、价格或自定义 Lore。
• 非布尔值属于配置错误，插件会拒绝应用本次错误重载。

宠物商城配置在 shop.yml 的 entries。

entries:
  wolf:
    enabled: true
    pet-type: "wolf"
    pet-name: "<gradient:#B0BEC5:#FFFFFF>小狼</gradient>"
    currency: "INTERNAL"
    price: 250.0
    permission: ""

支持货币：

• INTERNAL：LiPet 内置宠物币
• VAULT：Vault 经济
• PLAYERPOINTS：PlayerPoints 点券；价格必须填写整数

排行榜每页数量在主配置中调整：

leaderboard:
  page-size: 10

范围为 1-20。使用 /lipet top coin [页码] 查看宠物币榜，使用 /lipet top level [页码] 查看宠物等级榜。

如果玩家已经拥有该类型宠物，购买会被拒绝。

宠物币获取

0.26.6+ 默认提供四条可持续获取路径：

• /lipet daily：每个自然日领取一次；主菜单中央默认也有领取按钮。
• 宠物战斗：由已召唤宠物完成有效击杀，按“固定值 + 目标最大生命倍率”结算。
• 宠物升级：喂养或战斗升级成功并保存后，按实际提升等级数结算。
• 成功捕捉：捕捉结果保存成功后结算。

所有金额、每日上限、排除实体、重置时区、音效和粒子位于 rewards.yml。示例：

reset-time-zone: "Asia/Shanghai"
daily:
  enabled: true
  amount: 100.0
combat:
  enabled: true
  base-amount: 1.0
  maximum-health-multiplier: 0.10
  minimum-amount: 1.0
  maximum-amount: 20.0
  daily-limit: 300.0
level-up:
  enabled: true
  amount-per-level: 25.0
  daily-limit: 300.0
capture:
  enabled: true
  amount: 15.0
  daily-limit: 150.0

daily-limit: 0 表示对应玩法不限制每日额度。每日领取防重复与三种玩法额度存入 lipet_currency_reward，奖励记录和余额会在同一数据库事务中更新，因此同时点击、跨服并发、重启或执行数据库热切换都不会重复领取。群组服必须让所有子服使用相同的 reset-time-zone；存储层会拒绝比已记录日期更早的周期，避免服务器时钟或时区不一致被用于反复领奖。热切换只切换数据目标，不会自动迁移旧库记录，迁库前仍需完整导入数据库。

13. 宠物道具商城

道具商城配置在 shop.yml 的 item-entries。

item-entries:
  growth_food:
    enabled: true
    currency: "INTERNAL"
    price: 30.0
    item:
      material: "COOKED_BEEF"
      amount: 8

适合出售宠物食物、技能书材料或服务器自定义道具。

14. 宠物背包

命令：

/lipet inventory [宠物名称]

特性：

• 每只宠物独立背包。
• SQLite / MySQL 持久化。
• 关闭 GUI 时自动保存。
• 删除宠物时清理背包数据。
• inventory.size: 0 表示禁用。
• 背包大小必须是 9 的倍数，最大 54。
• 默认背包为 54 格（6 行）。inventory.minimum-size: 54 会让旧版 18 格配置以 54 格运行，同时保留管理员原来的类型配置值。

菜单音效位于 gui.yml 的 sounds 节点，可分别配置打开、有效按钮点击和关闭音效；设置 sounds.enabled: false 可全部关闭。

GUI 完整自定义

gui.yml 中每个界面均可独立设置标题、1-6 行尺寸、动态内容槽位和空槽填充。主菜单、宠物管理和放生确认默认使用 5 行；全部菜单默认使用 BORDER 边框填充，中央不会再被玻璃板铺满。

0.26.7+ 的默认 Lore 使用青蓝紫灵契主色，经济信息使用金色，危险操作使用红色，并按功能定位、详细说明和操作引导分层。商城商品 Lore 同样支持完全自定义，<price>、<currency>、<amount> 等变量均会保留。升级时只有与旧版默认文本逐行完全一致的 Lore 才会自动换成新样式；管理员自定义过任意一行都会原样保留。

填充模式：

• ALL：填满全部空槽。
• BORDER：只填菜单四周边框。
• NONE：不放置任何填充物。
• CUSTOM：只填 filler.slots 指定的槽位。

所有内置按钮和 custom-items 都支持：

• enabled：显示或隐藏。
• slot：按钮槽位。
• material、amount：材质与数量。
• custom-model-data、item-model：资源包模型标识。
• glow、hide-tooltip：附魔光效与提示隐藏。
• name、lore：MiniMessage 名称与描述。
• action：任意点击的默认动作。
• actions.LEFT、RIGHT、SHIFT_LEFT、SHIFT_RIGHT、MIDDLE、DROP：按点击方式覆盖动作。

常用动作：

action: "nav:warehouse"                # 打开插件内菜单
action: "command:balance"              # 执行 /lipet balance
action: "player-command:spawn"          # 玩家执行 /spawn
action: "console-command:give <player> apple 1"
action: "store"                         # 收回当前宠物
action: "close"                         # 关闭菜单

以下为 LiPet 内置 <变量>，按界面或元素的实际上下文应用于标题、填充物、名称、Lore 和点击动作；商品及属性按钮专属变量并不是所有标题都能使用：

• 全部界面：<player>、<player_name>、<player_uuid>。
• 宠物商城：<entry_id>、<pet_type>、<pet_type_id>、<pet_name>、<price>、<currency>、<permission>。
• 道具商城：<entry_id>、<item_type>、<item_name>、<amount>、<price>、<currency>、<permission>。
• 宠物界面：<owner_name>、<owner_id>、<pet_id>、<entity_id>、<pet_name>、<pet_type>、<pet_type_id>、<pet_state>、<pet_state_key>、等级、经验、四维属性和全部衍生属性变量。
• 属性按钮：额外提供 <attribute>、<attribute_name>、<attribute_key>、<value>、<attribute_value>、<points>。显示文本中的 <attribute> 为中文；旧版动作中的 <attribute> 仍按英文键替换，推荐新动作明确使用 <attribute_key>。

warehouse.pet-item.actions 默认提供四种独立操作：LEFT 召唤所选宠物、RIGHT 查看属性与管理、SHIFT_LEFT 收回当前宠物、SHIFT_RIGHT 打开放生二次确认。四项均可自由更换或留空禁用；放生入口只打开确认页，不会单击直接删除。默认 Lore 带有独立红色“⚠放生会永久删除全部数据”警告，只有官方旧默认 Lore、注释与动作会安全迁移，服主自定义内容不会被覆盖。

旧版紧凑默认布局会在升级时迁移到 5 行宽松布局；只要管理员改动过旧版行数或按钮槽位，就视为自定义布局并保留原值。其他新增节点只补缺项，不覆盖已有配置和值或注释。

19. PlaceholderAPI

可用变量：

%lipet_active_name%
%lipet_active_id%
%lipet_active_owner_id%
%lipet_active_owner_name%
%lipet_active_type%
%lipet_active_type_id%
%lipet_active_state%
%lipet_active_state_key%
%lipet_active_level%
%lipet_active_max_level%
%lipet_active_experience%
%lipet_active_required_experience%
%lipet_active_experience_percent%
%lipet_active_attribute_points%
%lipet_active_critical_chance%
%lipet_active_critical_damage%
%lipet_active_dodge%
%lipet_active_knockback_resistance%
%lipet_active_life_steal%
%lipet_active_strength%
%lipet_active_vitality%
%lipet_active_defense%
%lipet_active_agility%
%lipet_active_health%
%lipet_active_max_health%
%lipet_active_health_percent%
%lipet_active_damage%
%lipet_active_speed%
%lipet_active_riding_speed%
%lipet_active_resistance%
%lipet_active_regeneration%
%lipet_attribute_strength_name%
%lipet_attribute_vitality_name%
%lipet_attribute_defense_name%
%lipet_attribute_agility_name%
%lipet_pet_count%
%lipet_server_id%

active_state 返回 messages.yml 中配置的中文状态；active_state_key 返回 ACTIVE 等原始键。四个 attribute_*_name 变量返回可配置中文属性名称。没有活动宠物时，数值变量稳定返回 0 / 0.0，文本变量返回空文本，不会把未解析变量留在计分板上。

PlaceholderAPI 是软依赖。未安装时 LiPet 会跳过 PAPI Hook，不影响主体功能。 Paper 26.2 建议搭配 PlaceholderAPI 2.12.3+；LiPet 不调用其版本专用内部接口。