id: unit-library title: Every unit MegaMek knows is queryable, from any MegaMek status: open repos: [helm] dependsOn: [] exitCriterion: > helm builds its outputs from an unmodified MegaMek install, of a version given to it rather than baked in, committing none of MegaMek's data — and says how far the result agrees with MegaMek. #

unit-library #

helm reads MegaMek's unit library and writes an indexed SQLite database of it: 10,988 units with tonnage, tech base, era, movement, armour, loadout, quirks and critical slots. That much works.

What it does not yet do is stand on its own. Three things are still borrowed.

Battle value, cost and the Alpha Strike conversion are computed, not declared. They appear in no .mtf or .blk file — MegaMek derives them when it loads a design. helm gets them today from bridge/, two Java programs that read MekSummaryCache. That is honest and it works, but it means a build needs a JDK container and it means those columns are MegaMek's answer rather than one we can check.

The equipment catalogue comes from the same place. 4,348 entries with heat, damage, ranges and tonnage. This is the hidden dependency: computing battle value ourselves needs the catalogue first, so the catalogue is the real prerequisite for unit-rules, not the battle value formula.

Nothing says how far we agree with MegaMek. The database has one figure per unit and no record of where it came from or whether it is right.

What this epic is for #

The unit data has three consumers coming — unit-search, unit-rules and forces — and each of them wants the library to be a value they are handed, not a thing they go and find. That shape has to exist before they are built on it.

There are two outputs, not one. The database is the server's and the agent's; a reduced index is the browser's, for the force-building screen. Both are generated from the same read of the same install, so neither can be a version behind the other. See unit-search for what the index has to carry.

A unit's identity across all of this is chassis and model, as two fields, because that is what a .mul records and so what forces's blue.lance.force and any export must carry. The display name is chassis (clanname) model and is not a key; the MUL id is not one either, since 153 of 4,279 Meks have none.

• Take the MegaMek version as an input, not a constant. helm should read whatever install it is pointed at and stamp every artefact with the version it came from. Deciding which version the runtime uses is a separate question and a real one: arena pins 0.51.0, so a battle value shown to a player from a newer MegaMek disagrees with the number the game gives them.

• Commit none of MegaMek's data. The catalogue and the units are read from the install at build time. It stays CC BY-NC-SA content living in MegaMek's tree, not ours, which is the same reason the built .sqlite is gitignored.

• Record provenance. Which MegaMek, which producer, which rules version. Without it a conformance failure is indistinguishable from a database built against a different MegaMek, which is exactly the ambiguity you hit while chasing a deviation.

• Run the boundary check automatically. The crates are split and scripts/check-boundaries.sh encodes both rules, but helm has no commit hooks and no CI, so nothing runs it. A check somebody has to remember is the comment it was meant to replace.

• Build the conformance harness. Run both producers over the same library and diff. It reports zero agreement until unit-rules starts, and that is the point — it is the scoreboard that work is scored against, and it doubles as the drift detector when MegaMek releases.

• Register deviations rather than remembering them. crates/mms already does this for scenario files: Quirk::UnreadFactionKey and its siblings record where MegaMek reads less than its own format says, as data, in the parser. The same shape here — each entry naming the units affected, both answers, the argument from the rules text, and an upstream link. The test asserts the set exactly, so a new unexpected difference fails, and one that quietly disappears because they fixed it fails too.

The first deviation is already known #

ASTurretSummary.getSpecialsDisplayString() throws on certain turreted units. It cost the Alpha Strike special abilities of 967 units, 887 of them Tanks, and it took down the first dump entirely before the walk over MekSummary was made defensive. It is the template for what the registry holds.

Done #

• The computed values are a type, not a source. ComputedStats lives in helm-core — battle value, cost and the Alpha Strike figures as a plain value that helm-bridge fills today and helm-bv fills later. helm-db consumes it and never learns which produced it, which is what keeps it free of a battle value dependency and what makes the conformance harness a diff between two of these rather than bespoke code.

• The crates are split. helm-core carries the types and the catalogue and does no I/O; helm-facet and helm-force sit beside it, all three clear of rusqlite, zip and serde_json so they can reach wasm. scripts/check-boundaries.sh states both rules and checks them — wiring it to something that runs is the open item above.

• The repo exists and reads both formats. helm-unitfile parses .mtf and .blk directly — MegaMek's two unit formats, neither of them XML despite one looking like it. All 10,988 files in the 0.51.0 library parse with no failures. The awkward parts are covered by tests rather than discovered later: the Weapons:N count block, crit sections, source:TR:3039 keeping its own colon, and blank lines inside a .blk block body.

• A database with the computed columns in it. helm-db writes units, loadout, criticals, armour by location, quirks and the equipment catalogue, indexed, with full-text search over names. Every one of the 10,988 units carries battle value, cost and Alpha Strike figures.

• Two naming traps found and handled. A Clan dual-named design is chassis (clanname) model — Black Hawk (Nova) Prime — and 434 units have one; treating the chassis as the whole name silently lost every one of them. And .blk spells unit types unspaced (GunEmplacement) where MekSummary spaces them (Gun Emplacement), so a filter written against MekSummary's spelling excluded nothing at all.