sapdon 3.2.2 → 3.4.0

package/doc/user/api/item.md

@@ -0,0 +1,1125 @@
+# 物品系统 API 参考
+
+本文档提供 sapdon 框架中物品系统的完整 API 参考。
+
+---
+
+## 目录
+
+1. [ItemAPI](#1-itemapi)
+2. [Item 类](#2-item-类)
+3. [ItemComponent](#3-itemcomponent)
+4. [Armor 子类](#4-armor-子类)
+5. [Food 类](#5-food-类)
+6. [ItemCategory 枚举](#6-itemcategory-枚举)
+7. [Attachable 类](#7-attachable-类)
+8. [注册流程](#8-注册流程)
+9. [ItemCatalog 类](#9-itemcatalog-类)
+
+---
+
+## 1. ItemAPI
+
+`ItemAPI` 是一个工厂对象，提供创建各种类型物品的静态方法。所有创建方法会自动调用 `GRegistry.register()` 注册物品到游戏。
+
+### createItem()
+
+创建普通物品。
+
+```typescript
+import { ItemAPI, ItemCategory } from '@sapdon/core'
+
+const item = ItemAPI.createItem(
+    'my_mod:simple_item',    // identifier: string — 唯一标识符（命名空间:名称）
+    ItemCategory.Items,       // category: string — 创造菜单分类
+    'my_texture',             // texture: string — 纹理名称
+    {                         // options?: object — 可选配置
+        group: 'minecraft:itemGroup.name.ingredients',
+        hide_in_command: false,   // 是否在命令中隐藏
+        max_stack_size: 64,       // 最大堆叠数量
+        format_version: '1.21.40', // 格式版本
+    }
+)
+```
+
+**参数：**
+
+| 参数 | 类型 | 必填 | 描述 |
+|------|------|------|------|
+| `identifier` | string | 是 | 物品唯一标识符，格式 `namespace:name` |
+| `category` | ItemCategory | 是 | 创造模式物品栏分类，见 `ItemCategory` 枚举 |
+| `texture` | string | 是 | 纹理名称 |
+| `options.group` | string | 否 | 物品分组 |
+| `options.hide_in_command` | boolean | 否 | 是否在命令自动补全中隐藏（默认 false） |
+| `options.max_stack_size` | number | 否 | 最大堆叠数量（默认 64，范围 1-99） |
+| `options.format_version` | string | 否 | 格式版本（默认 `'1.21.40'`） |
+
+**返回值：** `Item` — 创建的物品实例。
+
+---
+
+### createFood()
+
+创建食物物品。
+
+```typescript
+import { ItemAPI, ItemCategory } from '@sapdon/core'
+
+const food = ItemAPI.createFood(
+    'my_mod:magic_apple',    // identifier: string
+    ItemCategory.Items,       // category: string
+    'magic_apple',            // texture: string
+    {
+        group: 'minecraft:itemGroup.name.food',
+        hide_in_command: false,
+        animation: 'eat',            // 使用动画（'eat' | 'drink'）
+        canAlwaysEat: false,         // 是否可随时食用
+        nutrition: 6,                // 营养值
+        saturationModifier: 1.2,     // 饱和度修正值
+        movement: 1,                 // 移动速度修正
+        useDuration: 1,              // 使用时间（秒）
+    }
+)
+```
+
+**参数：**
+
+| 参数 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `identifier` | string | — | 唯一标识符 |
+| `category` | ItemCategory | — | 创造菜单分类 |
+| `texture` | string | — | 纹理名称 |
+| `options.group` | string | `undefined` | 物品分组 |
+| `options.hide_in_command` | boolean | `false` | 是否在命令中隐藏 |
+| `options.animation` | string | `'eat'` | 食用动画 |
+| `options.canAlwaysEat` | boolean | `false` | 是否可随时食用 |
+| `options.nutrition` | number | `0` | 营养值（非负） |
+| `options.saturationModifier` | number | `1` | 饱和度修正（正数） |
+| `options.movement` | number | `1` | 食用时移动速度缩放 |
+| `options.useDuration` | number | `1` | 食用所需时间（秒） |
+
+**返回值：** `Food` — 创建的食物物品实例。
+
+---
+
+### createAttachable()
+
+创建可附着物（用于手持 3D 模型或穿戴物品）。
+
+```typescript
+import { ItemAPI } from '@sapdon/core'
+
+const attachable = ItemAPI.createAttachable(
+    'my_mod:special_item',          // identifier: string
+    'textures/items/special_item',  // texture: string — 纹理路径
+    'entity_alphatest',              // material: string — 材质类型
+    // options?: object — 当前未使用额外选项
+)
+
+// 进一步配置
+attachable
+    .addGeometry('default', 'geometry.special_item')
+    .addTexture('enchanted', 'textures/misc/enchanted_item_glint')
+    .addRenderController('controller.render.special_item')
+```
+
+**参数：**
+
+| 参数 | 类型 | 必填 | 描述 |
+|------|------|------|------|
+| `identifier` | string | 是 | 唯一标识符 |
+| `texture` | string | 是 | 纹理路径（如 `'textures/items/my_item'`） |
+| `material` | string | 是 | 材质类型（如 `'entity_alphatest'`、`'armor'`） |
+| `options` | object | 否 | 预留扩展参数 |
+
+**返回值：** `Attachable` — 可附着物实例。
+
+---
+
+### createChestplateArmor()
+
+创建胸甲盔甲。
+
+```typescript
+import { ItemAPI } from '@sapdon/core'
+
+const chestplate = ItemAPI.createChestplateArmor(
+    'my_mod:ruby_chestplate',       // identifier: string
+    'ruby_chestplate',               // item_texture: string — 物品图标纹理
+    'textures/models/armor/ruby',   // texture_path: string — 模型纹理路径
+    {                                // options?: object
+        displayName: '红宝石胸甲',   // 自定义显示名称（默认："我的自定义胸甲"）
+    }
+)
+```
+
+**返回值：** `Armor` — 盔甲实例（`type === ArmorType.Chestplate`）。
+
+---
+
+### createHelmetArmor()
+
+创建头盔盔甲。
+
+```typescript
+const helmet = ItemAPI.createHelmetArmor(
+    'my_mod:ruby_helmet',
+    'ruby_helmet',
+    'textures/models/armor/ruby'
+)
+```
+
+**返回值：** `Armor` — 盔甲实例（`type === ArmorType.Helmet`）。
+
+---
+
+### createBootArmor()
+
+创建靴子盔甲。
+
+```typescript
+const boots = ItemAPI.createBootArmor(
+    'my_mod:ruby_boots',
+    'ruby_boots',
+    'textures/models/armor/ruby'
+)
+```
+
+**返回值：** `Armor` — 盔甲实例（`type === ArmorType.Boots`）。
+
+---
+
+### createLeggingsArmor()
+
+创建护腿盔甲。
+
+```typescript
+const leggings = ItemAPI.createLeggingsArmor(
+    'my_mod:ruby_leggings',
+    'ruby_leggings',
+    'textures/models/armor/ruby'
+)
+```
+
+**返回值：** `Armor` — 盔甲实例（`type === ArmorType.Leggings`）。
+
+> **说明：** 盔甲已重构为数据驱动结构，所有类型共享同一个 `Armor` 类，通过 `ArmorType` 枚举区分。
+> 可直接使用 `new Armor(id, item_texture, texture_path, ArmorType.Helmet, options)` 创建，
+> 并通过 `setAttachableGeometry(key, geometry)` 自定义几何模型（原 `setArrachableGeometry` 已改名）。
+> 访问内部对象：`armor.item`（物品）与 `armor.attachable`（可附着物），或 `armor.toObject()` 获取 `{ behavior, resource }`。
+
+---
+
+### createFlipbookItem()
+
+创建翻书物品（动态帧动画物品）。
+
+```typescript
+import { ItemAPI, ItemCategory } from '@sapdon/core'
+
+const flipbook = ItemAPI.createFlipbookItem(
+    'my_mod:animated_block',     // identifier: string
+    ItemCategory.Construction,    // category: ItemCategory
+    'my_flipbook_tex',            // texture: string — 纹理名称
+    {
+        group: 'minecraft:itemGroup.name.construction',
+        hide_in_command: false,
+        ticks_per_frame: 8,       // 每帧持续刻数（默认 8，1秒=20刻）
+        max_stack_size: 64,
+        format_version: '1.21.40',
+    }
+)
+```
+
+**参数：**
+
+| 参数 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `identifier` | string | — | 唯一标识符 |
+| `category` | ItemCategory | — | 创造菜单分类 |
+| `texture` | string | — | 纹理名称（位于 `textures/blocks/` 目录） |
+| `options.group` | string | `undefined` | 物品分组 |
+| `options.hide_in_command` | boolean | `false` | 是否在命令中隐藏 |
+| `options.ticks_per_frame` | number | `8` | 每帧持续刻数 |
+| `options.max_stack_size` | number | `64` | 最大堆叠数量 |
+| `options.format_version` | string | `'1.21.40'` | 格式版本 |
+
+**返回值：** `FlipbookItem` — 翻书物品实例。可通过 `.block` 属性访问关联的 `GeometryBlock`。
+
+---
+
+## 2. Item 类
+
+`Item` 是所有物品类型的基类，提供组件管理和序列化功能。
+
+### 构造函数
+
+```typescript
+import { Item, ItemCategory } from '@sapdon/core'
+
+const item = new Item(
+    'my_mod:custom_item',   // identifier: string — 唯一标识符
+    ItemCategory.Items,      // category: ItemCategory — 创造菜单分类
+    'custom_texture',        // texture: string — 纹理名称
+    {                        // options?: object
+        group: '...',
+        hide_in_command: false,
+        max_stack_size: 64,
+        format_version: '1.21.40',
+    }
+)
+```
+
+**参数：**
+
+| 参数 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `identifier` | string | — | 唯一标识符 |
+| `category` | ItemCategory | — | 创造菜单分类 |
+| `texture` | string | — | 纹理名称 |
+| `options.group` | string | `undefined` | 分组 |
+| `options.hide_in_command` | boolean | `false` | 是否在命令中隐藏 |
+| `options.max_stack_size` | number | `64` | 最大堆叠数量 |
+| `options.format_version` | string | `'1.21.40'` | 格式版本 |
+
+构造函数自动添加 `minecraft:icon` 和 `minecraft:max_stack_size` 组件。
+
+### 方法
+
+#### addComponent(componentMap)
+
+添加一个或多个组件到物品。
+
+```typescript
+item.addComponent(
+    ItemComponent.setDisplayName('自定义物品')
+)
+
+// 或合并多个组件
+item.addComponent(
+    ItemComponent.combineComponents(
+        ItemComponent.setHandEquipped(true),
+        ItemComponent.setDurability(100),
+    )
+)
+```
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `componentMap` | Map | 组件 Map 对象 |
+
+**返回值：** `this` — 支持链式调用。
+
+---
+
+#### removeComponent(key)
+
+移除指定组件。
+
+```typescript
+item.removeComponent('minecraft:icon')  // 移除图标组件
+```
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `key` | string | 要移除的组件名称 |
+
+**返回值：** `this` — 支持链式调用。
+
+---
+
+#### toObject()
+
+将物品转换为 JSON 对象（使用 `@Serializer` 装饰器），用于生成物品定义文件。
+
+```typescript
+const json = item.toObject()
+// 输出格式：
+// {
+//   format_version: '1.21.40',
+//   'minecraft:item': {
+//     description: { identifier, menu_category },
+//     components: { ... }
+//   }
+// }
+```
+
+**返回值：** `object` — 序列化后的物品定义对象。
+
+---
+
+## 3. ItemComponent
+
+`ItemComponent` 提供静态方法，用于构建 `minecraft:item` 的组件 Map。每个方法返回一个 `Map<string, any>`。
+
+### setIcon(texture)
+
+设置物品图标纹理。支持字符串（默认纹理）或对象（多纹理）两种格式。
+
+```typescript
+ItemComponent.setIcon('my_texture')
+// → Map { 'minecraft:icon' => 'my_texture' }
+
+ItemComponent.setIcon({ default: 'my_texture', dyed: 'my_texture_dyed' })
+// → Map { 'minecraft:icon' => { textures: { default: 'my_texture', dyed: 'my_texture_dyed' } } }
+```
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `texture` | string \| object | 纹理名称，或包含 `default`/`dyed`/`iconTrim`/`bundleOpenBack`/`bundleOpenFront` 的纹理对象 |
+
+---
+
+### setMaxStackSize(size)
+
+设置最大堆叠数量。
+
+```typescript
+ItemComponent.setMaxStackSize(16)
+// → Map { 'minecraft:max_stack_size' => 16 }
+```
+
+| 参数 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `size` | number | `64` | 最大堆叠数量（正整数） |
+
+---
+
+### setDisplayName(name)
+
+设置物品显示名称。
+
+```typescript
+ItemComponent.setDisplayName('§c传奇之剑')
+// → Map { 'minecraft:display_name' => { value: '§c传奇之剑' } }
+```
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `name` | string | 显示名称（支持 § 颜色代码） |
+
+---
+
+### setFoodComponent(options)
+
+设置食物属性组件。
+
+```typescript
+ItemComponent.setFoodComponent({
+    nutrition: 6,
+    saturationModifier: 1.2,
+    canAlwaysEat: true,
+    usingConvertsTo: 'minecraft:bowl', // 可选
+})
+// → Map { 'minecraft:food' => { can_always_eat: true, nutrition: 6, saturation_modifier: 1.2, using_converts_to: 'minecraft:bowl' } }
+```
+
+| 参数 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `options.canAlwaysEat` | boolean | `false` | 是否可随时食用 |
+| `options.nutrition` | number | `0` | 营养值 |
+| `options.saturationModifier` | number | `0.6` | 饱和度修正值 |
+| `options.usingConvertsTo` | string | `undefined` | 食用后转换的目标物品 ID |
+
+---
+
+### setWearable(protection?, slot?, hidesPlayerLocation?)
+
+设置可穿戴组件。
+
+```typescript
+// 头盔
+ItemComponent.setWearable(3, 'slot.armor.head')
+// 胸甲
+ItemComponent.setWearable(5, 'slot.armor.chest')
+// 护腿
+ItemComponent.setWearable(6, 'slot.armor.legs')
+// 靴子
+ItemComponent.setWearable(4, 'slot.armor.feet')
+// → Map { 'minecraft:wearable' => { protection: 3, slot: 'slot.armor.head' } }
+```
+
+| 参数 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `protection` | number | `0` | 保护值 |
+| `slot` | string | `undefined` | 装备槽位（如 `'slot.armor.head'`） |
+| `hidesPlayerLocation` | boolean | `undefined` | 穿戴时是否在定位栏与定位地图中隐藏 |
+
+---
+
+### setFuel(duration)
+
+设置燃料组件，使物品可在熔炉中作为燃料使用。
+
+```typescript
+ItemComponent.setFuel(200)
+// → Map { 'minecraft:fuel' => { duration: 200 } }
+```
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `duration` | number | 燃烧持续时间（秒），最小值 0.05 |
+
+---
+
+### setGlint(hasGlint)
+
+设置附魔光效。
+
+```typescript
+ItemComponent.setGlint(true)
+// → Map { 'minecraft:glint' => true }
+```
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `hasGlint` | boolean | 是否显示附魔光效 |
+
+---
+
+### setHandEquipped(isHandEquipped)
+
+设置手持渲染方式。
+
+```typescript
+ItemComponent.setHandEquipped(true)  // 像工具一样手持
+ItemComponent.setHandEquipped(false) // 像物品一样手持
+// → Map { 'minecraft:hand_equipped' => true }
+```
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `isHandEquipped` | boolean | 是否像工具一样渲染 |
+
+---
+
+### setThrowable(doSwingAnimation?, launchPowerScale?, maxDrawDuration?, maxLaunchPower?, minDrawDuration?, scalePowerByDrawDuration?)
+
+设置可投掷组件。
+
+```typescript
+ItemComponent.setThrowable(true, 1.5, 0, 2.0, 0, true)
+// → Map { 'minecraft:throwable' => { do_swing_animation: true, launch_power_scale: 1.5, ... } }
+```
+
+| 参数 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `doSwingAnimation` | boolean | `false` | 是否使用挥动动画 |
+| `launchPowerScale` | number | `1.0` | 投掷力量缩放 |
+| `maxDrawDuration` | number | `0.0` | 最大蓄力时间 |
+| `maxLaunchPower` | number | `1.0` | 最大投掷力量 |
+| `minDrawDuration` | number | `0.0` | 最小蓄力时间 |
+| `scalePowerByDrawDuration` | boolean | `false` | 力量是否随蓄力增加 |
+
+---
+
+### setProjectile(minimumCriticalPower?, projectileEntity?)
+
+设置投射物组件。
+
+```typescript
+ItemComponent.setProjectile(0.5, 'minecraft:snowball')
+// → Map { 'minecraft:projectile' => { minimum_critical_power: 0.5, projectile_entity: 'minecraft:snowball' } }
+```
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `minimumCriticalPower` | number | 暴击所需的最小蓄力值 |
+| `projectileEntity` | string | 发射的投射物实体 ID |
+
+---
+
+### setUseModifiers(options?)
+
+设置使用修饰组件。
+
+```typescript
+ItemComponent.setUseModifiers({
+    movementModifier: 0.5,
+    useDuration: 1.5,
+})
+// → Map { 'minecraft:use_modifiers' => { movement_modifier: 0.5, use_duration: 1.5 } }
+```
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `options.movementModifier` | number | 使用物品时玩家移动速度缩放值 |
+| `options.useDuration` | number | 物品使用所需时间（秒） |
+| `options.emitVibrations` | boolean | 是否在开始/停止使用时发出振动 |
+| `options.startSound` | string | 开始使用时触发的原版音效 |
+| `options.startUsing` | string | 使用修饰生效时机（`'always'` 或 `'if_first'`） |
+
+---
+
+### setUseAnimation(animation)
+
+设置使用动画。
+
+```typescript
+ItemComponent.setUseAnimation('eat')
+ItemComponent.setUseAnimation('drink')
+// → Map { 'minecraft:use_animation' => 'eat' }
+```
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `animation` | string | 动画类型（如 `'eat'`、`'drink'`） |
+
+---
+
+### setDurability(maxDurability, damageChanceMin?, damageChanceMax?)
+
+设置耐久度组件。
+
+```typescript
+ItemComponent.setDurability(500, 10, 50)
+// → Map { 'minecraft:durability' => { max_durability: 500, damage_chance: { min: 10, max: 50 } } }
+```
+
+| 参数 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `maxDurability` | number | — | 最大耐久值 |
+| `damageChanceMin` | number | `0` | 最小损坏概率（百分比） |
+| `damageChanceMax` | number | `100` | 最大损坏概率（百分比） |
+
+---
+
+### setInteractButton(text)
+
+设置交互按钮。支持字符串（自定义文案）或布尔值（通用 "Use Item" 文案）。
+
+```typescript
+ItemComponent.setInteractButton('打开')
+// → Map { 'minecraft:interact_button' => '打开' }
+ItemComponent.setInteractButton(true)
+// → Map { 'minecraft:interact_button' => true }
+```
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `text` | string \| boolean | 交互时显示的文本，或 `true`/`false` |
+
+---
+
+### setBlockPlacer(block, options?)
+
+设置方块放置器组件。
+
+```typescript
+ItemComponent.setBlockPlacer(
+    'my_mod:custom_block',                // 要放置的方块 ID
+    {
+        replaceBlockItem: false,           // 是否替换方块物品（可选）
+        alignedPlacement: true,            // 是否启用对齐放置（可选）
+        useOn: ['minecraft:dirt'],         // 可放置的目标方块列表（可选）
+    }
+)
+// → Map { 'minecraft:block_placer' => { block: '...', replace_block_item: false, aligned_placement: true, use_on: [...] } }
+```
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `block` | string | 要放置的方块标识符 |
+| `options.replaceBlockItem` | boolean | 是否替换方块物品 |
+| `options.alignedPlacement` | boolean | 是否启用对齐放置 |
+| `options.useOn` | BlockDescriptor[] | 可使用此物品的方块描述符列表 |
+
+---
+
+### setCustomComponentV2(componentId, params)
+
+设置自定义 V2 组件（需要 format_version > 1.21.90 和 Scripting V2）。
+
+```typescript
+ItemComponent.setCustomComponentV2(
+    'my_mod:my_component',
+    { speed: 1.5, damage: 10 }
+)
+// → Map { 'my_mod:my_component' => { speed: 1.5, damage: 10 } }
+```
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `componentId` | string | 组件标识符 |
+| `params` | object | 自定义参数对象 |
+
+---
+
+### combineComponents(...maps)
+
+将多个组件 Map 合并为一个。
+
+```typescript
+const combined = ItemComponent.combineComponents(
+    ItemComponent.setDisplayName('神剑'),
+    ItemComponent.setHandEquipped(true),
+    ItemComponent.setDurability(1000),
+)
+// → Map { 'minecraft:display_name': ..., 'minecraft:hand_equipped': ..., 'minecraft:durability': ... }
+```
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `...componentMaps` | Map[] | 多个组件 Map |
+
+**返回值：** `Map` — 合并后的组件集合。
+
+---
+
+### toJSON(components)
+
+将组件 Map 转换为普通 JSON 对象。
+
+```typescript
+const map = ItemComponent.setDisplayName('测试')
+const json = ItemComponent.toJSON(map)
+// → { 'minecraft:display_name': { value: '测试' } }
+```
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `components` | Map | 组件集合 |
+
+**返回值：** `object` — JSON 对象。
+
+---
+
+### setCustomComponents(customComponents)
+
+设置自定义组件数组。
+
+```typescript
+ItemComponent.setCustomComponents(['my_mod:my_component'])
+// → Map { 'my_mod:my_component' => {} }
+```
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `customComponents` | string[] | 自定义组件标识符数组 |
+
+---
+
+### 更多组件（对齐 Bedrock Wiki 1.26.30）
+
+以下方法均参考 [Bedrock Wiki Item Components](https://wiki.bedrock.dev/items/item-components)，覆盖 wiki 收录的全部组件。
+
+**布尔/数值/字符串组件：**
+
+| 方法 | JSON 组件 | 描述 |
+|------|-----------|------|
+| `setAllowOffHand(allowed)` | `minecraft:allow_off_hand` | 是否可装备至副手 |
+| `setCanDestroyInCreative(can)` | `minecraft:can_destroy_in_creative` | 创造模式下能否破坏方块 |
+| `setDamage(damage)` | `minecraft:damage` | 额外攻击伤害（0-32767） |
+| `setHoverTextColor(color)` | `minecraft:hover_text_color` | 物品名颜色 |
+| `setLiquidClipped(clipped)` | `minecraft:liquid_clipped` | 是否在液体内部交互 |
+| `setRarity(rarity)` | `minecraft:rarity` | 稀有度（`common`/`uncommon`/`rare`/`epic`） |
+| `setShouldDespawn(should)` | `minecraft:should_despawn` | 掉落物是否最终消失 |
+| `setStackedByData(stacked)` | `minecraft:stacked_by_data` | 不同数据值的物品是否分开堆叠 |
+| `setSwingDuration(value)` | `minecraft:swing_duration` | 挥动动画时长（秒） |
+| `setCompostable(chance)` | `minecraft:compostable` | 堆肥成功率（0-100） |
+| `setBundleInteraction(numSlots)` | `minecraft:bundle_interaction` | Bundle 可查看槽位数（1-64） |
+
+**对象组件：**
+
+```typescript
+// 冷却
+ItemComponent.setCooldown({ category: 'wiki:cd', duration: 0.2, type: 'use' })
+// → { category, duration, type? }
+
+// 伤害吸收（需搭配 durability 与盔甲槽位）
+ItemComponent.setDamageAbsorption(['all'])
+
+// 挖掘
+ItemComponent.setDigger({
+    destroySpeeds: [{ block: 'minecraft:gravel', speed: 0 }, { block: { tags: "q.any_tag('x')" }, speed: 6 }],
+    useEfficiency: true,
+})
+
+// 耐久传感器
+ItemComponent.setDurabilitySensor({
+    durabilityThresholds: [{ durability: 100, particleType: 'minecraft:explosion_manual', soundEvent: 'blast' }],
+})
+
+// 可染色
+ItemComponent.setDyeable('#ffffff')
+
+// 可附魔
+ItemComponent.setEnchantable('sword', 10)
+
+// 放置实体
+ItemComponent.setEntityPlacer('minecraft:spider', { useOn: ['minecraft:dirt'], dispenseOn: ['minecraft:dirt'] })
+
+// 防火
+ItemComponent.setFireResistant(true)
+
+// 动能武器
+ItemComponent.setKineticWeapon({
+    delay: 15,
+    reach: { min: 2.0, max: 4.5 },
+    creativeReach: { min: 2.0, max: 7.5 },
+    hitboxMargin: 0.25,
+    damageMultiplier: 0.7,
+    damageConditions: { max_duration: 300 },
+    knockbackConditions: { min_speed: 5.1 },
+    dismountConditions: { min_speed: 14.0 },
+})
+
+// 穿刺武器
+ItemComponent.setPiercingWeapon({ reach: { min: 2.0, max: 4.5 }, creativeReach: { min: 2.0, max: 7.5 } })
+
+// 唱片
+ItemComponent.setRecord({ comparatorSignal: 1, duration: 5, soundEvent: 'bucket.empty.powder_snow' })
+
+// 可修复
+ItemComponent.setRepairable([
+    { items: ['minecraft:diamond'], repairAmount: 10 },
+    { items: [{ tags: "q.any_tag('minecraft:planks')" }], repairAmount: 'q.max_durability * 0.25' },
+])
+
+// 射击（需搭配 use_modifiers）
+ItemComponent.setShooter({
+    ammunition: [{ item: 'minecraft:arrow', searchInventory: true, useInCreative: true, useOffhand: true }],
+    scalePowerByDrawDuration: true,
+})
+
+// 容器物品（需 max_stack_size 为 1）
+ItemComponent.setStorageItem({
+    maxSlots: 64,
+    allowNestedStorageItems: true,
+    bannedItems: ['minecraft:shulker_box'],
+})
+
+// 容器重量上限（需搭配 storage_item）
+ItemComponent.setStorageWeightLimit(64)
+
+// 容器重量修正（0 表示禁止放入其他容器）
+ItemComponent.setStorageWeightModifier(4)
+
+// 挥砍音效
+ItemComponent.setSwingSounds({
+    attackMiss: 'item.wooden_spear.attack_miss',
+    attackHit: 'item.wooden_spear.attack_hit',
+    attackCriticalHit: 'item.wooden_spear.attack_critical_hit',
+})
+
+// 标签
+ItemComponent.setTags(['wiki:custom_tag'])
+```
+
+---
+
+## 4. Armor 类
+
+盔甲系统已重构为数据驱动结构：单一 `Armor` 类 + `ArmorType` 枚举，内部创建 `Item` 和 `Attachable` 实例。
+
+### Armor 构造
+
+```typescript
+import { Armor, ArmorType } from '@sapdon/core'
+
+new Armor(identifier, item_texture, texture_path, type, options?)
+```
+
+| 属性/方法 | 类型 | 描述 |
+|-----------|------|------|
+| `type` | ArmorType | 盔甲类型 |
+| `item` | Item | 关联的物品实例 |
+| `attachable` | Attachable | 关联的可附着物实例 |
+| `setAttachableGeometry(key, geometry)` | this | 设置可附着物几何模型 |
+| `toObject()` | object | 返回 `{ behavior, resource }` 两包 JSON |
+
+### 类型对照表
+
+| ArmorType | 创建方法 | 保护值 | 插槽 | 几何模型 | 脚本 |
+|----|---------|--------|------|---------|------|
+| **Helmet** | `ItemAPI.createHelmetArmor()` | 3 | `slot.armor.head` | `geometry.player.armor.helmet` | `v.helmet_layer_visible = 0.0;` |
+| **Chestplate** | `ItemAPI.createChestplateArmor()` | 5 | `slot.armor.chest` | `geometry.player.armor.chestplate` | `v.chest_layer_visible = 0.0;` |
+| **Leggings** | `ItemAPI.createLeggingsArmor()` | 6 | `slot.armor.legs` | `geometry.player.armor.leggings` | `v.leg_layer_visible = 0.0;` |
+| **Boots** | `ItemAPI.createBootArmor()` | 4 | `slot.armor.feet` | `geometry.player.armor.boots` | `v.boot_layer_visible = 0.0;` |
+
+### 默认配置
+
+所有盔甲类型自动配置以下属性：
+
+- 分类：`'equipment'`
+- 分组：对应的 `itemGroup.name.*`
+- 最大堆叠数量：`1`
+- 显示名称：各类型的默认名称（可通过 `options.displayName` 覆盖）
+- 纹理：通过 `texture_path` 参数指定
+- 材质：`'armor'`（默认）和 `'armor_enchanted'`（附魔）
+- 渲染控制器：`'controller.render.armor'`
+
+```typescript
+// 自定义盔甲几何模型示例
+ItemAPI.createHelmetArmor('my_mod:custom_helmet', 'custom_helmet', 'textures/models/armor/custom')
+    .setAttachableGeometry('default', 'geometry.custom.helmet')
+```
+
+---
+
+## 5. Food 类
+
+`Food` 继承自 `Item`，自动添加食物相关组件。
+
+```typescript
+class Food extends Item {
+    constructor(identifier, category, texture, options?)
+}
+```
+
+### 构造函数自动添加的组件
+
+| 组件 | 来源 |
+|------|------|
+| `minecraft:icon` | 父类构造 |
+| `minecraft:max_stack_size` | 父类构造 |
+| `minecraft:use_modifiers` | Food 构造 |
+| `minecraft:food` | Food 构造 |
+| `minecraft:use_animation` | Food 构造 |
+
+```typescript
+import { Food, ItemCategory } from '@sapdon/core'
+
+const food = new Food('my_mod:apple', ItemCategory.Items, 'apple', {
+    nutrition: 8,
+    saturationModifier: 1.5,
+    canAlwaysEat: true,
+    animation: 'eat',
+    movement: 0.8,
+    useDuration: 1.5,
+})
+```
+
+---
+
+## 6. ItemCategory 枚举
+
+`ItemCategory` 提供标准的创造模式物品栏分类。
+
+```typescript
+enum ItemCategory {
+    Commands     = 'commands',      // 命令分类
+    Construction = 'construction',  // 建筑分类
+    Equipment    = 'equipment',     // 装备分类
+    Nature       = 'nature',        // 自然分类
+    Items        = 'items',         // 物品分类
+    None         = 'none',          // 无分类
+}
+```
+
+### 使用示例
+
+```typescript
+import { ItemAPI, ItemCategory } from '@sapdon/core'
+
+ItemAPI.createItem('test:item', ItemCategory.Construction, 'tex')
+```
+
+> **注意：** `category` 参数为严格枚举类型，传 `'construction'` 等裸字符串会报 TS 编译错误，并会在运行时校验失败。必须使用 `ItemCategory.Construction` 等枚举成员。
+
+---
+
+## 7. Attachable 类
+
+`Attachable` 用于创建可附着物（attachables），实现手持 3D 模型或穿戴物品渲染。继承自 `AddonAttachableDescription`。
+
+### 构造函数
+
+```typescript
+import { Attachable } from '@sapdon/core'
+
+const att = new Attachable('my_mod:my_attachable')
+```
+
+### 方法
+
+| 方法 | 描述 |
+|------|------|
+| `addMaterial(name, material)` | 添加材质（如 `'default'`, `'entity_alphatest'`） |
+| `addTexture(name, texture)` | 添加纹理路径 |
+| `addGeometry(name, geometry)` | 添加几何模型标识符 |
+| `addAnimation(name, animation)` | 添加动画 |
+| `addAnimationController(name, controller)` | 添加动画控制器 |
+| `addRenderController(controller)` | 添加渲染控制器 |
+| `addLocator(name, locator)` | 添加定位器 |
+| `setScript(key, value)` | 设置脚本变量 |
+| `getId()` | 获取标识符 |
+| `toObject()` | 序列化为 JSON |
+
+### 完整示例
+
+```typescript
+const att = new Attachable('my_mod:custom_armor')
+att
+    .addMaterial('default', 'armor')
+    .addMaterial('enchanted', 'armor_enchanted')
+    .addTexture('default', 'textures/models/armor/custom_main')
+    .addTexture('enchanted', 'textures/misc/enchanted_actor_glint')
+    .addGeometry('default', 'geometry.player.armor.chestplate')
+    .addRenderController('controller.render.armor')
+    .setScript('parent_setup', 'v.chest_layer_visible = 0.0;')
+```
+
+---
+
+## 8. 注册流程
+
+所有通过 `ItemAPI` 创建的对象会自动注册到游戏。但如果你手动创建 `Item` 或需要提交注册数据，需要调用 `registry.submit()`。
+
+### 基本流程
+
+```typescript
+import { ItemAPI, registry, ItemComponent, ItemCategory } from '@sapdon/core'
+
+// 1. 创建物品（自动注册到全局注册表）
+ItemAPI.createItem('my_mod:sword', ItemCategory.Equipment, 'sword')
+
+// 2. 提交所有注册数据到游戏引擎
+//    必须在所有物品创建完成后调用
+registry.submit()
+```
+
+### 手动注册
+
+```typescript
+import { GRegistry } from '@sapdon/core'
+
+// 手动注册物品数据
+GRegistry.register(
+    'my_item',            // name: string — 文件名（不含扩展名）
+    'behavior',           // root: string — 根目录（'behavior' / 'resource'）
+    'items/',             // path: string — 子目录
+    itemDataObject        // data: object — 数据对象（需有 toObject 方法）
+)
+
+// 提交
+GRegistry.submit()
+```
+
+### registry 命名空间
+
+```typescript
+import { registry } from '@sapdon/core'
+
+// 提交所有注册数据
+registry.submit()
+```
+
+### 完整工作流
+
+```typescript
+// main.ts
+import { ItemAPI, registry, ItemComponent, ItemCategory } from '@sapdon/core'
+
+// === 定义所有物品 ===
+
+// 基础物品
+ItemAPI.createItem('my_mod:materials', ItemCategory.Items, 'materials')
+    .addComponent(ItemComponent.setDisplayName('§b基础材料'))
+
+// 食物
+ItemAPI.createFood('my_mod:food', ItemCategory.Items, 'food', {
+    nutrition: 8,
+    saturationModifier: 1.5,
+})
+
+// 盔甲
+ItemAPI.createHelmetArmor('my_mod:helmet', 'helmet', 'textures/models/armor/set')
+ItemAPI.createChestplateArmor('my_mod:chestplate', 'chestplate', 'textures/models/armor/set')
+
+// === 提交注册 ===
+registry.submit()
+```
+
+> **重要**：`registry.submit()` 必须在所有物品创建完成后调用一次，且通常在文件末尾执行。
+
+---
+
+## 9. ItemCatalog 类
+
+参考 [Bedrock Wiki Item Catalog](https://wiki.bedrock.dev/items/item-catalog)，用于生成行为包 `BP/item_catalog/crafting_item_catalog.json`，指定物品在创造菜单与配方手册中的分组位置。
+
+### 构造与注册
+
+```typescript
+import { ItemAPI, ItemCatalog } from '@sapdon/core'
+
+// 方式一：ItemAPI 工厂（自动注册）
+const catalog = ItemAPI.createItemCatalog()   // 默认 format_version "1.26.30"
+
+// 方式二：直接使用类（需手动 register）
+const catalog2 = new ItemCatalog().register()
+```
+
+### addGroup(category, items, options?)
+
+添加一组物品到指定分类。分类仅支持 `construction` / `equipment` / `items` / `nature`。
+
+```typescript
+catalog.addGroup('nature', ['wiki:silver_ore', 'wiki:steel_ore'], {
+    icon: 'wiki:silver_ore',       // 分组图标（可选）
+    name: 'wiki:itemGroup.name.ore' // 分组本地化键（可选，需同时在 .lang 中定义）
+})
+```
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `category` | string | 创造菜单分类（`construction`/`equipment`/`items`/`nature`） |
+| `items` | string[] | 物品标识符列表 |
+| `options.icon` | string | 分组图标物品 |
+| `options.name` | string | 分组本地化键，可用作物品/方块的 `menu_category.group` |
+
+### addItem(category, item, options?)
+
+添加单个物品到指定分类（内部调用 `addGroup(category, [item], options)`）。
+
+```typescript
+catalog.addItem('items', 'wiki:custom_item')
+```
+
+### register()
+
+将目录注册到行为包 `item_catalog/` 目录，返回当前实例。
+
+### toObject()
+
+```typescript
+ItemAPI.createItemCatalog()
+    .addGroup('nature', ['wiki:silver_ore', 'wiki:steel_ore'], { icon: 'wiki:silver_ore', name: 'wiki:itemGroup.name.ore' })
+    .addItem('items', 'wiki:custom_item')
+    .toObject()
+// → {
+//   format_version: '1.26.30',
+//   'minecraft:crafting_items_catalog': {
+//     categories: [
+//       { category_name: 'nature', groups: [{ group_identifier: { icon: 'wiki:silver_ore', name: 'wiki:itemGroup.name.ore' }, items: ['wiki:silver_ore', 'wiki:steel_ore'] }] },
+//       { category_name: 'items', groups: [{ items: ['wiki:custom_item'] }] },
+//     ],
+//   },
+// }
+```
+
+### 完整示例
+
+```typescript
+import { ItemAPI, registry } from '@sapdon/core'
+
+// 定义物品
+ItemAPI.createItem('wiki:silver_ore', ItemCategory.Nature, 'silver_ore')
+ItemAPI.createItem('wiki:steel_ore', ItemCategory.Nature, 'steel_ore')
+
+// 添加到创造菜单分组
+ItemAPI.createItemCatalog()
+    .addGroup('nature', ['wiki:silver_ore', 'wiki:steel_ore'], {
+        icon: 'wiki:silver_ore',
+        name: 'wiki:itemGroup.name.ore',
+    })
+
+registry.submit()
+```
+
+对应的 `RP/texts/en_US.lang` 需包含本地化文本：
+
+```
+wiki:itemGroup.name.ore=Custom Ores
+```