This file describes the elements in a MegaMek XML file.  In addition to the
attributes defined below, an element can have any amount of CDATA text.  This
text will have no effect on the game, but it may be helpful for humans reading
the file.  Unless otherwise stated, any well-formed string is a valid value.

Please note, this document does *not* describe the XML files produces by The
Drawing Board.

<packet> - A top-level element that identifies a transmission between a
        client and the server.  Contains zero or one <packetData> elements.
     The following attributes are defined for this element:
        type - required - identifies the type of packet.  The meanings of
                the various packet types, and the expected contents of the
                data are documented in [insert URL here].  Valid values are
                any positive integer.

<unit> - A top-level element that identifies a unit of entitys.  Contains
        zero or more <entity> elements.  The entities in the units must be
        based on existing templates and will describe how each unit is
        different than its template.

<template> - A top-level element that identifies a new class of entity
        available for selection in the ChatLounge.  Contains one <entity>
        element.  The entity in template must completely define the
        capabilities of the class.  No <location> may be omitted in the
        template, but any <slot> whose type attribute value is System may
        be omitted for its location.  The <armor> element of type Internal
        will be ignored.
     The following attributes are defined for this element:
        type - required - identifies the type of entity being described.
                Valid values are: Mech, Tank, BattleArmor, or Infantry.

<packetData> - The "payload" for the packet.  Contains one or more other
        elements.  The exact details on the number and types of elements
        are included in the packet documentation. 
     The following attributes are defined for this element:
        count - required - identifies the number of data elements in
                the packet.  Any non-negative integer is valid.
        isGzipped - default: false - identifies if the contents of the element
                (the sub-elements and the CDATA) have been compressed with
                the ZLIB algorithm.  If so, then the CDATA of this element
                is *not* text meant for a human, but is instead the Base64
                encoding of the compressed data.

<board> - A rectangular, hex-based battlefield, specifying the terrain
        (including fire and smoke), buildings, and burning Inferno rounds. 
        Contains one <boardData> element, zero or one <buildings> elements,
        and zero or one <infernos> elements.  The hex field of every board is
        rotated so that, if you consider the top of the board to be North, the
        every hex has an edge in the North and South directions and a vertex
        in the East and West directions.
     The following attributes are defined for this element:
        version - required - identifies the version number of the <board>
                element definition used to encode this element.  It is
                anticipated that this value will be used by decoders to
                support forward XML version compatibility.

<boardData> - Information about the current board.  Contains zero or more
        <hex> elements; the exact number of <hex> elements should be the
        product of the values of the width and height attributes of this
        element.  The <hex> elements are presented by rows (i.e. hex
        0101 is followed by hex 0201, and *not* hex 0102).
     The following attributes are defined for this element:
        width - required - the width of the board in hexes.  Any integer
                between 0 and 8388607 is valid.  Expected values are between
                16 and 240 (i.e. 1-to-15 standard map sheets).  Please note,
                the "width" dimension is the one that runs parallel to the
                North and South faces of the hexes.
        height - required - the height of the board in hexes.  Any integer
                between 0 and 255 (i.e. 0-to-15 standard map sheets).  Please
                note, the "height" dimension is the one that runs perpendicular
                to the North and South faces of the hexes.
        roadsAutoExit - default: true - identifies if the roads on the map
                are assumed to exit onto adjacent pavement hexes.  Any boolean
                value is valid.  

<hex> - A single hex on a battlefield, specifying the terrain (including fire
        and smoke).  Contains one <terrains> element.
     The following attributes are defined for this element:
        version - required - identifies the version number of the <hex>
                element definition used to encode this element.  It is
                anticipated that this value will be used by decoders to
                support forward XML version compatibility.

<terrains> - The information for all terrain features in a hex.  Contains
        zero or more <terrain> elements.
     The following attributes are defined for this element:
        count - required - identifies the number of <terrain> elements in
                the hex.  Any non-negative integer is valid.
        elevation - required - identifies the base elevation of the hex.  Any
                integer is valid.
        theme - optional - identifies the theme of the graphics for the hex. 
                Any string is valid.  Not all values for theme produce
                meaningful results.

<terrain> - The information for a single terrain feature in a hex.
     The following attributes are defined for this element:
        type - required - identifies the type of this terrain feature.  Valid
                values are any positive integer.  The meanings of the various
                terrain types are documented in [insert URL here].
        level - required - the level of the terrain feature.  Valid
                values are any non-negative integer.  The meanings of
                the various levels are documented with the terrain types.
        exits - required - the level of the terrain feature.  Any integer
                between 0 and 63 is valid.  Certain terrain features like
                roads and buildings have special rules when one travels 
                from one hex to another along (or inside) the terrain feature.
                This attribute specifies when a terrain feature in one hex is
                connected to the same terrain feature in an adjacent hex. 
                Each edge of a hex is assigned a numeric value: the North edge
                is 1, the Northeast edge is 2, the Southeast edge is 4, the
                South edge is 8, the Southwest edge is 16, and the Northwest
                edge is 32.  The value of this attribute is the sum of the
                values for every edge that the terrain feature in this hex
                crosses.  For example, if a road runs from hex 0101 through
                0102 into 0103, the exits for the roads of the three hexes
                would be 8, 9, and 1 (respectively).  If the road ran from
                0101 to 0201 to 0102, the exits would be 4, 48, and 2.
        exitsSpecified - required - whether the exits have been calulated or
                were specified explicitly.  Any boolean value is valid.

<buildings> - Information about the buildings present on the battlefield.
        Contains one or more <building> elements.

<building> - Information about a single (possibly multi-hex) building on the
        battlefield.  Contains one <buildingData> element.  Please note, the
        <terrain> elements of the board for the building specify the *starting*
        values for the building, but the <building> element specifies the
        *current* values for the building.  Please note that the height of
        the building and the depth of the building's basement are documented
        in the <terrain> elements, and not in the <building> element.
     The following attributes are defined for this element:
        version - required - identifies the version number of the <building>
                element definition used to encode this element.  It is
                anticipated that this value will be used by decoders to
                support forward XML version compatibility.

<buildingData> - The details of this particular building.  Contains one or
        more <coords> elements that represent the location of the hex(es) that
        this building occupies.
     The following attributes are defined for this element:
        id - required - a unique identifier for the building.  Valid values
                are any non-negative integer.
        type - required - identifies the construction type of this building. 
                Valid values are 1, 2, 3, and 4.  A value of 1 indicates a
                light building, 2 is for medium buildings, 3 is for heavy
                construction, and 4 is for hardened buildings.
        currentCF - required - the remaining number of construction factors
                (i.e. damage points) that the building can sustain.  Valid
                values are any non-negative integer.  A building will collapse
                at the end of the phase that it's currentCF falls to zero.
                The currentCF also represents the cumulative number of tons
                of Tanks and Meks that a building can support on a single
                floor in a single hex; if the cumulative tonnage exceeds the
                currentCF, the building will collapse immediately.
        phaseCF - required - the number of construction factors (i.e. damage
                points) that the building had at the beginning of the phase. 
                Valid values are any positive integer.  The damage that a
                building inflicts during a collapse and upon units moving
                through its walls is based upon the phaseCF, not the currentCF.
        name - required - the name of the building, as it will appear on the
                map and in reports.
        isBurning - default: false - identifies when at least one hex of the
                building is on fire.  Any boolean value is valid.

<infernos> - Information about the Inferno rounds burning on the battlefield.
        Contains one or more <inferno> elements.  Each <inferno> element
        will contain a <coords> element that represents the location of the
        hex containing these inferno rounds.

<inferno> - The information about the Inferno rounds burning at a set of
        coordinates or on an entity.  Contains one <standard> element, zero
        or one <coords> element, and zero or one <arrowiv> element.

<standard> - The burn time of standard Inferno rounds remaining.
     The following attributes are defined for this element:
        turns - required - the width of the board in hexes.  Any non-negative
               integer is valid.

<arrowiv> - The burn time of Arrow IV Inferno rounds remaining.
     The following attributes are defined for this element:
        turns - required - the width of the board in hexes.  Any non-negative
               integer is valid.

<coords> - Identifies a set of coordinates in an abstract metric where (0, 0)
        is the upper-lefthand-corner, X increases to the right of the origin,
        and Y increases below the origin.  
     The following attributes are defined for this element:
        hash - required - the hash value that represents these coordinates. 
               Any non-negative integer is valid.  The value = X * 256 + Y.

<entity> - A playable item in the game.  Contains zero or one <pilot>
        elements, zero or more <location> elements, and zero or one <fluff>
        elements.  All optional attributes for this element are ignored if
        it appears as part of a <unit> element.
     The following attributes are defined for this element:
        chassis - required - the chassis of the entity.
        model - optional - the entity's specfic model within the chassis.
                This value must be supplied, if available.
        type - optional - movement type of entity being described.  Valid
                values are Biped, Quad, Tracked, Wheeled, Hover, Leg,
                Motorized, and Jump.  Note that not all entity types are
                valid for all template types.
        typeVal - optional - numeric movement type of entity being described.
                Valid values are any integer between 0 and 5 (inclusive).
                Note that not all entity types are valid for all template
                types.
        techBase - optional - the technology base used to construct the
                entity.  Valid values are: Mixed, Clan or IS.
        year - optional - the year the entity entered service.  Any 
                numberic value between 2750 and 3100 is valid.  The value
                of 3025 means that the entity uses Level 1 rules.
        mass - optional - the mass of the unit.  Any integer value between
                0 and 100 is valid.  Not all mass values are valid for all
                template types.
        engineRating - optional - the rating of the entity's engine. Any 
                numberic value between 0 and 400 is valid.
        engineType - optional - the type of engine used by the entity.
                Valid values are: IC, Fusion, XL, and Light.  Not all 
                engineType values are valid for all entity techBase and
                entity year values.
        structure - optional - the structural materials used in the entity's
                construction.  Valid values are: Standard and Endo Steel.
                Not all structure values are valid for all template type,
                entity techBase and entity year values.
        myomer - optional - the myomer system used in the entity's
                construction.  Valid values are: Standard, MASC, and TSM.
                Not all myomer values are valid for all template type,
                entity techBase and entity year values.
        armor - optional - the armor system used in the construction of
                the entity.  Valid values are: Standard, Ferro-Fibrous,
                and Stealth.  Not all armor values are valid for all
                template type, entity techBase and entity year values.
        sinkTotal - optional - the total number of heat sinks on the entity.
                Any integer value from 0 to 30 is valid.  This attribute
                is not valid for every template type.
        sinkType - optional - the type of heat sinks used in the entity's
                construction.  Valid values are: Single and Double.  This
                attribute is not valid for every template type.
        walkMp - optional - the entity's walk speed (cruise for tanks) if
                it is not damaged.  Any integer value from 1 to 20 is valid.
        jumpMp - optional - the entity's jump distance if it is not damaged.
                Any integer value from 0 to 20 is valid.

<fluff> - Any background or history text for the entity.

<pilot> - The name and skills of the pilot or crew of the entity.  If the
        entity is part of a <template>, this element is ignored.
     The following attributes are defined for this element:
        name - optional - the name of the pilot or crew.
        gunnery - required - the gunnery skill of the pilot or crew.  Any
                integer value from 0 to 7 is valid.
        piloting - required - the piloting skill of the pilot or crew.  Any
                integer value from 0 to 7 is valid.
        hits - default: 0 - the number of hits the pilot has suffered.  Valid
                values are any integer value from 0 to 5 or Dead.
        advantages - default: empty - a colon (':') separated list of codes
                specifying the MaxTech advantages the pilot posesses.
        autoeject - default: false - identifies if the pilot will autoeject
                if the unit sufferes an ammo explosion.  Any boolean value is
                valid.

<movement> - Lets you define alternate (lower) speed for a tank.  This tag
        is designed only for use on vehicles.  Also note, this can cause
        the validator to reject the vehicle (engine rating is based on
        the new movement value).
     The following attributes are defined for this element:
        speed - required - "immobile" or an integer are allowed values.

<turretlock> - Lets you start a tank's turret as locked.  This tag is
        designed only for use on vehicles.
     The following attributes are defined for this element:
        direction - The direction in which the turret is locked.  0 is
                forwards, and it increases clockwise (1 is one to the right,
                3 is backwards).

<location> - The contents and condition of a single location within the
        entity.  Contains zero to three <armor> elements and zero or more
        <slot> elements.  Not every template type can have the maximum
        number of <armor> or <slot> elements.  If a <location> is omitted
        from an <entity> in a <unit>, the values of the entity's template
        will be used. 
     The following attributes are defined for this element:
        index - required - the index of the location on the entity.  Any
                integer value from 0 to 7 is valid.  Not all index values
                are valid for all template types.
        isDestroyed - default: false - identifies if the location has been
                destroyed.  Any boolean value is valid.  This attribute is
                ignored if the <entity> is part of a <template>.  If a
                location has been destroyed, all dependent locations on
                the entity must not be omitted.  If a location has been
                destroyed, the default value of the points attribute of
                all <armor> elements in the <location> will be Destroyed,
                unless the armor's points are NA in the template.  Also,
                the default value of the isDestroyed attribute of all <slot>
                elements in the <location> will be true.  In the instance
                that a limb is blown off, the armor points and the condition
                of the slots for that location will be ignored when the
                file is read (i.e. the limb will be completely destroyed).

<armor> - A piece of armor or internal structure for the location.
     The following attributes are defined for this element:
        points - required - the number of points of damage this piece of
                armor or internal structure can absorb.  Valid values are
                any integer from 0 to 100, N/A, or Destroyed.  The value
                Destroyed is not valid if the <entity> is part of a
                <template>.
        type - default: Front - distinguishes internal structure from armor
                and identifies the facing for armor.  Valid values are:
                Front, Rear, and Internal.  Not every location index can
                have a Rear armor type.  Only one <armor> element of each
                type value can be identified for a <location>.

<slot> - A single critical slot in the location.  Please note, some pieces
        of equipment (like Clan CASE) and some template types (like
        Infantry) do not occupy a slot on the entity's hit diagram, but are
        still represented by a <slot>; the index value for these elements
        will be N/A.
     The following attributes are defined for this element:
        index - required - the position of the slot in this location.  Valid
                values are any integer from 1 to 12 or N/A.
        type - required - the internal name the piece of equipment within
                the MegaMek application.  The value of System identifies
                the equipment in the slot as the standard system normally
                found at this slot's index.  The value of Empty identifies
                that there is no equipment in the slot; any standard system
                normally found at this slot's index will be removed.
        isRear - default: false - specifies that the weapon in this slot
                fires to the rear.  Any boolean value is valid.
        shots - default: N/A - if the slot is for ammunition, the number of
                shots left in this slot.  Valid values are any integer from
                0 to 200 and N/A.  Ammunition may not have a value of N/A
                and only ammunition may have an integer value.
        isHit - default: false - identifies that this slot has suffered a
                critical hit.  Any boolean value is valid.
        isDestroyed - default: false - identifies that the equipment in this
                slot has been destroyed.  Any boolean value is valid.  Note
                that a single slot in a multi-slot piece of equipment can
                be destroyed but not hit; it is still available to absorb
                additional critical hits.


An example unit would be:

<unit>
   Boris is piloting an undamaged ARC-2S
   <entity chassis="Archer" model="ARC-2S">
      <pilot name="Boris Gudanov" piloting="3" gunnery="5"/>
   </entity>

   Natasha is in a LCT-1S that has been hit by 3 SRM missiles (1 RT and 2 LA)
   and 1 Medium Laser (in RT rear), had its left arm blown off, and has fired
   3 shots.
   <entity chassis="Locust" model="LCT-1S">
      <pilot name="Natasha Kerensky" piloting="2" gunnery="2"/>
      The first slot in a location is at index="1".
      <location index="1"> Center Torso
         <slot index="12" type="IS Ammo SRM-2" shots="47"/>
      </location>
      <location index="2"> Right Torso
         <armor points="4"/>
         <armor points="Destroyed" type="Rear"/>
         <armor points="3" type="Internal"/>
      </location>
      <location index="5" isDestroyed="true"> Left Arm has been blown off.
         <slot index="1" type="System" isDestroyed="false"/>
         <slot index="2" type="System" isDestroyed="false"/>
         <slot index="3" type="SRM 2" isDestroyed="false"/>
         <slot index="4" type="Empty"/>
      </location>
   </entity>
</unit>


An example template would be:

<template type="Mech">
   <entity chassis="Barney" model="KIL-ME" 
        type="Biped" techBase="IS" year="3025" engineRating="40"
        engineType="Fusion" structure="Standard" myomer="Standard"
        armor="Standard" sinkTotal="Standard" sinkType="Single"
        walkMp="2" jumpMp="0">
      <fluff>
   An annoying purple lizard-shaped Mech with bad breath and a killer hug.
   This unit is intentionally easy to kill.  They tend to explode... a lot!
      </fluff>
      The first slot in a location is at index="1".
      <location index="0"> Head
         <armor points="9"/>
         <slot index="4" type="Flamer"/>
      </location>
      <location index="1"> Center Torso
         <armor points="10"/>
         <armor points="2" type="Rear"/>
         <slot index="11" type="IS Ammo MG - Full"/>
         <slot index="12" type="IS Ammo MG - Full"/>
      </location>
      <location index="2"/> Right Torso
         <armor points="8"/>
         <armor points="2" type="Rear"/>
         <slot index="1" type="Machine Gun"/>
         <slot index="2" type="Machine Gun"/>
         <slot index="3" type="Machine Gun"/>
         <slot index="4" type="IS Ammo MG - Full"/>
      </location>
      <location index="3"/> Left Torso
         <armor points="8"/>
         <armor points="2" type="Rear"/>
         <slot index="1" type="Machine Gun"/>
         <slot index="2" type="Machine Gun"/>
         <slot index="3" type="Machine Gun"/>
         <slot index="4" type="IS Ammo MG - Full"/>
      </location>
      <location index="4"/> Right Arm
         <armor points="6"/>
         <slot index="5" type="IS Ammo MG - Full"/>
      </location>
      <location index="5"/> Left Arm
         <armor points="6"/>
         <slot index="5" type="IS Ammo MG - Full"/>
      </location>
      <location index="6"/> Right Leg
         <armor points="8"/>
         <slot index="5" type="IS Ammo MG - Full"/>
      </location>
      <location index="7"/> Left Leg
         <armor points="8"/>
         <slot index="5" type="IS Ammo MG - Full"/>
      </location>
   </entity>
</template>
