把 Blockbench 吊灯导入 Fabric

01 / 10

模型只是起点

把 Blockbench 作品连接到真正的游戏系统。

Simon 已经在 Blockbench 中完成 light.bbmodel。本课连接模型、贴图、资源 JSON、Java 注册和客户端渲染，让吊灯可以通过 /give 获取、放入世界并发出 15 级亮光。

1. 解释 .bbmodel 为什么不能直接复制进 Fabric 资源目录。
2. 转换出 blockstates、方块模型、物品模型与独立 PNG。
3. 完成注册、创造栏、透明渲染、构建与客户端排错。

1. 检查 bbmodel
2. 烘焙旋转与坐标
3. 生成资源
4. 注册 LIGHT_BLOCK
5. 设置 Cutout
6. 构建并进入游戏

02 / 10

先读懂 light.bbmodel

检查格式、几何、旋转与贴图。

模型格式：free

它不是 Minecraft Java Block 格式，不能直接改名为 JSON 使用。

几何元素：45

包括立方体与零厚度平面，从不同角度检查结构。

内嵌贴图：2

两张 PNG 分别为 128 × 128 与 64 × 64。

特殊旋转：90°

Java 方块模型不能直接使用这些编辑器旋转，需要转换器烘焙。

03 / 10

运行模型转换器

把编辑器数据转换为 Minecraft 资源。

在 MOD 工程根目录运行课程配套的 tools/import-bbmodel.mjs。把示例里的输入文件与输出目录改成你的实际路径；脚本不属于 Minecraft 内置命令。

$modelFile = "C:\TeacherMa\Student\SimonJF2027\light.bbmodel"
$resourceDir = "C:\TeacherMa\Mod\simon-minecraft-template-1.20\src\main\resources"
node tools/import-bbmodel.mjs $modelFile $resourceDir "simon-minecraft" "light"

解析层级

读取 elements、groups、outliner 与 textures。

烘焙几何

合并旋转、原点和坐标偏移。

处理贴图

提取 PNG，将 UV 换算到 0–16。

生成资源

输出 blockstate、block model 和 item model。

04 / 10

每份资源都有一份工作

以下路径位于 assets/simon-minecraft/。

blockstates/light.json

方块状态入口，指向 simon-minecraft:block/light。

models/block/light.json

世界模型，包含 45 个 elements 与两张贴图引用。

models/item/light.json

背包模型，继承 block/light。

textures/block/light_texture.png

从 bbmodel 提取的主体贴图。

textures/block/light_upper.png

顶部贴图带透明背景，需要 Cutout 渲染。

lang/zh_cn.json + en_us.json

分别提供“吊灯”与 Light 的显示名称。

完整注册 ID 为 simon-minecraft:light。资源引用中省略文件扩展名；贴图 ID 中也省略 textures/。

05 / 10

在 IntelliJ 注册吊灯

复用第 2 课的双注册辅助方法。

public static Block LIGHT_BLOCK;

public static void registerModBlocks() {
    LIGHT_BLOCK = registerBlock("light",
            new Block(FabricBlockSettings.create()
                    .strength(1.0f)
                    .luminance(state -> 15)
                    .nonOpaque()));
    ItemGroupEvents.modifyEntriesEvent(ItemGroups.FUNCTIONAL)
            .register(entries -> entries.add(LIGHT_BLOCK));
}

registerBlock("light")

调用模板辅助方法，同时注册方块和同 ID 的 BlockItem。

strength(1.0f)

设置破坏硬度。

luminance(state -> 15)

让放置的吊灯持续发出最高 15 级亮光。

nonOpaque()

告诉光照系统它不是不透明整方块。

ItemGroups.FUNCTIONAL

加入创造模式功能方块分类。

06 / 10

透明渲染与显示名称

客户端渲染层与材料透明属性配合使用。

public void onInitializeClient() {
    BlockRenderLayerMap.INSTANCE.putBlock(
            ModBlocks.LIGHT_BLOCK,
            RenderLayer.getCutout()
    );
}

import net.fabricmc.fabric.api.blockrenderlayer.v1.BlockRenderLayerMap;
import net.minecraft.client.render.RenderLayer;
import com.malaoshi.simon.block.ModBlocks;

把调用合并进现有客户端入口，保留其他客户端初始化。两张贴图含完全透明像素，Cutout 丢弃透明部分并保留清晰边缘；只写 nonOpaque() 不能代替渲染层。不要把客户端渲染类放到服务端入口。

{ "block.simon-minecraft.light": "\u540a\u706f" }

{ "block.simon-minecraft.light": "Light" }

/give @s simon-minecraft:light

07 / 10

沿 JSON 追到贴图

区分可以直接使用的文件和结构示意。

{
  "variants": {
    "": { "model": "simon-minecraft:block/light" }
  }
}

{
  "parent": "simon-minecraft:block/light"
}

{
  "ambientocclusion": false,
  "textures": {
    "0": "simon-minecraft:block/light_texture",
    "1": "simon-minecraft:block/light_upper",
    "particle": "simon-minecraft:block/light_texture"
  },
  "elements": [ ... 45 elements ... ]
}

08 / 10

进入游戏，确认吊灯发光

构建成功之后，还要检查实际显示。

.\gradlew.bat build
.\gradlew.bat runClient

1. 模型：木质顶架、铁链和灯罩结构完整。
2. 透明：透明像素正确，没有黑色背景或紫黑缺失纹理。
3. 光照：暗室墙面和地面被照亮，注册亮度为 15。
4. 资源：日志中没有 light 专属的模型和贴图加载错误。

原教材记录了模板 Gradle build 成功、runClient 进入已有世界，以及由 Minecraft ScreenshotRecorder 保存的实机截图。你需要在自己的工程中重新完成这些验证。

09 / 10

排查 IntelliJ 启动配置

命令行能运行而 IDE 失败时，先检查运行模块。

ClassNotFoundException: net.fabricmc.devlaunchinjector.Main

原教材遇到的情况是命令行 runClient 能启动，但 IntelliJ 的 Minecraft Client 配置绑定到不含运行依赖的根模块。此时先检查类路径，不要删除 Java 代码或重装贴图。

<module name="simon-minecraft-template-1.20.main"/>

.\gradlew.bat ideaSyncTask
.\gradlew.bat build

重新加载所有 Gradle 项目，再选择 Minecraft Client。模块名称应与你实际工程一致；上述名称适用于指定模板。

10 / 10

把导入流程变成自己的工具

选择一个挑战，保留可重复验证的结果。

A · 模型

在 Blockbench 修改一处灯架尺寸，重新转换并验证。

B · 光照

把亮度改成 10，比较夜间照明范围。

C · 资源排错

故意改错一处 texture 路径，利用日志定位并修复紫黑贴图。

D · 交互

尝试加入 BooleanProperty，让右键控制亮灭；第 6 课会展开。

E · 转换工具

给 import-bbmodel.mjs 增加尺寸报告和超范围提示。

1. 能解释 bbmodel、blockstates、block model、item model、texture 与 Java 注册的关系。
2. 重新转换后 build 成功，游戏里能获取、放置并看到透明模型和预期照明。