等级模型、随机属性与捕捉球商店 - LiPet 文档

适用版本：LiPet 0.27.5-SNAPSHOT。修改配置后执行 /lipet reload，替换插件 Jar 则需要停服重启。

1. MEG 按宠物等级换模型

在 plugins/LiPet/宠物/ 下找到目标宠物的 YML，将下面的 model 放在该宠物类型中。保留已有实体类型、成长和食物配置，不要重复创建同名宠物 ID。

升级会自动生成默认禁用的 宠物/自定义宠物/ModelEngine等级模型示例.yml。也可直接编辑该案例，替换模型 ID 后再启用。

# 单个宠物类型；wolf 替换为当前文件中的真实类型 ID。
types:
  wolf:
    model:
      # 模型提供器；使用 ModelEngine 时填写 MODEL_ENGINE。
      provider: "MODEL_ENGINE"
      # 没有命中任何等级门槛时使用的模型；必须是已安装的真实蓝图 ID。
      id: "a"
      # 是否隐藏原版生物载体；true 隐藏，false 显示。
      hide-base-entity: true
      # 是否使用模型碰撞箱；true 使用，false 保留载体碰撞箱。
      override-hitbox: true
      # 等级门槛映射；取不超过当前等级的最高档，没有新档位则沿用上一档。
      levels:
        # 从 1 级开始使用此档模型。
        '1':
          # 已安装的 ModelEngine 模型 ID，区分大小写。
          id: "a"
        # 从 2 级开始使用此档模型。
        '2':
          # 同样需要替换成服务器真实存在的模型 ID。
          id: "b"

以上配置中：1 级显示 a，2 级及以上显示 b。若增加 '10': {id: "c"}，则 2–9 级显示 b，10 级及以上显示 c。门槛必须是 1 到该宠物 maximum-level 的整数。每档可覆盖 hide-base-entity 和 override-hitbox，不填写时继承基础模型设置。

喂养、战斗升级，以及重新召唤、区块恢复和配置重载均使用当前等级。旧配置不写 levels 时继续使用固定模型。模型切换错误会记录中文原因并尝试保留旧外观，不回滚已经获得的等级。

ModelEngine 和蓝图、客户端资源包需要自行安装；LiPet 不附带 a、b 模型。不要把此配置放进所有宠物共用的默认项，除非希望所有宠物都使用同一套模型。

2. 原版捕捉生成随机数值

默认对使用原版实体生成方式的捕捉宠物开启四属性随机：力量、体质、防御、敏捷分别在 0–5 内独立抽取整数，两端都包含。体质会影响初始最大生命，其他属性沿用已有攻击、减伤和速度计算。

随机结果在成功捕捉创建宠物时写入数据库。收回、重召唤、重载、重启和后续升级不重新抽取；两只宠物可能碰巧抽到相同数值。既有宠物不改值，宠物商城购买和管理员指令发放不随机。

具体开关与范围位于 capture.yml 的 vanilla-random-attributes，所有新节点带中文注释。设 enabled: false 时后续捕捉恢复为四项初始值 0；已经保存的随机值不会被清空。

# 原版捕捉初始属性；每项独立随机，范围包含两端，已有宠物不会改变。
vanilla-random-attributes:
  # true 开启随机；false 恢复四项初始值 0。
  enabled: true
  # 力量：影响攻击和相关战斗属性。
  strength:
    # 最小整数，0–10000，不能大于 max。
    min: 0
    # 最大整数，0–10000，与 min 相同时得到固定值。
    max: 5
  # 体质：影响生命与恢复。
  vitality:
    # 最小整数，0–10000，不能大于 max。
    min: 0
    # 最大整数，0–10000，与 min 相同时得到固定值。
    max: 5
  # 防御：影响减伤与击退抗性。
  defense:
    # 最小整数，0–10000，不能大于 max。
    min: 0
    # 最大整数，0–10000，与 min 相同时得到固定值。
    max: 5
  # 敏捷：影响速度、暴击与闪避。
  agility:
    # 最小整数，0–10000，不能大于 max。
    min: 0
    # 最大整数，0–10000，与 min 相同时得到固定值。
    max: 5

3. 商店出售真正的捕捉球

升级后默认 shop.yml 会补入 item-entries.basic_capture_ball：45 宠物币购买 3 个普通捕捉球，使用 capture.yml 的 balls.basic。玩家执行 /lipet itemshop 即可购买。

下面是单个商品案例，应合并到已有 item-entries 下，不要再创建第二个顶层 item-entries：

# 宠物道具商店商品表；保留已有商品，只添加下方新商品。
item-entries:
  basic_capture_ball:
    # 是否上架；true 上架，false 下架。
    enabled: true
    # 购买权限；空字符串表示所有玩家均可购买。
    permission: ""
    # 货币：INTERNAL 宠物币、VAULT 经济或 PLAYERPOINTS 点数。
    currency: "INTERNAL"
    # 一次购买的总价格，必须是非负有限数；PlayerPoints 必须为整数。
    price: 45.0
    item:
      # capture.yml 中 balls 下已启用的球 ID；此项决定发放真实捕捉球。
      capture-ball: "basic"
      # 一次发放的数量，范围 1–64；不要超过自定义物品允许的堆叠数。
      amount: 3
    icon:
      # 仅为商店图标，支持 Bukkit 材质或 CraftEngine 完整 ID。
      material: "SLIME_BALL"
      # 图标名称，支持 MiniMessage 和 amount 占位符。
      name: "<aqua><bold>普通捕捉球 ×<amount></bold></aqua>"
      # 图标介绍，支持 amount、price、currency 占位符。
      lore:
        - "<gray>手持捕捉球右键野生生物</gray>"
        - "<gray>数量：</gray><white><amount></white>"
        - "<gray>费用：</gray><gold><price> <currency></gold>"
        - "<green>点击购买</green>"

捕捉球商品的真实材质、名称和 Lore 来自 capture.yml，不能通过商品 item.material 或改名伪造。商店生成的物品会带有 LiPet 捕捉球识别标记；普通雪球改成相同名称也不能捕捉。

如果要出售 CE 捕捉球：先启用 balls.craftengine_example 并把材料改成实际 CE 完整 ID，再将商品的 item.capture-ball 改成 craftengine_example。icon.material 也可改为同一 CE ID，它仅影响商店显示。

关闭捕捉系统、禁用捕捉球或填写不存在的球 ID 时，购买会被拒绝且不会扣款；如果扣款期间球失效，或 CE 物品生成失败，会走退款流程。已有普通道具商品继续使用原来的 item.material/name/lore 配置。

4. 实服检查

停服备份并替换新版 Jar，启动后执行 /lipet status。
管理员用 /lipet givecoin 玩家名 100 发放测试宠物币，玩家打开 /lipet itemshop 购买普通捕捉球。
确认得到 3 个可捕捉的球、扣除 45 宠物币；手持球右键允许捕捉的野生生物。
捕捉成功后查看四属性，再收回和重新召唤，确认数值不变。
安装真实模型与资源包后配置等级门槛，喂养升级确认模型切换；检查动画和碰撞箱。

自动验证不能替代客户端模型画面验证；未安装 ModelEngine 或没有对应蓝图时无法验证最终视觉效果。