自定义容器方块

自定义容器方块让你创建类似箱子的物品存储方块。容器使用原生 C++ 驱动的背包界面，支持长按分堆、双击合堆、Shift 快速移入等操作。方块被破坏后，内部物品会自动掉落。

前置条件

请先阅读 自定义基础方块 了解方块的注册流程和 JSON 组件体系。自定义容器需要设置 base_block: "netease_container"，推荐使用 format_version: "1.16.100"。不需要开启实验性玩法。

概述

自定义容器方块是中国版中功能最丰富的特殊方块类型之一。通过 netease:block_container 组件，你可以配置：

• 存储容量：1 到 108 个物品槽位
• 自定义 UI：通过 screen_name 指定容器打开时显示的 JSON UI 界面
• 漏斗交互：配置方块与漏斗的物品输入/输出规则
• 容器标题：自定义容器打开时显示的标题文本

容器方块的核心行为：

• 玩家右键交互打开容器 UI
• 物品存储持久化，退出游戏后数据不丢失
• 方块被破坏时，所有内部物品自动掉落为实体
• 支持漏斗的物品漏入和漏出
• 可通过 PlayerTryPutCustomContainerItemServerEvent 事件实现物品过滤

netease:block_container 组件

键	类型	默认值	说明
custom_description	string	—	可选，容器 UI 打开时显示的标题文本
screen_name	string	—	必填，交互方块时打开的 UI 界面，格式为 namespace.screenName
container_size	int	—	必填，容器的物品槽位数量，取值范围 1 ~ 108
hopper	dict	{}	可选，配置漏斗的物品漏入/漏出规则

"netease:block_container": {
    "custom_description": "自定义储物箱",
    "screen_name": "mymod_ui.custom_chest_screen",
    "container_size": 27,
    "hopper": {}
}

container_size 匹配

container_size 必须与 UI 中的槽位数量匹配：

• 若 UI 槽位 > container_size：超出部分的槽位无法放入物品
• 若 UI 槽位 < container_size：物品可通过 Shift 放入但在 UI 中不可见

建议保持两者完全一致。

hopper 字段详解

hopper 字段控制漏斗与容器之间的物品传输规则。

键	类型	说明
input	bool	是否支持漏斗漏入。true 启用 input_slot 规则；false 禁用漏入；缺省表示所有面、所有槽位均支持漏入
input_slot	list(dict)	仅 input 为 true 时生效，定义各面的漏入规则
output	bool	是否支持从底部漏出。缺省表示支持从所有槽位漏出
output_slot	list(dict)	仅 output 为 true 时生效，指定支持漏出的槽位

input_slot / output_slot 子字段

键	类型	说明
face	int	方块的面编号
slot	list(int)	该面支持的槽位编号列表。缺省表示该面所有槽位均支持

face 编号对照：

编号	面
0	下方（down）
1	上方（up）
2	北（north）
3	南（south）
4	西（west）
5	东（east）

完整示例：27 槽自定义储物箱

行为包 — 方块定义

文件路径：行为包/netease_blocks/custom_chest.json

{
    "format_version": "1.16.100",
    "minecraft:block": {
        "description": {
            "identifier": "mymod:custom_chest",
            "base_block": "netease_container",
            "register_to_create_menu": true,
            "category": "Construction"
        },
        "components": {
            "minecraft:destroy_time": 2.5,
            "minecraft:explosion_resistance": 2.5,
            "netease:tier": {
                "digger": "hatchet",
                "destroy_special": false
            },
            "netease:face_directional": {
                "type": "direction"
            },
            "netease:block_container": {
                "custom_description": "自定义储物箱",
                "screen_name": "netease_container.netease_custom_container_screen",
                "container_size": 27,
                "hopper": {
                    "input": true,
                    "input_slot": [
                        {
                            "face": 1,
                            "slot": [0, 1, 2, 3, 4, 5, 6, 7, 8]
                        }
                    ],
                    "output": true,
                    "output_slot": [
                        {
                            "face": 0,
                            "slot": [18, 19, 20, 21, 22, 23, 24, 25, 26]
                        }
                    ]
                }
            }
        }
    }
}

上面的配置含义：

• 容器有 27 个槽位（3 行 × 9 列）
• 漏斗从上方（face 1） 漏入时，物品只能进入第一行的 0~8 号槽位
• 漏斗从下方（face 0） 漏出时，只从第三行的 18~26 号槽位抽取物品

资源包 — blocks.json

文件路径：资源包/blocks.json

{
    "mymod:custom_chest": {
        "textures": {
            "up": "mymod:chest_top",
            "down": "mymod:chest_bottom",
            "north": "mymod:chest_front",
            "south": "mymod:chest_side",
            "west": "mymod:chest_side",
            "east": "mymod:chest_side"
        },
        "sound": "wood"
    }
}

资源包 — 本地化

文件路径：资源包/texts/zh_CN.lang

tile.mymod:custom_chest.name=自定义储物箱

UI 配置要点

容器的 UI 通过 JSON UI 系统定义。你的 UI 中需要使用 collection_name 为 netease_container 的网格来绑定容器槽位。

关键配置

• collection_name 必须设为 "netease_container"
• UI 中每个槽位通过 collection_index 指定编号，从 0 开始
• UI 槽位总数应与 container_size 完全匹配

使用内置 UI

如果你不需要完全自定义 UI，可以直接使用网易内置的容器 UI：

"screen_name": "netease_container.netease_custom_container_screen"

此内置 UI 提供了一个标准的箱子样式界面，槽位数量会根据 container_size 自动适配。

自定义 UI 示例片段

如果你需要完全自定义 UI，以下是槽位绑定的关键片段：

{
    "container_grid": {
        "type": "grid",
        "size": [162, 54],
        "grid_dimensions": [9, 3],
        "collection_name": "netease_container",
        "grid_item_template": "common.container_item"
    }
}

相关事件

事件	端	说明
PlayerTryPutCustomContainerItemServerEvent	服务端	玩家尝试向容器中放入/移动物品时触发。可通过设置 cancel 为 True 阻止操作，用于实现物品过滤

物品过滤示例

def OnTryPutItem(self, args):
    """只允许矿石类物品放入容器"""
    itemName = args.get("itemName", "")
    if "ore" not in itemName:
        args["cancel"] = True

常见问题

container_size 超出范围导致注册失败

原因： container_size 的有效范围是 1 ~ 108。超出此范围的值会导致方块注册失败，引擎不会加载该方块。

物品通过 Shift 放入但在 UI 中看不到

原因： container_size 大于 UI 中实际的槽位数量。Shift 快速移入时，物品会按编号顺序填入槽位，如果超出 UI 显示范围的槽位被填入了物品，玩家在 UI 中无法看到。请确保 container_size 与 UI 槽位数完全一致。

漏斗无法向容器中输入物品

原因： 检查 hopper.input 的配置：

• 如果 input 为 false，漏斗无法漏入
• 如果 input 为 true 但 input_slot 中没有匹配漏斗所在面的 face，同样无法漏入
• 如果 hopper 字段缺省（空对象 {}），默认所有面、所有槽位都支持漏入

方块破坏后物品没有掉落

原因： 请确认 base_block 已正确设为 "netease_container"。只有使用此 base_block 的方块才具有物品自动掉落的行为。

screen_name 格式不正确

screen_name 的格式必须为 namespace.screenName，其中 namespace 是你的 UI JSON 文件的命名空间，screenName 是屏幕定义的名称。例如 "mymod_ui.chest_screen" 指向命名空间为 mymod_ui 的 UI 文件中名为 chest_screen 的屏幕。

下一步

• 自定义基础方块 — 回顾方块注册流程和组件配置
• 方块组件速查 — 所有方块组件一览
• UI 开发指南 — JSON UI 系统的完整开发文档