捕捉、宠物商城与道具商城 - LiPet 文档

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

0.27.16 捕捉幼体年龄与认主

捕捉时保存为幼体的原版宠物会保持幼体并锁定自然年龄；召唤、区块重新载入和活动实体恢复都会按数据库外观校正。成年宠物不会被锁成幼体。旧版已经自然长大的捕捉幼体无需重建档案，停服替换 Jar 后重新召唤即可恢复。Paper 26.2 实测狼、猫、马跨越成年边界时 UUID、PDC、驯服状态和主人 UUID都会保留。

捕捉球、宠物商品图标、道具商城商品与图标均可直接填写 CraftEngine 完整物品 ID。CE 商品生成失败时交易自动退款，详细规则见 CraftEngine 完整物品挂钩。

0.27.9 道具商城提示与退款

道具余额不足使用独立的 messages.yml -> item-shop-insufficient-funds，默认显示“余额不足，无法购买该道具”；宠物商城继续使用 shop-insufficient-funds。扣款后的物品发放改为可观察任务，玩家实体在任务受理后、执行前退出或退休时，交易会结束并全额退款，不会永久等待或只扣款不发货。已有商品价格、货币 ID 与自定义消息不会被默认值覆盖。

0.27.5 新增配置与行为

默认道具商店新增普通捕捉球：45 宠物币购买 3 个，玩家执行 /lipet itemshop。商品通过 item.capture-ball: basic 发放带真实捕捉标记的球，材质和名称来自 capture.yml；生成失败走退款。原版宠物捕捉成功后默认独立随机力量、体质、防御、敏捷各 0–5，结果保存后不因重召唤或重启改变。

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

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"

默认文件还提供一个关闭状态的 CraftEngine 捕捉球案例：

balls:
  craftengine_example:
    enabled: false
    material: "yourpack:pet_capture_ball"
    name: "<gradient:#69F0AE:#40C4FF><bold>灵契捕捉球</bold></gradient>"
    base-chance: 0.25
    low-health-bonus: 0.50
    maximum-chance: 0.75

把 material 换成真实 CE 完整 ID，再将 enabled 改为 true。关闭的球不会出现在 /lipet captureball 补全、识别和发放流程中；至少要保留一个已启用捕捉球。

兼容处理：

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

12. 宠物商城

商城总开关

shop.yml 顶层可统一关闭宠物商城和宠物道具商城：

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

关闭并执行 /lipet reload 后：

/lipet shop 与 /lipet itemshop 只提示商城未开放，不会打开 GUI。
主菜单、仓库和自定义 GUI 动作不会再进入商城。
已经打开商城的玩家也不能继续购买。
/lipet help 自动隐藏两个商城入口。
商品、价格和自定义 Lore 原样保留，重新开启后立即恢复。

旧版 shop.yml 缺少 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 点券；价格必须填写整数

currency 是配置识别用的提供器 ID。shop.yml 继续使用 INTERNAL、VAULT、PLAYERPOINTS，不要改成中文。从 0.27.6 起，两个商城的 <currency> 都按 config.yml 中对应的显示名称渲染：

# config.yml：合并到现有 currency 节点，保留其他货币设置。
# 下面只配置显示文字，不改变商品价格、货币 ID 或扣款方式。
currency:
  # INTERNAL 内置货币。
  internal:
    # 非空单行文本，支持 MiniMessage；默认“宠物币”。
    display-name: "宠物币"
  # VAULT 外部经济，需要 Vault 和经济插件可用。
  vault:
    # 非空单行文本，支持 MiniMessage；默认“金币”。
    display-name: "金币"
  # PLAYERPOINTS 点数，需要 PlayerPoints 插件可用。
  playerpoints:
    # 非空单行文本，支持 MiniMessage；默认“点券”。
    display-name: "点券"

因此 price: 100.0、currency: "PLAYERPOINTS" 默认显示为 100.00 点券；INTERNAL、VAULT 默认分别显示“宠物币”“金币”。100.00 的两位小数格式不变，PlayerPoints 价格仍必须为整数。商品 Lore 应使用 <price> <currency>；手动写死的 PlayerPoints 文本不会被替换。

首次换用 LiPet-0.27.6-SNAPSHOT.jar 需要停服替换并重启一次。后续仅修改显示名称时，执行 /lipet reload 并等待成功，再关闭旧界面、重新执行 /lipet shop 或 /lipet itemshop 即可；已经打开的菜单不会自动重绘。主配置验证或数据库重载失败、并发重载被拒绝时保留原名称，管理员自定义名称和注释不会被默认值覆盖。

这个热更入口只更新显示名称。server.id、服务器群组 server.group、currency.internal.initial-balance 仍按启动时读取，不随改名重载改变；数据库继续使用原有热切换流程。

PlayerPoints 是可选软依赖。未安装时 LiPet 继续运行，使用该货币的商品不可购买；未挂钩或未知提供器继续显示大写 ID 供排查，名称配置不会代替前置插件。安装后可通过 /lipet status 的独立状态行确认挂钩为 ONLINE。

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

宠物币获取

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

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

道具商城同样支持 INTERNAL、VAULT 与 PLAYERPOINTS。