Model Lab

Model Lab

在 Blender 中根据参数绘制游戏枪械模型，完成绑定，并与真实枪械进行核对。

一个 MCP 服务，可根据少量参数在 Blender 中绘制游戏枪械模型。每次构建都包含按真实比例制作的真实部件，每个活动部件各有一根骨骼、弹匣，以及游戏所需的信息。每次构建都会进行自检，另有一项检查会将模型轮廓与真实枪械的照片进行比对。

输入“制作一把右侧导轨装有红点瞄准镜和枪灯的 M4A1”，Model Lab 就会生成已绑定的 FBX、每个配件各自的 FBX、一个 .blend 文件、一张图片集，以及包含枪械空间中所有标记的 facts.json。如果有检查未通过，它也会告诉你。它只制作游戏模型：外部形状和活动部件。它不会绘制可运作的内部结构，也不会生成制造数据。

构建产物

你将获得	内容
SK_<name>_Rig.fbx	安装在骨架上的枪械：Bolt、ChargingHandle、DustCover、BoltCatch、MagRelease、Selector、Trigger、ForwardAssist、Magazine、MagRound、Stock；每个部件都有真实的枢轴和行程
SM_<name>_Magazine.fbx	单独的弹匣，原点位于供弹唇处，供手部使用
一个配件 FBX	原点位于后坐力榫处；有活动部件时使用 SK_（折叠式瞄准具、防尘盖、翻转式放大镜）
<name>.blend	包含所有内容，并将活动部件的循环设为一个动作
facts.json	标记（膛室、抛壳口、弹匣井、供弹唇、握把、支撑手、枪口、瞄准具）、导轨及其槽位、配件及其插槽、部件表、所有检查结果
sheet.png	带标注的视图：两侧、顶部、前部、局部特写、打开的枪机、瞄准视野

枪械空间：单位为厘米，+X 指向枪械左侧，+Y 朝前，+Z 朝上。原点位于枪膛轴线上、静止状态下的枪机平面。

安装

Model Lab 需要 Python 3.10 或更高版本，以及 Blender 4.2 或更高版本。

uvx modellab-mcp

或

pip install modellab-mcp

将其添加到你的 MCP 客户端（Claude Code、Claude Desktop，或任何可运行 stdio 服务的客户端）：

{
  "mcpServers": {
    "modellab": {
      "command": "uvx",
      "args": ["modellab-mcp"],
      "env": { "MODELLAB_BLENDER": "C:/Program Files/Blender Foundation/Blender 4.2/blender.exe" }
    }
  }
}

设置	作用
MODELLAB_BLENDER	Blender 可执行文件的路径。如果 Blender 已在 PATH 中或位于常见安装目录，可省略此项。
MODELLAB_OUT	Model Lab 唯一会写入文件的文件夹。默认为 ~/.modellab。
MODELLAB_WAIT_FOR	可选的进程名称，用于指定会占用机器的进程，例如 UnrealEditor.exe,blender.exe。此类进程运行时，构建会拒绝启动。默认关闭。
MODELLAB_IDLE_OK	配合 MODELLAB_WAIT_FOR 使用：命令行中用于标识长期运行工作进程的部分（默认为 poselab_mcp）。只有此类工作进程处于忙碌状态时，才会被视为占用机器。

工具

工具	功能
list_presets	开箱即用的枪械：M4A1、M16A2、AR15、M4A1_Kitted、AR15_Optic。
list_platforms、describe_params	枪械系列及每个参数：取值范围或可选项、单位、含义，以及真实数值的来源。
list_attachments	适用于导轨和 M-LOK 槽位的 9 类配件。
build_gun	根据预设或平台构建枪械，并可更改任意参数。motion=true 会添加枪械循环动作的 GIF。
build_gun_clips	在构建所用的骨架上生成枪械自身的动画片段，每个片段均经过测量，并分别提供一个 FBX 和一个 GIF。
list_references、compare_to_reference	检查真实枪械：将构建的轮廓与照片进行比对。
list_builds、read_build	查看已有构建及其信息。

也可以在 shell 中执行相同的调用：modellab presets、modellab build M4A1 stock_pos=2 name=MyM4、 modellab clips <build>、modellab compare。运行 modellab help 查看命令列表。

每次构建都会自检

构建会报告每项检查的结果。检查内容包括：

• 长度是否符合公开数据（M4A1 为 29.75 和 33 英寸，M16A2 为 39.63 英寸）；
• 弹膛是否与膛线对齐；
• 防尘盖：是否完全覆盖抛壳口、铰链是否位于底边，以及打开后是否抵在下方而非穿过下方 （构建会让防尘盖每次摆动一度，并在首次接触时停止）；
• 弹匣是否避开弹匣井壁且安装到位；
• 枪机是否越过最上方的弹药；
• 瞄准线：后照门孔和前准星是否处于同一高度；
• 每个配件是否安装在适配的导轨上、在所有状态下是否都不与枪械相撞，以及光学瞄准镜是否位于机械瞄准线之上；
• 每个可见部件是否都具备其真实特征（parts_complete）。部件表列出真实枪械上可见的每个部件，以及让人能够辨认出该部件的特征：拉机柄的后掠翼、指钩、卡扣和卷销；枪机卡榫的锯齿；枪托管锁紧螺母的槽口；前准星座的刺刀座、背带环和锥形销；等等。缺少任何特征都会导致构建检查失败。导轨编号等标记会列为纹理，而非形状。

真实枪械检查

compare_to_reference 会按照参考照片自身的比例绘制构建的侧面轮廓。它会将构建与枪口和膛线对齐，逐列测量两个轮廓，并指出不同之处。叠加图会将模型以半透明红色显示在照片上：透过模型显出的深色照片区域，就是模型遗漏的真实枪械部分。

这项检查发现了自检无法发现的问题：下机匣向后偏移了 1.55 cm，前准星座向后偏移了 2.4 cm 且形状错误，枪托轮廓、弹匣曲线和导轨高度也不正确。现在，枪械轮廓上没有任何长度超过 1.75 cm 的部分偏差超过 1 cm。配件采用的是类别，而非照片中的确切型号，因此检查时会将配件轮廓分开处理。

该参考资料随软件包一同提供：一张由 PEO Soldier 拍摄的 M4A1 卡宾枪照片，来源为 Wikimedia Commons 上的 File:M4A1-flattop.jpg，属于美国联邦政府作品，且为公有领域作品。检查会根据导轨齿测量比例，齿间距为 0.394 英寸。

枪械导轨上的附件

每条导轨都会报告其槽位，槽位间距遵循皮卡汀尼导轨标准（MIL-STD-1913），后端的槽位为 0。M-LOK 护木也会报告其槽位（32 × 7 mm，间距 40 mm）。可按名称传入附件，也可使用 {item, rail, slot, state, options}：

{"preset": "M4A1", "params": {"attachments": [{"item": "flip_rear", "state": "down"}, "red_dot", "weapon_light"]}}

九类附件：折叠式后准星和前准星、M4 提把、带翻盖的 30 mm 红点瞄准镜、全息瞄准镜、安装在翻转支架上的 3 倍放大镜、4x32 棱镜瞄准镜、垂直握把、枪灯。构建时会检查每件附件是否适配其导轨、在所有状态下是否与枪身及其他附件发生干涉。若某件附件会阻挡另一件的移动，构建结果会列出：例如，放大镜后方的后准星只有在放大镜翻开后才能竖起。

动作与片段

每个 .blend 文件都将操作循环保存为一个动作。motion=true 会将其渲染为 GIF：拉回拉机柄、护盖弹开、枪机框复进、弹匣取出并装回，然后是各附件自身的动作。

build_gun_clips 会根据实际时间数据，以每秒 60 帧为枪械的动作片段设置关键帧：上膛、检查膛室、射击（75 ms 的循环）、最后一发（枪机卡在枪机卡笋上）、装弹、空仓装弹，以及枪托的不同位置。每段片段都经过测量：每个部件各自绕其轴运动、完整行程、枪机框移动 1 cm 前护盖打开、弹匣脱离弹匣井并就位，以及枪机保持卡住，直至弹匣装入。

下一步：手握部位的圆滑边缘

所有者，2026-10-21：“握把上没有锋利的边缘，这是 Model Lab 接下来要改进的地方。在手册或图像中查看时，要把边角稍微做圆，尤其是人手抓握的地方。大多数情况下，这些地方不会有锋利边缘，因为锋利的边缘会伤到手或人。把它们做得圆滑些，让手能握住。”

• 所有供手抓握的部件都要做圆角：握把、手枪握把的护板、护木、弹匣、拉机柄，以及枪托的贴腮部和底板。
• 手册、图纸或照片显示了圆角半径时，就按其中的数据读取。否则使用明确标注名称的人体工程学资料，并将其与部件一同记录。
• 实枪检查也会对比这些边缘。

实测结果说明了其重要性：在一份数字化的 M1911A1 模型中，握把保险是方形凸起。手放在握把上时，保险的边缘会压入掌心 0.42 cm（掌心可让位 0.27 cm）。将握把部件的圆角设为 0.75 mm（MIL-STD-1472G 5.7.7.6 允许的最小值）后，超过掌心让位量的部分降至 0.09 cm。红色表示之前（尖锐），蓝色表示之后（圆滑）。下方是该部位处理前后的特写。

限制

• 目前仅支持一个平台：AR-15 系列。其他平台将陆续支持。
• 目前仅有一张参考照片：M4A1 右侧视图。
• 片段仅呈现枪械侧面的动作。手部动作片段需要手臂骨架。
• 暂无保险选择杆片段：尚未依据资料检查其处于 SAFE 时的方向。
• 许多数值是根据照片估算得出。describe_params 会列出所有来源和估算值。

商标

M-LOK 是 Magpul Industries 的商标。Model Lab 按照已公布的尺寸绘制 M-LOK 槽位，与 Magpul 没有关联。AR-15 是 Colt's Manufacturing 的商标；在此处，该名称按其通常含义指代步枪系列。军事名称（M4A1、M16A2、M68）用于指代 Model Lab 复制的枪械和部件。不为任何产品背书。

许可证

MIT。请参阅 LICENSE。