What Is MekHQ and How Does It Work With MegaMek?
MekHQ is the campaign and force-management companion to MegaMek: it tracks your mercenary unit's personnel, finances, contracts, and equipment between battles, then hands the actual tactical fight off to MegaMek and reads the result back into the campaign. You'd use it if you want a persistent, multi-mission BattleTech campaign rather than one-off games. Both are unofficial, open-source, GPL-licensed projects from the MegaMek family, which also includes MegaMekLab for unit design.
The division of labor
The two programs do different jobs, and understanding the split explains most of how MekHQ feels to use.
| Layer | Program | What it handles |
|---|---|---|
| Campaign | MekHQ | Roster, hiring, contracts, payroll, supplies, repairs, salvage, advancement, calendar |
| Tactical battle | MegaMek | Map, units, movement, combat resolution, victory conditions |
| Unit design | MegaMekLab | Building and editing 'Mechs, vehicles, and other units |
MekHQ is where you make decisions that span weeks or months of in-game time. MegaMek is where a single engagement is played out. The campaign state lives in MekHQ; the battle itself is a separate scenario that MegaMek runs.
The campaign loop
A typical cycle in MekHQ looks like this:
- Manage the unit. Hire and assign personnel, set roles, and keep an eye on salaries and upkeep.
- Take a contract. Accept a job with terms covering pay, duration, and salvage or support rights.
- Advance the calendar. Time passes; maintenance, training, and administrative events resolve.
- Deploy to a mission. A scenario is generated from the contract, and you launch it into MegaMek.
- Fight the battle in MegaMek. Play the tactical engagement to completion.
- Return the result. MekHQ records the outcome — casualties, damage, and salvage.
- Repair, resupply, and advance. Fix damaged units, replace losses, pay the bills, and move on.
The loop repeats until the contract ends or the unit collapses under its own costs. That economic pressure — payroll, parts, and transport against contract income — is the core tension MekHQ adds on top of MegaMek's tactics.
Launching a battle and bringing results back
The handoff is the part new players most often get wrong, so it's worth stating plainly: MekHQ generates the scenario and starts MegaMek for you, and when the battle finishes, the outcome is written back into the campaign. You don't manually re-enter results.
The practical implications:
- Play the battle through to a resolved end. An abandoned or crashed battle may not report cleanly, leaving the campaign out of sync with what actually happened.
- Don't edit the same campaign from two places at once. Keep one program in charge of the save at a time.
- Expect the campaign to change after a fight. Damage, injuries, and salvage are applied automatically, so review the roster before the next deployment.
Common setup pitfalls
Most early frustration with MekHQ comes from version and file mismatches rather than gameplay.
- Match versions across the family. MekHQ, MegaMek, and MegaMekLab are released together; mixing versions is a frequent source of load and compatibility errors.
- Treat saves as version-bound. A campaign saved under one release may not open cleanly under another, so finish or archive a campaign before upgrading.
- Keep backups of campaign files. Because a campaign accumulates weeks of state, a corrupted save is costly; periodic copies are cheap insurance.
- Check Java. These are Java applications, so an appropriate Java runtime needs to be present for them to start.
When MekHQ is the right choice
Choose MekHQ if you want continuity — a unit with a history, a budget, and consequences that carry from one battle to the next. If you only want to play individual tactical engagements, MegaMek alone is the simpler path, and MegaMekLab covers unit design on its own. The three tools are designed to be used together, but each stands on its own for its specific job.