Minecraft OBJ Cubizer / Minecraft OBJ 方块转换器

作者 / Author: Ylong 版本 / Version: 1.6.1 适用 / For: Blockbench 桌面版、Minecraft Java 版资源包模型、Animated Java 流程

Minecraft OBJ Cubizer 可以把 Minecraft 建筑 OBJ 转成 Blockbench Java 方块模型，也可以直接导入 Minecraft 结构文件。 制作思路

功能 / Features

• OBJ 导入：读取 .obj、.mtl、PNG 贴图，并重建轴对齐方块。
• 直接导入：支持 .schematic、.schem、.litematic、结构 .nbt、单个 .mca 区域文件。
• 特殊方块：可读取原版 blockstate/model JSON，并内置箱子、床、告示牌、陶罐、铜傀儡像等基础模型。
• 贴图来源：可使用资源包根目录或 Minecraft jar 作为模型与贴图来源。
• Jar 预览贴图：从 Minecraft jar/zip 读取的贴图只用于预览，不会在保存时自动另存 PNG。
• 模型 UV：原版模型没有显式写 UV 的小面，会按 cube 实际像素尺寸自动计算 UV。
• 结构分组：支持逐方块、空间分块、单组和动画部件；Animated Java 自动模式使用静态主体与指定运动部件，其他格式使用逐方块分组。
• 范围筛选：按 X/Y/Z 坐标和方块 ID 筛选，ID 支持 * 通配符。
• 方块合并：沿连续轴合并同状态的完整方块、半砖及部分楼梯等模型，按面裁剪与平铺贴图，保持像素密度；支持竖向动画贴图及可选透明合并。
• 可见面：可选移除被实心邻居遮挡的面，不把玻璃和特殊形状当作遮挡方块。
• 分批导入：显示创建进度，支持取消并回滚；复用重复导入的贴图。
• 后台读取：NBT 解压、解析、选区扫描在 Worker 中运行；跳过物品、文字等实体数据，取消时终止后台任务。
• 结构预览：最多 2048 个低细节实例，先检查坐标和筛选结果，再生成选区内的可编辑 cube。
• 新版兼容：保留当前项目的贴图尺寸和 UV 模式；适配 Blockbench 5.2.2 的对象式纹理引用。
• 红石预览：红石线会按 power 给贴图着色，并修正旋转连接的 UV 方向。
• 资源包路径：导出时自动补全 minecraft:block/... 或自定义命名空间路径。
• 导入提示：结构导入完成后会列出退回完整方块的方块 ID、数量和原因。
• 插件页面：自动修复 About、Changelog 和 Features 的本地显示来源。
• 顶栏菜单：所有插件功能已移动到 Blockbench 顶栏的 Minecraft 方块转换器 菜单。

菜单 / Menu

加载插件后，Blockbench 顶栏会出现：

Minecraft 方块转换器

里面包含：

将 Minecraft OBJ 导入为方块
导入 Minecraft 结构
预览 Minecraft 结构
将所选方块设为动画部件
建筑性能模式
OBJ 导入设置
结构导入设置
导出导入贴图到资源包

原先挂在 文件 > 导入/导出 里的插件功能已经移动到这个独立菜单。

推荐流程 / Recommended Workflow

1. OBJ 流程：用 Mineways 等工具把 Minecraft 建筑导出为 OBJ，然后用本插件导入。
2. 直接结构流程：准备 .schematic、.schem、.litematic、结构 .nbt 或单个 .mca 文件；大型建筑建议先使用“预览 Minecraft 结构”。
3. 在导入结构弹窗或“结构导入设置”里设置贴图来源，建议选择解包后的 Minecraft 资源目录或版本 jar。
4. 导入后检查模型、贴图和方块数量。
5. 使用 Blockbench 自带 Java Block/Item Model 导出 JSON。
6. 需要做原版动画时，可先打开 Animated Java Blueprint，再导入到该项目；无需先转换为 Java 模型。

新版设置

入口：Minecraft 方块转换器 > 结构导入设置，也可以在选择结构文件后的导入窗口设置。

设置	用法
新建项目格式	只在没有打开项目时生效；选择 Animated Java 前须安装并启用该插件。
每格方块大小	默认 1 保留紧凑 Java 模型比例；动画场景可用 16，表示每个 Minecraft 方块占 16 个 Blockbench 单位。
限制坐标范围	最小/最大 X、Y、Z 均包含边界；使用文件中的原始坐标，筛选发生在移动或居中之前。
只导入/排除方块 ID	逗号或空格分隔，例如 minecraft:stone,minecraft:*_planks；留空表示不限制。排除优先。
合并相邻兼容方块模型	默认关闭；沿模型所有子 cube 都连续的轴合并同状态方块，支持半砖、部分楼梯和 90 度方块状态旋转。任意角度的元素旋转、无法精确裁剪的 UV 等仍保留独立 cube。
合并透明完整方块	默认关闭，仅对带明确剔除面的兼容模型生效；移除内部面会影响透明叠加，要求原样效果时请关闭。
分组方式	Animated Java 自动模式使用 body 静态主体和指定动画部件；其他格式默认逐方块分组。仍可手动选择空间分块或单组。
分块边长	默认 16 格；分块组的轴心放在该分块的原点。合并不会跨越分块边界。
最多处理源方块数	默认 1,000,000，与默认 5,000 的 cube 创建预算分别统计。MCA 解码时应用筛选并限制读取。

合并后的纹理需要重复显示，插件会生成 textures/block/cubizer/ 下的平铺 PNG。这些 PNG 不属于原版贴图，导出 Java JSON 后需要通过“导出导入贴图到资源包”一并导出。Animated Java 的资源包导出由其自身处理。

合并不会保留每个源方块的独立编辑边界；要逐块修改或分别制作动画，请关闭合并。隐藏面剔除同样默认关闭，需要拆开方块动画时建议保持关闭，以免移动后露出已移除的面。

平铺贴图按各面的实际 UV 像素区域裁剪后生成，不把小面的纹理拉伸成整张图片。每帧最长不超过 1024 像素，竖向动画总高度不超过 4096 像素；每次导入新增平铺图 RGBA 预算为 64 MiB。触及预算后会提示，后续方块保留独立 cube，仍受 cube 数量限制。竖向动画的帧顺序、时长和插值设置随 PNG 的 .mcmeta 一起导出。

先预览再导入

1. 打开 Minecraft 方块转换器 > 预览 Minecraft 结构，选择结构文件。
2. 修改坐标范围和方块 ID 条件，点击刷新图标。预览只表示粗略形状与方块类别，不展示真实特殊方块模型和纹理。
3. 点击“导入选区”，才会在当前项目中创建可编辑 cube。Minecraft Jar/Zip 或文件夹贴图来源沿用“结构导入设置”。

整理动画部件

预览窗口中，先把坐标范围设为螺旋桨、车轮等运动部件的范围，再点击动画部件旁的加号，填写组名并调整 X/Y/Z 轴心。重复添加各个部件后导入，剩余方块放入 body。范围和轴心使用原始 Minecraft 坐标，移动到原点和缩放会同步作用于骨骼轴心；范围重叠时，先添加的部件优先。合并不会跨越动画部件边界。

导入后，也可以选中需要一起运动的导入 cube，使用“将所选方块设为动画部件”。此时轴心填写的是 Blockbench 模型单位；操作支持撤销，不自动转移旧组上的动画。已旋转的父组下不能直接重组，以免改变模型位置。

大建筑的视口性能

Minecraft 方块转换器 > 建筑性能模式 默认开启。项目中有至少 512 个导入 cube 时，在编辑模式下按父组和材质批量绘制未选中的兼容模型，减少显卡绘制调用。逻辑 cube、原始几何、UV、骨骼和导出数据不变；仍可在视口选中方块，选中的 cube 使用原生渲染，编辑、撤销和模式切换会同步恢复或重建视图。

性能模式下，UV 面板只叠加前 64 个选中元素，避免全选建筑时生成成千上万个 UV 控件；不修改全局 UV 显示设置。未选中 cube 的像素网格辅助线暂不绘制，选中后恢复。关闭性能模式、切换项目或卸载插件后恢复原显示方式。动画贴图、半透明贴图、特殊渲染模式不参与批量绘制；绘画与动画模式使用原生模型。如果 Multi Cube Mesh Optimizer 已启用代理渲染，本插件不再重复创建视口代理。

导入过程中暂缓新 cube 的绘制，图片尺寸提前解析，结束时不再重复重建所有几何。对用户提供的 tower.nbt（2509 个源方块），本机独立 Blockbench 5.2.2 测试生成 3677 个 cube、34 张贴图，导入约 1.5～1.8 秒，静态视口约 37 次绘制调用，原生视图约 3892 次。该结果不是对所有设备与插件组合的速度保证。

读取与缓存

结构解压和解析在后台进行，但最终可编辑 cube 的创建仍由 Blockbench 主线程完成。经典 schematic、litematic 和 MCA 会先按范围限制解码；MCA 缓存最多 16 个已解析区块，不解析选区以外的区块。

支持底层文件读取的环境对 JAR 只读目录和所需资源；Blockbench 5.2.2 的受限文件接口下，JAR 异步读取一次后缓存，仍需要容纳整个压缩包。解出的资源缓存限制为 16 MiB。插件也复用方块状态、模型面和贴图缓存，减少重复读取。

兼容与验证

• 插件基础最低版本仍为 Blockbench 4.8.0；后台结构导入还要求运行环境支持 Worker 和 DecompressionStream，缺少时会提示升级。本轮实机检查使用 5.2.2 与 Animated Java 1.11.0。
• Animated Java 当前要求 Blockbench 5.1.4+、Minecraft Java 1.20.4+；具体导出目标和旋转限制由 Animated Java 设置决定。官方安装说明
• node --check minecraft_obj_cubizer/minecraft_obj_cubizer.js 检查语法；node tests/run.cjs、node tests/worker.cjs、node tests/zip.cjs 运行不依赖额外包的回归检查；浏览器验证步骤见 测试说明。尚未进行游戏内导出与播放验证。

另一个插件下载链接：

https://treehey.github.io/Fimel/#/works/tools

注意 / Notes

• OBJ 转换适合由 Minecraft 方块组成、轴对齐的建筑模型，不适合普通三角网格或曲面模型。
• 直接结构导入会读取方块模型，但不会读取箱子物品、告示牌文字等方块实体数据。
• 结构导入里的方块上限统计的是生成后的 Blockbench cube，不是原始 Minecraft 方块数；默认上限是 5,000 个 cube。
• 若要导出为 Java Block/Item Model，建议最终模型尽量控制在约 48 x 48 x 48 格以内。
• 上述 48 格仅对应默认每格 1 单位的比例；实际 Java 模型元素坐标通常限于 -16 到 32。每格设为 16 时，48 个单位只相当于 3 格，并且放置位置也必须满足坐标范围。
• 大型建筑建议拆分导入。超过 5,000 个 cube 可能变慢，超过 10,000 个 cube 通常建议分批处理。
• 修改插件后，需要在 Blockbench 里重新加载插件。
• 后台解析与创建阶段都支持取消。大型文件仍需容纳解压后的 NBT，预览也要扫描所选区域；低细节预览不等于无限内存或瞬间完成。超大文件建议先裁剪或拆分。