物品分组、分页与微缩方块

本文介绍三个用于扩展创造物品栏展示的功能：物品分组用于将自定义物品加入原版分组或创建新分组；物品分页用于创建独立的物品分页标签；微缩方块用于将游戏内的区域方块缩小为单个小方块进行展示。三者均通过行为包 JSON 配置实现。

前置知识

阅读本文前，建议先了解 自定义物品 的基础概念与注册方法。

物品分组（netease_group/）

物品分组允许开发者将自定义物品放入原版背包分组或创建新的分组，让物品展示更加清晰。

配置方法

在行为包 behavior 文件夹下建立 netease_group/ 文件夹，添加任意名称的 JSON 文件：

{
  "groups": [
    {
      "group_name": "itemGroup.name.sword",
      "icon": "mymod:my_custom_sword",
      "list": [
        "mymod:my_custom_sword",
        "mymod:my_custom_sword_2"
      ]
    }
  ]
}

字段	说明
group_name	分组名称。使用原版分组名可将物品加入原版分组之后
icon	分组图标的物品 identifier（原版分组时无效）
list	分组包含的自定义物品 identifier 数组

注意

如需加入原版分组，自定义物品 JSON 中的 category 必须与原版分组的 category 一致。例如加入羊毛分组时，category 必须为 "Nature"。

原版分组名称参考

分组名	对应物品
itemGroup.name.sword	剑
itemGroup.name.pickaxe	镐
itemGroup.name.axe	斧头
itemGroup.name.shovel	锹
itemGroup.name.helmet	头盔
itemGroup.name.chestplate	胸甲
itemGroup.name.wool	羊毛
itemGroup.name.planks	木板
itemGroup.name.ore	矿石
itemGroup.name.mobEgg	生物蛋

待补充：完整的原版分组名称列表。

物品分页（netease_tab/）

物品分页允许开发者创建独立的物品栏标签页，让同一 Mod 的自定义物品统一展示。

配置方法

在行为包 behavior 文件夹下新建 netease_tab/ 文件夹，添加任意名称的 JSON 文件：

{
  "category": [
    {
      "name": "my_tab",
      "labelText": "itemCategory.name.my_tab",
      "icon": "textures/items/diamond",
      "sort_by_identifier": true
    }
  ]
}

字段	说明
name	分页名称，小写字母和下划线组成
labelText	分页描述，可在 zh_CN.lang 中设置中文名称
icon	分页图标路径
sort_by_identifier	是否按 identifier 排序（可选，默认 false）

注意

name 由小写字母组成，请勿使用大写字母。

使用方法

在自定义物品的 JSON 中将 category 值设为分页的 name：

{
  "format_version": "1.10.0",
  "minecraft:block": {
    "description": {
      "identifier": "mymod:my_block",
      "category": "my_tab"
    }
  }
}

自定义分页排列在原版分页之后，顺序按 category 数组顺序排列。

多 Mod 合并

从 2.6 版本开始，当多个 Mod 都配置了自定义分页时，引擎会将 name 和 labelText 字段完全相同的物品合并到同一个分页。

待补充：排序规则详细说明与多分页组织建议。

微缩方块（netease_micro_blocks/）

微缩方块用于将游戏内的若干区域的方块形状缩小成单个小方块进行显示。目前游戏内仅开放预微缩方块——通过 ModSDK 接口生成微缩方块数据，将文件放入 Mod 后即可像原生方块一样使用。

行为包配置

在行为包 behavior 目录下的 netease_micro_blocks/ 文件夹中创建微缩方块 JSON：

{
  "format_version": "1.13.0",
  "minecraft:block": {
    "description": {
      "identifier": "micro_block:my_micro",
      "category": "construction",
      "micro_size": "2 2 2"
    },
    "components": {}
  }
}

字段	说明
identifier	必须以 micro_block: 开头，冒号后的名称全局唯一
category	创造物品栏分类（如 construction）
micro_size	微缩方块占据的方格大小（如 "2 2 2"），最大支持 4×4×4

注意

微缩方块不支持原版和网易版的 JSON 组件。identifier 必须以 micro_block: 开头，否则无法识别。

资源包配置

在资源包 models/netease_micro_block/ 文件夹下创建同名 JSON 文件，内容通过 CreateMicroBlockResStr 接口生成。

import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlock(levelId)
result = comp.CreateMicroBlockResStr(
    "my_micro",
    (12, 60, 12),    # 起始坐标
    (26, 76, 26),    # 结束坐标
    colorMap={'minecraft:grass': [12, 22, 123, 255]},
    isMerge=True,
    icon="my_micro_icon"
)

参数	说明
identifier	微缩方块标识（自动添加 micro_block: 前缀）
start	微缩起始坐标
end	微缩结束坐标
colorMap	指定方块类型的微缩颜色
isMerge	是否合并同类型方块（减少性能消耗）
icon	物品栏图标（对应 terrain_texture.json 中的注册名）

待补充：微缩方块资源数据格式详解、渲染方向控制说明。

完整示例

待补充：

1. 物品分组示例：将自定义剑类物品加入原版剑分组
2. 物品分页示例：创建独立的 Mod 分页并添加多个物品
3. 微缩方块示例：从场景中截取区域生成微缩方块

下一步

• 了解 自定义物品 以注册分组和分页中引用的物品
• 了解 Python 脚本开发 中 CreateMicroBlockResStr 接口的使用
• 参考官方 Demo MicroBlocksMod 获取微缩方块示例