Weapon Lab

Name: Weapon Lab
Author: hpdkhoa

本地服务

github.com/hpdkhoa开发工具21 天前更新

代码仓库

关于 Weapon Lab

Weapon Lab 是用于跨游戏武器查找和修复第一人称视角表现问题的 MCP 服务。它依靠针对游戏编写的探针进行测量，再通过案例和 Gate，根据目标与基线评判变更。

主要功能

01按案例跟踪武器问题
02通过探针测量并试验修复
03Gate 按目标和基线给出判定
04装备绑定与动作分析工具
05枪械模型绑定、构建和验证

适用场景

01发现手部、弹匣或武器姿势错误
02针对多个武器案例测试修复方案
03绑定并验证枪械模型和动作片段

MCP 相关

向 MCP 客户端提供探针、案例、Gate 判定、绑定与动作分析、枪械模型工作流及蓝图建模工具。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "hpdkhoa-weaponlab": {
      "command": "uvx",
      "args": [
        "weaponlab-mcp"
      ],
      "env": {
        "WEAPONLAB_PROJECT": "<WEAPONLAB_PROJECT>",
        "WEAPONLAB_BLENDER": "<WEAPONLAB_BLENDER>"
      }
    }
  }
}

启动命令uvx weaponlab-mcp

需要配置的环境变量

WEAPONLAB_PROJECTThe project folder holding weaponlab.json; the current folder if not set

WEAPONLAB_BLENDERBlender's executable for Motion Lab, if it is not on the PATH or in the usual install folder

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypiweaponlab-mcp0.1.0stdio

工具

收录的工具列表 · 更新于 2 周前

此工具无需参数。

详细介绍

Weapon Lab

第一人称武器问题按类型修复一次，再通过门禁检查每件武器。

一个 MCP 服务，可在门禁机制下发现并修复第一人称武器问题：手没有握住枪、弹匣在弹匣槽中歪斜、刀刃握法不对、手臂遮挡屏幕。

每个问题都会成为一个案例：包含一项指标、一件武器、一个动作和一条通过规则。由你游戏自己的探针测量武器。只有当目标案例通过且其他方面没有变差时，门禁才会放行更改。每种问题只需修复一次，然后用它检查每件武器。

Weapon Lab 不会自行运行你的游戏。你需要为自己的引擎编写一个遵循探针契约的小型探针：输入一个作业文件，输出一个行数据文件。其他所有功能都会基于探针写回的内容工作。

功能

分组	工具	用途
门禁	`gate_run`、`gate_verdict`、`gate_propose`、`gate_approve`、`gate_set_baseline`、`gate_cases`、...	将问题作为案例保存，进行测量并与基线比较，评估更改，记录人员审批。
探针	`probe_run`、`probe_plan`、`probe_status`	启动你游戏的探针。在写入修复之前先尝试修复：调整字段、暂存资源、生成截图和部件转储。
Rig Lab	`rig_pieces`、`rig_facts`、`rig_align`、`rig_part_line`、`rig_fist`	从部件转储中读取摆好姿势的武器：查看其部件、现实世界特征（位于枪管后方的弹匣）、弹匣插入弹匣槽的轴线，以及拳头中的刀柄。
Motion Lab	`motion_roll`、`motion_roll_profile`、`motion_roll_set`、`motion_track`、`motion_render`	在 Blender 中重建动画片段：在前臂活动范围内转动手部，并将滑动部件移回其轴线上。
规格	`spec_list`、`spec_read`、`spec_validate`、`spec_write`	每件武器一个文件：标记（握持、支撑）、锚点（用于查找部件）、特征、限制。
契约	`contract_check`	检查探针的作业、行数据或部件转储。
Gun Kit	`gunkit_inspect`、`gunkit_draft`、`gunkit_from_modellab`、`gunkit_proxy`、`gunkit_rig`、`gunkit_build`、`gunkit_verify`、`gunkit_export`、`gunkit_cases`、`gunkit_actions`、`gunkit_action`	将任意枪械模型带入游戏：为 18 种动作之一搭建骨架，使用一对共用手臂制作武器动画片段和手部动画片段，检查并暂存文件。参见 docs/GUNKIT.md。
Blueprint Lab	`blueprint_source_add`、`blueprint_scan`、`blueprint_specs`、`blueprint_figure_add`、`blueprint_calibrate`、`blueprint_trace`、`blueprint_part`、`blueprint_check`、`blueprint_build`、`blueprint_to_gunkit`、...	根据公开资料（手册、专利、照片）制作真实枪械的视觉复刻：从数据表提取特征，从缩放图纸描摹轮廓，制作标明每个数值来源的蓝图，并在 Blender 中构建模型。参见 docs/BLUEPRINT.md。

在演示项目中试用

演示项目是一个玩具游戏，约有 150 行代码，其中埋有两个 bug 和一个探针。不需要游戏引擎。

pip install -e .
cd examples/demo
weaponlab gate run probe,rig

（当 pip 的脚本目录不在 PATH 中时，运行 python -m weaponlab 的效果相同。）

步枪的左手与护木相差 3.75 cm。匕首的刀柄与拳头横成 90 度。 tests/test_demo.py 展示了完整流程：测量、找到修复方法、通过调优进行尝试，并评估效果。

在你的游戏中使用

在项目中运行 weaponlab init。它会创建 weaponlab.json 和空数据文件。
根据合约编写探针，从 examples/demo/probe/demo_probe.py 开始。在 weaponlab.json 中设置探针命令。
在 weaponlab/data/weapons.json 中列出武器，并在 actions.json 中列出对应动作。
为每个已知 bug 添加一个用例。先测量所有内容，再设置基线。
按照以下流程修复：通过调优或暂存进行尝试，查看截图，提出方案、批准并导入。

使用 weaponlab contract job|rows|parts <file> 单独检查探针。

将其添加到 MCP 客户端

{"mcpServers": {"weaponlab": {"command": "weaponlab-mcp", "env": {"WEAPONLAB_PROJECT": "C:/path/to/your/game"}}}}

设置	含义
`WEAPONLAB_PROJECT`	包含 `weaponlab.json` 的项目文件夹。默认使用当前文件夹。
`WEAPONLAB_BLENDER`	Blender，用于 Motion Lab。若未指定，则从 PATH 或常见安装文件夹中查找。

要求

Python 3.10 或更高版本。
Motion Lab 和渲染需要 Blender 4.4 或更高版本。其他功能都不需要它。
手部骨骼需采用 Unreal 人形骨架的命名方式（hand_r、index_01_r、lowerarm_r），以供拳头测量和前臂扭转使用。

项目起源

Weapon Lab 是为 ToangTown 构建的工具中的通用部分。ToangTown 是一款使用 Unreal 5.8 开发、拥有 46 种武器的游戏。其首个探针来自 ToangTown。合约中的经验也源自该探针。 Pose Lab（poselab-mcp）负责处理角色身体相关问题：穿模、视角和握持求解器。Gate 可以将其用作提供方。