sapdon 3.3.3 → 3.4.0

package/doc/user/api/item.md

@@ -14,6 +14,7 @@
 6. [ItemCategory 枚举](#6-itemcategory-枚举)
 7. [Attachable 类](#7-attachable-类)
 8. [注册流程](#8-注册流程)
+9. [ItemCatalog 类](#9-itemcatalog-类)
 
 ---
 
@@ -46,10 +47,10 @@ const item = ItemAPI.createItem(
 | 参数 | 类型 | 必填 | 描述 |
 |------|------|------|------|
 | `identifier` | string | 是 | 物品唯一标识符，格式 `namespace:name` |
-| `category` | string | 是 | 创造模式物品栏分类 |
+| `category` | ItemCategory | 是 | 创造模式物品栏分类，见 `ItemCategory` 枚举 |
 | `texture` | string | 是 | 纹理名称 |
 | `options.group` | string | 否 | 物品分组 |
-| `options.hide_in_command` | boolean | 否 | 是否在命令自动补全中隐藏（默认 false）。为 true 时自动创建附加物。 |
+| `options.hide_in_command` | boolean | 否 | 是否在命令自动补全中隐藏（默认 false） |
 | `options.max_stack_size` | number | 否 | 最大堆叠数量（默认 64，范围 1-99） |
 | `options.format_version` | string | 否 | 格式版本（默认 `'1.21.40'`） |
 
@@ -86,7 +87,7 @@ const food = ItemAPI.createFood(
 | 参数 | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `identifier` | string | — | 唯一标识符 |
-| `category` | string | — | 创造菜单分类 |
+| `category` | ItemCategory | — | 创造菜单分类 |
 | `texture` | string | — | 纹理名称 |
 | `options.group` | string | `undefined` | 物品分组 |
 | `options.hide_in_command` | boolean | `false` | 是否在命令中隐藏 |
@@ -147,12 +148,12 @@ const chestplate = ItemAPI.createChestplateArmor(
     'ruby_chestplate',               // item_texture: string — 物品图标纹理
     'textures/models/armor/ruby',   // texture_path: string — 模型纹理路径
     {                                // options?: object
-        // 可传入标准选项
+        displayName: '红宝石胸甲',   // 自定义显示名称（默认："我的自定义胸甲"）
     }
 )
 ```
 
-**返回值：** `Chestplate` — 胸甲实例。
+**返回值：** `Armor` — 盔甲实例（`type === ArmorType.Chestplate`）。
 
 ---
 
@@ -168,7 +169,7 @@ const helmet = ItemAPI.createHelmetArmor(
 )
 ```
 
-**返回值：** `Helmet` — 头盔实例。
+**返回值：** `Armor` — 盔甲实例（`type === ArmorType.Helmet`）。
 
 ---
 
@@ -184,7 +185,7 @@ const boots = ItemAPI.createBootArmor(
 )
 ```
 
-**返回值：** `Boot` — 靴子实例。
+**返回值：** `Armor` — 盔甲实例（`type === ArmorType.Boots`）。
 
 ---
 
@@ -200,7 +201,12 @@ const leggings = ItemAPI.createLeggingsArmor(
 )
 ```
 
-**返回值：** `Leggings` — 护腿实例。
+**返回值：** `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 }`。
 
 ---
 
@@ -209,11 +215,11 @@ const leggings = ItemAPI.createLeggingsArmor(
 创建翻书物品（动态帧动画物品）。
 
 ```typescript
-import { ItemAPI } from '@sapdon/core'
+import { ItemAPI, ItemCategory } from '@sapdon/core'
 
 const flipbook = ItemAPI.createFlipbookItem(
     'my_mod:animated_block',     // identifier: string
-    'construction',               // category: string
+    ItemCategory.Construction,    // category: ItemCategory
     'my_flipbook_tex',            // texture: string — 纹理名称
     {
         group: 'minecraft:itemGroup.name.construction',
@@ -230,7 +236,7 @@ const flipbook = ItemAPI.createFlipbookItem(
 | 参数 | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `identifier` | string | — | 唯一标识符 |
-| `category` | string | — | 创造菜单分类 |
+| `category` | ItemCategory | — | 创造菜单分类 |
 | `texture` | string | — | 纹理名称（位于 `textures/blocks/` 目录） |
 | `options.group` | string | `undefined` | 物品分组 |
 | `options.hide_in_command` | boolean | `false` | 是否在命令中隐藏 |
@@ -249,11 +255,11 @@ const flipbook = ItemAPI.createFlipbookItem(
 ### 构造函数
 
 ```typescript
-import { Item } from '@sapdon/core'
+import { Item, ItemCategory } from '@sapdon/core'
 
 const item = new Item(
     'my_mod:custom_item',   // identifier: string — 唯一标识符
-    'items',                 // category: string — 创造菜单分类
+    ItemCategory.Items,      // category: ItemCategory — 创造菜单分类
     'custom_texture',        // texture: string — 纹理名称
     {                        // options?: object
         group: '...',
@@ -269,7 +275,7 @@ const item = new Item(
 | 参数 | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `identifier` | string | — | 唯一标识符 |
-| `category` | string | — | 创造菜单分类 |
+| `category` | ItemCategory | — | 创造菜单分类 |
 | `texture` | string | — | 纹理名称 |
 | `options.group` | string | `undefined` | 分组 |
 | `options.hide_in_command` | boolean | `false` | 是否在命令中隐藏 |
@@ -348,16 +354,19 @@ const json = item.toObject()
 
 ### 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 | 纹理名称 |
+| `texture` | string \| object | 纹理名称，或包含 `default`/`dyed`/`iconTrim`/`bundleOpenBack`/`bundleOpenFront` 的纹理对象 |
 
 ---
 
@@ -391,25 +400,30 @@ ItemComponent.setDisplayName('§c传奇之剑')
 
 ---
 
-### setFoodComponent(nutrition, saturation, canAlwaysEat?, usingConvertsTo?)
+### setFoodComponent(options)
 
 设置食物属性组件。
 
 ```typescript
-ItemComponent.setFoodComponent(true, 6, 1.2)
-// → Map { 'minecraft:food' => { can_always_eat: true, nutrition: 6, saturation_modifier: 1.2 } }
+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' } }
 ```
 
 | 参数 | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `canAlwaysEat` | boolean | — | 是否可随时食用 |
-| `nutrition` | number | `0` | 营养值 |
-| `saturationModifier` | number | `0.6` | 饱和度修正值 |
-| `usingConvertsTo` | string | `undefined` | 食用后转换的目标物品 ID |
+| `options.canAlwaysEat` | boolean | `false` | 是否可随时食用 |
+| `options.nutrition` | number | `0` | 营养值 |
+| `options.saturationModifier` | number | `0.6` | 饱和度修正值 |
+| `options.usingConvertsTo` | string | `undefined` | 食用后转换的目标物品 ID |
 
 ---
 
-### setWearable(slot, protection)
+### setWearable(protection?, slot?, hidesPlayerLocation?)
 
 设置可穿戴组件。
 
@@ -429,6 +443,7 @@ ItemComponent.setWearable(4, 'slot.armor.feet')
 |------|------|--------|------|
 | `protection` | number | `0` | 保护值 |
 | `slot` | string | `undefined` | 装备槽位（如 `'slot.armor.head'`） |
+| `hidesPlayerLocation` | boolean | `undefined` | 穿戴时是否在定位栏与定位地图中隐藏 |
 
 ---
 
@@ -514,19 +529,25 @@ ItemComponent.setProjectile(0.5, 'minecraft:snowball')
 
 ---
 
-### setUseModifiers(movementModifier?, useDuration?)
+### setUseModifiers(options?)
 
 设置使用修饰组件。
 
 ```typescript
-ItemComponent.setUseModifiers(0.5, 1.5)
+ItemComponent.setUseModifiers({
+    movementModifier: 0.5,
+    useDuration: 1.5,
+})
 // → Map { 'minecraft:use_modifiers' => { movement_modifier: 0.5, use_duration: 1.5 } }
 ```
 
 | 参数 | 类型 | 描述 |
 |------|------|------|
-| `movementModifier` | number | 使用物品时玩家移动速度缩放值 |
-| `useDuration` | number | 物品使用所需时间（秒） |
+| `options.movementModifier` | number | 使用物品时玩家移动速度缩放值 |
+| `options.useDuration` | number | 物品使用所需时间（秒） |
+| `options.emitVibrations` | boolean | 是否在开始/停止使用时发出振动 |
+| `options.startSound` | string | 开始使用时触发的原版音效 |
+| `options.startUsing` | string | 使用修饰生效时机（`'always'` 或 `'if_first'`） |
 
 ---
 
@@ -565,37 +586,43 @@ ItemComponent.setDurability(500, 10, 50)
 
 ### setInteractButton(text)
 
-设置交互按钮文本。
+设置交互按钮。支持字符串（自定义文案）或布尔值（通用 "Use Item" 文案）。
 
 ```typescript
 ItemComponent.setInteractButton('打开')
 // → Map { 'minecraft:interact_button' => '打开' }
+ItemComponent.setInteractButton(true)
+// → Map { 'minecraft:interact_button' => true }
 ```
 
 | 参数 | 类型 | 描述 |
 |------|------|------|
-| `text` | string | 交互时显示的文本 |
+| `text` | string \| boolean | 交互时显示的文本，或 `true`/`false` |
 
 ---
 
-### setBlockPlacer(block, replaceBlockItem?, useOn?)
+### setBlockPlacer(block, options?)
 
 设置方块放置器组件。
 
 ```typescript
 ItemComponent.setBlockPlacer(
-    'my_mod:custom_block',    // 要放置的方块 ID
-    false,                    // 是否替换方块物品
-    ['my_mod:custom_block']  // 可以使用的方块列表
+    'my_mod:custom_block',                // 要放置的方块 ID
+    {
+        replaceBlockItem: false,           // 是否替换方块物品（可选）
+        alignedPlacement: true,            // 是否启用对齐放置（可选）
+        useOn: ['minecraft:dirt'],         // 可放置的目标方块列表（可选）
+    }
 )
-// → Map { 'minecraft:block_placer' => { block: '...', replace_block_item: false, use_on: [...] } }
+// → Map { 'minecraft:block_placer' => { block: '...', replace_block_item: false, aligned_placement: true, use_on: [...] } }
 ```
 
 | 参数 | 类型 | 描述 |
 |------|------|------|
 | `block` | string | 要放置的方块标识符 |
-| `replaceBlockItem` | boolean | 是否替换方块物品 |
-| `useOn` | string[] | 可使用此物品的方块列表 |
+| `options.replaceBlockItem` | boolean | 是否替换方块物品 |
+| `options.alignedPlacement` | boolean | 是否启用对齐放置 |
+| `options.useOn` | BlockDescriptor[] | 可使用此物品的方块描述符列表 |
 
 ---
 
@@ -663,7 +690,7 @@ const json = ItemComponent.toJSON(map)
 
 ```typescript
 ItemComponent.setCustomComponents(['my_mod:my_component'])
-// → Map { 'minecraft:custom_components' => ['my_mod:my_component'] }
+// → Map { 'my_mod:my_component' => {} }
 ```
 
 | 参数 | 类型 | 描述 |
@@ -672,40 +699,152 @@ ItemComponent.setCustomComponents(['my_mod:my_component'])
 
 ---
 
-## 4. Armor 子类
+### 更多组件（对齐 Bedrock Wiki 1.26.30）
+
+以下方法均参考 [Bedrock Wiki Item Components](https://wiki.bedrock.dev/items/item-components)，覆盖 wiki 收录的全部组件。
 
-盔甲系统包含四个子类，分别对应四种盔甲类型。它们继承自 `Armor` 基类，内部创建 `Item` 和 `Attachable` 实例。
+**布尔/数值/字符串组件：**
 
-### Armor 基类
+| 方法 | 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
-// 基类构造函数（不直接使用）
-new Armor(identifier, category, item_texture, texture_path, options?)
+// 冷却
+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 | 关联的可附着物实例 |
-| `setArrachableGeometry(key, geometry)` | this | 设置可附着物几何模型 |
+| `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;` |
-| **Boot** | `ItemAPI.createBootArmor()` | 4 | `slot.armor.feet` | `geometry.player.armor.boots` | `v.boot_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'`
@@ -713,7 +852,7 @@ new Armor(identifier, category, item_texture, texture_path, options?)
 ```typescript
 // 自定义盔甲几何模型示例
 ItemAPI.createHelmetArmor('my_mod:custom_helmet', 'custom_helmet', 'textures/models/armor/custom')
-    .setArrachableGeometry('default', 'geometry.custom.helmet')
+    .setAttachableGeometry('default', 'geometry.custom.helmet')
 ```
 
 ---
@@ -739,9 +878,9 @@ class Food extends Item {
 | `minecraft:use_animation` | Food 构造 |
 
 ```typescript
-import { Food } from '@sapdon/core'
+import { Food, ItemCategory } from '@sapdon/core'
 
-const food = new Food('my_mod:apple', 'items', 'apple', {
+const food = new Food('my_mod:apple', ItemCategory.Items, 'apple', {
     nutrition: 8,
     saturationModifier: 1.5,
     canAlwaysEat: true,
@@ -773,12 +912,11 @@ enum ItemCategory {
 ```typescript
 import { ItemAPI, ItemCategory } from '@sapdon/core'
 
-// 使用枚举值
 ItemAPI.createItem('test:item', ItemCategory.Construction, 'tex')
-// 等价于
-ItemAPI.createItem('test:item', 'construction', 'tex')
 ```
 
+> **注意：** `category` 参数为严格枚举类型，传 `'construction'` 等裸字符串会报 TS 编译错误，并会在运行时校验失败。必须使用 `ItemCategory.Construction` 等枚举成员。
+
 ---
 
 ## 7. Attachable 类
@@ -894,3 +1032,94 @@ 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
+```