Custom Block

Custom-Block — 为 BONE:MSD 添加自定义方块，每个方块只需一行

本项目在 Claude Code（Anthropic 的 AI 编程助手）的帮助下完成。

它协助编写了生成器、将 BONE:MSD 引擎移植到 Minecraft 26.3、编写测试和本文档。

在 blocks.json 中用列表描述方块，格式类似枚举值：完整方块、台阶和
楼梯。其余内容都由生成器完成：方块物品、战利品表、创造模式菜单
条目、模型、翻译和原版覆盖项。最终生成一个
适用于 Minecraft 26.3、且已包含 BONE:MSD 引擎的整合包。

Custom-Block/
├── blocks.json          ← your block "enum" (edit this)
├── textures/            ← 16×16 PNG textures (put them here)
├── slots.lock.json      ← which slab each full block occupies (auto-generated, do NOT delete)
├── generator/build.py   ← the generator
├── engine-patches/26.3/ ← fixes that port the BONE:MSD engine to Minecraft 26.3
├── tests/               ← build check on a real 26.3 server, no client needed
├── build/               ← output: custom_blocks.zip (recreated on every build)
└── extension/           ← original BONE:MSD engine, author's example and PDF (reference, do not edit)

快速开始

1. 将纹理放入 textures/，例如 textures/marble.png。
2. 在 blocks.json 中添加一项：

   { "id": "marble", "name": { "en_us": "Marble", "ru_ru": "Мрамор" }, "material": "stone", "texture": "marble" }

同一纹理的台阶或楼梯各加一行，并设置 shape：

   { "id": "marble_slab",   "name": "Marble Slab",   "material": "stone", "shape": "slab",   "texture": "marble" },
   { "id": "marble_stairs", "name": "Marble Stairs", "material": "stone", "shape": "stairs", "texture": "marble" }

1. 构建并安装到世界：

   python3 generator/build.py --install "<path to the world folder>"

1. 重新进入世界。 /reload 还不够：新的创造模式菜单条目（画作）只有在世界加载时才会注册。如果只更改了纹理或模型，按 F3+T 即可。

获取方块：/function custom_blocks:give_all 或 /function custom_blocks:give/<id>。
在创造模式中，它们位于 功能方块 标签页的画作列表中。

需要 Python 3.9 或更高版本（仅使用标准库）。生成器提示信息为俄语。

方块字段

| 字段 | 必填 | 含义 |
|—|—|—|
| id | 是 | 方块名称：a-z、0-9、_。重命名会导致世界中已放置的方块丢失。 |
| name | 否 | 字符串（en_us）或 { "en_us": "...", "ru_ru": "..." }。默认根据 id 派生。 |
| title | 否 | 创造模式菜单中的标题。仅限 A-Z a-z 0-9 和空格，因为引擎字体不支持其他字符。默认为 name.en_us。 |
| material | 否 | wood · stone（默认）· copper · wool · concrete。用于设置声音、硬度、所需工具和易燃性。 |
| shape | 否 | full（默认）· slab · stairs。台阶和楼梯由 item_display 绘制（见下文）；对它们来说，model 只能是 cube_all、cube_column 或 cube_bottom_top。 |
| texture | * | 所有面使用同一张材质（模型 cube_all）。 |
| model + textures | * | cube_column（side、end）· cube_bottom_top（side、top、bottom）· cube（up、down、north、south、east、west，可选 particle）。 |
| model_file | 否 | 仅适用于完整方块。自定义 JSON 模型的路径（例如由 Blockbench 创建的模型），相对于 Custom-Block/。textures 中的条目会合并到该模型中。模型仍必须是完整方块（见限制）。 |
| drop | 否 | 改为掉落的其他战利品表，例如 minecraft:blocks/oak_planks。默认掉落方块本身。 |
| creative | 否 | false 会将方块从创造模式菜单中隐藏。 |
| slab / waterlogged | 否 | 仅适用于完整方块。将方块固定到指定台阶上，例如 "slab": "cherry_slab"。很少需要使用。 |

\* 必须提供 texture 或 textures 其中之一。对于台阶和楼梯，texture 会应用于每个面；
使用 cube_column 时，end 材质会用于顶面和底面；使用 cube_bottom_top 时，top、bottom
和 side 材质会用于名称所指的对应面。

不带 : 的材质值表示文件 textures/<name>.png。你可以在旁边放置一个 .png.mcmeta
来添加动画。带有 : 的值表示现有材质，例如 minecraft:block/calcite。

全局设置位于 blocks.json：

• namespace — 生成内容的命名空间（custom_blocks）；
• description — 资源包描述；
• minecraft_version — 目前仅支持 26.3。它用于选择资源包格式编号和数据语法：26.3 对战利品表和谓词进行了大量改动（modifier、condition、match_block）；
• use_waterlogged_slots — 也使用每个台阶的第二种含水状态。默认关闭：PDF 列出了这些状态下的错误；
• reserved_slabs — 生成器不得修改的台阶，因为其他资源包正在使用它们。

工作原理

槽位。每个方块都会占用一个原版台阶的 <slab>[type=double] 状态。
BONE:MSD 引擎会将玩家制作的双层台阶转换为完整方块，因此该状态在
世界中空闲。资源包会在其上绘制你的模型，数据包则会替换其掉落物。方块
没有方块实体：运行速度快，可被活塞推动，也不会发生不同步。

每种材料可用的槽位：木材 12 个、石头 44 个、铜 3 个、羊毛 15 个、混凝土 15 个。使用
use_waterlogged_slots
时，槽位数量会翻倍。每种材料会留出一个台阶，不纳入可用槽位：
它是自定义台阶的基础（见下文）。

槽位稳定性。每个槽位只分配一次，并保存在 slots.lock.json 中，因此
blocks.json 的顺序无关紧要。移除方块时，其槽位会被永久弃用，不会再分配给
新方块；否则，世界中已放置的方块就会变成新方块。若仍要重新使用
已弃用的槽位：python3 generator/build.py --free-retired。

放置方块。 方块物品是携带 bone_cb 数据的屏障方块。引擎会拦截屏障方块的放置
操作，在其位置放置命令方块；下一刻，命令方块会放置真正的
方块。

台阶和楼梯（"shape"，1.1.0 新增）。 台阶或楼梯方块不能使用空闲方块状态：因为没有形状合适的空闲台阶或楼梯状态。于是，这些方块会以一个原版基础方块为底，
并在其上方显示一个
：item_display

| 材料 | 台阶基础方块 | 楼梯基础方块 |
|—|—|—|
| 木头 | oak_slab | oak_stairs |
| 石头 | stone_slab | stone_stairs |
| 铜 | waxed_cut_copper_slab | waxed_cut_copper_stairs |
| 羊毛 | white_wool_slab | white_wool_stairs |
| 混凝土 | white_concrete_slab | white_concrete_stairs |

• 方块物品实际上是基础方块物品（例如 oak_slab），并带有你的模型和 bone_cs 数据。游戏会像往常一样放置它，因此上下位置、朝向、楼梯转角和含水状态都能正常工作。放置操作会触发进度，随后从玩家视角发出的射线会找到方块，并在方块位置召唤一个item_display，其中携带该物品的副本。基础方块提供碰撞箱、声音和硬度。
• 模型使用原版 slab/stairs 模型并替换为你的纹理，尺寸比基础方块大 1%，防止基础方块纹理透出来。楼梯的显示实体每刻都会读取方块状态并切换模型（直梯、内角、外角）及旋转方向，因此转角会像原版楼梯一样跟随相邻方块变化。
• 破坏方块时，基础方块消失后，显示实体会查找刚掉落的基础方块物品，取走一个并改为掉落你的物品。如果没有掉落物（创造模式、/setblock），则不会额外掉落任何物品。
• 两个自定义台阶可以在同一格中叠放（生成两个显示实体）。引擎不会把这种双台阶转换成木板。

引擎移植。原版引擎（extension/bone-msd-26-5）在 26.3 中无法加载：
世界会以安全模式打开，并显示 Failed to parse bone_msd:block_engine/placed_block。生成器会复制引擎，并在其上应用
：engine-patches/26.3/

• 新的 placed_block 进度格式；
• 放置修复：原版引擎会响应任何已放置的屏障方块，并将 7 格范围内的所有屏障方块转换成命令方块。普通屏障因此变成了多余的命令方块，而放置自定义方块附近的屏障则会变成它的副本。现在，只有携带 bone_cb 的物品才会触发进度，并且只转换玩家准星所指向的屏障方块；
• item modify 中的新语法；update_slot
• 作者的存档中缺失的五个红石方块标签；
• 引擎射线中的检查（raycast/trigger）：如果双台阶中包含 Custom-Block 台阶，就不会将其转换为原版完整方块。

资源包只包含引擎实际使用的文件：字体未引用的纹理和作者的
演示字符串都不会打包进去。

一个包，兼具两种用途。在 26.3 中，数据包和资源包使用不同的格式编号
（121 和 97），但该包只有一个 pack.mcmeta。因此它声明了
min_format: 97、max_format: 121。游戏自身代码会将该包报告为两种用途都兼容；已对此进行验证。

从 1.0.x 升级

已经放置的方块会继续正常工作；它们的槽位不会改变。不同之处在于：现在有五种台阶
作为自定义台阶的基底，不再分配给完整方块：oak_slab、stone_slab、
waxed_cut_copper_slab、white_wool_slab、white_concrete_slab。如果你的 slots.lock.json 将
其中一种分配给了完整方块，构建就会报错并指出该方块名称。用 "slab" 将该方块固定到
另一种台阶上；已经放置的该类方块随后会显示为普通的双层台阶。使用默认顺序时，只有当某种材料几乎没有空闲槽位后才会发生这种情况。

安装

build/custom_blocks.zip 是唯一需要的文件：一个包含 data/ 和 assets/ 的 zip 文件。

自动安装：运行 --install（参见快速入门），会将 zip 复制到 <world>/datapacks/ 和同一游戏实例的
resourcepacks/ 文件夹中。它还会移除这些资源包的旧版本，并在作者提供的原版文件仍存在时发出警告。请在游戏设置中启用该资源包一次。

手动安装：将 custom_blocks.zip 复制到 <world>/datapacks/ 以及 resourcepacks/ 中。

不要将原版 bone-msd-26-5 或作者的 bone-msd-example-pack 与此资源包一同安装。原版引擎会破坏 26.3 地图，而示例资源包会覆盖同一个
items/painting.json。

如果遇到问题，请检查该游戏实例的 logs/latest.log。包含 Missing data pack、
Failed to load function、Failed to parse 或 Missing block model 的日志行会指出原因。

创造模式菜单提示框（omg_font）

omg_font 是引擎资源包中的字体。它的“字符”实际上是图片：

• … — 高 47 像素的背景部件，外观类似原版提示框（深色填充、紫色边框）；
• … — 空格，包括负空格；
• A-Z a-z 0-9 — 大号字母。

在创造模式中，方块就是一幅画，而它的提示框内容为：画作 / 变体标题 / 作者 /
尺寸。变体标题使用这种字体显示。背景向上延伸，覆盖画作这一行，并绘制出带有方块名称的伪提示框。背景宽度会根据名称调整（生成器中的 painting_title）。

标题之后的行会在之后绘制，也就是说会显示在伪提示框上方：

• 画作尺寸（“16×16”）。引擎只会在英文中将其清空，所以其他语言会显示出尺寸。现在生成器会为所有语言清空尺寸，因此原版画作的尺寸也会被隐藏。
• 高级提示（F3+H）：minecraft:painting 和组件数量。资源包无法移除这些内容；关闭 F3+H 即可获得干净的提示框。

无需游戏客户端进行测试

python3 tests/run_gametest.py

该脚本会从 Prism Launcher 获取 Java 和 26.3 的 jar，并启动 Minecraft 内置的
GameTest 服务器，加载 build/ 中的资源包以及测试资源包 tests/cbtest。大约 15 秒内
会检查：

• 资源包能否无错误或警告地加载；
• 方块物品是否带有 bone_cb；
• 屏障 → 命令方块 → 已放置的方块，且不会触碰附近的普通屏障；
• 自定义方块和普通台阶的掉落物；
• 画作 → 方块物品的转换；
• 台阶和楼梯：显示放置、楼梯跟随形状变化、由两个自定义台阶组成的双层台阶，以及破坏后的掉落物（共 16 项检查）。

测试针对示例方块 split_oak、engraved_copper、split_oak_slab 和 split_oak_stairs。无法通过这种方式检查资源包；只有游戏客户端才能渲染它。

限制

• 完整方块就是双层台阶，因此它们的命中箱、碰撞箱和遮挡效果始终都是完整方块。非立方体model_file只会改变外观，在世界中留下可透视的空隙。
• 台阶和楼梯（1.1.0 新增；逻辑已通过服务端测试，但尚未在游戏客户端中检查外观）：
• 每个方块都是一个实体（双层台阶则是两个），每刻都会进行检查，因此成千上万个这类方块比完整方块更耗性能；
• 旋转楼梯时，贴图会随模型一起旋转（原版楼梯会保持贴图方向不变，uvlock），所以带方向性的贴图看起来会与原版不同；
• 破坏粒子和裂纹使用基础方块（例如橡木）的效果；
• 活塞只会移动基础方块：该方块会变成普通的基础方块；
• 自定义双层台阶会使用上方方块的光照；
• 中键选取会得到原版基础方块。
• 贴图必须是不透明的：台阶会渲染成实心方块。
• 在创造模式中使用中键选取，得到的是原版台阶，而不是你的方块。
• 玩家将同类型台阶叠成双层时，自定义方块会闪现 1 刻（已知的引擎问题）。
• 世界中已有的双层台阶，或由世界生成创建的双层台阶，都会变成自定义方块。因此会优先使用较少见的台阶（pale_oak、bamboo_mosaic、resin_brick……）。
• 引擎通过命令方块放置方块：服务器需要安装enable-command-block=true。
• 引擎会将待放置的方块存放在一个共享存储区。如果两名玩家在同一刻放置自定义方块，两人都会得到第二名玩家放置的方块。

鸣谢

BONE:MSD（“Bhex’s Over-Named Extension for Mod-Sized Datapacks”）由 Bhex 制作。原始
引擎、示例包和文档位于extension/。这里唯一的改动是：删除了
作者的草稿（*-old函数）和未使用的字体贴图，并替换了整合包图标和
说明。textures/中的贴图来自该示例包。这些内容由第三方制作，不属于
本项目；所有权利均归其作者所有。如作者提出要求，我们会将其移除。