View source for Making Maps by Hand

This tutorial is to help map designer to get a grasp of the Map
format used by Armagetron Advance.

This version of the tutorial address the syntax defined by map-0.2.8_beta3.dtd and present the rules of interpreting the syntax as used by the parsing engine in the version 0.2.8 of Armagetron Advance.

== Format overview ==

The classic Armagetron arena could be described with the following
map:

[[Image:original-1.0.1.png|right|thumbnail|Original Armagetron Map]]

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map-0.2.8_beta3.dtd">
<Resource type="aamap" name="square" version="1.0.1" author="Anonymous" category="polygon/regular">
	<Map version="0.2.8">
		<!-- The original square map, technically created by z-man.
	         Converted to XML by philippeqc.
	         License: Do with it what you want.                          -->

		<World>
			<Field>
				<Axes number="4"/>

				<Spawn	x="255"	y="50"	xdir="0"	ydir="1"	/>
				<Spawn	x="245"	y="450"	xdir="0"	ydir="-1"	/>
				<Spawn	x="50"	y="245"	xdir="1"	ydir="0"	/>
				<Spawn	x="450"	y="255"	xdir="-1"	ydir="0"	/>

				<Spawn	x="305"	y="100"	xdir="0"	ydir="1"	/>
				<Spawn	x="195"	y="400"	xdir="0"	ydir="-1"	/>
				<Spawn	x="100"	y="195"	xdir="1"	ydir="0"	/>
				<Spawn	x="400"	y="305"	xdir="-1"	ydir="0"	/>

				<Spawn	x="205"	y="100"	xdir="0"	ydir="1"	/>
				<Spawn	x="295"	y="400"	xdir="0"	ydir="-1"	/>
				<Spawn	x="100"	y="295"	xdir="1"	ydir="0"	/>
				<Spawn	x="400"	y="205"	xdir="-1"	ydir="0"	/>

				<Wall>
					<Point	x="0"	y="0"	/>
					<Point	x="500"	y="0"	/>
					<Point	x="500"	y="500"	/>
					<Point	x="0"	y="500"	/>
					<Point	x="0"	y="0"	/>
				</Wall>
			</Field>
		</World>
	</Map>
</Resource>
</pre>

The Map format start with a XML header. The actual definition
of the Map is wrapped in a Resource. The Resource gives a
description of the content, such as the author and the version of
the map included. This particuliar map is the xml version of the
original map that supported directly in the game before version
0.2.8 (Arthemis). 

Skippin ahead in to the Field element, line 11 defines that 
that 4 axes are to be
used. From line 13 to 26, all the spawn points, ie: the points where
the cycles are located when the match starts, are defined. Finally
the walls are defined, delimiting the play area.

== Header ==
The header of the map can nearly be considered as constant. It is
composed of 2 lines.

Header for Arthemis' maps:
<pre>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map-0.2.8.dtd">
</pre>

The only element you need to consider is the name of the dtd. The
dtd should always be named after the version it targets. For
Arthemis, it should be "map-0.2.8.dtd". 

Nota: during the beta process, version can change often and have
great difference between them. To limit the scope of the problem
during the beta phase, the name of the dtd should include the beta
it targets. 

Header for the beta 3 of Arthemis' maps:
<pre>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map-0.2.8_beta3.dtd">
</pre>

== Resource ==
The Resource element describe some meta-information of the Map,
such as who created it, how should the resource file be named and
what type of information is to be expected.

One part of the Resource details describe who made this map a
reality. In the Resource element, it is possible to differenciate
between the person or organism that comissioned the map, the
commisionner, and the person who executed the request and coded
it, the author. 

Both operations might be carried by the same and only person, in
this instance both entities are the same and the commissioner
field should be left blank. The commissioner field should be used
when the concept of a map and its execution are performed by two
different persons or entities. It could range from anything from
"could someone make a map where the feeling of <X> is emphased" to
coding from a hand-drawn sketch. The commissioner could also be
implied. Without him/it ever placing an open request, a
commisioner could be assign to a map when the author whan to
express an assumed sharing of the creation of the map. This can be
the case, for example, when the member of a Clan wrote a map that
falls in the ideals of the Clan.

Maps can be implicitly grouped together. The category field is
there for this purpose. Prolific authors and their public will
appreciate a clear grouping of similar themed maps.

As ever refining one's work is a very respected quality in the
Armagetron community, the latest changes need to be properly
propagated to everybody. The version field allow an author to
identify each specific instance of her work, and also insure that
a client will receive the exact version used by a server when
playing on it.

The type specifies that the file hold an Armagetron Advance
map. While this is the only type available at the moment, the
development team is eager to expand this in the furture.

Finally, and most importantly, the name of the ''ouvrage'' being
presented. 

The fields for Resource are:
;name
:The name of the map, mandatory.
;type
:The only valid type is "aamap". This field is defaulted "aamap" when abscent.
;version 
:The version of the map described in this particuliar file. This value should be modified each time a change is applied to the map to ensure everybody have the proper copy. This field is defaulted to "1.0" when abscent.
;author
:The author who produced this map. This field is defaulted to "Anonymous" when abscent.
;commisioner
:The entity who dreamt, requested or even inspired in any way this map. This field is optional and has no default value. 
;category
:How this map should be categorised. This field can have any number of sub categories, each separated by a "\". An example could be "category\subcategory\subsubcategory". This field is defaulted to "unsorted" when abscent. 

Example: The castle map made by philippeqc
<pre>
<Resource name="Castle" type="aamap" version="1.1" author="philippeqc" category="examples">
    ...
</Resource>
</pre>

Example: The StarTron map made by Your_mom
<pre>
<Resource name="5ptstar" version="beta" author="Your_mom" category="beta" type="aamap">
    ...
</Resource>
</pre>

Example: The MBC training map, made by Zorgul
<pre>
<Resource name="TrainingDay" version="1.6" author="Zorgul" category="MBC" type="aamap" commisioner="Micro Bus City">
    ...
</Resource>
</pre>

Example: The Reverso map, writen by Nemosultra based on a drawing by lucifer, for the Crack Pipe server
<pre>
<Resource name="Reverso" version="1.1-b" author="Nemosultra" category="CrackPipe" type="aamap" commisioner="lucifer">
    ...
</Resource>
</pre>

To facilitate manipulation of the file over distributed systems,
the Resource holds explicit information about the naming and
storing of the file. This information can be used by tools such as
scripts and resource repositories to manipulate the file. 

Many tools, including the game client, will expect the following
to indicate the location of a 
filee inside the local store of resources.

<Author>/[Category/]<ResourceName>-<VersionNumber>.<ResourceType>.<Extension>

== Map ==
This element is the basic holder of the description of the
Map. From the opening element to the closing one, all the
information will be used to construct an in-game representation
for the players to explore and possibly compete in.

The version attribute of the map indicate an specific parsing
engine version that should be used to express the map in the exact
manners that are desired by the map creator. 

Example: Map element
<pre>
    <Map version="0.2.8">
        ...
    </Map>
</pre>

Sooner in the file,
the dtd has already specified a version. The difference between
both version is one specify the version of the syntax to be use,
and the other, the version of the rules to be used to interprete
the syntax.

The dtd control the syntax, what keywords are valid and in which
arrangement. The parsing engine has specific rules how to read the
syntax and create the game elements. It is possible for different
parsing engine to operate from the same syntax, be it because the syntax
allows for many interpretation, or because a specific
interpretation has been found faulty in some case. Because each
interpretation could lead to very different instantiation, it is
best for the map designer to specify the one that should be
used. Even when no alternative interpretation exist, ie: there is
only one version available, it is best for the map designer to
specify it. Should a new one be implemented at a later time, the
map defined would continue to be instanciated properly.

At the time of writing, the only parsing engine version is
"0.2.8". Maps using a version that is not understood by the
parsing engine of a specific client or server will be
automatically rejected by said application, on the ground that the
parsing engine doesn't know how to operate on it.

Even if only one value exist, it is impossible to provide it as a
default, as there are no assurance that a new interpretation of
the syntax will not arrive at a future time.

== Settings ==
It is possible for a map designer to indicate specific game
settings, similar to the ones available through the configuration
files of the application, to be used with the map. When
this is not desired, the Settings element can be safely removed
from the map definition.

Any number of Setting can be defined inside of the Settings
element. Each Setting defined will overwrite the value previously
defined in the game. Each new Setting addressing a specific
configuration item will keep on overwriting previously defined
values. The Settings items are processed in order, from the top to
the bottom one.

The Settings should be considered to be global to the World and
its sub-elements. This has very little relevance at the moment as
only one World and one Field can exist in the game. It is not
excluded that future version of the game could support multiple
elements such as World and Field. Each such elements and sub-elements would
receive the Settings defined in its parents, but would also be
able to overwrite parent received Settings for itself and its
sub-elements. 

One such overwriting capacity already exist, in the form of the
Axes element. This element can and will overwrite the value passed
by the Setting ARENA_AXES.

At the time of writing, there are no known case where the order of
writing Setting should matter. There are no garanties of it being
the case. Be carefull of the order of the Setting provided.

<pre>
	<Settings>
		<Setting name="a" value="1"/>
		<Setting name="b" value="2"/>
		<Setting name="c" value="3"/>
	</Settings>
</pre>

== Setting ==
Each individual Setting defines a specific element normally
configurable throught the config files of the game
application. For a full list and description of the setting
available, consult the [[Console Commands]] page. As config items
are the same as console commands, you will find all the
information there.

The Setting has two attributes, the name and the value. The name
field hold the setting name as found in the various configuration
files. The value field will be assigned to the designated setting.

<pre>
	<Setting name="CYCLE_BRAKE_REFILL" value=".1"/>
</pre>
will assing .1 to the configuration item CYCLE_BRAKE_REFILL.

No validation are done on either fields by the parsing engine. The
values are passed directly to the setting engine, where the usual
validation is performed. Unexisting or misspelled settings names
will be ignored. Setting with valid names and invalid values have
an undetermined effect.

The different Setting used have the potential of overwriding
client or server ones. While this behavior offers great capacity
to custom behavior for a specific map, users playing locally on
their machine and server administrator might find it a disruption
of their craftfully designed settings. Use with care and
moderation.

== World ==
At this moment, the element possible inside of the World element is
the Field element. Only one Field can be defined. No parameters
are available at the moment.

<pre>
	<World>
            ...
	</World>
</pre>

== Field ==
The Field element holds the description required to construct the
play area. Inside the Field, Axes, Spawn and Wall elements can be
defined. 

The field define the zone on a 2D plane where the gaming can
occur. The full support of this definition will be developed under
Bacchus. In Arthemis, the old philosophy of "the play zone has to
be bounded by walls" is somewhat preserved. A secondary mechanism
also exist to prevent the players from escaping the rim. This is a
bried description of the mechanism used.

While setting all the walls to be used during a round, the engine
will keep track of the minimal and maximal x's and y's values
encountered through wall coordinates.
A logical box will be formed, using the coordinate
(minX, minY), (maxX, minY), (maxX, maxY) and (minX, maxY) as its
corners.

Example: Logical box around the classical arena.
The classical arena has the coordinates (0,0), (0,500), (500,500)
and (500, 0). This means that minX=0, minY=0, maxX=500 and
maxY=500.

Example: Logical box around a square arena moved by 20 on the x's.
The classical arena has the coordinates (20,0), (20,500), (520,500)
and (520, 0). This means that minX=20, minY=0, maxX=520 and
maxY=500.

Example: Logical box around a trapeze arena
A trapeze has a base lenght of 300, a top lenght of 200 and a
height of 200 with the following coordinates: (0, 0), (300, 0),
(250, 200), (50, 200). This means that minX=0, minY=0, maxX=300,
maxY=200.

Example: Logical box around 2 walls of the classical arena
Should the south and west walls of the classical arena be ommited,
and only the north (from (0,500) to (500,500)) and east one (from
(500,0) to (500,500)) remain, the logical box is still the same
around it. This means that minX=0, minY=0, maxX=500 and
maxY=500.

Example: 2 walls at strange angle
If two walls, organised at strange angle and not even meeting,
compose the arena, are described as (200,200) to (600, 400) and
(350, 350) to (-10, 720). This means that minX=-10, minY=200,
maxX=600 and maxY=720.

A no-motion logical box will be put at 10 game units outside of the
logical box. Should a player meet this no-motion zone, she will
find herself pushing agains a coussin of air. Rubber has undefined
effect agains this no-motion box.

A second logical box will be put at 20 games units from the first
logical box. Should any players be outside of this logical box,
they are automatically killed.

In game terms, should the players not be bounded by a continous
wall, they are free to roam around it but they will find an
invisible barrier keeping them from excaping into the infinite.

Should you want to allow your players to roam without
restrictions, exploring the infinity of the grid, you have to
specify to use an infinite field.

The Field support a single parameter, named logicalBox, which
control if the logical box should be used to limit roaming on the
Field. 
;logicalBox
:When set to true, the motion will be restrained by the logical
box, and when set to false, no logical box will be used. This
field is optional and default to true.

Example: Logical box bounded Field
<pre>
            <Field>
                ...
            </Field>
</pre>

Example: Field with its logical box disabled
<pre>
            <Field logicalBox="false">
                ...
            </Field>
</pre>

The following 2 paragraph are post map-0.1 and 0.2.8_beta2.

For clarity purpose, the Axes element, if defined, need to be
defined first. After this, Spawn point, Walls and Zones can be
defined in any order.

While a Field without any Spawn points is syntaxly valid, and
the parsing engine doesnt report any error, the effect is
undetermined. While a Field without any Wall is syntaxly valid,
and the parsing engine doesn't report any error, the effect is
undetermined.

== Axes ==
The Axes element define how the cycles will behave on this
particular Field. The original Armagetron used 4 axes. 

The Axes element has 2 field:
;number
: This specifies the number of axes that should be used. If not specified, 4 axes are assumed.
;normalize
:When set to true, specify that the game should ensure that the direction vectors are scaled to have a size of exactly 1.0. When not specified, the individual axis will be keep at the exact length they are specified. This is covered in section 6. When not specified, it is assumed that normalization is desired.

        <Axes number="6" normalize="true"/>

When used without any other information, it is assumed that equally spaced axes should be generated, starting from (1,0) and going clockwise. The number generated is the value specified by the number attribute.

The Axes element can also be used to describe each direction that can be used, instead of relying on the automatic generation. To do this, Axis elements are used to describe each directions.

<pre>
	<Axes number="4">
	      <Axis xdir="1" ydir="1"/>
	      <Axis xdir="1" ydir="-1"/>
	      <Axis xdir="-1" ydir="-1"/>
	      <Axis xdir="-1" ydir="1"/>
	</Axes>
</pre>

The Axis element uses the following fields:
;xdir
: This is size of the displacement along the x's for this axis
;ydir
: This is size of the displacement along the y's for this axis
;angle
: This allow to describe the Axis in degrees
;length
: When the angle is specified, the length can be used to scale the size of the vector described. This value is only used when angle are specified.

If the angle field is found, the length will be queried and used. If the length is absent, a default of 1 is used for the length. If no angle is specified, then both the xdir and ydir need to be specified for the Axis to be valid.

The previous example could be re-written with:
<pre>
	<Axes number="4">
	      <Axis angle="45" length="1.4142"/>
	      <Axis angle="135" length="1.4142"/>
	      <Axis angle="225" length="1.4142"/>
	      <Axis angle="335" length="1.4142"/>
	</Axes>
</pre>

Note that even though the length is specified, because the Axes element doesn't have the normalize="false", all the lengths will be scaled back to exactly 1.

The Axes should be specified in clockwise order. The specified axes are stored in the order they appear. When a player want to turn right, it is passed to the next axis on the list, or to the first when turning from the last direction.

You might observe that in Example 5.2, the direction sum up to more than 1.0. For example, the first Axis has a xdir and a ydir of 1. The real length of the described Axis is 
<math>\sqrt{xdir^2+ydir^2}</math>
, which is approximately 1.4142. By specifying the normalize="true", or using the default behavior, you ensure that they are scaled back to 1.0.

The number of Axis specified should be the same as the number of axes. Any extra axes will be discarded. Any missing Axis will be assumed to be (1,0). 

Note: Some old maps will use Point instead of Axis. The Point is deprecated in this context. New maps should use the Axis element.

== Advanced Axes ==

=== Normalization ===

It is often easier to write directions are (2,1) rather than
(.89442719099991587856 , .44721359549995793928), which is the
normalized equivalent. The normalization mechanism ensure that
displacement is constant on all the axes. This has always been the
behavior of the game. So what is the effect of having non normalized
Axis? Before anything else, a bit of understanding how the engine of
Armagetron operates might be required. 

You might recall from your physic class that the distance traveled is
computed from the speed at which you travel multiplied by the time
during with you traveled ie: distance = speed * time.

Armagetron has at its core a 2D engine. Vehicle move along a 2D
surface, changing their x's and y's position. To find the new position
of a vehicle, the distance is multiplied by a 2D vector, the
direction, before being added to the old position. Because the
direction is a normalized vector, the resulting displacement is of the
same size than the calculated distance. But if the direction is a
non-normalized vector, ie: it has a size that is lesser or greater
than 1, but not equal, then the displacement gets to have a different
size than the distance.

By setting the Axis to non-normalized values, the map designer can
modify displacement in the arena. By defining Axis with a vector size
of 2, see example 6.1.1, all the cycles would behave as if they where
moving twice as fast. Setting the Axis a length of 0.5, see example
6.1.2, the opposite effect occurs. Now the cycle move as if their
speed was halved.

Example: Axes of size 2
<pre>
	<Axes number="4" normalize="false">
	      <Axis xdir="0" ydir="2"/>
	      <Axis xdir="2" ydir="0"/>
	      <Axis xdir="0" ydir="-2"/>
	      <Axis xdir="-2" ydir="0"/>
	</Axes>
</pre>

Example: Axes of size 0.5
<pre>
	<Axes number="4" normalize="false">
	      <Axis xdir="0" ydir="0.5"/>
	      <Axis xdir="0.5" ydir="0"/>
	      <Axis xdir="0" ydir="-0.5"/>
	      <Axis xdir="-0.5" ydir="0"/>
	</Axes>
</pre>

By setting the normalize attribute to false, the designer ensure
that the game will use the Axis values as is. While this section has
used Axis that all have the same size, this is not a requirement. The
next section will explore setting Axis with different size.
This permit to affect the displacement on certain axes.

=== Uneven Axes ===
Up to now, the Axis have always have the same size. This mean that for
a given speed, the displacement of a cycle is always the same in every
direction. But nothing permit you to define it differently. 

Imagine an arena shaped as a rectangle. The height, along the y's,
would be ten times the size of the length, along the x's. Normally, with
the Axis all of the same size, it would take a player ten time as long to
run from one wall to another when cruising along the height of the
rectangle. 

But you could decide to make motion along the height occur at ten time the
rate, so it would take a player the same time to cover the height of
the arena than to cover the length, giving it an "Alice in Wonderland"
feeling (see example 6.2.1). This feeling could be exaggerated even more
by making traveling along the longest distance occur in half the time
that travel along the shortest distance. To do this, you could double
the size of the Axis set in the previous example (see example
6.2.2). Now, even thou one dimension of the rectangle is 10 time the
other, travel along this longer dimension occur at a much higher rate,
compressing this dimension in the player's mind.

Example: Rectangle of equal travel time
<pre>
	<Axes number="4" normalize="false">
	      <Axis xdir="0" ydir="10"/>
	      <Axis xdir="1" ydir="0"/>
	      <Axis xdir="0" ydir="-10"/>
	      <Axis xdir="-1" ydir="0"/>
	</Axes>
	<Wall>
	      <Point x="0" y="0"/>
	      <Point x="100" y="0"/>
	      <Point x="100" y="1000"/>
	      <Point x="0" y="1000"/>
	      <Point x="0" y="0"/>
	</Wall>
</pre>

Example: Rectangle of compressed travel time
<pre>
	<Axes number="4" normalize="false">
	      <Axis xdir="0" ydir="20"/>
	      <Axis xdir="1" ydir="0"/>
	      <Axis xdir="0" ydir="-20"/>
	      <Axis xdir="-1" ydir="0"/>
	</Axes>
	<Wall>
	      <Point x="0" y="0"/>
	      <Point x="100" y="0"/>
	      <Point x="100" y="1000"/>
	      <Point x="0" y="1000"/>
	      <Point x="0" y="0"/>
	</Wall>
</pre>

The current game play is balanced around the fact that normally,
the displacement factor is of size 1. By increasing this too much, your
map might quickly become unplayable. While the example present Axis
size of 10's and 20's, it is only for a pedagogical value. If you want
to create great difference of displacement among different Axis, you
might find that augmenting Axes size a little bit and raising others
also could produce a better effect. The following example offers a ratio of
6 between the displacement on the x's and y's, while keeping the faster
displacement at only 3 times the regular one. This reduce the
effect of playing at very high speed while having a huge
difference between directions.

Example: Factor of 6 between displacement, centered around a speed
of ~1.
<pre>
	<Axes number="4" normalize="false">
	      <Axis xdir="0.5" ydir="0"/>
	      <Axis xdir="0" ydir="-3"/>
	      <Axis xdir="-0.5" ydir="0"/>
	      <Axis xdir="0" ydir="3"/>
	</Axes>
</pre>

Example: Factor of 6 between displacement, centered around a speed
of ~3
<pre>
	<Axes number="4" normalize="false">
	      <Axis xdir="1" ydir="0"/>
	      <Axis xdir="0" ydir="-6"/>
	      <Axis xdir="-1" ydir="0"/>
	      <Axis xdir="0" ydir="6"/>
	</Axes>
</pre>

While the ratio of speed is the same between both examples, the
later one has speed that might be difficult to control in one
direction. The first example produce the same difference, but
present the players with a more balanced alternative.

Up to now, the Axes where always evenly placed around the
player. Distributing the Axes in a non-equal fashion can allow for
different kind of game play. If you where to make a parallelogram
shaped arena, you might want the players to be able to move along the
walls of the arena. For this, the different Axis would need to be
properly set. 

Example: Parallelogram arena
<pre>
	<Axes number="4" normalize="false">
	      <Axis xdir="0" ydir="1"/>
	      <Axis xdir="1" ydir="0.5"/>
	      <Axis xdir="0" ydir="-1"/>
	      <Axis xdir="-1" ydir="-0.5"/>
	</Axes>
	<Wall>
	      <Point x="0" y="0"/>
	      <Point x="100" y="50"/>
	      <Point x="100" y="150"/>
	      <Point x="0" y="100"/>
	      <Point x="0" y="0"/>
	</Wall>
</pre>

=== Order of the axes ===
Turning right is translated to passing to the next axis, and
turning left to the previous axis. But by changing the order that
the axes are defined, this behavior can be altered.

Example: 6 Axis in cartesian, in the order 4, 5, 6, 1, 2, 3
<pre>
        <Axes number="6" normalize="true">
            <Axis xdir="-0.5" ydir="-0.866025404"/>
            <Axis xdir="-1" ydir="0"/>
            <Axis xdir="-0.5" ydir="0.866025404"/>
            <Axis xdir="0.5" ydir="0.866025404"/>
            <Axis xdir="1" ydir="0"/>
            <Axis xdir="0.5" ydir="-0.866025404"/>
        </Axes>
</pre>

Example: 6 Axis in degrees, in the order 4, 5, 6, 1, 2, 3
<pre>
        <Axes number="6">
            <Axis angle="210"/>
            <Axis angle="270"/>
            <Axis angle="330"/>
            <Axis angle="30"/>
            <Axis angle="90"/>
            <Axis angle="150"/>
        </Axes>
</pre>

Both define a regular 6 axes. Turning right will make the cycle
face a direction that is 60 degrees to its right. But by changing
the order, this can be altered.

Example: 6 Axis in cartesian, in the order 4, 6, 5, 1, 3, 2
<pre>
        <Axes number="6" normalize="true">
            <Axis xdir="-0.5" ydir="-0.866025404"/>
            <Axis xdir="-0.5" ydir="0.866025404"/>
            <Axis xdir="-1" ydir="0"/>
            <Axis xdir="0.5" ydir="0.866025404"/>
            <Axis xdir="0.5" ydir="-0.866025404"/>
            <Axis xdir="1" ydir="0"/>
        </Axes>
</pre>

Example: 6 Axis in degrees, in the order 4, 6, 5, 1, 3, 2
<pre>
        <Axes number="6">
            <Axis angle="210"/>
            <Axis angle="330"/>
            <Axis angle="270"/>
            <Axis angle="30"/>
            <Axis angle="150"/>
            <Axis angle="90"/>
        </Axes>
</pre>

Now turning right from the first axis, the player will have the
impression of turning 120 degrees. Turning right again will turn
the player by -60 degrees. Continuing, the player would experience
turn of 120, 120 - 60 and 120 degrees, ending in the first
direction.
 
Also, the order of the axes could be totally reversed. This would
effectively make the left key turn the player to the right, and
the right key to the left

Example: 4 Axis counter clockwise
<pre>
        <Axes number="4" normalize="true">
            <Axis xdir="1" ydir="0"/>
            <Axis xdir="0" ydir="1"/>
            <Axis xdir="-1" ydir="0"/>
            <Axis xdir="0" ydir="-1"/>
        </Axes>
</pre>

== Wall ==
Walls are those big clunky elements normally associated with the
rim.

To define a wall, you need to specify all the corners of all its
segments. A wall segment will be created from one point to the
next. 

Example: A square Wall of size 200
<pre>
        <Wall>
            <Point x="0" y="0" />
            <Point x="200" y="0" />
            <Point x="200" y="200" />
            <Point x="0" y="200" />
            <Point x="0" y="0" />
        </Wall>
</pre>

You should notice that for an wall to be closed, you need to loop
back to the first point. 

Any number of walls can be specified inside the field element. A
Wall need at least 2 Points, but doesn't have any upper limits.

Walls to not need to be closed. In the arena defined earlier, it
would be possible to add some obstacle walls. 

Example: A 2 points wall, possibly as an obstacle
<pre>
        <Wall>
            <Point x="100" y="50" />
            <Point x="100" y="150" />
        </Wall>
</pre>

It is possible to have walls touching, and even crossing. There is
no difference between segments assembled from many wall elements,
or from a single one.

While it is possible to leave the play arena unbounded, this
behavior should be considered undefined and unsupported. It is
highly recommended that the play area be bounded by a wall or a
series of walls leaving no holes.

Also, while it it possible to define "holes" , ie
completely bounded areas inside a bigger area, or "islands", ie
independent bounded areas independent of another play area, these
behaviors are undefined and unsupported.

The Wall element has one attribute, the height. Controlling the
height affect the rendering height of a wall. A height of 1.0 is
about the same as the height of the original cycle model. A height
of 4.0 correspond to the Walls rendered with the lowRim setting on
the client. When no height is defined, the client defined setting
of either lowRim or highRim is used. This has the advantage of
respecting the players choice and often, capacity to render high
walls.

;''height''
: The height used for the rendering of the Wall.

Example : Using the client default height
<pre>
        <Wall>
            <Point x="0" y="0" />
            <Point x="10" y="10" />
        </Wall>
</pre>

Example : Controling the height
<pre>
        <Wall height="2.13">
            <Point x="0" y="0" />
            <Point x="10" y="10" />
        </Wall>
</pre>

== Spawn points ==
Spawn points are where cycles are first located on the map. At
game start, the game server will spread the players and AI among
the different spawn locations described. You should provide
sufficient spawn location for the number of players you entered to
play on your map.

Along with the location where the cycles will be placed, you
need to specify the starting direction of the cycle. This will
determine the direction that the cycle is facing when it appears.

To specify this, two methods are offered:
Vector orientation:
In this method, you specify the direction as a vector, from (0, 0)
to (xdir, ydir). This will indicate the direction to be face by
the cycle.
Angle orientation:
In this method, you specify the direction as an angle. Degrees are
used for this.

Because Armagetron is a game where motion occurs on certain axes
only, starting direction should also be done on those axes. The
game will use the direction described to find the closest matching
axis. It is the direction of the chosen axis that is assigned to
an spawned cycle. The direction specified is only used as a
recommendation.

A Spawn has six attributes. Only three to four are needed to
describe a Spawn. Two of them, x and y, are mandatory.
x= the x coordinate where the cycle is to be created
y= the y coordinate where the cycle is to be created
xdir= the x coordinate of the recommended direction the cycle will face at
creation.
ydir= the y coordinate of the recommended direction the cycle will face at
creation.
angle= the recommended angle to orient the cycle

If the angle attribute is specified, xdir and ydir are
ignored. When no angle attribute is specified, both xdir and ydir
are needed.

Example: Basic Spawn presentation
       <Spawn x="-15.5" y="368.0608" xdir="0.5" ydir="-0.866"/>
       <Spawn x="-15.5" y="368.0608" angle="60"/>

Only the direction indicated is used. The size of the direction
described doesn't influence the start up speed or displacement of a
cycle.

It is to be noted that specifying a direction of (0,0) is
undefined. Also, specifying spawn points outside the play area
that you defined is undefined and unsupported. 

== Zones ==
Zone are interactive areas on the Field. They manifest themself as
huge circles slowly rotating. The players can interact with the
Zones by entering or being inside them.

The Zone has an attribute effect which allows 3 values: win, death and
fortress. Entering a Zone of effect win makes the player the round
winner. Entering a Zone of effect death automatically kills the
player. Zones of effect fortress need to be occupied to be
triggered, and once triggered, they make the team the round winner.

;effect
:Any of win, death or fortress. When ommited, the value is defaulted to death

Example: Zone syntax
<pre>
        <Zone effect="death">
            ...
        </Zone>
</pre>

The Zone requires a sub element named ShapeCircle. 

The ShapeCircle has 2 attributes, the radius and the growth. The
radius attribute describe the size of the CircleShape and is
required. The unit used is the same game unit that are used as map
coordinates. A ShapeCircle with a radius of 10 will extend of 10
game units in every direction from its center.

The growth describe how the radius of the ShapeCircle changes over
time. This unit is game units per second from the moment the Zone
is create, which is the round start.

It is possible to specify a negative growth, in which case the ShapeCircle will
slowly shrink. Should at any time the radius be of 0 or less, the
Zone is removed without effect.
The growth is optional and defaults to 0, which hold the
ShapeCircle at a constant size during the round.

;radius
:The initial radius of the circle defining the Zone. This field is mandatory.
;growth
:The growth of the circle. The values can be positive, negative or 0. This field is optional and is defaulted to 0.

Example: Zone with CircleShape
<pre>
        <Zone effect="death">
            <ShapeCircle radius="20" growth="0.17">
                ...
            </ShapeCircle>
        </Zone>
</pre>

The ShapeCircle requires a Point sub-element which describe the
center of the ShapeCircle. The syntax of the Point is the same as
the one used for the Wall.

Example: A non-growing death zone
<pre>
        <Zone effect="death">
            <ShapeCircle radius="20">
                <Point x="120" y="86"/>
            </ShapeCircle>
        </Zone>
</pre>

Example: A growing fortress zone
<pre>
        <Zone effect="fortress">
            <ShapeCircle radius="20" growth="1.09">
                <Point x="250" y="7"/>
            </ShapeCircle>
        </Zone>
</pre>

Example: A shrinking win zone
<pre>
        <Zone effect="death">
            <ShapeCircle radius="200" growth="-0.2">
                <Point x="440" y="325"/>
            </ShapeCircle>
        </Zone>
</pre>

It is possible and valid to place the center of the Zone in a
location that is not accessible to the players, such as in a
walled compound or outside of the play area. This behavior might
change in future version. Consult the appropriate documentation.

Example: A death zone outside the rim
<pre>
        <Zone effect="death">
            <ShapeCircle radius="20">
                <Point x="-25" y="100"/>
            </ShapeCircle>
        </Zone>
        <Wall>
            <Point x="0" y="0" />
            <Point x="200" y="0" />
            <Point x="200" y="200" />
            <Point x="0" y="200" />
            <Point x="0" y="0" />
        </Wall>

</pre>

Example: A death zone partially outside the rim
<pre>
        <Zone effect="death">
            <ShapeCircle radius="20">
                <Point x="-15" y="100"/>
            </ShapeCircle>
        </Zone>
        <Wall>
            <Point x="0" y="0" />
            <Point x="200" y="0" />
            <Point x="200" y="200" />
            <Point x="0" y="200" />
            <Point x="0" y="0" />
        </Wall>

</pre>

Nota: It is important to note that while Zones are introduced in
Arthemis, a more complete implementation will follow in
Bacchus. Curious minds consulting the documentation presenting the
Bacchus implementation of Zones will notice that fortress isn't an
effect, but rather a trigger type. The Arthemis implementation of
Zones falsely uses it as an effect instead of exposing a trigger
mechanism. Map designers are to be warned this will no longer be
possible in maps defined for Bacchus.

=== Fortress Zone ===
The fortress Zone is particuliar because it uses a scoring system
to determine if and when the Zone is triggered. The score is
affected by the time passed in it by attackers and defenders.

At start time, the score is set to 0.0. While the score can move
freely, 2 restrictions are always applied. First, the score can
never drop below 0.0. Second, if the score reaches or exceed 1.0,
the Zone is triggered.

Each single adversary in the Zone add to the score for their time
passed in it. Each single defender in the Zone remove to the score
for their time passed in it. Also, the score always decays. Each
of these aspect is controlled by a different setting,
CONQUEST_RATE, DEFEND_RATE and CONQUEST_DECAY_RATE. They all
express a rate in points per seconds.

;CONQUEST_RATE
: Any single attacking player in the Zone add points to the score at this rate. 
;DEFEND_RATE
: Any single defending player in the Zone removes points to the score at this rate. 
;CONQUEST_DECAY_RATE
: The score of a Zone decays at this rate, irrelevantly of the numbers of attackers and defenders in the Zone. 

These 3 settings are global for all the Zones on a map.

Example: Configuring Fortress from the config file
<pre>
CONQUEST_RATE 0.5
DEFEND_RATE 0.3
CONQUEST_DECAY_RATE 0.1
</pre>

Example: Configuring Fortress from the settings in the map
<pre>
        <Settings>
            <Setting name="CONQUEST_RATE" value="0.5"/>
            <Setting name="DEFEND_RATE" value="0.3"/>
            <Setting name="CONQUEST_DECAY_RATE" value="0.1"/>
        </Settings>
</pre>


== Appendices ==

=== Map writing best practice ===

==== Comment your work ====

You should always comment the various parts of your work. Doing so improve maintainability. Something that is obvious during the creation of a particular map often becomes very cryptic after a few weeks. A good comment allow you to quickly grasp the meaning of what is described.

A comment in xml start with "<!--" (without the quotes) and ends with "-->". Comment can spawn on multiple lines. If your editor doesn't highlight the commented part, be careful not to exclude a part of your map by mistake.

==== Arena size ====

The original map is of size 500 by 500. Many servers have setting
that are oriented toward this size, and players are used to battle
in such an environment. 

A map that is significantly larger or smaller will require the
server admin to affect the scale facter to be used with the map to
preserve the gaming experience tailorder to the server. 

Also, arenas with many divisions or made of many interconnecting
rooms might find the efficace play space shrunk. Giving them a bit
more surface might help balance this. 

For example, if rooms are organised in a 3 by 4 pattern, with
corridors connecting them, many of the space between the rooms is
lost. The map designer might try to have a total
surface of for all the rooms that is of 250 000 square game units
(the same surface than a 500 by 500 room). He might feel that
ignoring the surface of the corridors compensate for the large
amount of walls reducing the motion.

On the other hand, one could easily imagine a
extremely large maze. In this instance, the true factor would be
the corridor width rather than the total size of the play area.

There are no hard rules of any sort about the size of an
arena. Experiment and adjust to produce the effect desired, and
the players will most probably appreciate your efforts.

==== Don't overload attributes ====

Certain elements of the map have attributes that are exclusive. For
example, in the Axis element, when the attribute angle is defined, the
xdir and ydir attribute are never queried.

While the engine ignore the exceeding data, this practice has the following drawbacks:

* File size: The exceeding information is never used, but need to be transmitted as part of the file, and stored.
* Readability: Exceeding information complicate the reading of a map by humans. 
* Maintenance: Maintenance of the map is not much more complex. If the author is minimalist, he/she risk updating the part of information that is ignored. Extremely good knowledge of the working of the parser is required to avoid this pitfall, and the change is only valid if the rule of precedences aren't updated. Specifying only one set of information avoid this problem. Also, if both set of information are updated, then the task for the author is double, and so are the risks for error.

=== Resource file name convention ===

Resource are external content that makes the game interesting. Textures, sounds, models and maps are all resources for Armagetron Ad. While at the time of writing of this tutorial, only maps are supported as true resources, soon support for the other types will be added. Also, while this section incorporated in the Maps tutorial, it might be moved as an independent document, and the standard described might be updated in a near future. Please inform yourself.

For ease of administration and to avoid conflicting versions, all resources for Armagetron Ad should follow the following naming convention. 

<pre><AuthorName>/[SubDirectory/]<ResourceName>-<VersionNumber>.<Extension></pre>

;AuthorName
: The name of the person who created the resource. This can be the full name, a nick name (such as the ones used on the Armagetron Ad forum) of the author. Alternatively, the author can forgo his or her name and instead opt for a group name. Group name should be used when the author want to indicate that a set of resources are associate with a group. Instances of this could be when the resources are for a clan, a community, a [set of] server[s].
;SubDirectory
: Prolific authors and those are free to set up any number of sub directories to help them organize and possibly categorize their resources. The Armagetron Ad team recommend you to categorize resources by topics (ie: all the resources required for a particular movie-pack set in the same sub directory) over other categorization, such as categorization by type (ie: all the floor tiles set in the same sub directory). Any number of sub directory level should be supported. This is not a mandatory item.
;ResourceName
: The actual name of the resource. This should be descriptive, and somewhat unique to facilitate identification of the described resource. The advantage of specifying a somewhat unique name here is that should the resource be accidentally moved out of its folder, it is still possible to quickly and easily identify it. A special note for maps: the ResourceName should be the same as the name attribute of the Map element defined in the xml file.
;VersionNumber
: This part should be used by the author to identify which version of the resource is described. During its life, a
resource can receive many modifications and improvements. To find new resources, Armagetron Ad rely solely on this part to be updated. Should a resource be updated and the old name kept, it would cause problems between different clients. Client already having the old resource would not get the modifications, as they would expect the content to
be the same, and only clients that would not have a local copy of file would get the latest version. The actual format to be used for the VersionNumber is left to the choice of the author. While the Armagetron Ad team recommend a VERSION.MAJOR.MINOR dot notation similar to those used for software's versions, any other notation can be
used, such as a simple numeral (GlowStick-1.png, GlowStick-2.png, ...). Keep in mind that it should be obvious to other as to which is the most up to date version of the resource. A special note for maps: the VersionNumber should be the same as the version attribute of the Map element defined in the xml file.

;Extension
: This is the regular type of extension. While Armagetron Ad doesn't verify that the extension describe the right type of content, it is favorable for other users that you set it to the appropriate type, and thus facilitate the usage of your resource.

A few examples:
<pre>
philippeqc/Firewall-0.3.2.png
philippeqc/castle-6.aamap.xml
TigersNetwork/CougarMoviepack/cougar-3.1.aamap.xml
TigersNetwork/CougarMoviepack/PawTrace-floor-2.png
AngelOfMercy-Clan/OfficialCycleMode-2.1.7.ace
AngelOfMercy-Clan/trainingMap-6.aamap.xml
</pre>

=== Resource repository ===

When a player doesn't have the map being used on a server, their game will
automatically download it from the resource repository. To add your completed
maps to the official resource repository, go to:
	http://beta.armagetronad.net/028-link/addmaps


=== Examples ===

==== Parallelogram arena ====

[[Image:Parallelogram-1.0.png|right|thumbnail|Parallelogram]]

<pre>
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map-0.2.8_beta3.dtd">
<Resource type="aamap" name="Parallelogram" version="1.0" author="Philippe Villeneuve" category="example">
<Map version="0.2.8">

<World>
<!-- A variation on the classic arena -->
    <Field>
        <Axes number="4" normalize="false">
            <Axis xdir="1" ydir="0"/>
            <Axis xdir="-0.2" ydir="-1"/>
            <Axis xdir="-1" ydir="0"/>
            <Axis xdir="0.2" ydir="1"/>
	</Axes>

	<Spawn x="265" y="50" xdir="0.2" ydir="1" />
	<Spawn x="335" y="450" xdir="-0.2" ydir="-1" />
	<Spawn x="99" y="245" xdir="1" ydir="0" />
	<Spawn x="501" y="255" xdir="-1" ydir="-0" />

	<Spawn x="325" y="100" xdir="0.2" ydir="1" />
	<Spawn x="275" y="400" xdir="-0.2" ydir="-1" />
	<Spawn x="139" y="195" xdir="1" ydir="0" />
	<Spawn x="461" y="305" xdir="-1" ydir="-0" />

	<Spawn x="225" y="100" xdir="0.2" ydir="1" />
	<Spawn x="375" y="400" xdir="-0.2" ydir="-1" />
	<Spawn x="159" y="295" xdir="1" ydir="0" />
	<Spawn x="441" y="205" xdir="-1" ydir="-0" />

	<Wall>
            <Point x="0" y="0" />
            <Point x="500" y="0" />
            <Point x="600" y="500" />
            <Point x="100" y="500" />
            <Point x="0" y="0" />
	</Wall>
    </Field>
</World>
</Map>
</Resource>
</pre>

==== HexaTRON ====

[[Image:HexaTRON-0.2.png|right|thumbnail|HexaTRON]]

The HexaTRON map has been developed by Luke-Jr for his HexaTRON
mod on the code. It has a hexagonal flower and uses 6
directions. Please note that this is version 0.2 of the map, and
that many newer version have been published.

<pre>
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map-0.2.8_beta3.dtd">
<Resource name="HexaTRON" version="0.2" author="Luke-Jr" category="HexaTRON">

<Map version="0.2.8">
<World>
    <Field>
<!-- This is the Hexa map put in XML. This should work out of the
box, ie: without changes to the aa engine code beside a flashy new
parser. Errors might have been introduced during the conversion to
XML by philippeqc, for your debugging amusement -->

        <Axes number="6"/>
        <Spawn x="99.5" y="73.612159" xdir="-0.5" ydir="0.866"/>
        <Spawn x="-15.5" y="368.0608" xdir="0.5" ydir="-0.866"/>
        <Spawn x="198.333333" y="196.29909" xdir="-1.0" ydir="0"/>
        <Spawn x="-114.333333" y="245.37387" xdir="1" ydir="0"/>
        <Spawn x="141.666666" y="343.52341" xdir="-0.5" ydir="-0.866"/>
        <Spawn x="-57.666666" y="98.149545" xdir="0.5" ydir="0.866"/>
        <Wall>
            <Point x="0" y="0" />
            <Point x="85" y="0" />
            <Point x="127.5" y="73.612159" />
            <Point x="212.5" y="73.612159" />
            <Point x="255" y="147.22432" />
            <Point x="212.5" y="220.83648" />
            <Point x="255" y="294.44864" />
            <Point x="212.5" y="368.0608" />
            <Point x="127.5" y="368.0608" />
            <Point x="85" y="441.67296" />
            <Point x="0" y="441.67296" />
            <Point x="-43.5" y="368.0608" />
            <Point x="-128.5" y="368.0608" />
            <Point x="-170" y="294.44864" />
            <Point x="-128.5" y="220.83648" />
            <Point x="-170" y="147.22432" />
            <Point x="-128.5" y="73.612159" />
            <Point x="-43.5" y="73.612159" />
            <Point x="0" y="0" />
        </Wall>
        <Wall>
            <Point x="127.5" y="73.612159" />
            <Point x="113.333333" y="98.149545" />
        </Wall>
        <Wall>
            <Point x="212.5" y="220.83648" />
            <Point x="184.166666" y="220.83648" />
        </Wall>
        <Wall>
            <Point x="127.5" y="368.0608" />
            <Point x="113.333333" y="343.52341" />
        </Wall>
        <Wall>
            <Point x="-43.5" y="368.0608" />
            <Point x="-29.666666" y="343.52341" />
        </Wall>
        <Wall>
            <Point x="-128.5" y="220.83648" />
            <Point x="-100.833333" y="220.83648" />
        </Wall>
        <Wall>
            <Point x="-43.5" y="73.612159" />
            <Point x="-29.666666" y="98.149545" />
        </Wall>
    </Field>
</World>
</Map>
</Resource>
</pre>

=== About the "undefined and unsupported" ===

Many possible combinations are marked as "undefined and unsupported". While it may be possible to do them now, and even amusing to do it, they are strongly discouraged. Later version of the World format will most probably conflict with those behaviors. This will make such behaviors difficult to preserve, if possible at all. For this reasons, it has been decided that _NO_ effort would be put to maintain them. Use them if you want, but do not come complaining if and when they stop working.