Kzeroko KTM2
EN
English

Blockbench 人形制作插件

自带部件工作台：声明、模板骨骼、预览、导出控制与当前限制。

更新于 2026/9/27 8 分钟阅读

使用自带的 Blockbench 插件导出人形部件与 NPC 起始资源。本指南说明本地安装、部件声明和导出流程的适用范围。

你要做的东西

模组自带的 IsekaiExpansion Humanoid Creator，版本 2.2.0，从 Blockbench 文档导出已声明部件，也能导出 NPC 身体与起始预设。输出包括几何体、纹理、可选遮罩模板、目录条目及筛选后的附加动画。

前置要求

通过桌面编辑器的本地插件加载功能载入 src/main/resources/blockbench_plugin/isekaiexpansion_humanoid_creator.js。插件注册为仅桌面使用，导出需要文件系统模块，不会下载远程插件。

文档须能由 Bedrock 模型编解码器编译，并符合人形骨架约定。导出器将几何格式 1.14.0、1.21.0 和 1.21.20 改为 1.12.0，并删除 item_display_transforms；这只是特定转换，并非通用格式转换器。

步骤

设置目标位置

在设置 → 导出或工作台的输出页设置根目录与命名空间。首先检查配置的已存在目录；若其中包含 src/main/resources，使用该子目录，否则直接使用配置目录。

配置根目录不可用时，插件沿文档保存或导出路径向上寻找仓库或资源目录，再回退到文档旁的 export。未保存文档且没有可用根目录时无法导出。写入前查看实际根目录：配置路径拼错或不存在时，可能直接选择后备位置。

设置／运行选项类型默认值作用
isekaiexpansion_humanoid_creator_rootexisting path""持久保存的导出根目录；接受仓库根目录、资源目录或已存在的输出目录。
isekaiexpansion_humanoid_creator_namespacestringisekaiexpansion持久保存的命名空间，采用与部件 ID 相同的清理规则。
stylestringdefaultPNG 样式名；移除无效字符，空值回退为 default。
genderenumnonenone、male、female；把声明部件的模型写成性别网格 <part>.male.geo.json 或 <part>.female.geo.json。纹理、目录条目和部件 ID 不变。
npcModebooleanfalse导出 NPC 身体；启用目录生成时也导出预设。
npcIdstring""NPC 模式必需，清理后不得为空。
generateMasksbooleantrue为有纹理且绑定通道的导出项生成遮罩模板。
generateCatalogbooleantrue生成部件 JSON；NPC 模式下也生成 NPC 预设。
generateAnimationsbooleantrue编译并筛选部件动画片段。
overwritebooleanfalse替换已有输出文件；关闭时逐文件跳过。

只有根目录和命名空间作为机器设置持久保存；其他值属于当前运行的面板状态。

声明部件

名为 hair 的骨骼声明头发槽位，部件 ID 来自文档名称；名为 hair_long_wavy 的骨骼声明 hair/long_wavy。槽位前缀按最长名称优先匹配。骨架自有骨骼不声明部件，显式身体部件使用 body_<part>。

声明骨骼上保存的 isekai_part_id 覆盖值优先于骨骼名称，其次才使用文档名称。在部件页编辑它，清空后恢复名称解析。ID 转为小写，空格替换为下划线，移除 a-z、0-9、_、- 之外的字符，再去掉两端下划线。

__ 之后的文本是分片标签。例如 outfit_top_robe__torso 和 outfit_top_robe__sleeve 合并为一个部件。声明骨骼拥有整个子树，嵌套的类似槽位名称不会另起部件。未声明几何体成为基础网格候选内容。

标记参考几何体并检查预览

使用大纲更多选项中的模板开关、骨骼右键操作，或工具 → 切换模板骨骼。保存的布尔属性是 isekai_template。子级继承标记而不逐个写入；选中方块时操作其父骨骼。编辑器支持撤销时，该操作会记录为撤销步骤，与编辑器锁定标记无关。

模板保留可见以供试穿对齐，但不进入检测出的部件和纹理覆盖范围；导出模型时剥离其几何体。手持物品代理骨骼 main_item 与 off_item 的方块和网格也会被移除。

选择部件后，部件预览通过渲染层 10 隔离对应元素，不改变保存到文档的元素可见性。清空选择显示整个模型，重置视图重新取景。预览使用独立灯光，显示地面网格并排除侧视网格。

验证并导出

检查页与工具 → 验证人形约定列出阻断问题及非阻断提示。问题包括没有骨骼、忽略大小写后的重名、缺失或多余根骨骼、缺失动画锚点、大写骨架名称，以及超过容差 0.0001 的非零锚点旋转。缺失可选特征或挂接骨骼、动画驱动骨架自有骨骼时仅给出提示。此检查不会验证全部枢轴、父级、纹理或输出资源。

先使用路径预览执行导出规划而不写入。全部导出写入声明部件及所请求的 NPC 输出；行内导出只写该部件，不写 NPC 身体或预设。关闭覆盖时逐文件跳过已有文件；更改样式不会向已有目录文件合并新样式。

模型导出操作编译后的副本，保留所属几何体和空骨架锚点，移除模板与代理几何体，并将保留骨骼重新挂到最近的保留祖先。动画导出只保留所属的非骨架自有骨骼，丢弃空片段。运行时仍按 idle 和 run 选择片段，见部件制作。

检查纹理输出

部件仅使用一张且基础网格未使用的纹理时，标为 own sheet，整张图像导出。该分类不会检查其他部件是否也使用此图像。否则，导出器用首个引用纹理，在原 UV 坐标裁出部件覆盖范围，不会将多个来源纹理合成图集。

没有分配纹理时，仍输出模型和目录，但没有图像，并在报告中列出。多纹理部件应先整理来源图像，或手工检查并补完输出。工具 → 分离所选纹理也使用文档的第一张纹理，将新纹理添加到编辑器，不会重写所有方块的纹理分配。

遮罩模板填充首个已绑定的遮罩通道。来源像素只要 alpha 非零，就生成完整覆盖 255；完全透明的像素保持零。来源半透明不会保留为部分遮罩覆盖。应再将模板编辑为所需 RGB 区域。遮罩操作会添加可编辑纹理，自动导出则将其写到样式旁。导出器不生成发光纹理图像。

声明它

插件输出遵循部件制作中的路径。目录生成写入 styles、按槽位显式指定的 channels 和 sort: 1000，不会推断种族限制、解锁条件或配套部件要求。应按格式参考手工补完这些字段。

NPC 模式另外生成：

assets/<namespace>/geo/entity/humanoid/body/<npc>.geo.json
assets/<namespace>/textures/entity/humanoid/body/<npc>/<style>.png
data/<namespace>/humanoid_parts/body/<npc>.json
data/<namespace>/npc_presets/<npc>.json

身体目录包含 unlock.type: locked 和 sort: 900。起始预设使用 gender: female、fixed_gender: true、生成的身体引用、带 default: true 和 sort: 0 的 default 换装、根级 sort: 1000，以及标签 unique。这些是固定导出默认值，不能从角色模型推断，应逐项检查。完整字段见预设数据。

性别变体开关不会为 NPC 模式的身体添加性别限定符。多个声明部件占用同一槽位时，起始换装保留排序后导出列表中最后遇到的部件，不会自动创建多套换装。

当前 NPC 身体限制：基础网格导出按每个骨骼自身名称是否声明部件来筛选。因此，声明服装中的任意命名子骨骼，也可能进入身体模型，即使检测流程已正确将其归于服装。将输出放入包之前，检查身体中是否存在这类重复几何体。模板几何体仍被排除。纹理覆盖范围分离失败时，身体纹理也可能回退为整张来源图像。

检查清单

在仓库根目录运行现有测试框架：

node tools/blockbench_plugin_test/run.js

运行器递归发现全部 *.test.js，逐个在独立进程中执行。这些桩测试覆盖注册、声明、模板、预览隔离和导出结构，不验证真实 Blockbench 渲染、纹理像素或游戏内对齐。

  • 重新打开保存的文档，确认模板标记与部件 ID 覆盖仍在。
  • 在两种编辑器语言下检查部件、输出和检查页。
  • 预览输出路径，导出到临时目录并检查全部文件。
  • 关闭覆盖后再次导出，确认手工编辑的目录和遮罩保留。
  • 检查共用或多张纹理、半透明像素和嵌套内容骨骼的部件。
  • 测试同槽位含多个部件的 NPC 文档，检查生成换装。
  • 在 Blockbench 和游戏内执行部件制作检查清单。

相关页面

人形部件、预设数据与 NPC 资源。