readme.txt

INTRODUCTION
============
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, battlemechs, 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, and Strategic Operations.



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.  Most modern systems have one installed by default.

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 and OSX, 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.

If you have a VM, but it does not support .jar files, then use your favorite
extraction program to decompress "MegaMek.jar", "collections.jar",
"TinyXML.jar", and "Ostermiller.jar" into a new "classes" folder (create
the "classes" folder in your main "megamek" folder).  Once these steps
have been done (you only need to do the above steps once), you will
need to set the classpath to the classes folder and the current folder
and run "MegaMek.class".  For example, using Sun Java, run:

`java -cp .;classes megamek/MegaMek`

Note that in some cases, the semicolon may need to be escaped:
`java -cp .\;classes megamek/MegaMek`


INSTALLING OR UPDATING YOUR JAVA RUNTIME
========================================
If your system did not come with a Java VM, or you need to update your Java
VM, here are some links.

**Oracle Java (Linux, Solaris, Windows):**
http://www.oracle.com/technetwork/java/javase/downloads/index.html

**Mac OSX:**
See this support article on the apple support website for 
instructions:
https://support.apple.com/en-us/HT204036

**OpenJDK (Linux):**
Open source version of Java. Used by most major Linux distributions.
http://openjdk.java.net/install/

GCJ/Gnu classpath (Linux):
Of interest to experienced developers, there may be some
compatibility problems.
http://gcc.gnu.org/java/

Microsoft VM (Windows):
Microsoft no longer makes their VM available for separate download.
This version of MegaMek uses features not supported by the Microsoft JVM.

**IBM VM:**
MegaMek seems to react badly to this VM - it is not recommended.

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 hotseat, 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 
www.whatismyip.com 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 button on the main menu and fill in your
player name and the host's IP address.

To play in a hotseat 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 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 after the
-dedicated switch, like this: "-dedicated 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 map boards that MegaMek comes with are 16x17.

Below the map size inputs is a not-to-scale representation of how the boards
are laid out relative to each other.  The middle column lists the current maps
and the rightmost column lists the available maps.  To change a current map,
select it in the middle column, select the map you want in the right column,
and press the "<<" button between the two columns.  You may also select a map
by clicking on its number in the map layout grid.  When you select a map,
(other than [SURPRISE] or [RANDOM]) you have the choice or rotating it 180
degrees (North becomes South, East becomes West, and vice versa) by clicking
on the "Rotate Board" checkbox; the fact that the map is rotated will be shown
in the middle column.

**[SURPRISE]** means that the Server will pick a random map and not tell you what
it has picked until the game starts.  

**[RANDOM]** means that the Server will pick
a map as soon as you hit "Okay".

**[GENERATED]** means that the server will create random terrain for you to play on.
You need to use the "generated map settings" button to select what kind of terrain
you want.

There is a set of settings with drop down list of choices.  For most settings, you
can pick "none", "low", "medium" or "high". Except for cities, where you pick a 
type of city instead.

**Theme** - leave blank for the default theme, or enter a theme supported by your tileset.
        grass, jungle, lunar, mars, snow, and volcano are supported by the standard tileset
        
**Elevation** - how hilly you want the map

**Cliffs** - chance of 2+ level elevation changes, if you have enough elevation already

**Woods** - higher settings have more and larger tree patchs and more heavy woods

**Roughs** - higher settings have more and larger rough patches

**Lakes** - works the same as woods, but deep water instead of heavy woods
Swamps/Pavement/Ice/Rubble/Fortified all work like roughs. 
Fortified hexes are described in the MaxTech rulebook.

**River** - chance to have a river running across the map

**Road** - chance to have a single road running across the map

**Craters** - chance for craters, also the size and number.  Good for a "moonscape" map

**City:**
**HUB** - roads wander out from the centre with plenty of twists and turns. A common
        pattern for older european cities.
        
**GRID** - vertical and horizontal roads divide the city into rectangular blocks. A pattern
        common in newer cities, especially in north america and asia.
        
**METRO** - a grid with roads forming a diagonal X from the centre as well. 

Water and swamp will affect the city plan, as the builders will have to make bridges to
        cross it or just give up and stop the road at the edge.        
Mountain tops (4+ height) are expensive to build on, so they will only build in the valleys. 
Other terrain will just be bulldozed in the name of progress, though you may find a few
        hexes left between buildings.  

There is also an "advanced" button, which lets you fine-tune the map to your liking.
See the "advanced map settings" section near the end of this file

###Initiative Report:

Each player's initiative rolls and the corresponding turn order will be shown
here.


###Movement Phase:

The buttons at the bottom of the screen let you change between different
modes of movement, switch to another unit, or commit to your current path.
You do not have to move the first selected unit first.

Left-click on the map to specify a hex to move to.  A path should appear on
the board, showing your unit's path to the target hex.  The numbers in the
center represent how many movement points you will have to use to reach each
hex.  Cyan indicates walking, yellow running, and red jump movement.  Dark grey
sections of the path indicate where you have exceeded your movement capacity,
or other illegal moves.  You can drag the mouse to see movement options for 
several different hexes.  Please note that you can change the colors used to
display the movement points by editing clientsettings.xml; you may specify a
color in RGB notation (e.g. 255 255 255 for white) or with any of the following
text values: black, blue, cyan, darkgray, gray, green, lightgray, magenta, 
orange, pink, red, white, or yellow.

Units can also be moved by using "waypoints."  By clicking each hex between 
the unit's current location and destination, you can delineate the exact path 
to be taken.

Holding the Shift key while clicking on the map allows you to change the 
unit's facing without moving.  Since you automatically change facing while 
moving, this is best done at the end of any movement.

To move backwards, click the "Back Up" button before clicking a hex in the arc
behind the unit.  To jump, click the "Jump" button before the destination hex.
Facing changes during jumps are free.

Prone units can change facing without getting up at the normal cost.  To get up, 
click the "Get Up" button, then the desired destination hex and/or facing.  
Facing changes performed immediately after getting up are free.  To get up and 
back up, click "Get Up," then "Back Up," then the destination hex and/or 
facing.  You cannot get up and jump in the same turn.

Charging and death from above attacks are also declared during the movement 
phase.  Click the "Charge" or "D.F.A." button and then click on the mech you
wish to target.  If the attack is valid, it will be sent to the server 
immediately (but resolve during the physical attack phase.)  If the program is
not using the path you want for your attack, you may plot a path near the 
target using the appropriate type of movement and then use the charge or dfa
button to complete the attack.

If a vehicle or Mek that has sufficient empty space starts a turn in the same
hex as a friendly infantry unit, it can Load the unit as its first move of the
turn.  A vehicle or Mek that is already carrying an infantry unit can unload
the unit as its last movement of the turn.

If an Anti-Mek infantry platoon or Battle Armor squad has succeeded in mounting
a Mek with a Swarm attack, the Mek can attempt to dislodge the squad during the
movement phase in one of three ways: 1) jumping (requires a Pilot Skill Roll,
with a +4 modifier), 2) walking into (and perhaps through) a Level 2 or deeper
water hex, or 3) ending its turn in a hex that is on fire (this will not work
against Battle Armor squads).  Swarming infantry automatically die if they are
dislodged into a Level 1 or deeper water hex.  Infantry dislodged in the
Movement Phase can not move or fire for the rest of the turn.  Swarming units
can not move off of their target Mek until they use the Stop Swarm action in
the Weapons Fire Phase.

VTOLs and VTOL BA use the "go up" and "go down" buttons to change 
elevation (flight level).

Movement around structures (buildings/bridges) is a little more complicated, because
of the different floors a unit can occupy.  The "climb mode" button sets your current
preference.  "Go thru" means you prefer to go under bridges or through the walls of
buildings, if there is a choice.  "Climb up" means you prefer to climb on top of 
structures when possible.  You can change mode multiple times during your movement,
for example a stormcrow prime could use "climb up" to go over a heavy building to save
MP, then change to "go thru" to pass a light building that won't support its weight.

Infantry can move up and down inside buildings using the stairs.  This is accomplished
by using the "go up" and "go down" buttons.
Also, infantry that jump into a building can use the "go up" and "go down" buttons to
choose which floor to jump through the window of.  Click the building hex you want to jump
into first, and the game will pick the highest floor you can reach (or the roof).  Then use
the "go down" button to select a lower floor if you want to.

The Esc key clears all current movement.


###Movement Report:

If any units needed piloting skill rolls during their movement, a report
showing the results of these rolls will be shown.


###Weapons Fire Phase:

If you need to check the range and line of sight (LoS) between two hexes, 
there are two tools available for you to use; the LoS tool and the ruler 
tool.  To use the LoS tool, hold CTRL and click on the two hexes you want to 
check. The ruler tool works like the LoS tool, but uses the ALT key instead 
of the CTRL key.  The ruler tool can also be used by middle-clicking the 
two hexes with a three-button mouse.  Both tools will pop up a window that
tells you what terrain is intervening and whether one or both hexes has
partial cover.  The ruler tool also draws the line of sight on the board 
so that you can see which hexes LoS passes through. 

You can switch between 'Mech line of sight and non-'Mech line of sight in the
"LoS Setting" panel, located under the "View" menu at the top of the screen.
'Mech line of sight and non-'Mech line of sight differ in that 'Mechs are
assumed to be "looking" from one elevation level above that of the hex
they are in, whereas infantry and vehicles only take up the elevation level
of their hex.

The buttons at the bottom of the screen allow you to fire your weapons,
switch to another unit, or commit to your currently declared fire.  Again, 
you do not need to declare fire for your first selected unit first.

To target another unit, click on it on the board.  Targeting information
for your current weapon should appear in the mech display window.  To fire
your current weapon at the target, press the "Fire" button at the bottom of 
the screen.  To switch to another weapon, click on its name at the top of the
mech display window.  Spread your fire among multiple targets by repeating 
these steps using unassigned weapons.  When all desired weapons have been 
assigned to a target, press the "Done" button at the bottom of the screen.

Note that fire is resolved in the order that it is declared, so if you feel 
that it is a good idea to fire weapons in a different order than they are 
listed, go ahead.

Secondary facing changes (torso twists) are accomplished by holding Shift and 
clicking on the board.  Your unit will attempt to change its secondary facing 
in the direction specified.  If you assign a weapon to a target and then
attempt a facing change, the weapons fire will be canceled.

You can not switch to another unit after declaring some weapons fire.  To 
switch to another unit, first cancel all current fire by hitting the Esc key.  
When you hit the fire button for your last available weapon, all declared 
fire will be committed.

An Anti-Mek trained infantry platoon or Battle Armor squad that is in the same
hex as a Mek can conduct a Leg Attack or a Swarm Mek attack.  The base to-hit
number varies with the number of men in the unit.  A Swarm Mek attack against
a Mek that is prone and/or immobile gains a -4 modifier to its to-hit roll.  A
successful Leg Attack may cause critical damage to one of the Meks legs; if no
critical is rolled, the leg will take 4 points of damage (which may damage the
leg's internal structure, and cause another critical roll).  A successful
Swarm Mek attack does no damage in the turn it hits, but it means that the unit
has attached itself to the Mek, and can begin to cause significant damage on
subsequent turns.  Starting the turn after the unit starts a Swarming a Mek,
all attacks by that unit automatically hit, use a location chart that is more
dangerous than normally, and automatically roll for a Thru-Armor Critical.  A
unit that is Swarming a Mek can also choose to Stop Swarming in any weapons
phase.  The Leg Attack, Swarm Mek, and Stop Swarm actions are all "solo"
actions: the unit can take no other action in the Weapons Fire Phase.  Attempts
to do so will cancel the "solo" action.  Swarming infantry can not be targeted
by any attacks other than a "Brush Off" attack (see Physical Attacks Phase).


###Weapons Fire Report:

If there were any weapon attacks, the server will resolve them all at the end
of the phase in the order they were declared.  The results will be shown in a
report.


###Physical Attacks Phase:

To declare a physical attack, select your target on the board and click the
button corresponding to the attack you want to make.  If a physical attack 
type is unavailable (or isn't programmed yet) the button will be greyed out.

Units ineligible to make physical attacks due to being out of range, having
made weapons attacks, or for any other reason, will be skipped.  If all units 
are ineligible, the entire phase will be skipped.

Prone Meks that are in the same hex as a vehicle can punch the vehicle, if
they have both arms.  Prone Meks that are in a Clear or Pavement hex as an
infantry platoon or Battle Armor squad can "thrash" at the unit if they have
at least one arm or leg.  Be warned, that "thrashing" causes a Pilot Skill Roll
that, if failed, causes the Mek to suffer damage as if it has fallen 1 level.

Meks that are not prone that have been Swarmed by an infantry platoon or Battle
Armor squad can attempt to "Brush Off" the squad with either or both arms.  Any
"Brush Off" attack that fails to hit the infantry will inflict punch damage on
the Mek.  Any successful "Brush Off" attack ends a Swarm Mek attack.


###End of Turn Report:

If there were any physical attacks, the results will be shown.  
The results of the Heat and End phases will be shown.  

After this phase, it's time for initiative again!  Hurrah!


CUSTOM UNITS
============
All units (mechs, vehicles, infantry, etc.) are located in the
data/mechfiles directory.  They may be individual files or zipped up
into archives (".zip"), and you may also create subdirectories if you
like.  There is also a special directory, named "unsupported" that
contains units that you would like MegaMek to ignore.  Mechs can be
loaded from any of several formats:

 **MegaMek Native** - files with the extension ".mtf"
    A simple format that is very whitespace sensitive.  All of the
    meks distributed with MegaMek are in this format, so just look
    inside the zips for examples of the format.  Units of this
    file type can be created with _MegaMekLab_, _Solaris Skunk Werks_,
    and the _HMPRead_ program.

 **Heavy Metal** - files with the extensions ".hmp" and ".hmv"
    This is a commercial mech design program officially sanctioned by
    FanPro.  MegaMek can read most ".hmp or ".hmv" files directly, but
    there are still some known problems.  Please note that neither
    Heavy Metal Pro nor Heavy Metal Vee is associated with MegaMek, so
    please do not email its authors about MegaMek.

 **The Drawing Board** - files with the extension ".xml"
    The Drawing Board is a very slick freeware editor written by
    Blackstone Interactive (Cord Awtry). In order to use it with MegaMek,
    you must install the program and then use the patch to update to
    version 2.0.23. Once you have created your mech, use the "File"->"Save
    as XML file" command to create the ".xml" file.

 **MekMaker** - files with the extension ".blk"
    Mech files with the extension ".blk" are created by MekMaker, a Java
    mech design program specifically created to work with MegaMek.
    MekMaker was the official mech design program, but it has since been
    abandoned and is therefore not up to date with the current ruleset.
    It's homepage is at: http://mekmaker.sourceforge.net/

 **Mech Engineer Pro** - files with the extension ".mep"
   This is an older freeware program not made by the makers of
   MegaMek.  You can find this program on many Battletech web sites.
   It is not up to date with the current ruleset.

_Note on mixed tech units:_
Units that contain both Inner Sphere and Clan technology are allowed
with certain restrictions.  Only ".mtf", ".xml", and ".blk" files may
contain mixed tech units.  In addition, some equipment cannot differ
in technology type from the base chassis.  Units with an Inner Sphere
chassis must mount Inner Sphere engines, internal structure, armor,
and CASE.  Clan units have the same restricted equipment list.


ADVANCED MAP SETTINGS
=====================
_**Tip:** Use the basic settings, then select advanced, and the boxes will be filled in with the values from the basic
settings._

**Board Size** - set the size of the map sheet generated.  When using generated
maps, it is better to generate one large play area than to try and combine
multiple mapsheets.

**Theme** - leave blank, or enter a theme supported by the tileset.
        grass, lunar, mars, snow are themes supported by the standard tileset.
        
**Elevation settings:** 

**Amount of elevation** - changes the "roughness" of the map, a low number
will have less elevation changes than a high number
Elevation range: height difference between the lowest and highest hex 
on the map.  Level 0 is set to the most common height.

**Probability of inverting** -  % chance to make a sinkhole instead of a mountain.

**Algorithm** - 0 generates rolling hills, 1 generates spiky terrain, 2 combines
both generators.  0 is likely to have less LOS blocking terrain.

**Cliffs** - % chance to change a steep slope into a cliff.  For example, if
a group of level 1 hexes have level 0 and level 2 hexes adjacent, they will all
be moved to level 0, giving a cliff for mechs to hide behind.  The effect is
quite subtle unless you have quite a high elevation range to begin with.

**Patch terrain settings (woods, roughs, swamps, lakes, pavements, rubble, fortified, ice):**

Each of these work the same way, but place a different type of terrain.

**Number of XXX** - the number of patches which would be present on a 16x17 map.
scales up if you have a bigger map.

**XXX size in hexes** - the size of each patch of terrain

**Probability for heavy woods/deep water** - % chance to place instead of light.

**River/road settings** - Probability is a % chance to have one on the map.  If a road crosses water, 
you'll get a bridge.

**Crater settings:**
    
**Probability for craters:** - % chance that craters are present
Number of craters: as for number of woods, the number that would be present on
a 16x17 map, scaled up for larger maps.

**Crater radius** - size range for each crater.

**Special effects settings:**

Each probability is a % chance.
FX modifier changes the amount of effect each one has. Values should be small,
e.g -3 to +3

**Fires** - woods hexes will be set on fire or already burned down to rough at the
start of the game. + modifier increases number of burned down hexes, - modifier
increases number of unscathed woods.

**Frozen water** -  water hexes are ice-covered. +modifier decreases the water depth,
so for example with a modifier of 1, shallow water hexes are frozen solid and
deep water hexes are converted to ice covered shallow water.

**Flooded map:** - hexes with negative elevations are converted to water hexes, while
level 0 hexes are converted to swamps.  Ideal for hovercraft and naval units.
modifier changes the "sea level"

**Drought** - water hexes are dried up, to shallower water, swamp or rough.  Modifier
changes the severity of the drought.

_**Special effects can be combined** - e.g. flood + drought = rocky shore, 
flood + frozen + high modifier = glacier_

**City Settings:**

City type is the same as for the basic settings.

**City Blocks (0-) [16 default]** - higher numbers mean more roads on the map. 
Scales with map size.

**CF min/max (1-150) [10-100 default]** - CF range for generated buildings. 
The CF determines the building type from the table in BMR.

**Floors min/max (1-50) [1-6 default]** - height range for generated buildings
 
**Density (1-100) [75 default]** - % chance of a building in each hex where a 
building is possible. Also chance to try and build multi-hex buildings. 

DIFFERENCES BETWEEN THE BOARD GAME AND MEGAMEK
==============================================
Although MegaMek tries to be faithful to the original board game rules, in
some cases, due to technical or design limitations, this is not possible.
These differences are not considered "bugs."  If you spot any more 
discrepancies, please contact the author (see "CONTACT" below.)

- If the line of fire lies along the edge of two hexes, in the board game,
    the defender chooses which hex to use.  Instead, MegaMek chooses the
    hex that most favors the defender.
    
- When punching, you automatically punch with both arms, if possible.  This
    means you can not punch two different targets in the same round.
    
- When kicking, you automatically use the leg with the better chance to hit.

- There are several situations, notably death from above, where a unit is
    displaced out of a hex, and that unit's owner may pick the hex to move to.
    MegaMek currently picks the hex for you, choosing high elevations over low
    ones, to avoid falling damage.
    
    
CONTACT & FURTHER INFORMATION
=============================
For more information, and to get the latest version of MegaMek, visit the
website at:
http://www.megamek.info/

For more information about the BattleTech board game, visit it's website at:
http://bg.battletech.com/

To submit a bug report, suggestion, or feature request please visit
https://github.com/MegaMek/megamek/issues

To discuss all things MegaMek, please visit the forums at http://megamek.info/forums/



COPYRIGHT & LICENSE INFORMATION
===============================
MegaMek - Copyright (C) 2002 Ben Mazur (bmazur@sev.org)
  
This program is free software; you can redistribute it and/or modify it 
under the terms of the GNU General Public License as published by the Free 
Software Foundation; either version 2 of the License, or (at your option) 
any later version.
  
This program is distributed in the hope that it will be useful, but 
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 
for more details.

MechWarrior, BattleMech, ‘Mech and AeroTech are registered trademarks of 
The Topps Company, Inc. Original BattleTech material Copyright by Catalyst Game Labs
All Rights Reserved.  Used without permission.