MegaMek—TableTop BattleTech on your computer

Table of Contents

1. About
2. Status
3. Running MegaMek
   1. Installing Or Updating Your Java Runtime
      1. Adoptium (Windows)
      2. Adoptium (Mac)
      3. Linux
4. Connecting
5. Playing The Game
   1. Pre-game Lobby
   2. Initiative Report
   3. Movement Phase
   4. Movement Report
   5. Weapons Fire Phase
   6. Weapons Fire Report
   7. Physical Attacks Phase
   8. End of Turn Report
6. Custom Units
7. Advanced Map Settings
8. Differences Between The Board Game and MegaMek
9. Compiling
10. Support
11. Contact & Further Information
12. Licensing

About

MegaMek is a Java version of BattleTech that you can play with your friends over the internet. All rules from Total Warfare are implemented. Rules from Tactical Operations and Strategic Operations are constantly in the works, and many of those rules and weapons are already implemented.

Players can create their own units, maps, and scenarios for use with MegaMek. MegaMek supports all unit types, from infantry, BattleMek, and vehicles, to Aerospace fighters, DropShips, and warships. Ground battles as well as space battles can be played.

If you would like information about how to play the game, see the "PLAYING THE GAME" section, below. If you're having trouble getting MegaMek started, see the next section, "RUNNING MEGAMEK."

For complete game rules, consult the Classic BattleTech rule books published by Catalyst Game Labs. These books include Total Warfare, Tactical Operations: Advanced Rules, Tactical Operations: Advanced Units & Equipment, and Strategic Operations.

Status

Type	MM Status	MML Status	MHQ Status
Latest Release
Javadocs
License
Build (CI)
Issues

Note that not everything has been implemented across the suite at this time, which will lead to gaps.

RUNNING MEGAMEK

Java programs run in their own environment, called a Virtual Machine or VM for short. These Java VMs are available on most systems from a variety of sources.

Windows users: To start MegaMek, run the MegaMek.exe file. If this fails to start MegaMek, see the "INSTALLING OR UPDATING YOUR JAVA RUNTIME" section, below.

Other graphical OSes: Many other graphical OSes, such as macOS, will allow you to double-click the .jar file to run it. If this does not work, try running MegaMek from the command line.

Running MegaMek from the command line: To do this using Sun Java, or most other implementations, navigate to the directory containing the .jar file and run: java -jar MegaMek.jar.

If none of the above options work for you, see the "INSTALLING OR UPDATING YOUR JAVA RUNTIME" section, below.

INSTALLING OR UPDATING YOUR JAVA RUNTIME

Of the versions available, we now require Java 21 LTS as the bare minimal version. Newer versions should work but are not currently supported.

Adoptium (Windows)

For Windows, follow the instructions here to ensure Java is installed correctly for the most seamless experience.

Adoptium (Mac)

For Mac, download the installer from Adoptium directly for your version of macOS and underling platform (AARCH64 is for M-Series Mac's).

Linux

For Linux, your distribution should have a version of Java available via your package manager.

CONNECTING

MegaMek is a network game. One player hosts a game and the rest of the players connect. The connecting players can connect from anywhere with a TCP/IP connection to the host, including the same computer (see "hot seat," below.)

To host a game, press the "Host a New Game..." button in the main menu. Fill in your name and click "Okay." The password field allows you to specify a password for certain server commands (Type /help in the chat line to get a list of server commands.) If you don't specify a password, anybody is allowed to reset the server or kick players, so be careful.

Once the lobby screen comes up, other players can connect and the game can begin. The other players will need to know the IP address of the host computer. There are several ways to determine your IP address. If you are on Windows 9x/ME, you can use the Run command on the start menu and enter winipcfg. On Windows 2000/NT/XP/Vista/7/8/10, you will need to open a command prompt and type ipconfig. As a last resort, there are some web pages, such as WhatIsMyIP that will try to detect your IP address, but if your internet service uses a proxy or firewall, these pages cannot accurately detect it.

To connect to a game, press the Connect To A Server button on the main menu and fill in your player name and the host's IP address.

To play in a hot seat fashion, you can run the host and any number of other players on the same computer. First, launch and host a game. Then, launch another copy of the game for each connecting player, and in the "Server Address" field of the Connect To A Server dialog, type localhost. Each player will need to switch to his/her copy of the game to play their turn.

To start a dedicated server, use the -dedicated command line switch. A dedicated server just runs the server, in the console, without a "host" player in the game. People, including yourself, can join it like a game with a host. The dedicated server reads the password and port options from the clientsettings.xml file, or uses the default (no password and port 2346.) If you want the dedicated server to load a saved game, supply the filename at the end of -dedicated args, like this: -dedicated savedgame.sav or -dedicated -port 2346 savedgame.sav. To stop the server, you will need to tell the Java machine to halt execution, which is CTRL + C on most platforms.

PLAYING THE GAME

Pre-game Lobby

Here you can chat, specify what units you wish to use, select map settings, declare starting positions, and change your player's color. When everybody has at least one unit, you may all hit "ready" to start the game. Most changes to the game parameters will cancel your ready status, so you should wait for everybody to finish choosing their units and positions. Note: If you wish to use custom unit designs, please see the section below entitled "CUSTOM UNITS."

You can enter the map selector by clicking on the "Select Map" tab at the top of the lobby. You can change the dimensions of the map boards (in hexes) or the dimensions of the whole map (in boards). All maps are loaded off the server. Most of the ma