CraftEngine 完整物品挂钩 - LiPet 文档

适用版本：0.26.14-SNAPSHOT

本次更新把原先仅用于喂食识别的 CraftEngine 兼容层升级为统一物品提供器。LiPet 现在可以生成、识别、索引并热重载 CE 物品，全部业务模块不再自行拼装自定义物品的原版底材。

1. 已覆盖入口

pet-types.yml：宠物食物。
capture.yml：全部捕捉球。
skills.yml：全部技能书。
items.yml：宠物信号棒。
shop.yml：宠物商城图标、道具商城商品和道具商城图标。
gui.yml：内置按钮、自定义按钮、属性按钮、信息卡片、导航按钮和填充物。

所有 material 都支持以下三种格式：

material: "BLAZE_ROD"                 # Bukkit 材质
material: "minecraft:blaze_rod"       # 原版完整 ID
material: "mypack:pet_signal_stick"   # CraftEngine 完整 ID

CE ID 必须包含命名空间。物品不存在或 CraftEngine 尚未就绪时，LiPet 不会生成同底材原版物品冒充成功。

2. 配置示例

# capture.yml
balls:
  spirit:
    material: "mypack:spirit_capture_ball"

# skills.yml
skills:
  power:
    book:
      material: "mypack:power_skill_book"

# items.yml
signal-stick:
  material: "mypack:pet_signal_stick"

# shop.yml
item-entries:
  pet_cookie:
    item:
      material: "mypack:pet_cookie"
      amount: 8
    icon:
      material: "mypack:pet_cookie_icon"

# gui.yml
main:
  buttons:
    warehouse:
      material: "mypack:warehouse_icon"

pet-types.yml 的食物仍支持旧版 Material 节点。对于包含点号的 CE ID，建议使用别名节点和 item-id：

foods:
  spirit-cookie:
    item-id: "my.pack:pet.food"
    display-name: "灵宠饼干"
    experience: 35
    healing: 8.0
    attribute-points: 0
    minimum-level: 1
    maximum-level: 0

3. 安全行为

CE 物品由 CraftEngine 构建，LiPet 再追加 PDC、名称和 Lore，原有模型及组件数据会保留。
商城交付失败会自动退款，不会扣款后发出错误底材。
GUI 图标不可用时显示屏障和中文原因，菜单仍能安全打开。
捕捉返还、技能书和信号棒发放失败时会显示具体 CE ID。
CraftEngine 未安装或 API 不兼容时 LiPet 不会被禁用，原版物品功能继续工作。
/lipet reload 会重读 LiPet 的全部 CE 物品配置；CraftEngine 自身重载后会通过事件自动刷新索引。

4. 状态与自检

/lipet status
/lipet status default:topaz_pickaxe

状态页使用中文显示 未安装、等待物品索引、已就绪、API 不兼容 或 已停用，并显示当前索引数量。第二条命令会完成“CE ID → 构建 Bukkit ItemStack → 反向读取 CE ID”的闭环；只有返回“全链路自检通过”才表示该物品在当前服务端可安全使用。CE ID 参数会从当前物品索引提供 Tab 补全。

5. 模型能力边界

CraftEngine 的当前稳定 API 面向物品、方块和家具，没有 LiPet 活体宠物模型控制接口。本轮“完整挂钩”覆盖所有 LiPet 物品入口；宠物活体模型继续使用原版实体或 ModelEngine / MEG。这样可以避免把不存在的 CE 生物模型接口写进配置或作出无法兑现的兼容声明。

参考：CraftEngine 官方 API、CraftEngine 官方仓库。

6. 验证记录

默认兼容构建：102 项自动测试，0 失败、0 错误、0 跳过。
-Ppaper-26.2 构建：102 项自动测试，0 失败、0 错误、0 跳过。
Paper 26.1.2 Build 70 + CraftEngine 26.8.1：加载 109 个 CE 物品；生成/识别闭环、CE 重载、LiPet 热重载和安全关闭通过。
Paper 26.2 Build 111 + CraftEngine 26.8.1：加载 109 个 CE 物品；生成/识别闭环、CE 重载、LiPet 热重载和安全关闭通过。
成品保持 Java 21 字节码，共 310 个 LiPet 业务 class，外部依赖 class 数为 0。
成品 SHA-256：06FEE21AF8F5858F0D383748C32908B6ACB0B4AB929511BCC774AA96D71DC554。

服务端测试已证明物品在 API 层能够真实生成并保持 CE 身份；本轮没有连接带资源包的游戏客户端，因此自定义贴图的最终视觉效果仍由服务器实际安装的 CE 资源包决定。

7. 升级方式

停服并备份 plugins/LiPet/。
替换为 LiPet-0.26.14-SNAPSHOT.jar。
启动一次，让插件增量生成 items.yml 并补齐其他配置的中文注释。
把需要替换的原版 material 改为 CE 完整 ID。
执行 /lipet reload。
使用 /lipet status <CE物品ID> 验证每个关键物品。

升级只补缺失节点与明确的旧默认文本，不覆盖管理员已有值、布局或注释。