Hytale角色建模与附件系统：Blockbench MCP打造可换装装备模型的实战指南

blockbench-mcp-plugin 是一个为 Blockbench 添加 MCP Server 的开源插件，它让 AI 助手可以直接驱动 Blockbench 完成 Hytale 角色建模、骨骼搭建、附件（Attachments）绑定与模型校验，是打造"可换装"装备模型的实用工具。本文面向新手，带你用最少的手动操作，理解角色 + 附件系统的完整工作流。

为什么用 Blockbench MCP 做 Hytale 角色？ 🎯

传统流程里，做一个带盔甲、武器、披风的换装角色意味着：反复导出、手动命名骨骼、逐个检查节点数、来回对照格式文档。接入 Blockbench MCP 后，AI 客户端可以直接调用 hytale_* 系列工具，把"建骨架 → 摆几何 → 标记附件件 → 校验导出"变成对话式操作，新手也能一次做对。

该插件在 README.md 中说明了两种接入方式：Blockbench 桌面版插件（HTTP）与无头 stdio 服务，本文以桌面版插件为主要场景。

三步接入：MCP Server 最快配置方法 ⚡

1. 安装插件：打开 Blockbench 桌面版，进入 File > Plugins，选择 "Load Plugin from URL" 并粘贴插件地址完成安装（地址见 docs/llms/install.md）。
2. 确认 Hytale 插件：Hytale 相关工具依赖 Hytale Models 插件处于安装且启用状态，未安装时工具会自动隐藏，不会报错。
3. 在 AI 客户端配置：在客户端的 MCP 配置中填入默认地址 http://localhost:3000/bb-mcp。各客户端（VS Code、Cline、Claude Desktop 等）的完整示例可直接参考 llms-install.md 和 README.md，替换端口与端点即可。

💡 小贴士：端口和端点可在 Blockbench 的 Settings > General > MCP Server Port / MCP Server Endpoint 中修改。

角色建模核心概念：格式、节点与骨骼 🦴

Hytale 提供两种模型格式（详见 prompts/hytale_model_creation.md）：

格式	密度	适用场景
hytale_character	64 像素/世界单位	角色、附件、手持武器与食物
hytale_prop	32 像素/世界单位	场景道具与装饰物

新手最需要记住的三条硬规则：

• 节点上限 255：骨骼（Group）与方块（Cube）都计入节点，超出会无法导出，用 hytale_validate_model 可随时检查当前数量；
• 用 stretch 而非小数尺寸：Hytale 偏好拉伸倍数，UV 处理更干净；
• 纹理尺寸必须是 32 的整数倍：如 128x96 的矩形图集是合法的。

创建项目的推荐顺序：先用 get_capabilities 发现格式，再 create_project 创建项目，接着 add_group 搭骨骼、place_cube / hytale_create_quad 添加几何，最后运行校验。这些工具的完整定义位于 server/tools/hytale.ts。

附件系统：可换装装备模型的核心原理 🧩

附件（Attachments）是独立的模型，运行时动态挂载到基础模型的骨骼上，这是实现"可换装"的关键。官方指南 prompts/hytale_attachments.md 给出了清晰的模型：

• 附件集合（Collection）：每套装备是一个独立可导出的集合，拥有自己的纹理，导出编码为 blockymodel；
• 附件件（Attachment Piece）：集合内的骨骼被标记 is_piece: true 后，就会吸附到主模型中同名骨骼上——例如附件里的 head 骨骼自动扣到角色头骨上；
• 多变体共存：同一骨骼可以挂多个附件（剑、斧、镐都挂 hand_right），由游戏逻辑决定显示哪一个。

基础模型 character.blockymodel
├── head          ← 头盔集合挂这里
├── body         ← 胸甲集合挂这里
└── hand_right   ← 剑 / 斧 / 镐集合挂这里

典型换装架构一览：头盔、胸甲、护手分别成为独立集合，各自维护纹理与节点数，互不干扰。

用 MCP 工具搭建一个附件：标准四步走 🛠️

1. 建集合：在 Blockbench 集合面板创建新集合，导出编码设为 blockymodel；
2. 摆几何：向集合中添加 Hytale 方块/Quad，按需要挂到骨骼下；
3. 标记附件件：调用 hytale_set_attachment_piece，传入 group_name: "hand_right"、is_piece: true，该骨骼即成为挂载点（锚点即骨骼原点，旋转决定朝向）；
4. 分配纹理：每个集合使用独立纹理，便于混搭和换色板。

过程中可随时用 hytale_list_attachments 与 hytale_list_attachment_pieces 自查。除工具外，插件还暴露了只读资源 hytale://attachments 与 hytale://pieces，让 AI 无需"动手"就能盘点当前所有附件集合与挂载点，实现见 server/resources/hytale.ts。

动画与可见性：让装备"活"起来 🎬

附件会继承主模型骨骼动画——角色挥臂时，手套、武器自动跟随，无需为每件装备单独做动画。两个进阶技巧（详见 prompts/hytale_animation_workflow.md）：

• 可见性关键帧：hytale_create_visibility_keyframe 可在指定时间切换骨骼显隐，适合做装备穿上/脱下的切换效果、受击状态表现；
• 循环模式：hytale_set_animation_loop 支持 loop（循环）、hold（定格）、once（单次）三种模式。

注意 Hytale 动画以 60 帧/秒为时间基准，工具中使用小数秒（如 0.5、1.0）设置关键帧时间即可。

导出前必做：模型校验清单 ✅

导出前建议按清单逐项确认：

检查项	工具 / 方法
主模型节点数 ≤ 255	hytale_validate_model
纹理尺寸是否为 32 的倍数	hytale_validate_model 一并报告
附件是否单独校验	附件导出需逐个验证（主模型校验不覆盖附件）
格式信息确认	hytale_get_format_info（返回密度、FPS、节点数）

需要特别说明：校验通过并不等于 100% 运行时兼容，导出后仍建议在游戏侧或目标引擎里最终确认一次。

项目资料索引 📚

• 附件系统完整指南：prompts/hytale_attachments.md
• 角色建模指南：prompts/hytale_model_creation.md
• 动画工作流：prompts/hytale_animation_workflow.md
• Hytale 工具实现：server/tools/hytale.ts
• Hytale 检测与附件读取逻辑：lib/hytale.ts
• MCP 资源定义：server/resources/hytale.ts
• 扩展开发（为插件注册自定义 MCP 工具）：docs/plugin.md

总结 🏁

用 blockbench-mcp-plugin 打造 Hytale 可换装装备模型，核心思路只有三点：同名骨骼自动吸附决定挂载逻辑、独立集合 + 独立纹理保证混搭自由、导出前用 hytale_validate_model 兜底守住 255 节点与 32 倍数纹理两条红线。掌握这套流程后，从光板角色到全身盔甲 + 多武器变体，都能在 AI 助手的协助下快速完成。