Weapon Lab

Weapon Lab

一人称視点の武器のバグを種類ごとに一度だけ修正し、ゲートを通してすべての武器に適用します。

ゲートを通して一人称視点の武器のバグを見つけて修正する MCP サーバーです。手が銃から離れている、マガジンが装填部で傾いている、刃の持ち方が間違っている、腕が画面を覆っている、といった問題に対応します。

各バグは、メトリクス、武器、アクション、合格ルールをまとめたケースになります。ゲーム独自のプローブで武器を測定します。ゲートは、対象のケースに合格し、ほかのケースを悪化させていない場合に限り、変更を合格と判定します。バグの種類ごとに一度修正し、その修正ですべての武器を確認します。

Weapon Lab がゲーム自体を実行することはありません。エンジン用の小さなプローブを作成し、プローブ契約に従って、ジョブファイルを入力し、行ファイルを出力するようにしてください。それ以外の処理はすべて、プローブが書き戻したデータを使って行います。

できること

グループ	ツール	用途
Gate	gate_run, gate_verdict, gate_propose, gate_approve, gate_set_baseline, gate_cases, ...	バグをケースとして管理し、測定してベースラインと比較し、変更を判定して、人による承認を記録します。
Probe	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 でクリップを再構築します。前腕の可動範囲内で手を前腕の周りに回したり、スライドするパーツを軸上に戻したりします。
Specs	spec_list, spec_read, spec_validate, spec_write	武器ごとに1つのファイルを用意します。マーク（グリップ、サポート）、アンカー（検索するパーツ）、情報、制限を記述します。
Contract	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 行で 2 つの仕込まれたバグとプローブを備えた簡単なゲームです。エンジンは不要です。

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

（pip のスクリプトフォルダーが PATH に含まれていない場合も、python -m weaponlab で同じように実行できます。）

ライフルの左手は、ハンドガードから 3.75 cm ずれています。ナイフの柄は、拳に対して 90 度横向きになっています。 tests/test_demo.py では、測定、修正方法の特定、調整による試行、判定まで、一連の流れを確認できます。

ゲームで使う

1. プロジェクト内で weaponlab init を実行します。weaponlab.json と空のデータファイルが作成されます。
2. コントラクトに沿ってプローブを作成します。examples/demo/probe/demo_probe.py から始めてください。 weaponlab.json でそのコマンドを設定します。
3. 武器を weaponlab/data/weapons.json に、アクションを actions.json に登録します。
4. 既知のバグごとにケースを追加します。すべてを一度測定し、ベースラインを設定します。
5. 次の流れで修正します。調整またはステージングで試し、スクリーンショットを確認し、提案して、承認し、インポートします。

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	Motion Lab 用の Blender です。PATH 上、または通常のインストール先フォルダーから検出されます。

要件

• Python 3.10 以降。
• Motion Lab とレンダリングには Blender 4.4 以降が必要です。それ以外には必要ありません。
• 握りの測定と前腕の回転には、Unreal のマネキンと同じ名前の手のボーン（hand_r、index_01_r、lowerarm_r）が必要です。

開発の経緯

Weapon Lab は、武器 46 種を収録した Unreal 5.8 のゲーム ToangTown 向けに開発されたツール群の汎用部分です。最初のプローブは ToangTown 用です。コントラクトで得られた知見は、そのプローブから得られたものです。 Pose Lab（poselab-mcp）は、クリッピング、視界、グリップソルバーといった身体側の問題に対応します。Gate では、これをプロバイダーとして使用できます。

ライセンス

MIT