Making Maps by Hand

From Armagetron

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

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 Advanced.

Format overview

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

<?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="75"	xdir="1"	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="0"	y="500"	/>
					<Point	x="500"	y="500"	/>
					<Point	x="500"	y="0"	/>
					<Point	x="0"	y="0"	/>
				</Wall>
			</Field>
		</World>
	</Map>
</Resource>

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).

Skipping 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:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE Resource SYSTEM "AATeam/map-0.2.8.0.dtd">

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".

Note: 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:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map-0.2.8_beta3.dtd">

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 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/her ever placing an open request, a commisioner could be assigned to a map when the author wants 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 his/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 holds an Armagetron Advanced 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 absent.
version
The version of the map described in this particuliar file. This value needs to be modified each time a change is applied to the map to ensure everybody have the proper copy.
author
The current maintainer of this map, usually the author who produced it. This either should be a user name registered with the central resource repository, or, for lone wolves who don't want to register, a valid email address encoded in the spambot safe as "unofficial/mailto/<Domain>/<User>", where "<User>@<Domain>" would be the address.
This field is defaulted to "Anonymous" when absent.
commisioner
The entity who dreamt, requested or inspired this map in any way. 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 "/" (a forward slash). An example could be "category/subcategory/subsubcategory". This field is defaulted to "unsorted" when absent.

Example: The castle map made by philippeqc

<Resource name="Castle" type="aamap" version="1.1" author="philippeqc" category="examples">
    ...
</Resource>

Example: The StarTron ("5ptstar") map made by Your_mom (note that while 'beta' is more or less correct for the 'version' attribute, it should not be in the 'category' as it is here)

<Resource name="5ptstar" version="beta" author="Your_mom" category="beta" type="aamap">
    ...
</Resource>

Example: The MBC training map, made by Zorgul

<Resource name="TrainingDay" version="1.6" author="Zorgul" category="MBC" type="aamap" commisioner="Micro Bus City">
    ...
</Resource>

Example: The Reverso map, writen by Nemosultra based on a drawing by lucifer, for the Crack Pipe server

<Resource name="Reverso" version="1.1-b" author="Nemosultra" category="CrackPipe" type="aamap" commisioner="lucifer">
    ...
</Resource>

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.

A resource has a unique filepath determined by these attributes. The resource must be the only one to ever appear as this filepath and any changes must affect the 'version' and the person making the change must place their name in the 'author' attribute unless given permission by the original author.

The filepath is formed by the attributes in the following syntax:

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

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 indicates a 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

    <Map version="0.2.8">
        ...
    </Map>

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 controls the syntax, what keywords are valid and in what arrangement. The parsing engine has specific rules how to read the syntax and create the game elements. It is possible for different parsing engines to operate from the same syntax, be it because the syntax allows for many interpretations, 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 exists, 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 exists, 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 cases where the order of writing Settings should matter. There are no garanties of this being the case. Be carefull of the order of the Settings provided.

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

The Settings element is inserted in the Map element, before the World element.

<Map ...>
	<Settings>
		...
	</Settings>
	<World>
		...
	</World>
</Map>

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.

	<Setting name="CYCLE_BRAKE_REFILL" value=".1"/>

will assing .1 to the configuration item CYCLE_BRAKE_REFILL.

No validation is done on any 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 Settings 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.

	<World>
            ...
	</World>

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 defines 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 trapazoid arena. A trapazoid has a base lenght of 300, a top length 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, organized 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 supports a single parameter, named logicalBox, which controls 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

            <Field>
                ...
            </Field>

Example: Field with its logical box disabled

            <Field logicalBox="false">
                ...
            </Field>

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

For clarity purposes, 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 defines how the cycles will behave on this particular Field. The original Armagetron used 4 axes.

The Axes element has 2 fields:

number
This specifies the number of axes that should be used. If not specified, 4 axes are assumed.
normalize
When set to true, it specifies 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 direction.

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

The Axis element uses the following fields:

xdir
This is the size of the displacement along the x's for this axis.
ydir
This is the size of the displacement along the y's for this axis.
angle
This allows to describe the Axes 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:

	<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>

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 directions 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 physics 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. Vehicles move along a 2D surface, changing their x and y positions. 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

	<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>

Example: Axes of size 0.5

	<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>

By setting the normalize attribute to false, the designer ensures that the game will use the Axis values as is. While this section has used Axes that all have the same size, this is not a requirement. The next section will explore setting Axis with different sizes. This permits affecting 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 prevents you from defineing 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 though one dimension of the rectangle is 10 times that of the other, traveling along this longer dimension occurs at a much higher rate, compressing this dimension in the player's mind.

Example: Rectangle of equal travel time

	<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>

Example: Rectangle of compressed travel time

	<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>

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.

	<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>

Example: Factor of 6 between displacement, centered around a speed of ~3

	<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>

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

	<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>

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

        <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>

Example: 6 Axis in degrees, in the order 4, 5, 6, 1, 2, 3

        <Axes number="6">
            <Axis angle="210"/>
            <Axis angle="270"/>
            <Axis angle="330"/>
            <Axis angle="30"/>
            <Axis angle="90"/>
            <Axis angle="150"/>
        </Axes>

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

        <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>

Example: 6 Axis in degrees, in the order 4, 6, 5, 1, 3, 2

        <Axes number="6">
            <Axis angle="210"/>
            <Axis angle="330"/>
            <Axis angle="270"/>
            <Axis angle="30"/>
            <Axis angle="150"/>
            <Axis angle="90"/>
        </Axes>

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

        <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>

Wall

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

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

Example: A square Wall of size 200

        <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>

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

        <Wall>
            <Point x="100" y="50" />
            <Point x="100" y="150" />
        </Wall>

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 affects 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. When a height of 0 or less (ie: negative value) is given, an unresonably large value is substitued.

height
The height used for the rendering of the Wall. Positive value only.

Example : Using the client default height

        <Wall>
            <Point x="0" y="0" />
            <Point x="10" y="10" />
        </Wall>

Example : Controling the height

        <Wall height="2.13">
            <Point x="0" y="0" />
            <Point x="10" y="10" />
        </Wall>

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 in degrees.

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 in the map file is only used as a recommendation.

However, for team spawns, the settings SPAWN_WINGMEN_SIDE and SPAWN_WINGMEN_BACK do respect the map's spawn directions for determining the wingmen's spawn positions. This can be used to create asymmetrical team spawn formations.

A Spawn has six attributes. Only three or 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

Zones 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

        <Zone effect="death">
            ...
        </Zone>

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 ShapeCircle 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 created, 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

        <Zone effect="death">
            <ShapeCircle radius="20" growth="0.17">
                ...
            </ShapeCircle>
        </Zone>

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

        <Zone effect="death">
            <ShapeCircle radius="20">
                <Point x="120" y="86"/>
            </ShapeCircle>
        </Zone>

Example: A growing fortress zone

        <Zone effect="fortress">
            <ShapeCircle radius="20" growth="1.09">
                <Point x="250" y="7"/>
            </ShapeCircle>
        </Zone>

Example: A shrinking win zone

        <Zone effect="death">
            <ShapeCircle radius="200" growth="-0.2">
                <Point x="440" y="325"/>
            </ShapeCircle>
        </Zone>

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

        <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>

Example: A death zone partially outside the rim

        <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>

Note: 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

CONQUEST_RATE 0.5
DEFEND_RATE 0.3
CONQUEST_DECAY_RATE 0.1

Example: Configuring Fortress from the settings in the map

        <Settings>
            <Setting name="CONQUEST_RATE" value="0.5"/>
            <Setting name="DEFEND_RATE" value="0.3"/>
            <Setting name="CONQUEST_DECAY_RATE" value="0.1"/>
        </Settings>


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 starts with "<!--" (without the quotes) and ends with "-->". Comments can span 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 risks 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 sets of information are updated, then the task for the author is double, and so are the risks for error.

Resource Filename Convention

Resources are external content that makes the game interesting. Textures, sounds, models and maps are all resources for Armagetron Advanced. 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.

For ease of administration, and to avoid conflicting versions all resources for Armagetron Advanced should adhere to the following naming convention:

<AuthorName>/[SubDirectory/]<ResourceName>-<VersionNumber>.<Extension>
AuthorName
The name of the person who currently maintains the resource; it needs to match the author attribute of the Resource element described above and either be a forum nickname on forums.armagetronad.net, a user name registered at the central resource repository, or an email address encoded as unofficial/mailto/<Domain>@<User>.
Alternatively, the author can forgo his or her name and instead opt for a group-name. The 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, or a set of servers.
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 Advanced team recommends that 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 levels 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 Advanced relys solely on this part to be updated. Should a resource be updated and the old name kept, it would cause problems between different clients. Clients still 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 Advanced team recommends a VERSION.MAJOR.MINOR dot notation similar to those used for software 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 Advanced 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:

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

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: Resource repository

Examples

Parallelogram arena

Parallelogram
<?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>

HexaTRON

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.

<?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>

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.