• 低代码
• 代码生成
• 桌面应用
• 游戏开发

本文基于 MCreator 仓库中 de_DE 语言包的 beblock 模型帮助文档（英文原文见 default 语言包同路径文档）展开。该文档面向 MCreator 的 Bedrock Edition Add-On 生成器（generator-addon-26.5x），讲解「Bedrock Block（基岩版方块，元素类型BEBLOCK）」的模型（Model）选择：模型决定方块的视觉外观，而不决定方块的边框（Bounding Box）。读完本文，你将掌握四种模型选项的含义与适用场景、模型与渲染方法（Render Method）的配合关系、纹理联动逻辑，以及 MCreator 从 UI 配置到生成block.json的完整底层实现链路。

1. 文档背景：它挂在哪个界面、服务哪个功能

在 MCreator 中新建BE Block（基岩版方块）元素后，GUI 分为「视觉（Visual）」「属性（Properties）」「生成（Generation）」「脚本（Scripts）」四个页面，其中「视觉」页顶部即「模型」下拉框。该下拉框的帮助按钮绑定的帮助入口正是beblock/model，相关代码见 BEBlockGUI.java：

renderSettings.add( HelpUtils.wrapWithHelpButton(this.withEntry("beblock/model"), L10N.label("elementgui.beblock.model"))); renderSettings.add(renderType);

也就是说，plugins/mcreator-localization插件在语言包help/<语言>/beblock/model.md中提供该下拉框的逐语言帮助文本，MCreator 的 UI 会按当前界面语言自动加载对应的 Markdown 并渲染为帮助弹窗。这也是为什么同一份文档在仓库中存在de_DE、zh_CN、default（英文基准）等多份副本。

核心前提（原文第一句）：模型只定义视觉外观，不定义方块的边框。这一点至关重要——在 Bedrock 引擎中，方块的碰撞体积（collision box）与模型几何体是两套独立的数据；即使选用了自定义几何模型，方块仍然可以（也通常需要）单独设置贴合或不贴合模型形状的边框。

2. 四种模型选项详解

原文档给出了四个选项：Normal、Cross、Single texture、Custom。MCreator 源码中这三个内置模型被定义为常量，见 BEBlockGUI.java：

public static final Model normal = new Model.BuiltInModel("Normal"); public static final Model cross = new Model.BuiltInModel("Cross model"); public static final Model singleTexture = new Model.BuiltInModel("Single texture"); public static final Model[] builtinitemmodels = new Model[] { normal, cross, singleTexture };

2.1 Normal —— 每面独立纹理的普通方块

• 视觉表现：标准立方体方块，六面均可使用独立纹理。
• 适用场景：绝大多数常规方块（石块、矿石、地板等）。
• 纹理要求：需要顶部、底部、前后左右共最多 6 张纹理（未填写的面会回退到主纹理，见下文）。
• 代码对应：renderType = 10。生成方块预览图标时使用顶/左/前三面纹理合成透视方块图（BEBlock.java）：

if (renderType == 10) { return (BufferedImage) MinecraftImageGenerator.Preview.generateBlockIcon( getTextureWithFallback(textureTop), getTextureWithFallback(textureLeft), getTextureWithFallback(textureFront)); }

选中 Normal 时，GUI 会启用六面独立纹理选择器；其它模型则切换为单一纹理选择器（见 BEBlockGUI.java）：

private void updateTextureOptions() { if (normal.equals(renderType.getSelectedItem())) { textures.setTextureFormat(BlockTexturesSelector.TextureFormat.ALL); } else { textures.setTextureFormat(BlockTexturesSelector.TextureFormat.SINGLE_TEXTURE); } }

生成时，六面纹理分别映射到up / down / north / south / east / west六种材质实例，纹理图集由 terrain_texture.json.ftl 生成；未单独指定顶/左/前面时，源码通过textureTop()、textureLeft()、textureFront()等访问器自动回退到主纹理texture（BEBlock.java）。

2.2 Cross —— 十字交叉模型（花卉类方块）

• 视觉表现：纹理以X 形交叉摆放，典型如花朵、草丛、作物。
• 适用场景：所有非立方体、站立在地面的小型植物类方块。
• 代码对应：renderType = 11。生成block.json时几何体被指定为内置的minecraft:geometry.cross（见 block.json.ftl）：

"minecraft:geometry": <#if data.hasCustomModel()> "geometry.${data.getModel().getReadableName()}" <#elseif data.renderType() == 11> "minecraft:geometry.cross" <#else> "minecraft:geometry.full_block" </#if>,

• 渲染注意事项（原文重点）：选用 Cross 模型时，建议将渲染方法（Render Method）设为alpha_test_single_sided、blend或opaque，以避免纹理闪烁（texture flickering）。原因在于 Cross 模型由两个交叉平面构成，若使用双面渲染或不当的透明混合，两个面会在重叠像素处互相穿插、导致 z-fighting 闪烁。另外，模板对 Cross 还强制关闭了环境光遮蔽与面变暗，见 block.json.ftl：

"*": <@material_face "" data.renderType() == 11 data.renderType() == 11/>

即ambient_occlusion: false、face_dimming: false（宏定义见 block.json.ftl），确保交叉面不会因相邻方块遮挡产生明暗差异。

2.3 Single texture —— 单纹理普通方块

• 视觉表现：外观与 Normal 相同的标准立方体，但六面共用同一张纹理。
• 适用场景：需要快速建模的简单方块，或纹理本身六面一致（如单色块、泥土等）。
• 代码对应：renderType = 12。hasOneTexture()返回true（见 BEBlock.java），因此材质实例退化为单一"*"项，纹理图集也只为该方块注册一条记录（terrain_texture.json.ftl）。预览图标生成时三面均使用主纹理：

} else if (renderType == 12) { return (BufferedImage) MinecraftImageGenerator.Preview.generateBlockIcon( getMainTexture(), getMainTexture(), getMainTexture()); }

与 Normal 相比，Single texture 的主要差异就是减少了纹理槽位，本质上仍是完整立方体几何（minecraft:geometry.full_block），碰撞/边框行为与 Normal 一致。

2.4 Custom —— 自定义 Bedrock 模型（.geo.json）

• 视觉表现：使用你自行制作的Bedrock 几何模型文件（.geo.json），几何体完全由模型决定。
• 尺寸硬限制：方块模型被限制在30×30×30 像素以内（原文档明确说明）。
• 代码对应：renderType = 2。MCreator 将.geo.json识别为Model.Type.BEDROCK，见 Model.java：

} else if (file.getName().endsWith(".geo.json")) { this.file = new File[1]; this.file[0] = file; this.type = Type.BEDROCK; }

模型的显示名由文件名去掉.geo.json后缀得到（Model.java），并最终作为geometry.<显示名>写入生成的block.json（见上文 2.2 的模板分支）。加载时，MCreator 会在工作区models/目录（由 WorkspaceFolderManager.java 的getModelsDir()定义）下查找<名称>.geo.json：

else if (type == Type.BEDROCK) return new Model(new File(workspace.getFolderManager().getModelsDir(), name + ".geo.json"));

在 UI 侧，模型下拉框在三个内置模型之外还会动态并入工作区中所有 Bedrock 模型（BEBlockGUI.java）：

ComboBoxUtil.updateComboBoxContents(renderType, ListUtils.merge(Arrays.asList(normal, cross, singleTexture), Model.getModelsWithTextureMaps(mcreator.getWorkspace()).stream() .filter(el -> el.getType() == Model.Type.BEDROCK).collect(Collectors.toList())));

使用流程：把做好的.geo.json（及配套纹理）放入工作区models/目录 → 重新打开 BE Block 编辑器 → 在「模型」下拉框选择该模型。选中的模型名会被写入数据模型的customModelName字段。

3. 渲染方法（Render Method）与纹理闪烁的配合

原文档在 Cross 条目中给出了渲染方法建议，因此必须结合同目录帮助文档 beblock/render_method.md 理解其含义。渲染方法决定方块的透明表现、背面剔除与远距离渲染行为，相关概念：

• Transparenz（透明度）：完全不可见的像素被裁剪掉（alpha test）。
• Durchscheinend（半透明）：像素半透明，可透视（blend）。
• Rückseiten-Keulung（背面剔除）：从背面看时面不可见。
• Distanzvernichtung（远距离剔除）：面在渲染距离一半之后消失。

MCreator 的BEBlock数据模型提供以下可选渲染方法（BEBlock.java）：

为什么 Cross 推荐这三种？原文档给出的组合（alpha_test_single_sided、blend、opaque）的共同点是都启用背面剔除，从而避免交叉的两个平面在重叠处相互穿透产生纹理闪烁；其中blend适合需要半透明裁切的植物（配合 alpha 通道），opaque适合完全不透明的纹理。模板在写入render_method时仅在非默认值opaque时才输出该字段（block.json.ftl）：

<#if data.renderMethod != "opaque">,"render_method": "${data.renderMethod}"</#if>

4. 从 UI 选项到数据模型与生成的完整链路

把「模型下拉框的每一次选择」到「最终 JSON」串起来，可以得到完整的调用链：

1. UI 选择：BEBlockGUI.java 的getElementFromGUI()将选中模型映射为整数renderType与名称customModelName：

Model model = Objects.requireNonNull(renderType.getSelectedItem()); block.renderType = 10; if (model.getType() == Model.Type.BEDROCK) block.renderType = 2; else if (model.equals(cross)) block.renderType = 11; else if (model.equals(singleTexture)) block.renderType = 12; block.customModelName = model.getReadableName();

2. 数据模型：BEBlock.java 根据renderType反查模型对象，并提供hasCustomModel()（renderType == 2）与hasOneTexture()（自定义 / Cross / 单纹理）两个供模板调用的判断方法。

3. 代码生成：beblock.definition.yaml（插件定义文件）声明block/block.json.ftl输出到@SRCROOT/blocks/@registryname.json，全局模板resourcepack/terrain_texture.json.ftl输出到@RESROOT/textures/terrain_texture.json；block.json.ftl依据hasCustomModel() / renderType() / hasOneTexture()决定minecraft:geometry与minecraft:material_instances的最终形态。

4. 旧版迁移：将 Java 版方块转换为基岩版方块的转换器 BlockToBedrockConverter.java 也会完整迁移纹理、硬度、掉落等属性（并将摩擦系数上限收敛到 0.9、掉落数量上限收敛到 64 以符合 Bedrock 限制），说明模型选择体系是 BE Block 元素配置的一部分，与其它属性一体保存。

5. 实战操作速查

在 MCreator 中配置方块模型的完整步骤：

1. 新建元素 → 类型选择Bedrock Block（BE Block）（对应元素类型BEBLOCK，由ModElementTypeLoader注册）。
2. 进入「视觉（Visual）」页 → 「模型（Model）」下拉框选择Normal / Cross model / Single texture，或从下拉列表中选择已导入的自定义 Bedrock 模型。
3. 根据模型类型设置纹理：
   • Normal：分别指定顶部、底部、前后左右纹理（缺省面自动回退主纹理）；
   • Cross / Single texture / 自定义：指定一张主纹理。
4. 若选择Cross，在「渲染方法（Render Method）」中从alpha_test_single_sided、blend、opaque中择一，避免纹理闪烁。
5. 若选择自定义模型：先将.geo.json放入工作区models/目录（模型尺寸不得超过30×30×30 像素），再刷新编辑器并重新选择。
6. 在「属性」页单独配置方块的边框/碰撞相关属性——模型选择不会影响边框。

6. 常见误区与要点小结

• 模型 ≠ 碰撞箱：模型只改外观，碰撞箱是独立的；需要非标准碰撞体时，务必在其它属性中单独配置，切勿以为选了自定义模型就会自动拥有匹配的碰撞形状。
• Cross 闪烁：交叉平面模型必须搭配启用背面剔除的渲染方法（文档推荐的三种均可），否则会出现纹理闪烁。
• 尺寸上限：自定义.geo.json模型不得超过 30×30×30 像素，超限模型可能无法正确生成或渲染。
• 纹理槽位：Normal 模型用满六面纹理槽位；其它三种模型统一使用单纹理槽位（hasOneTexture()为 true 时材质实例退化为"*"）。
• 默认值：新创建的 BE Block 默认renderType = 10、customModelName = "Normal"（BEBlock.java），渲染方法默认opaque。

若需进一步阅读，可参考英文基准文档 default/beblock/model.md，以及配套的 render_method.md 帮助页；底层实现可深入 BEBlockGUI.java、BEBlock.java 与 block.json.ftl。

• 低代码
• 代码生成
• 桌面应用
• 游戏开发