weaponlab-mcp 0.1.0__tar.gz

weaponlab_mcp-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+weaponlab/work/
+examples/demo/weaponlab/work/

weaponlab_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0
+
+The general core of the tools built for ToangTown's weapons (2026-10-13 and 14), split out so any game can use them.
+
+* The probe contract (`weaponlab-probe/1`, docs/PROBE_CONTRACT.md): a job file in, a rows file out, screenshots and
+  parts dumps at moments. `weaponlab contract job|rows|parts` checks a probe's files. Run against ToangTown's probe
+  (149 jobs, 1,021 dumps), it found two real bugs there: a tagged entry's view rows under the plain weapon id, and a
+  gun built into an arms mesh dumped as arms.
+* The Gate: cases, metrics (the contract's standard ones built in), named budgets, runs, the baseline, check evals,
+  the verdict, proposals and approval. Rows that break the contract are refused.
+* Rig Lab without Blender: pieces and twins, the spec's facts, a magazine's line into its well, a sliding part's
+  line, a melee hilt against the fist's grip channel and the turn and move that lay it in.
+* Motion Lab in Blender: a forearm's roll (auto per clip, every frame checked against the forearm's range), a part's
+  track on its axis, dev renders.
+* One MCP server (`weaponlab-mcp`, 30 tools) and a command line (`weaponlab`).
+* A demo game with two planted bugs and a 150-line probe; tests walk the whole loop on it.

weaponlab_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Khoa Hoang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

weaponlab_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.5
+Name: weaponlab-mcp
+Version: 0.1.0
+Summary: An MCP server that finds and fixes first-person weapon bugs behind a gate: your game's probe measures, the Gate judges, Rig Lab and Motion Lab read and mend.
+Author: Khoa Hoang
+License-Expression: MIT
+License-File: LICENSE
+Keywords: animation,blender,first-person,game-development,mcp,testing,unreal
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: mcp<3,>=2.0
+Requires-Dist: numpy>=1.24
+Description-Content-Type: text/markdown
+
+# Weapon Lab
+
+<!-- mcp-name: io.github.hpdkhoa/weaponlab-mcp -->
+
+An MCP server that finds and fixes first-person weapon bugs behind a gate: hands off the gun, a magazine crooked in
+its well, a blade held wrong, arms covering the screen.
+
+Each bug becomes a **case**: a metric, a weapon, an action and a pass rule. Your game's own **probe** measures the
+weapons. The **Gate** passes a change only when its target cases pass and nothing else got worse. Fix each kind of
+bug once, then check every weapon with it.
+
+Weapon Lab never runs your game itself. You write a small probe for your engine that follows the
+[probe contract](docs/PROBE_CONTRACT.md): a job file in, a rows file out. Everything else works on what the probe
+writes back.
+
+## What it does
+
+| Group | Tools | What for |
+|---|---|---|
+| Gate | `gate_run`, `gate_verdict`, `gate_propose`, `gate_approve`, `gate_set_baseline`, `gate_cases`, ... | Keeps the bugs as cases, measures, compares against a baseline, judges a change, records a person's approval. |
+| Probe | `probe_run`, `probe_plan`, `probe_status` | Starts your game's probe. Tries a fix before it is written: tuned fields, staged assets, screenshots, parts dumps. |
+| Rig Lab | `rig_pieces`, `rig_facts`, `rig_align`, `rig_part_line`, `rig_fist` | Reads the posed weapon from a parts dump: its pieces, real-world facts (the magazine behind the barrel), a magazine's line into its well, a hilt in the fist. |
+| Motion Lab | `motion_roll`, `motion_roll_profile`, `motion_roll_set`, `motion_track`, `motion_render` | Rebuilds clips in Blender: turns a hand about its forearm inside the forearm's range, puts a sliding part back on its axis. |
+| Specs | `spec_list`, `spec_read`, `spec_validate`, `spec_write` | One file a weapon: marks (grip, support), anchors (pieces to find), facts, limits. |
+| Contract | `contract_check` | Checks a probe's job, rows or parts dump. |
+
+## Try it on the demo
+
+The demo is a toy game with two planted bugs and a probe in about 150 lines. It needs no engine.
+
+```bash
+pip install -e .
+cd examples/demo
+weaponlab gate run probe,rig
+```
+
+(`python -m weaponlab` works the same when pip's scripts folder is not on your PATH.)
+
+The rifle's left hand misses its handguard by 3.75 cm. The knife's hilt lies 90 degrees across the fist.
+`tests/test_demo.py` walks the whole loop: measure, find the fix, try it by tune, judge it.
+
+## Use it in your game
+
+1. `weaponlab init` in your project. It writes `weaponlab.json` and empty data files.
+2. Write your probe from [the contract](docs/PROBE_CONTRACT.md), starting from `examples/demo/probe/demo_probe.py`.
+   Set its command in `weaponlab.json`.
+3. List your weapons in `weaponlab/data/weapons.json` and their actions in `actions.json`.
+4. Add a case for each bug you know. Measure everything once and set the baseline.
+5. Fix through the loop: try by tune or staging, look at the screenshots, propose, approve, import.
+
+Check your probe on its own with `weaponlab contract job|rows|parts <file>`.
+
+## Add it to an MCP client
+
+```json
+{"mcpServers": {"weaponlab": {"command": "weaponlab-mcp", "env": {"WEAPONLAB_PROJECT": "C:/path/to/your/game"}}}}
+```
+
+| Setting | Meaning |
+|---|---|
+| `WEAPONLAB_PROJECT` | The project folder with `weaponlab.json`. The current folder by default. |
+| `WEAPONLAB_BLENDER` | Blender, for Motion Lab. Found on the PATH or in the usual install folders otherwise. |
+
+## Requirements
+
+- Python 3.10 or later.
+- Blender 4.4 or later for Motion Lab and renders. Nothing else needs it.
+- Hand bones named as Unreal's mannequin names them (`hand_r`, `index_01_r`, `lowerarm_r`) for the fist measure and
+  the forearm roll.
+
+## Where it came from
+
+Weapon Lab is the general part of the tools built for ToangTown, an Unreal 5.8 game with 46 weapons. Its first probe
+is ToangTown's. The [contract's lessons](docs/PROBE_CONTRACT.md#lessons-from-the-first-probe) come from that probe.
+Pose Lab ([poselab-mcp](https://github.com/hpdkhoa/poselab-mcp)) answers the body's side: clipping, the view, a grip
+solver. The Gate can use it as a provider.
+
+## License
+
+MIT

weaponlab_mcp-0.1.0/PUBLISHING.md

@@ -0,0 +1,37 @@
+# Publishing Weapon Lab
+
+The order matters. The MCP Registry accepts the listing only after the PyPI package is live. It also checks that the
+README on PyPI carries `mcp-name: io.github.hpdkhoa/weaponlab-mcp`. README.md holds that line as an HTML comment.
+
+## 1. GitHub
+
+Push `main` to https://github.com/hpdkhoa/weaponlab-mcp and tag the release (`git tag v0.1.0`, `git push --tags`).
+
+## 2. PyPI
+
+Use your PyPI API token from your password manager. Do not keep it in a file.
+
+    python -m pip install build twine
+    python -m build
+    python -m twine check dist/*
+    python -m twine upload dist/*
+
+twine asks for the token (user name `__token__`). Check it after: `pip install weaponlab-mcp` in a fresh
+environment, then `weaponlab-mcp` starts the server (it waits for a client on stdin; Ctrl+C stops it).
+
+## 3. The MCP Registry
+
+In this folder (server.json is here):
+
+    mcp-publisher login github
+    mcp-publisher publish
+
+`login github` proves you own the io.github.hpdkhoa namespace. Search for it afterwards:
+https://registry.modelcontextprotocol.io/v0/servers?search=weaponlab
+
+## Each release
+
+Run the tests first: `python -m pytest tests` (the ToangTown checks run only on the machine that has the game).
+
+Raise the version in three places: `pyproject.toml`, `src/weaponlab/__init__.py`, and `server.json` (both `version`
+fields). Add the release to CHANGELOG.md. Build and upload to PyPI first, then `mcp-publisher publish`.

weaponlab_mcp-0.1.0/README.md

@@ -0,0 +1,80 @@
+# Weapon Lab
+
+<!-- mcp-name: io.github.hpdkhoa/weaponlab-mcp -->
+
+An MCP server that finds and fixes first-person weapon bugs behind a gate: hands off the gun, a magazine crooked in
+its well, a blade held wrong, arms covering the screen.
+
+Each bug becomes a **case**: a metric, a weapon, an action and a pass rule. Your game's own **probe** measures the
+weapons. The **Gate** passes a change only when its target cases pass and nothing else got worse. Fix each kind of
+bug once, then check every weapon with it.
+
+Weapon Lab never runs your game itself. You write a small probe for your engine that follows the
+[probe contract](docs/PROBE_CONTRACT.md): a job file in, a rows file out. Everything else works on what the probe
+writes back.
+
+## What it does
+
+| Group | Tools | What for |
+|---|---|---|
+| Gate | `gate_run`, `gate_verdict`, `gate_propose`, `gate_approve`, `gate_set_baseline`, `gate_cases`, ... | Keeps the bugs as cases, measures, compares against a baseline, judges a change, records a person's approval. |
+| Probe | `probe_run`, `probe_plan`, `probe_status` | Starts your game's probe. Tries a fix before it is written: tuned fields, staged assets, screenshots, parts dumps. |
+| Rig Lab | `rig_pieces`, `rig_facts`, `rig_align`, `rig_part_line`, `rig_fist` | Reads the posed weapon from a parts dump: its pieces, real-world facts (the magazine behind the barrel), a magazine's line into its well, a hilt in the fist. |
+| Motion Lab | `motion_roll`, `motion_roll_profile`, `motion_roll_set`, `motion_track`, `motion_render` | Rebuilds clips in Blender: turns a hand about its forearm inside the forearm's range, puts a sliding part back on its axis. |
+| Specs | `spec_list`, `spec_read`, `spec_validate`, `spec_write` | One file a weapon: marks (grip, support), anchors (pieces to find), facts, limits. |
+| Contract | `contract_check` | Checks a probe's job, rows or parts dump. |
+
+## Try it on the demo
+
+The demo is a toy game with two planted bugs and a probe in about 150 lines. It needs no engine.
+
+```bash
+pip install -e .
+cd examples/demo
+weaponlab gate run probe,rig
+```
+
+(`python -m weaponlab` works the same when pip's scripts folder is not on your PATH.)
+
+The rifle's left hand misses its handguard by 3.75 cm. The knife's hilt lies 90 degrees across the fist.
+`tests/test_demo.py` walks the whole loop: measure, find the fix, try it by tune, judge it.
+
+## Use it in your game
+
+1. `weaponlab init` in your project. It writes `weaponlab.json` and empty data files.
+2. Write your probe from [the contract](docs/PROBE_CONTRACT.md), starting from `examples/demo/probe/demo_probe.py`.
+   Set its command in `weaponlab.json`.
+3. List your weapons in `weaponlab/data/weapons.json` and their actions in `actions.json`.
+4. Add a case for each bug you know. Measure everything once and set the baseline.
+5. Fix through the loop: try by tune or staging, look at the screenshots, propose, approve, import.
+
+Check your probe on its own with `weaponlab contract job|rows|parts <file>`.
+
+## Add it to an MCP client
+
+```json
+{"mcpServers": {"weaponlab": {"command": "weaponlab-mcp", "env": {"WEAPONLAB_PROJECT": "C:/path/to/your/game"}}}}
+```
+
+| Setting | Meaning |
+|---|---|
+| `WEAPONLAB_PROJECT` | The project folder with `weaponlab.json`. The current folder by default. |
+| `WEAPONLAB_BLENDER` | Blender, for Motion Lab. Found on the PATH or in the usual install folders otherwise. |
+
+## Requirements
+
+- Python 3.10 or later.
+- Blender 4.4 or later for Motion Lab and renders. Nothing else needs it.
+- Hand bones named as Unreal's mannequin names them (`hand_r`, `index_01_r`, `lowerarm_r`) for the fist measure and
+  the forearm roll.
+
+## Where it came from
+
+Weapon Lab is the general part of the tools built for ToangTown, an Unreal 5.8 game with 46 weapons. Its first probe
+is ToangTown's. The [contract's lessons](docs/PROBE_CONTRACT.md#lessons-from-the-first-probe) come from that probe.
+Pose Lab ([poselab-mcp](https://github.com/hpdkhoa/poselab-mcp)) answers the body's side: clipping, the view, a grip
+solver. The Gate can use it as a provider.
+
+## License
+
+MIT

weaponlab_mcp-0.1.0/docs/PROBE_CONTRACT.md

@@ -0,0 +1,175 @@
+# The probe contract (weaponlab-probe/1)
+
+Weapon Lab never runs your game itself. A **probe** does: a program you write for your game, in any language or
+engine. Weapon Lab writes a **job file** and starts your probe with its path. The probe plays each weapon's actions,
+measures them and writes a **rows file**. It may also write screenshots and **parts dumps**. Weapon Lab checks what
+comes back, and the Gate judges the rows.
+
+`weaponlab contract job|rows|parts <file>` checks a file against this contract, so you can test a probe on its own.
+`examples/demo/probe/demo_probe.py` is a complete probe in about 200 lines. It measures a toy game.
+
+## How Weapon Lab starts the probe
+
+The project's `weaponlab.json` names the command. `{job}` becomes the job file's path:
+
+```json
+{"probe": {"command": ["MyGame.exe", "-probe={job}", "-log={work}/probe/game-{stamp}.log"],
+           "timeout_s": 1800, "refuse": ["MyGame.exe"], "busy": ["UnrealEditor.exe"], "wait_s": 3600,
+           "job_extra": {"quit": true}, "low_priority": true}}
+```
+
+- `{job}` is the job file, `{work}` the project's work folder, `{stamp}` the run's time stamp.
+- The probe reads the job, runs, writes the rows file at the job's `out`, and exits.
+- Exit code 0 means it finished. Weapon Lab still checks the rows file. A missing or broken file is an error.
+- Weapon Lab waits up to `timeout_s`, or longer when the job's own length needs it, scaled by `1 / slomo`.
+- `refuse` lists processes Weapon Lab never runs beside, such as the player's own copy of the game. It stops at once.
+- `busy` lists other heavy jobs, such as an editor or Blender. Weapon Lab waits up to `wait_s` for them to end.
+- `job_extra` adds keys to every job for the probe's own use.
+- `low_priority` starts the probe below normal priority, so the machine stays usable.
+
+## The gun's space
+
+Every position in a job, a rows file or a parts dump is in the gun's space, in centimetres:
+
+- +Y runs along the barrel, toward the muzzle.
+- +Z is up.
+- +X is the gun's left.
+- The origin is the probe's choice, but it must stay the same for one weapon across runs. A spec's marks use it.
+
+## The job file
+
+```json
+{
+  "contract": "weaponlab-probe/1",
+  "out": "C:/proj/weaponlab/work/probe/rows-20261014-120000.json",
+  "weapons": [
+    {
+      "id": "Rifle_M4",
+      "tag": "fix1",
+      "actions": [
+        {"name": "idle", "seconds": 1.6, "at": [1.2]},
+        {"name": "reload", "run": "reload", "seconds": 3.0, "at": [0.6, 1.2]}
+      ],
+      "bones": {"bolt": "Bolt_j"},
+      "support_l": [0.0, 25.0, 1.0],
+      "tune": {"ArmsGunOffset": {"X": 0, "Y": 18.5, "Z": -1.4}}
+    }
+  ],
+  "overrides": {"/Game/Anims/A_Idle": "/Game/Staging/S1/A_Idle"},
+  "shots": "C:/proj/weaponlab/work/shots/fix1",
+  "parts": "C:/proj/weaponlab/work/parts/fix1",
+  "slomo": 0.2,
+  "view": true
+}
+```
+
+| Field | Required | Meaning |
+|---|---|---|
+| `contract` | no (default `weaponlab-probe/1`) | The contract version. A probe refuses a version it does not know. |
+| `out` | yes | Where the probe writes the rows file. |
+| `weapons[].id` | yes | The weapon, by the game's own id. |
+| `weapons[].tag` | no | A label for this entry. Its rows report the weapon as `<id>@<tag>`. One job can run the same weapon twice, for example before and after a tune. |
+| `weapons[].actions[].name` | yes | The action: `idle`, `fire`, `reload` or any name the probe knows. |
+| `weapons[].actions[].seconds` | no | How long to watch it. |
+| `weapons[].actions[].run` | no | The probe's own command for the action. Weapon Lab passes it through from `actions.json`. |
+| `weapons[].actions[].at` | no | Moments, in seconds from the action's start, for screenshots and parts dumps. |
+| `weapons[].actions[]` other keys | no | Passed through from `actions.json` for the probe's own use. |
+| `weapons[].bones` | no | A spec mark's name to a bone. The probe reports how far each travels (`events.<mark>_travel_cm`). |
+| `weapons[].support_l` | no | The spec's support mark. The probe reports the left palm's distance to it. |
+| `weapons[].tune` | no | Fields of the weapon's definition, set before the weapon is drawn and put back after the entry. This is how a fix is tried before it is written. |
+| `overrides` | no | Assets the probe loads in place of others: staged clips or models, tried without replacing anything. |
+| `shots` | no | A folder for screenshots. Empty or missing means none. |
+| `parts` | no | A folder for parts dumps. Empty or missing means none. |
+| `slomo` | no | A time scale in (0, 1]. Dumps are slow, so the game runs slower while they are taken. |
+| `view` | no | Measure the screen cover (`view.*` metrics). |
+
+A probe ignores keys it does not know. A probe that cannot do something it was asked (`tune`, `overrides`) says so
+in `notes` and does not fail.
+
+## The rows file
+
+```json
+{
+  "rows": [
+    {"weapon": "Rifle_M4@fix1", "action": "idle", "metric": "hands.l_gap_cm", "value": 0.22},
+    {"weapon": "Rifle_M4@fix1", "action": "idle", "metric": "view.hand_l_shown", "value": 0.27},
+    {"weapon": "Rifle_M4@fix1", "action": "reload", "metric": "hands.l_to_support_cm", "value": null, "note": "no support mark"}
+  ],
+  "notes": ["Rifle_M4@fix1: ArmsGunOffset tuned"]
+}
+```
+
+- One row per weapon, action and metric.
+- `value` is a finite number, or `null` when the probe could not measure it. The Gate skips a null.
+- `note` is optional text for a person.
+- A metric name has a group and a name: `hands.l_gap_cm`. The standard metrics are below. A project adds its own in
+  its `metrics.json`.
+- `notes` holds text about the run as a whole.
+
+## Screenshots and parts dumps
+
+- A screenshot at a moment: `<shots>/<weapon>_<action>_<t>.png`, with `t` to two decimals (`Rifle_M4_idle_1.20.png`).
+- A screenshot of the idle view without a moment: `<shots>/<weapon>_idle.png`.
+- A parts dump at a moment: `<parts>/<weapon>_<action>_<t>.obj`.
+
+A parts dump is a Wavefront OBJ of every drawn part as posed at that moment, in the gun's space:
+
+```
+# eye 22.0 -31.1 36.2
+# hold rig AKS offset 0.0 18.5 -1.4
+g arms|Arms|/Game/Arms/SK_Arms|hand_l
+v 1.0 2.0 3.0
+...
+f 1 2 3
+g gun|Gun|/Game/Guns/M4/SK_M4|root
+g part|Mag|/Game/Guns/M4/SM_Mag|Mag1
+```
+
+- A group name has four fields: `role|component|asset|bone`.
+- `role` is `arms`, `gun` (the weapon's own model), `part` (a separate piece of it, such as a magazine) or `item`
+  (something carried in a hand).
+- `bone` is the bone the triangles follow. Use `-` for a static mesh.
+- `# eye x y z` is the camera in the gun's space.
+- Any other `# key ...` line is free for the probe's own facts. Weapon Lab keeps them as a header.
+- Every group needs triangles. A dump needs a `gun` group or, when the weapon is drawn only as pieces (a melee
+  model swapped into another weapon's hands), a `part` group.
+
+Hand bones follow Unreal's mannequin names (`hand_l`, `index_01_r`, `pinky_01_r`, `middle_01_r`, `thumb_03_r`,
+`lowerarm_r`). The fist measure and the forearm roll read those names.
+
+## The standard metrics
+
+| Metric | Unit | Better | Meaning |
+|---|---|---|---|
+| `hands.arms_shown` | 0/1 | higher | The weapon is held by visible arms. |
+| `hands.l_gap_cm` | cm | lower | The left palm's distance to the gun's surface, the worst over the action. |
+| `hands.r_gap_cm` | cm | lower | The right palm's distance to the gun's surface. |
+| `hands.r_handle_gap_cm` | cm | lower | The right palm's distance to the grip. |
+| `hands.l_drift_cm` | cm | lower | How far the left hand moves in the gun's space during the action. |
+| `hands.l_to_support_cm` | cm | lower | The left palm's distance to the spec's support mark. |
+| `hands.r_hold_drift_cm` | cm | lower | How far a held melee weapon moves in the right hand. |
+| `hands.l_ride_<mark>_cm` | cm | lower | The left hand's distance to a moving part it rides, such as a pump. |
+| `view.cover_total` | share | lower | The share of the screen the arms and weapon cover. |
+| `view.cover_lower_left` | share | lower | The share of the lower left third they cover. |
+| `view.cover_bottom_middle` | share | lower | The share of the bottom middle third they cover. |
+| `view.hand_l_shown` | share | higher | The share of the left hand the player sees. |
+| `view.hand_r_shown` | share | higher | The share of the right hand the player sees. |
+| `view.item_shown` | share | higher | The share of a carried item the player sees. |
+| `parts.copies_magazine` | count | none | Magazines drawn at once. |
+| `events.played` | 0/1 | higher | The action's clip played. |
+| `events.item_in_hand` | 0/1 | none | An item was in the hand during the action. |
+| `events.<mark>_travel_cm` | cm | higher | How far a spec's moving bone travels. |
+| `swing.edge_lead` | cos | higher | How well a blade's edge leads its cut: 1 is the edge, 0 the flat. |
+
+"Better: none" means the Gate never calls a change in it a regression. Only a case's rule judges it.
+
+## Lessons from the first probe
+
+ToangTown's probe (Unreal 5.8, C++) found these. A new probe should handle them too.
+
+- **The first action of a run can read wrong.** One read the hands 44 cm off the gun. Weapon Lab adds a warm-up entry
+  and drops its rows.
+- **Actions depend on the state the last one left.** Start fire and chamber actions from a full magazine.
+- **Melee swing rows vary between runs.** Run an unchanged weapon twice before you trust a small change.
+- **A dump stalls the game for a moment.** Take dumps in slow motion.
+- **Set tuned fields before the weapon is drawn.** Some fields are read only when it is equipped.

weaponlab_mcp-0.1.0/examples/demo/probe/demo_probe.py

@@ -0,0 +1,108 @@
+"""A complete probe for a toy game, written to the probe contract (docs/PROBE_CONTRACT.md). It is the template for
+your own: read the job, play each action, measure, write the rows and the dumps.
+
+The toy game has two weapons, each with a bug that shows in the numbers:
+- Demo_Rifle: its model sits 4 cm too high on the arms (game.json "Demo_Rifle.offset"), so the left palm misses the
+  handguard by 4 cm. Tuning "offset" to [0, 0, 0] fixes it.
+- Demo_Knife: its hilt runs forward out of the fist (+Y) instead of along the fist's channel (+X). Rig Lab's fist
+  measure finds the turn ("rot") and the move ("offset") that lay it in; tune them to try the fix.
+
+    python demo_probe.py <job.json>"""
+import json
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+GAME = json.loads((HERE / "game.json").read_text(encoding="utf-8"))
+
+
+def box(c, size):
+    """A box's 12 triangles around centre c (cm)."""
+    (x, y, z), (a, b, h) = c, (s / 2.0 for s in size)
+    v = [(x + i * a, y + j * b, z + k * h) for i in (-1, 1) for j in (-1, 1) for k in (-1, 1)]
+    q = [(0, 1, 3, 2), (4, 6, 7, 5), (0, 4, 5, 1), (2, 3, 7, 6), (0, 2, 6, 4), (1, 5, 7, 3)]
+    return [(v[a], v[b], v[c]) for a, b, c, d in q] + [(v[a], v[c], v[d]) for a, b, c, d in q]
+
+
+def turn(m, p):
+    return tuple(sum(m[i][k] * p[k] for k in range(3)) for i in range(3))
+
+
+def model(wid, d):
+    """The weapon's pieces in gun space: [(role, component, bone, triangles)], after its definition's offset and turn."""
+    off, rot = d.get("offset", [0, 0, 0]), d.get("rot", [[1, 0, 0], [0, 1, 0], [0, 0, 1]])
+    move = lambda tris: [tuple(tuple(a + o for a, o in zip(turn(rot, p), off)) for p in t) for t in tris]
+    if wid == "Demo_Rifle":
+        return [("gun", "Rifle", "-", move(box((0, 10, 0), (4, 40, 6)))),        # receiver and handguard
+                ("gun", "Rifle", "-", move(box((0, 40, 1), (1.5, 20, 1.5)))),    # barrel
+                ("part", "Mag", "Mag", move(box((0, 4, -9), (2.4, 6, 12))))]     # magazine under the well
+    # the knife: hilt from the pommel at y -6 to y 5, blade to y 25, along +Y before its turn
+    return [("gun", "Knife", "-", move(box((0, -0.5, 0), (2.2, 11, 2.6)) + box((0, 15, 0), (0.5, 20, 3))))]
+
+
+def arms():
+    """The hands in gun space: the left palm under the handguard, the right fist's channel along +X at the origin."""
+    out = [("hand_l", box((0, 25, -4), (7, 9, 2.5)))]
+    out += [("hand_r", box((0, 0, -2.5), (8, 9, 2))), ("middle_01_r", box((0, 0, 3), (2, 2, 2))),
+            ("middle_02_r", box((0, 0, 4.5), (2, 2, 2))), ("middle_03_r", box((0, 0, 2), (2, 2, 2))),
+            ("index_01_r", box((3.5, 0, 0), (2, 2, 2))), ("pinky_01_r", box((-3.5, 0, 0), (2, 2, 2))),
+            ("thumb_03_r", box((3, -2.5, 2), (1.5, 1.5, 1.5)))]
+    return out
+
+
+def dump(path, wid, d):
+    lines = ["# demo probe parts: gun space, cm", "# eye 0.0 -20.0 12.0"]
+    n = 1
+    groups = [("arms", "Arms", "/Demo/Arms", b, t) for b, t in arms()] + [(r, c, "/Demo/" + wid, b, t) for r, c, b, t in model(wid, d)]
+    for role, comp, asset, bone, tris in groups:
+        lines.append("g %s|%s|%s|%s" % (role, comp, asset, bone))
+        for t in tris:
+            lines += ["v %.3f %.3f %.3f" % p for p in t]
+        for _ in tris:
+            lines.append("f %d %d %d" % (n, n + 1, n + 2))
+            n += 3
+    Path(path).write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def main(job_path):
+    job = json.loads(Path(job_path).read_text(encoding="utf-8"))
+    if job.get("contract", "weaponlab-probe/1") != "weaponlab-probe/1":
+        raise SystemExit("unknown contract %s" % job.get("contract"))
+    rows, notes = [], []
+    if job.get("overrides"):
+        notes.append("the demo game has no assets: overrides ignored")
+    if job.get("shots"):
+        notes.append("the demo game draws nothing: no screenshots")
+    for w in job["weapons"]:
+        wid = w["id"] + ("@" + w["tag"] if w.get("tag") else "")
+        d = dict(GAME.get(w["id"], {}))
+        for k, v in (w.get("tune") or {}).items():
+            if k in d:
+                d[k] = v
+                notes.append("%s: %s tuned" % (wid, k))
+            else:
+                notes.append("%s: no field %s" % (wid, k))
+        pieces = model(w["id"], d)
+        tris = [t for _, _, _, ts in pieces for t in ts]
+        hands = dict(arms())
+        for a in w["actions"]:
+            row = lambda m, v, note=None: rows.append(dict({"weapon": wid, "action": a["name"], "metric": m, "value": v}, **({"note": note} if note else {})))
+            row("hands.arms_shown", 1)
+            row("events.played", 1)
+            if w["id"] == "Demo_Rifle":
+                # the palm's top against the handguard's underside, where the palm is (in or out of it, both wrong)
+                palm_top = max(p[2] for t in hands["hand_l"] for p in t)
+                under = min(p[2] for t in tris for p in t if 20.0 <= p[1] <= 30.0)
+                row("hands.l_gap_cm", round(abs(under - palm_top), 3))
+                low = -min(p[2] for t in tris for p in t)
+                if job.get("view", True) and a["name"] == "idle":
+                    row("view.cover_lower_left", round(min(1.0, 0.05 + 0.01 * low), 3))
+                    row("view.hand_l_shown", round(max(0.0, 0.3 - 0.02 * max(0.0, low - 15)), 3))
+            for t in a.get("at", []):
+                if job.get("parts"):
+                    dump(Path(job["parts"]) / ("%s_%s_%.2f.obj" % (wid, a["name"], t)), w["id"], d)
+    Path(job["out"]).write_text(json.dumps({"rows": rows, "notes": notes}, indent=1), encoding="utf-8")
+
+
+if __name__ == "__main__":
+    main(sys.argv[1])

weaponlab_mcp-0.1.0/examples/demo/probe/game.json

@@ -0,0 +1,33 @@
+{
+ "Demo_Rifle": {
+  "offset": [
+   0,
+   0,
+   4
+  ]
+ },
+ "Demo_Knife": {
+  "rot": [
+   [
+    1,
+    0,
+    0
+   ],
+   [
+    0,
+    1,
+    0
+   ],
+   [
+    0,
+    0,
+    1
+   ]
+  ],
+  "offset": [
+   0,
+   0,
+   0
+  ]
+ }
+}

weaponlab_mcp-0.1.0/examples/demo/weaponlab/data/actions.json

@@ -0,0 +1,20 @@
+{
+ "*": {
+  "idle": {
+   "seconds": 1.6
+  },
+  "fire": {
+   "run": "fire",
+   "seconds": 1.5
+  }
+ },
+ "Melee": {
+  "idle": {
+   "seconds": 1.6
+  },
+  "swing": {
+   "run": "fire",
+   "seconds": 3.0
+  }
+ }
+}

weaponlab_mcp-0.1.0/examples/demo/weaponlab/data/budgets.json

@@ -0,0 +1,3 @@
+{
+ "view_lower_left": 0.2
+}

weaponlab_mcp-0.1.0/examples/demo/weaponlab/data/cases.json

@@ -0,0 +1,54 @@
+[
+ {
+  "id": "Demo_Rifle-support",
+  "weapon": "Demo_Rifle",
+  "action": "idle",
+  "metric": "hands.l_gap_cm",
+  "rule": {
+   "op": "<=",
+   "value": 1.0
+  },
+  "about": "the left palm on the handguard",
+  "source": "demo",
+  "status": "open"
+ },
+ {
+  "id": "Demo_Rifle-view",
+  "weapon": "Demo_Rifle",
+  "action": "idle",
+  "metric": "view.cover_lower_left",
+  "rule": {
+   "op": "<=",
+   "value": "view_lower_left"
+  },
+  "about": "the arms leave the lower left clear",
+  "source": "demo",
+  "status": "open"
+ },
+ {
+  "id": "Demo_Rifle-facts",
+  "weapon": "Demo_Rifle",
+  "action": "idle",
+  "metric": "facts.false",
+  "rule": {
+   "op": "==",
+   "value": 0
+  },
+  "about": "the magazine under the receiver, behind the barrel",
+  "source": "demo",
+  "status": "open"
+ },
+ {
+  "id": "Demo_Knife-fist",
+  "weapon": "Demo_Knife",
+  "action": "idle",
+  "metric": "fist.angle_deg",
+  "rule": {
+   "op": "<=",
+   "value": 10
+  },
+  "about": "the hilt along the fist's channel",
+  "source": "demo",
+  "status": "open"
+ }
+]