Armagetron Advanced - User contributions [en]

Zones v2

2007-06-21T16:49:38Z

Philippeqc: Acceleration instead of speed

== Preamble ==

You will note that the examples below dont sound that fun. I'd like to think its because my creative power went into building a good system, and now there is little left to put on examples. But I'm sure you will find interesting ways to use the mechanisms in here. My goal with this was to be able to have zones that could have different effect depending on who would use them. For example, having a fortress that team Blue could conquer, but only 2 of the players of team Red could actually defend. The other Red could still circle it and block the enemy, but they could not lower its value actively. Everything described here works. There are still glitches small and not so small. The code is in my private branch, but feel free to grab a local copy if you want to play with it.

The format is anything but closed. I'd like to hear your opinion on it too (yes it is a PITA to write, but if you have a constructive remark about that, I'd like to know it)

-ph

Most of this is from a forum post by philippeqc. I reworded some stuff and formatted a bit for the wiki. Some stuff might have gotten lost or reworded wrongly so cross refrence with the post if the wording gets hazy and/or just to double check @ http://forums.armagetronad.net/viewtopic.php?p=77491#77491. Some stuff might be in the wrong place. --[[User:Your mom|Your mom]] 11:42, 30 July 2006 (CDT)

== Zone element ==

Individual zones may have a name. Entering a name is optional, and re-using a name will be considered to mean "add/override with the following information". Dont rely on this behavior for anything, in other words '''Dont re-use the same name.''' All zones need a shape defined. At the moment only one shape exists, the ShapeCircle. More shapes are planned in the future and are ToDo

Ex:
<Zone name="redFortress">
<ShapeCircle radius="29">
<Point x="50" y="50"/>
<Color red="0.988" green="0.059" blue="0.753" />
</ShapeCircle>

</Zone>

== Rules and EffectGroups ==

A zone can have up to 4 different "rules" (need better name ToDo). Enter, Inside, Leave, Outside. It classifies when the held elements should be inspected. Inside each of the "rules", one can define EffectGroups. EffectGroup(s) are the fundamental building blocks of this new system. It associate owners with consequences. Note that ownership is part of effectGroup(s), ''NOT'' the zone. So a zone may have multiple effectGroup(s), each with unique or interlapping owners. There are 2 types of owners: owner (individuals) and ownerTeam (every member of a team). It is possible to define 0,1 or many for each items.

''HACK:
ATM, only owner is supported, and it must be an exact match with a
player's name to associated the effect.
The real solution will translate the labels used to players based on
some other logic depending on "game type". This is to be defined
later.''

''HACK:
It should be possible to associate individual with teams in some part
of the map. In this text, I will user lowercase color name + number for
individual, and uppercase color name for teams. So the individual
red1, red7 and red90210 should be considered as players of the team
RED. I will also allow myself to insert _description_ in names to help
the reader when appropriate.''

Ex:
<pre><Zone name="redFortress">
<ShapeCircle ...>
...
</ShapeCircle>
<Enter>
<EffectGroup owner="red1,red2" ownerTeam="BLUE,YELLOW">
...
</EffectGroup>
<EffectGroup owner="" ownerTeam="RED">
...
</EffectGroup>
</Enter>
<Leave>
<EffectGroup owner="green7" ownerTeam="">
...
</EffectGroup>
</Leave>
</Zone></pre>

== User element ==

Inside the EffectGroup, elements User are set. This element offers different readily made rules to determine if a player in the "rule" condition for the zone, is allowed to be considered a user. This is decided based from the following information: owner, ownerTeam and the player matching the rule. Two other conditions can be set for a player to be considered a valid user: positive and marked. These element are of type Triad. The possible values are true, false and ignore. We will come back to these later. If the current player is found to be valid, the processing will continue to the child elements. Otherwise, nothing happens. A valid user will be called triggerer from now on.

The following users are currently implemented:
* all: Anybody can be considered a valid user,
* owner: only a player direcly in the owner list can be considered a valid user,
* ownerTeam: only a player member of a team mentionned in the ownerTeam list can be considered a valid user,
* allButOwner only a player NOT mentioned in the owner list can be considered a valid user,
* allButTeamOwner only a player NOT member of a team mentioned in the ownerTeam list can be considered a valid user, (TO COME, NOT IMPLEMENTED YET)
* anotherTeammate only a player in the same team as one of the individual owner can be considered a valid user (TO COME, NOT IMPLEMENTED YET)

Ex:
<pre><EffectGroup owner="red1,red2" ownerTeam="BLUE,YELLOW">
<User user="all" >
... 
</User>
<User user="allButOwner" >
... 
</User>
</EffectGroup>
<EffectGroup owner="" ownerTeam="RED">
<User user="owner" >
... 
</User>
<User user="ownerTeam" >
... 
</User>
</EffectGroup></pre>

Inside a User element, it is possible to make use of 3 different
elements. Target, ZoneInfluence and MonitorInfluence.

=== Target ===

The Target element will take the information of the valid user, and
calculate who will receive the effect of the zone. Depending on the
described target rule to use and the state of the game, the calculated
target can be from no players to everybody in game.

The currently implemented target rules are :

*self : the triggerer himself
*teammate : a randomly selected teammate of the triggerer
*team : all the member of the team of the triggerer
*all : everybody in the game
*allButSelf : everybody in the game BUT the triggerer
*another : a randomly selected player that is not the triggerer
*ownerTeamTeammate : a randomly selected player member of one of the teams mentioned in the teamOwner list.
*owner : all the players owning the effectGroup
*ownerteam : all the players member of the team owning the effectGroup
*ownerteamteammate : a single player member from a owning team
*anydead : any single dead player
*alldead : all the dead players
*singledeadowner : one of the owners that is dead
*anotherteammatedead : a single player member of the team of the triggerer that is dead
*anothernotteammatedead : a single player that is not member of the team of the triggerer and that is dead
<nowiki>
*Much more are detailed in a document named zones.txt hidden somewhere
on the forum.</nowiki>

Once the targets are selected, they all are applied all the effects
described under the Target element.

Nota: In a User element, it is possible to user any amount of Target,
ZoneInfluence and MonitorInfluence.

Ex:
<pre><User user="ownerTeam" >
<Target target="self">
... 
</Target>
<Target target="another">
... 
</Target>
</User></pre>

== Effect ==

The Effect element hold specific effects. The attribute count can limit the number of times a specific effect can be used. By default, the count is unlimited.

valid effect currently implemented are:
*win : win the round
*death : kill the target(s)
*point : give points to the target(s)
*spawnplayer : Respawns target(s)
*brakerecharge : Refills target(s) cycle brake (planned)
*rubberrecharge : Refills target(s) cycle rubber (planned)
*acceleration: Accelerate the target(s) by this rate,
*teleport: Instantly move target(s) to a random location (planned)
*setting : has 2 attributes ; settingName & settingValue

new attribute for all effects: description
Acceleration uses the rate stored in the attribute named value.

When the effect is triggered, the message is displayed on the console. Somehow I'm not able to do the "parsing" similar to when points are given (player x received y points because he is sooo leet). That should come.

When point is use, an attribute score will mention the amount of point
to give.

<pre><Target target="self">
<Effect effect="point" score="3" count="2">
... 
</Effect>
<Effect ...>
...
</Effect>
</Target></pre>

ex:
<pre><Effect effect="acceleration" value="20.0" /></pre>
Would make the target accelerate drastically.

<pre><Effect effect="setting" settingName="cycle_speed" settingValue="100" /></pre>
Would change the base speed for all the players.

A reminder about manipulating settings from the map: This mechanism is quite raw and powerful. Use it with care. Not everything is manipulable during a round, nor make sense to manipulate. Reap the benefit but respect the limitations. Consider yourself warned.
=== ZoneInfluence ===

Inside the User element, the element ZoneInfluence and MonitorInfluence are use to affect back game element. ZoneInfluence allows to affect a zone in play. The name attribute must match exactly a zone's name elsewhere in the map.

The possible thing to affect on a zone are:
*Rotation with attribute rotationAngle and rotationSpeed
*Radius with attribute radius
*Point with attribute x and y

Ex:
<pre><User user="all">
<ZoneInfluence name="redFortress">
<Rotation rotationAngle="0.3" rotationSpeed="0.5" />
<Radius radius="50"/>
<Point x="100" y="100" />
</ZoneInfluence>
<ZoneInfluence name="blueFortress">
<Radius radius="-1" />
</ZoneInfluence>
</User></pre>

=== MonitorInfluence ===

Monitors are simple valiables that can be affected by interaction with different zones. The old "fortress" zone is to be considered as a zone where being inside slowly influence its monitor. Monitors are to be inserted in the map at the same level as Zone. Monitor have a name that is used to refer to from the MonitorInfluence, a initial value, and a drift, that slowly move the value, low and high, which clamp the monitor's value between their owns.

<pre><Field>
...
<Monitor name="monitorFortressRed" init="0.2" drift="-0.1" low="0.0" high="1.0">
... 
</Monitor>
...
</Field></pre>

The Monitor as different rules that can be used to inspect and react on its value. They are OnOver, OnUnder, InRange and OutsideRange. Any amount of rules can be used in a monitor.

*OnOver has an attribute named value and will be used when the monitor's value exceed it,
*OnUnder has an attribute named value and will be used when the monitor's value is under it,
*InRange has attributes low and high and will be used when the monitor's value fall between both
*OutRange has attributes low and high and will be used when the monitor's value is not falling between both

The monitors' rules are similar to the zone's rule in that they hold EffectGroups that are inspected when the rule conditions are met.

What differs a Monitor from a zone regarding to EffectGroup is who are considered players to be inspected as users. Anyone who contributed to a monitor during a game time step is registered, along with if the contribution was positive (conquering) or negative (defending), and if they where marked. This information is passed along up to the User element. There it can be used on additional tests to determine a valid user.

<pre><Monitor name="monitorFortressRed" init="0.2" drift="-0.1" low="0.0" high="1.0">
<OnOver value="1.0">
<EffectGroup ...>
<User user="..." positive="true" marked="ignore">
... 
</User>
<User ...>
...
</User>
</EffectGroup>
</OnOver>
</Monitor></pre>

==== User ====

The User element always have these attributes, but outside of an EffectGroup from a Monitor, this is always ignored.

MonitorInfluence element is the one where one describe how to affect a monitor. It has an attribute name to point to the monitor to influence. It has a marked attribute which is a Triad, ie: allows for the value true, false or ignore. Players using this MonitorInfluence will carry this mark into their contribution to the monitor.

There are 3 ways to influence the value of a monitor:
*1 the attribute influenceSlide will affect the monitor's value in a fashion proportional to the time passed in the zone. This is how the classical fortress operates. This is the same as saying influenceSlide * duration of the current game time step.
*2 the attribute influenceAdd will affect the monitor's value by this amount. This is NOT affected by time.
*3 the attribute influenceSet will set the monitor's value immediatly to this value.

These can of course be used simulteanously. It is important here that
attributes that are not desired should not be defined, rather than
defined at a default value.

Ex:
<pre><User ...>
...
<MonitorInfluence name="monitorFortressRed" marked="true" influenceSlide="0.5"/>

<MonitorInfluence name="monitorFortressGreen" marked="true" influenceAdd="2"/>

<MonitorInfluence name="monitorFortressBlue" influenceSet="0.0" />

</User></pre>

== Quiz ==
Respond on the forums after reading through this entire page with any ideas or questions of your own.(Optional)

1 Are you able to express some new ideas with it?

2 Do you see items that could be added, either now or as a later
version that could improve its value?

3 Anything else?

-ph

== Examples ==
An example might help you get through the mess of the description

Its blue vs red Each team has zones in opposing corners which are interconnected. As they get conquered, they jump toward the center.

For your convenience:
MAP_FILE philippeqc/zone/DoubleZoneJumping-1.aamap.xml

Code:
<pre><?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map-0.3.1-a.dtd">
<Resource type="aamap" name="DoubleZoneJumping" version="1" author="philippeqc" category="zone">


<pre> <Map version="2">

<World>
<Field>
<Spawn x="50" y="245" xdir="1" ydir="0" />
<Spawn x="450" y="255" 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>
<Zone name="zRed1">
<ShapeCircle radius="49" red="1.0" green="0.1" blue="0.1">
<Point x="50" y="50"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="-0.25" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="0.5" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Zone name="zRed2">
<ShapeCircle radius="49" red="1.0" green="0.1" blue="0.1">
<Point x="450" y="450"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="-0.25" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="0.5" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Monitor name="mRed" init="0.0" drift="-0.1" >
<InRange low="0.0" high="0.30">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="100" y="100"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="400" y="400"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.4" high="0.60">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="150" y="150"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="350" y="350"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.7" high="1.0">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="200" y="200"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="300" y="300"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<OnOver value="1">
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<Target target="self">
<Effect effect="point" count="2" score="7"/>
</Target>
<ZoneInfluence name="zRed1">
<Radius radius="-1" />
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Radius radius="-1" />
</ZoneInfluence>
</User>
</EffectGroup>
</OnOver>
</Monitor>



<Zone name="zBlue1">
<ShapeCircle radius="49" red="0.10" green="0.10" blue="1.0">
<Point x="50" y="450"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="0.3" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="-0.3" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Zone name="zBlue2">
<ShapeCircle radius="49" red="0.10" green="0.10" blue="1.0">
<Point x="450" y="50"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="0.3" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="-0.3" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Monitor name="mBlue" init="0.0" drift="-0.1" >
<InRange low="0.0" high="0.30">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="100" y="400"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="400" y="100"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.4" high="0.60">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="150" y="350"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="350" y="150"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.7" high="1.0">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="200" y="300"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="300" y="200"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<OnOver value="1">
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<Target target="self">
<Effect effect="point" count="2" score="7"/>
</Target>
<ZoneInfluence name="zBlue1">
<Radius radius="-1" />
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Radius radius="-1" />
</ZoneInfluence>
</User>
</EffectGroup>
</OnOver>
</Monitor>

</Field>
</World>
</Map>
</Resource></pre>

Ex:
Code:

<pre><Zone name="redFortress">
<ShapeCircle radius="29" red="0.988" green="0.059" blue="0.753"/>
<Point x="50" y="50"/>
</ShapeCircle>
...
</Zone></pre>

is now

Code:
<pre><Zone name="redFortress">
<ShapeCircle radius="29" >
<Color red="0.988" green="0.059" blue="0.753" alpha="0.0"/>
<Point x="50" y="50"/>
</ShapeCircle>
...
</Zone></pre>

Also added Color as a child of ZoneInfluence:
Code:
<pre> <ZoneInfluence name="blueFortress">
<Radius radius="-1" />
<Color red="0.988" green="0.059" blue="0.753" alpha="0.0"/>
</ZoneInfluence></pre>

This map has 4 zones that activate one another. Only one should be present, and when not there, they are put outside of the arena. They are activated in a crossed fashion.

Code:
<pre><?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map.dtd">
<Resource type="aamap" name="zone" version="d" author="philippeqc" category="">

<Map version="2">

<World>
<Field>
<Spawn x="50" y="245" xdir="1" ydir="0" />
<Spawn x="450" y="255" 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>

<Zone name="SW">
<ShapeCircle radius="29" >
<Point x="50" y="50"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="SW">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="NE">
<Point x="450" y="450"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="NE">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="NE">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="NW">
<Point x="50" y="450"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="NW">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="NW">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="SE">
<Point x="450" y="50"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="SE">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="SE">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="SW">
<Point x="50" y="50"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>
</Field>
</World>
</Map>
</Resource></pre>

Its a really crude idea, that has been retaken in a much better way by wrt. But it show some things that can be done (influencing individual zones, and using ZoneInfluence from one zone to affect another).

Targets have a count:
Code:
The target has an attribute count that will limit the number of time
it is called. Not having the attribute or setting it to -1 means infinite.

-ph

Zones v2

2007-06-21T16:47:07Z

Philippeqc: Acceleration instead of speed

== Preamble ==

You will note that the examples below dont sound that fun. I'd like to think its because my creative power went into building a good system, and now there is little left to put on examples. But I'm sure you will find interesting ways to use the mechanisms in here. My goal with this was to be able to have zones that could have different effect depending on who would use them. For example, having a fortress that team Blue could conquer, but only 2 of the players of team Red could actually defend. The other Red could still circle it and block the enemy, but they could not lower its value actively. Everything described here works. There are still glitches small and not so small. The code is in my private branch, but feel free to grab a local copy if you want to play with it.

The format is anything but closed. I'd like to hear your opinion on it too (yes it is a PITA to write, but if you have a constructive remark about that, I'd like to know it)

-ph

Most of this is from a forum post by philippeqc. I reworded some stuff and formatted a bit for the wiki. Some stuff might have gotten lost or reworded wrongly so cross refrence with the post if the wording gets hazy and/or just to double check @ http://forums.armagetronad.net/viewtopic.php?p=77491#77491. Some stuff might be in the wrong place. --[[User:Your mom|Your mom]] 11:42, 30 July 2006 (CDT)

== Zone element ==

Individual zones may have a name. Entering a name is optional, and re-using a name will be considered to mean "add/override with the following information". Dont rely on this behavior for anything, in other words '''Dont re-use the same name.''' All zones need a shape defined. At the moment only one shape exists, the ShapeCircle. More shapes are planned in the future and are ToDo

Ex:
<Zone name="redFortress">
<ShapeCircle radius="29">
<Point x="50" y="50"/>
<Color red="0.988" green="0.059" blue="0.753" />
</ShapeCircle>

</Zone>

== Rules and EffectGroups ==

A zone can have up to 4 different "rules" (need better name ToDo). Enter, Inside, Leave, Outside. It classifies when the held elements should be inspected. Inside each of the "rules", one can define EffectGroups. EffectGroup(s) are the fundamental building blocks of this new system. It associate owners with consequences. Note that ownership is part of effectGroup(s), ''NOT'' the zone. So a zone may have multiple effectGroup(s), each with unique or interlapping owners. There are 2 types of owners: owner (individuals) and ownerTeam (every member of a team). It is possible to define 0,1 or many for each items.

''HACK:
ATM, only owner is supported, and it must be an exact match with a
player's name to associated the effect.
The real solution will translate the labels used to players based on
some other logic depending on "game type". This is to be defined
later.''

''HACK:
It should be possible to associate individual with teams in some part
of the map. In this text, I will user lowercase color name + number for
individual, and uppercase color name for teams. So the individual
red1, red7 and red90210 should be considered as players of the team
RED. I will also allow myself to insert _description_ in names to help
the reader when appropriate.''

Ex:
<pre><Zone name="redFortress">
<ShapeCircle ...>
...
</ShapeCircle>
<Enter>
<EffectGroup owner="red1,red2" ownerTeam="BLUE,YELLOW">
...
</EffectGroup>
<EffectGroup owner="" ownerTeam="RED">
...
</EffectGroup>
</Enter>
<Leave>
<EffectGroup owner="green7" ownerTeam="">
...
</EffectGroup>
</Leave>
</Zone></pre>

== User element ==

Inside the EffectGroup, elements User are set. This element offers different readily made rules to determine if a player in the "rule" condition for the zone, is allowed to be considered a user. This is decided based from the following information: owner, ownerTeam and the player matching the rule. Two other conditions can be set for a player to be considered a valid user: positive and marked. These element are of type Triad. The possible values are true, false and ignore. We will come back to these later. If the current player is found to be valid, the processing will continue to the child elements. Otherwise, nothing happens. A valid user will be called triggerer from now on.

The following users are currently implemented:
* all: Anybody can be considered a valid user,
* owner: only a player direcly in the owner list can be considered a valid user,
* ownerTeam: only a player member of a team mentionned in the ownerTeam list can be considered a valid user,
* allButOwner only a player NOT mentioned in the owner list can be considered a valid user,
* allButTeamOwner only a player NOT member of a team mentioned in the ownerTeam list can be considered a valid user, (TO COME, NOT IMPLEMENTED YET)
* anotherTeammate only a player in the same team as one of the individual owner can be considered a valid user (TO COME, NOT IMPLEMENTED YET)

Ex:
<pre><EffectGroup owner="red1,red2" ownerTeam="BLUE,YELLOW">
<User user="all" >
... 
</User>
<User user="allButOwner" >
... 
</User>
</EffectGroup>
<EffectGroup owner="" ownerTeam="RED">
<User user="owner" >
... 
</User>
<User user="ownerTeam" >
... 
</User>
</EffectGroup></pre>

Inside a User element, it is possible to make use of 3 different
elements. Target, ZoneInfluence and MonitorInfluence.

=== Target ===

The Target element will take the information of the valid user, and
calculate who will receive the effect of the zone. Depending on the
described target rule to use and the state of the game, the calculated
target can be from no players to everybody in game.

The currently implemented target rules are :

*self : the triggerer himself
*teammate : a randomly selected teammate of the triggerer
*team : all the member of the team of the triggerer
*all : everybody in the game
*allButSelf : everybody in the game BUT the triggerer
*another : a randomly selected player that is not the triggerer
*ownerTeamTeammate : a randomly selected player member of one of the teams mentioned in the teamOwner list.
*owner : all the players owning the effectGroup
*ownerteam : all the players member of the team owning the effectGroup
*ownerteamteammate : a single player member from a owning team
*anydead : any single dead player
*alldead : all the dead players
*singledeadowner : one of the owners that is dead
*anotherteammatedead : a single player member of the team of the triggerer that is dead
*anothernotteammatedead : a single player that is not member of the team of the triggerer and that is dead
<nowiki>
*Much more are detailed in a document named zones.txt hidden somewhere
on the forum.</nowiki>

Once the targets are selected, they all are applied all the effects
described under the Target element.

Nota: In a User element, it is possible to user any amount of Target,
ZoneInfluence and MonitorInfluence.

Ex:
<pre><User user="ownerTeam" >
<Target target="self">
... 
</Target>
<Target target="another">
... 
</Target>
</User></pre>

== Effect ==

The Effect element hold specific effects. The attribute count can limit the number of times a specific effect can be used. By default, the count is unlimited.

valid effect currently implemented are:
*win : win the round
*death : kill the target(s)
*point : give points to the target(s)
*spawnplayer : Respawns target(s)
*brakerecharge : Refills target(s) cycle brake (planned)
*rubberrecharge : Refills target(s) cycle rubber (planned)
*acceleration: Accelerate the target(s) by this rate,
*teleport: Instantly move target(s) to a random location (planned)
*setting : has 2 attributes ; settingName & settingValue

new attribute for all effects: description

When the effect is triggered, the message is displayed on the console. Somehow I'm not able to do the "parsing" similar to when points are given (player x received y points because he is sooo leet). That should come.

When point is use, an attribute score will mention the amount of point
to give.

<pre><Target target="self">
<Effect effect="point" score="3" count="2">
... 
</Effect>
<Effect ...>
...
</Effect>
</Target></pre>

ex:
<pre><Effect effect="setting" settingName="cycle_speed" settingValue="100" /></pre>
Would change the base speed for all the players.

A reminder about manipulating settings from the map: This mechanism is quite raw and powerful. Use it with care. Not everything is manipulable during a round, nor make sense to manipulate. Reap the benefit but respect the limitations. Consider yourself warned.
=== ZoneInfluence ===

Inside the User element, the element ZoneInfluence and MonitorInfluence are use to affect back game element. ZoneInfluence allows to affect a zone in play. The name attribute must match exactly a zone's name elsewhere in the map.

The possible thing to affect on a zone are:
*Rotation with attribute rotationAngle and rotationSpeed
*Radius with attribute radius
*Point with attribute x and y

Ex:
<pre><User user="all">
<ZoneInfluence name="redFortress">
<Rotation rotationAngle="0.3" rotationSpeed="0.5" />
<Radius radius="50"/>
<Point x="100" y="100" />
</ZoneInfluence>
<ZoneInfluence name="blueFortress">
<Radius radius="-1" />
</ZoneInfluence>
</User></pre>

=== MonitorInfluence ===

Monitors are simple valiables that can be affected by interaction with different zones. The old "fortress" zone is to be considered as a zone where being inside slowly influence its monitor. Monitors are to be inserted in the map at the same level as Zone. Monitor have a name that is used to refer to from the MonitorInfluence, a initial value, and a drift, that slowly move the value, low and high, which clamp the monitor's value between their owns.

<pre><Field>
...
<Monitor name="monitorFortressRed" init="0.2" drift="-0.1" low="0.0" high="1.0">
... 
</Monitor>
...
</Field></pre>

The Monitor as different rules that can be used to inspect and react on its value. They are OnOver, OnUnder, InRange and OutsideRange. Any amount of rules can be used in a monitor.

*OnOver has an attribute named value and will be used when the monitor's value exceed it,
*OnUnder has an attribute named value and will be used when the monitor's value is under it,
*InRange has attributes low and high and will be used when the monitor's value fall between both
*OutRange has attributes low and high and will be used when the monitor's value is not falling between both

The monitors' rules are similar to the zone's rule in that they hold EffectGroups that are inspected when the rule conditions are met.

What differs a Monitor from a zone regarding to EffectGroup is who are considered players to be inspected as users. Anyone who contributed to a monitor during a game time step is registered, along with if the contribution was positive (conquering) or negative (defending), and if they where marked. This information is passed along up to the User element. There it can be used on additional tests to determine a valid user.

<pre><Monitor name="monitorFortressRed" init="0.2" drift="-0.1" low="0.0" high="1.0">
<OnOver value="1.0">
<EffectGroup ...>
<User user="..." positive="true" marked="ignore">
... 
</User>
<User ...>
...
</User>
</EffectGroup>
</OnOver>
</Monitor></pre>

==== User ====

The User element always have these attributes, but outside of an EffectGroup from a Monitor, this is always ignored.

MonitorInfluence element is the one where one describe how to affect a monitor. It has an attribute name to point to the monitor to influence. It has a marked attribute which is a Triad, ie: allows for the value true, false or ignore. Players using this MonitorInfluence will carry this mark into their contribution to the monitor.

There are 3 ways to influence the value of a monitor:
*1 the attribute influenceSlide will affect the monitor's value in a fashion proportional to the time passed in the zone. This is how the classical fortress operates. This is the same as saying influenceSlide * duration of the current game time step.
*2 the attribute influenceAdd will affect the monitor's value by this amount. This is NOT affected by time.
*3 the attribute influenceSet will set the monitor's value immediatly to this value.

These can of course be used simulteanously. It is important here that
attributes that are not desired should not be defined, rather than
defined at a default value.

Ex:
<pre><User ...>
...
<MonitorInfluence name="monitorFortressRed" marked="true" influenceSlide="0.5"/>

<MonitorInfluence name="monitorFortressGreen" marked="true" influenceAdd="2"/>

<MonitorInfluence name="monitorFortressBlue" influenceSet="0.0" />

</User></pre>

== Quiz ==
Respond on the forums after reading through this entire page with any ideas or questions of your own.(Optional)

1 Are you able to express some new ideas with it?

2 Do you see items that could be added, either now or as a later
version that could improve its value?

3 Anything else?

-ph

== Examples ==
An example might help you get through the mess of the description

Its blue vs red Each team has zones in opposing corners which are interconnected. As they get conquered, they jump toward the center.

For your convenience:
MAP_FILE philippeqc/zone/DoubleZoneJumping-1.aamap.xml

Code:
<pre><?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map-0.3.1-a.dtd">
<Resource type="aamap" name="DoubleZoneJumping" version="1" author="philippeqc" category="zone">


<pre> <Map version="2">

<World>
<Field>
<Spawn x="50" y="245" xdir="1" ydir="0" />
<Spawn x="450" y="255" 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>
<Zone name="zRed1">
<ShapeCircle radius="49" red="1.0" green="0.1" blue="0.1">
<Point x="50" y="50"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="-0.25" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="0.5" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Zone name="zRed2">
<ShapeCircle radius="49" red="1.0" green="0.1" blue="0.1">
<Point x="450" y="450"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="-0.25" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="0.5" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Monitor name="mRed" init="0.0" drift="-0.1" >
<InRange low="0.0" high="0.30">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="100" y="100"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="400" y="400"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.4" high="0.60">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="150" y="150"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="350" y="350"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.7" high="1.0">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="200" y="200"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="300" y="300"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<OnOver value="1">
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<Target target="self">
<Effect effect="point" count="2" score="7"/>
</Target>
<ZoneInfluence name="zRed1">
<Radius radius="-1" />
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Radius radius="-1" />
</ZoneInfluence>
</User>
</EffectGroup>
</OnOver>
</Monitor>



<Zone name="zBlue1">
<ShapeCircle radius="49" red="0.10" green="0.10" blue="1.0">
<Point x="50" y="450"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="0.3" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="-0.3" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Zone name="zBlue2">
<ShapeCircle radius="49" red="0.10" green="0.10" blue="1.0">
<Point x="450" y="50"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="0.3" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="-0.3" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Monitor name="mBlue" init="0.0" drift="-0.1" >
<InRange low="0.0" high="0.30">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="100" y="400"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="400" y="100"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.4" high="0.60">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="150" y="350"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="350" y="150"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.7" high="1.0">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="200" y="300"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="300" y="200"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<OnOver value="1">
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<Target target="self">
<Effect effect="point" count="2" score="7"/>
</Target>
<ZoneInfluence name="zBlue1">
<Radius radius="-1" />
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Radius radius="-1" />
</ZoneInfluence>
</User>
</EffectGroup>
</OnOver>
</Monitor>

</Field>
</World>
</Map>
</Resource></pre>

Ex:
Code:

<pre><Zone name="redFortress">
<ShapeCircle radius="29" red="0.988" green="0.059" blue="0.753"/>
<Point x="50" y="50"/>
</ShapeCircle>
...
</Zone></pre>

is now

Code:
<pre><Zone name="redFortress">
<ShapeCircle radius="29" >
<Color red="0.988" green="0.059" blue="0.753" alpha="0.0"/>
<Point x="50" y="50"/>
</ShapeCircle>
...
</Zone></pre>

Also added Color as a child of ZoneInfluence:
Code:
<pre> <ZoneInfluence name="blueFortress">
<Radius radius="-1" />
<Color red="0.988" green="0.059" blue="0.753" alpha="0.0"/>
</ZoneInfluence></pre>

This map has 4 zones that activate one another. Only one should be present, and when not there, they are put outside of the arena. They are activated in a crossed fashion.

Code:
<pre><?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map.dtd">
<Resource type="aamap" name="zone" version="d" author="philippeqc" category="">

<Map version="2">

<World>
<Field>
<Spawn x="50" y="245" xdir="1" ydir="0" />
<Spawn x="450" y="255" 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>

<Zone name="SW">
<ShapeCircle radius="29" >
<Point x="50" y="50"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="SW">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="NE">
<Point x="450" y="450"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="NE">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="NE">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="NW">
<Point x="50" y="450"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="NW">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="NW">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="SE">
<Point x="450" y="50"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="SE">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="SE">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="SW">
<Point x="50" y="50"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>
</Field>
</World>
</Map>
</Resource></pre>

Its a really crude idea, that has been retaken in a much better way by wrt. But it show some things that can be done (influencing individual zones, and using ZoneInfluence from one zone to affect another).

Targets have a count:
Code:
The target has an attribute count that will limit the number of time
it is called. Not having the attribute or setting it to -1 means infinite.

-ph

Zones v2

2007-06-08T21:27:20Z

Philippeqc: Updated the attribute for the start-up angle and speed of rotation

== Preamble ==

You will note that the examples below dont sound that fun. I'd like to think its because my creative power went into building a good system, and now there is little left to put on examples. But I'm sure you will find interesting ways to use the mechanisms in here. My goal with this was to be able to have zones that could have different effect depending on who would use them. For example, having a fortress that team Blue could conquer, but only 2 of the players of team Red could actually defend. The other Red could still circle it and block the enemy, but they could not lower its value actively. Everything described here works. There are still glitches small and not so small. The code is in my private branch, but feel free to grab a local copy if you want to play with it.

The format is anything but closed. I'd like to hear your opinion on it too (yes it is a PITA to write, but if you have a constructive remark about that, I'd like to know it)

-ph

Most of this is from a forum post by philippeqc. I reworded some stuff and formatted a bit for the wiki. Some stuff might have gotten lost or reworded wrongly so cross refrence with the post if the wording gets hazy and/or just to double check @ http://forums.armagetronad.net/viewtopic.php?p=77491#77491. Some stuff might be in the wrong place. --[[User:Your mom|Your mom]] 11:42, 30 July 2006 (CDT)

== Zone element ==

Individual zones may have a name. Entering a name is optional, and re-using a name will be considered to mean "add/override with the following information". Dont rely on this behavior for anything, in other words '''Dont re-use the same name.''' All zones need a shape defined. At the moment only one shape exists, the ShapeCircle. More shapes are planned in the future and are ToDo

Ex:
<Zone name="redFortress">
<ShapeCircle radius="29">
<Point x="50" y="50"/>
<Color red="0.988" green="0.059" blue="0.753" />
</ShapeCircle>

</Zone>

== Rules and EffectGroups ==

A zone can have up to 4 different "rules" (need better name ToDo). Enter, Inside, Leave, Outside. It classifies when the held elements should be inspected. Inside each of the "rules", one can define EffectGroups. EffectGroup(s) are the fundamental building blocks of this new system. It associate owners with consequences. Note that ownership is part of effectGroup(s), ''NOT'' the zone. So a zone may have multiple effectGroup(s), each with unique or interlapping owners. There are 2 types of owners: owner (individuals) and ownerTeam (every member of a team). It is possible to define 0,1 or many for each items.

''HACK:
ATM, only owner is supported, and it must be an exact match with a
player's name to associated the effect.
The real solution will translate the labels used to players based on
some other logic depending on "game type". This is to be defined
later.''

''HACK:
It should be possible to associate individual with teams in some part
of the map. In this text, I will user lowercase color name + number for
individual, and uppercase color name for teams. So the individual
red1, red7 and red90210 should be considered as players of the team
RED. I will also allow myself to insert _description_ in names to help
the reader when appropriate.''

Ex:
<pre><Zone name="redFortress">
<ShapeCircle ...>
...
</ShapeCircle>
<Enter>
<EffectGroup owner="red1,red2" ownerTeam="BLUE,YELLOW">
...
</EffectGroup>
<EffectGroup owner="" ownerTeam="RED">
...
</EffectGroup>
</Enter>
<Leave>
<EffectGroup owner="green7" ownerTeam="">
...
</EffectGroup>
</Leave>
</Zone></pre>

== User element ==

Inside the EffectGroup, elements User are set. This element offers different readily made rules to determine if a player in the "rule" condition for the zone, is allowed to be considered a user. This is decided based from the following information: owner, ownerTeam and the player matching the rule. Two other conditions can be set for a player to be considered a valid user: positive and marked. These element are of type Triad. The possible values are true, false and ignore. We will come back to these later. If the current player is found to be valid, the processing will continue to the child elements. Otherwise, nothing happens. A valid user will be called triggerer from now on.

The following users are currently implemented:
* all: Anybody can be considered a valid user,
* owner: only a player direcly in the owner list can be considered a valid user,
* ownerTeam: only a player member of a team mentionned in the ownerTeam list can be considered a valid user,
* allButOwner only a player NOT mentioned in the owner list can be considered a valid user,
* allButTeamOwner only a player NOT member of a team mentioned in the ownerTeam list can be considered a valid user, (TO COME, NOT IMPLEMENTED YET)
* anotherTeammate only a player in the same team as one of the individual owner can be considered a valid user (TO COME, NOT IMPLEMENTED YET)

Ex:
<pre><EffectGroup owner="red1,red2" ownerTeam="BLUE,YELLOW">
<User user="all" >
... 
</User>
<User user="allButOwner" >
... 
</User>
</EffectGroup>
<EffectGroup owner="" ownerTeam="RED">
<User user="owner" >
... 
</User>
<User user="ownerTeam" >
... 
</User>
</EffectGroup></pre>

Inside a User element, it is possible to make use of 3 different
elements. Target, ZoneInfluence and MonitorInfluence.

=== Target ===

The Target element will take the information of the valid user, and
calculate who will receive the effect of the zone. Depending on the
described target rule to use and the state of the game, the calculated
target can be from no players to everybody in game.

The currently implemented target rules are :

*self : the triggerer himself
*teammate : a randomly selected teammate of the triggerer
*team : all the member of the team of the triggerer
*all : everybody in the game
*allButSelf : everybody in the game BUT the triggerer
*another : a randomly selected player that is not the triggerer
*ownerTeamTeammate : a randomly selected player member of one of the teams mentioned in the teamOwner list.
*owner : all the players owning the effectGroup
*ownerteam : all the players member of the team owning the effectGroup
*ownerteamteammate : a single player member from a owning team
*anydead : any single dead player
*alldead : all the dead players
*singledeadowner : one of the owners that is dead
*anotherteammatedead : a single player member of the team of the triggerer that is dead
*anothernotteammatedead : a single player that is not member of the team of the triggerer and that is dead
<nowiki>
*Much more are detailed in a document named zones.txt hidden somewhere
on the forum.</nowiki>

Once the targets are selected, they all are applied all the effects
described under the Target element.

Nota: In a User element, it is possible to user any amount of Target,
ZoneInfluence and MonitorInfluence.

Ex:
<pre><User user="ownerTeam" >
<Target target="self">
... 
</Target>
<Target target="another">
... 
</Target>
</User></pre>

== Effect ==

The Effect element hold specific effects. The attribute count can limit the number of times a specific effect can be used. By default, the count is unlimited.

valid effect currently implemented are:
*win : win the round
*death : kill the target(s)
*point : give points to the target(s)
*spawnplayer : Respawns target(s)
*brakerecharge : Refills target(s) cycle brake
*rubberrecharge : Refills target(s) cycle rubber
*setting : has 2 attributes ; settingName & settingValue

new attribute for all effects: description

When the effect is triggered, the message is displayed on the console. Somehow I'm not able to do the "parsing" similar to when points are given (player x received y points because he is sooo leet). That should come.

When point is use, an attribute score will mention the amount of point
to give.

<pre><Target target="self">
<Effect effect="point" score="3" count="2">
... 
</Effect>
<Effect ...>
...
</Effect>
</Target></pre>

ex:
<pre><Effect effect="setting" settingName="cycle_speed" settingValue="100" /></pre>

=== ZoneInfluence ===

Inside the User element, the element ZoneInfluence and MonitorInfluence are use to affect back game element. ZoneInfluence allows to affect a zone in play. The name attribute must match exactly a zone's name elsewhere in the map.

The possible thing to affect on a zone are:
*Rotation with attribute rotationAngle and rotationSpeed
*Radius with attribute radius
*Point with attribute x and y

Ex:
<pre><User user="all">
<ZoneInfluence name="redFortress">
<Rotation rotationAngle="0.3" rotationSpeed="0.5" />
<Radius radius="50"/>
<Point x="100" y="100" />
</ZoneInfluence>
<ZoneInfluence name="blueFortress">
<Radius radius="-1" />
</ZoneInfluence>
</User></pre>

=== MonitorInfluence ===

Monitors are simple valiables that can be affected by interaction with different zones. The old "fortress" zone is to be considered as a zone where being inside slowly influence its monitor. Monitors are to be inserted in the map at the same level as Zone. Monitor have a name that is used to refer to from the MonitorInfluence, a initial value, and a drift, that slowly move the value, low and high, which clamp the monitor's value between their owns.

<pre><Field>
...
<Monitor name="monitorFortressRed" init="0.2" drift="-0.1" low="0.0" high="1.0">
... 
</Monitor>
...
</Field></pre>

The Monitor as different rules that can be used to inspect and react on its value. They are OnOver, OnUnder, InRange and OutsideRange. Any amount of rules can be used in a monitor.

*OnOver has an attribute named value and will be used when the monitor's value exceed it,
*OnUnder has an attribute named value and will be used when the monitor's value is under it,
*InRange has attributes low and high and will be used when the monitor's value fall between both
*OutRange has attributes low and high and will be used when the monitor's value is not falling between both

The monitors' rules are similar to the zone's rule in that they hold EffectGroups that are inspected when the rule conditions are met.

What differs a Monitor from a zone regarding to EffectGroup is who are considered players to be inspected as users. Anyone who contributed to a monitor during a game time step is registered, along with if the contribution was positive (conquering) or negative (defending), and if they where marked. This information is passed along up to the User element. There it can be used on additional tests to determine a valid user.

<pre><Monitor name="monitorFortressRed" init="0.2" drift="-0.1" low="0.0" high="1.0">
<OnOver value="1.0">
<EffectGroup ...>
<User user="..." positive="true" marked="ignore">
... 
</User>
<User ...>
...
</User>
</EffectGroup>
</OnOver>
</Monitor></pre>

==== User ====

The User element always have these attributes, but outside of an EffectGroup from a Monitor, this is always ignored.

MonitorInfluence element is the one where one describe how to affect a monitor. It has an attribute name to point to the monitor to influence. It has a marked attribute which is a Triad, ie: allows for the value true, false or ignore. Players using this MonitorInfluence will carry this mark into their contribution to the monitor.

There are 3 ways to influence the value of a monitor:
*1 the attribute influenceSlide will affect the monitor's value in a fashion proportional to the time passed in the zone. This is how the classical fortress operates. This is the same as saying influenceSlide * duration of the current game time step.
*2 the attribute influenceAdd will affect the monitor's value by this amount. This is NOT affected by time.
*3 the attribute influenceSet will set the monitor's value immediatly to this value.

These can of course be used simulteanously. It is important here that
attributes that are not desired should not be defined, rather than
defined at a default value.

Ex:
<pre><User ...>
...
<MonitorInfluence name="monitorFortressRed" marked="true" influenceSlide="0.5"/>

<MonitorInfluence name="monitorFortressGreen" marked="true" influenceAdd="2"/>

<MonitorInfluence name="monitorFortressBlue" influenceSet="0.0" />

</User></pre>

== Quiz ==
Respond on the forums after reading through this entire page with any ideas or questions of your own.(Optional)

1 Are you able to express some new ideas with it?

2 Do you see items that could be added, either now or as a later
version that could improve its value?

3 Anything else?

-ph

== Examples ==
An example might help you get through the mess of the description

Its blue vs red Each team has zones in opposing corners which are interconnected. As they get conquered, they jump toward the center.

For your convenience:
MAP_FILE philippeqc/zone/DoubleZoneJumping-1.aamap.xml

Code:
<pre><?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map-0.3.1-a.dtd">
<Resource type="aamap" name="DoubleZoneJumping" version="1" author="philippeqc" category="zone">


<pre> <Map version="2">

<World>
<Field>
<Spawn x="50" y="245" xdir="1" ydir="0" />
<Spawn x="450" y="255" 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>
<Zone name="zRed1">
<ShapeCircle radius="49" red="1.0" green="0.1" blue="0.1">
<Point x="50" y="50"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="-0.25" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="0.5" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Zone name="zRed2">
<ShapeCircle radius="49" red="1.0" green="0.1" blue="0.1">
<Point x="450" y="450"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="-0.25" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="0.5" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Monitor name="mRed" init="0.0" drift="-0.1" >
<InRange low="0.0" high="0.30">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="100" y="100"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="400" y="400"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.4" high="0.60">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="150" y="150"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="350" y="350"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.7" high="1.0">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="200" y="200"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="300" y="300"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<OnOver value="1">
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<Target target="self">
<Effect effect="point" count="2" score="7"/>
</Target>
<ZoneInfluence name="zRed1">
<Radius radius="-1" />
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Radius radius="-1" />
</ZoneInfluence>
</User>
</EffectGroup>
</OnOver>
</Monitor>



<Zone name="zBlue1">
<ShapeCircle radius="49" red="0.10" green="0.10" blue="1.0">
<Point x="50" y="450"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="0.3" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="-0.3" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Zone name="zBlue2">
<ShapeCircle radius="49" red="0.10" green="0.10" blue="1.0">
<Point x="450" y="50"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="0.3" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="-0.3" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Monitor name="mBlue" init="0.0" drift="-0.1" >
<InRange low="0.0" high="0.30">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="100" y="400"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="400" y="100"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.4" high="0.60">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="150" y="350"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="350" y="150"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.7" high="1.0">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="200" y="300"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="300" y="200"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<OnOver value="1">
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<Target target="self">
<Effect effect="point" count="2" score="7"/>
</Target>
<ZoneInfluence name="zBlue1">
<Radius radius="-1" />
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Radius radius="-1" />
</ZoneInfluence>
</User>
</EffectGroup>
</OnOver>
</Monitor>

</Field>
</World>
</Map>
</Resource></pre>

Ex:
Code:

<pre><Zone name="redFortress">
<ShapeCircle radius="29" red="0.988" green="0.059" blue="0.753"/>
<Point x="50" y="50"/>
</ShapeCircle>
...
</Zone></pre>

is now

Code:
<pre><Zone name="redFortress">
<ShapeCircle radius="29" >
<Color red="0.988" green="0.059" blue="0.753" alpha="0.0"/>
<Point x="50" y="50"/>
</ShapeCircle>
...
</Zone></pre>

Also added Color as a child of ZoneInfluence:
Code:
<pre> <ZoneInfluence name="blueFortress">
<Radius radius="-1" />
<Color red="0.988" green="0.059" blue="0.753" alpha="0.0"/>
</ZoneInfluence></pre>

This map has 4 zones that activate one another. Only one should be present, and when not there, they are put outside of the arena. They are activated in a crossed fashion.

Code:
<pre><?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map.dtd">
<Resource type="aamap" name="zone" version="d" author="philippeqc" category="">

<Map version="2">

<World>
<Field>
<Spawn x="50" y="245" xdir="1" ydir="0" />
<Spawn x="450" y="255" 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>

<Zone name="SW">
<ShapeCircle radius="29" >
<Point x="50" y="50"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="SW">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="NE">
<Point x="450" y="450"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="NE">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="NE">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="NW">
<Point x="50" y="450"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="NW">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="NW">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="SE">
<Point x="450" y="50"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="SE">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="SE">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="SW">
<Point x="50" y="50"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>
</Field>
</World>
</Map>
</Resource></pre>

Its a really crude idea, that has been retaken in a much better way by wrt. But it show some things that can be done (influencing individual zones, and using ZoneInfluence from one zone to affect another).

Targets have a count:
Code:
The target has an attribute count that will limit the number of time
it is called. Not having the attribute or setting it to -1 means infinite.

-ph

Zones v2

2007-06-08T16:12:45Z

Philippeqc: Changed attribute name

== Preamble ==

You will note that the examples below dont sound that fun. I'd like to think its because my creative power went into building a good system, and now there is little left to put on examples. But I'm sure you will find interesting ways to use the mechanisms in here. My goal with this was to be able to have zones that could have different effect depending on who would use them. For example, having a fortress that team Blue could conquer, but only 2 of the players of team Red could actually defend. The other Red could still circle it and block the enemy, but they could not lower its value actively. Everything described here works. There are still glitches small and not so small. The code is in my private branch, but feel free to grab a local copy if you want to play with it.

The format is anything but closed. I'd like to hear your opinion on it too (yes it is a PITA to write, but if you have a constructive remark about that, I'd like to know it)

-ph

Most of this is from a forum post by philippeqc. I reworded some stuff and formatted a bit for the wiki. Some stuff might have gotten lost or reworded wrongly so cross refrence with the post if the wording gets hazy and/or just to double check @ http://forums.armagetronad.net/viewtopic.php?p=77491#77491. Some stuff might be in the wrong place. --[[User:Your mom|Your mom]] 11:42, 30 July 2006 (CDT)

== Zone element ==

Individual zones may have a name. Entering a name is optional, and re-using a name will be considered to mean "add/override with the following information". Dont rely on this behavior for anything, in other words '''Dont re-use the same name.''' All zones need a shape defined. At the moment only one shape exists, the ShapeCircle. More shapes are planned in the future and are ToDo

Ex:
<Zone name="redFortress">
<ShapeCircle radius="29">
<Point x="50" y="50"/>
<Color red="0.988" green="0.059" blue="0.753" />
</ShapeCircle>

</Zone>

== Rules and EffectGroups ==

A zone can have up to 4 different "rules" (need better name ToDo). Enter, Inside, Leave, Outside. It classifies when the held elements should be inspected. Inside each of the "rules", one can define EffectGroups. EffectGroup(s) are the fundamental building blocks of this new system. It associate owners with consequences. Note that ownership is part of effectGroup(s), ''NOT'' the zone. So a zone may have multiple effectGroup(s), each with unique or interlapping owners. There are 2 types of owners: owner (individuals) and ownerTeam (every member of a team). It is possible to define 0,1 or many for each items.

''HACK:
ATM, only owner is supported, and it must be an exact match with a
player's name to associated the effect.
The real solution will translate the labels used to players based on
some other logic depending on "game type". This is to be defined
later.''

''HACK:
It should be possible to associate individual with teams in some part
of the map. In this text, I will user lowercase color name + number for
individual, and uppercase color name for teams. So the individual
red1, red7 and red90210 should be considered as players of the team
RED. I will also allow myself to insert _description_ in names to help
the reader when appropriate.''

Ex:
<pre><Zone name="redFortress">
<ShapeCircle ...>
...
</ShapeCircle>
<Enter>
<EffectGroup owner="red1,red2" ownerTeam="BLUE,YELLOW">
...
</EffectGroup>
<EffectGroup owner="" ownerTeam="RED">
...
</EffectGroup>
</Enter>
<Leave>
<EffectGroup owner="green7" ownerTeam="">
...
</EffectGroup>
</Leave>
</Zone></pre>

== User element ==

Inside the EffectGroup, elements User are set. This element offers different readily made rules to determine if a player in the "rule" condition for the zone, is allowed to be considered a user. This is decided based from the following information: owner, ownerTeam and the player matching the rule. Two other conditions can be set for a player to be considered a valid user: positive and marked. These element are of type Triad. The possible values are true, false and ignore. We will come back to these later. If the current player is found to be valid, the processing will continue to the child elements. Otherwise, nothing happens. A valid user will be called triggerer from now on.

The following users are currently implemented:
* all: Anybody can be considered a valid user,
* owner: only a player direcly in the owner list can be considered a valid user,
* ownerTeam: only a player member of a team mentionned in the ownerTeam list can be considered a valid user,
* allButOwner only a player NOT mentioned in the owner list can be considered a valid user,
* allButTeamOwner only a player NOT member of a team mentioned in the ownerTeam list can be considered a valid user, (TO COME, NOT IMPLEMENTED YET)
* anotherTeammate only a player in the same team as one of the individual owner can be considered a valid user (TO COME, NOT IMPLEMENTED YET)

Ex:
<pre><EffectGroup owner="red1,red2" ownerTeam="BLUE,YELLOW">
<User user="all" >
... 
</User>
<User user="allButOwner" >
... 
</User>
</EffectGroup>
<EffectGroup owner="" ownerTeam="RED">
<User user="owner" >
... 
</User>
<User user="ownerTeam" >
... 
</User>
</EffectGroup></pre>

Inside a User element, it is possible to make use of 3 different
elements. Target, ZoneInfluence and MonitorInfluence.

=== Target ===

The Target element will take the information of the valid user, and
calculate who will receive the effect of the zone. Depending on the
described target rule to use and the state of the game, the calculated
target can be from no players to everybody in game.

The currently implemented target rules are :

*self : the triggerer himself
*teammate : a randomly selected teammate of the triggerer
*team : all the member of the team of the triggerer
*all : everybody in the game
*allButSelf : everybody in the game BUT the triggerer
*another : a randomly selected player that is not the triggerer
*ownerTeamTeammate : a randomly selected player member of one of the teams mentioned in the teamOwner list.
*owner : all the players owning the effectGroup
*ownerteam : all the players member of the team owning the effectGroup
*ownerteamteammate : a single player member from a owning team
*anydead : any single dead player
*alldead : all the dead players
*singledeadowner : one of the owners that is dead
*anotherteammatedead : a single player member of the team of the triggerer that is dead
*anothernotteammatedead : a single player that is not member of the team of the triggerer and that is dead
<nowiki>
*Much more are detailed in a document named zones.txt hidden somewhere
on the forum.</nowiki>

Once the targets are selected, they all are applied all the effects
described under the Target element.

Nota: In a User element, it is possible to user any amount of Target,
ZoneInfluence and MonitorInfluence.

Ex:
<pre><User user="ownerTeam" >
<Target target="self">
... 
</Target>
<Target target="another">
... 
</Target>
</User></pre>

== Effect ==

The Effect element hold specific effects. The attribute count can limit the number of times a specific effect can be used. By default, the count is unlimited.

valid effect currently implemented are:
*win : win the round
*death : kill the target(s)
*point : give points to the target(s)
*spawnplayer : Respawns target(s)
*brakerecharge : Refills target(s) cycle brake
*rubberrecharge : Refills target(s) cycle rubber
*setting : has 2 attributes ; settingName & settingValue

new attribute for all effects: description

When the effect is triggered, the message is displayed on the console. Somehow I'm not able to do the "parsing" similar to when points are given (player x received y points because he is sooo leet). That should come.

When point is use, an attribute score will mention the amount of point
to give.

<pre><Target target="self">
<Effect effect="point" score="3" count="2">
... 
</Effect>
<Effect ...>
...
</Effect>
</Target></pre>

ex:
<pre><Effect effect="setting" settingName="cycle_speed" settingValue="100" /></pre>

=== ZoneInfluence ===

Inside the User element, the element ZoneInfluence and MonitorInfluence are use to affect back game element. ZoneInfluence allows to affect a zone in play. The name attribute must match exactly a zone's name elsewhere in the map.

The possible thing to affect on a zone are:
*Rotation with attribute rotationBaseAngle, rotationValueAngle, rotationBaseSpeed and rotationValueSpeed
*Radius with attribute radius
*Point with attribute x and y

Ex:
<pre><User user="all">
<ZoneInfluence name="redFortress">
<Rotation rotationBaseSpeed="0.3" rotationValueSpeed="0.5" />
<Radius radius="50"/>
<Point x="100" y="100" />
</ZoneInfluence>
<ZoneInfluence name="blueFortress">
<Radius radius="-1" />
</ZoneInfluence>
</User></pre>

=== MonitorInfluence ===

Monitors are simple valiables that can be affected by interaction with different zones. The old "fortress" zone is to be considered as a zone where being inside slowly influence its monitor. Monitors are to be inserted in the map at the same level as Zone. Monitor have a name that is used to refer to from the MonitorInfluence, a initial value, and a drift, that slowly move the value, low and high, which clamp the monitor's value between their owns.

<pre><Field>
...
<Monitor name="monitorFortressRed" init="0.2" drift="-0.1" low="0.0" high="1.0">
... 
</Monitor>
...
</Field></pre>

The Monitor as different rules that can be used to inspect and react on its value. They are OnOver, OnUnder, InRange and OutsideRange. Any amount of rules can be used in a monitor.

*OnOver has an attribute named value and will be used when the monitor's value exceed it,
*OnUnder has an attribute named value and will be used when the monitor's value is under it,
*InRange has attributes low and high and will be used when the monitor's value fall between both
*OutRange has attributes low and high and will be used when the monitor's value is not falling between both

The monitors' rules are similar to the zone's rule in that they hold EffectGroups that are inspected when the rule conditions are met.

What differs a Monitor from a zone regarding to EffectGroup is who are considered players to be inspected as users. Anyone who contributed to a monitor during a game time step is registered, along with if the contribution was positive (conquering) or negative (defending), and if they where marked. This information is passed along up to the User element. There it can be used on additional tests to determine a valid user.

<pre><Monitor name="monitorFortressRed" init="0.2" drift="-0.1" low="0.0" high="1.0">
<OnOver value="1.0">
<EffectGroup ...>
<User user="..." positive="true" marked="ignore">
... 
</User>
<User ...>
...
</User>
</EffectGroup>
</OnOver>
</Monitor></pre>

==== User ====

The User element always have these attributes, but outside of an EffectGroup from a Monitor, this is always ignored.

MonitorInfluence element is the one where one describe how to affect a monitor. It has an attribute name to point to the monitor to influence. It has a marked attribute which is a Triad, ie: allows for the value true, false or ignore. Players using this MonitorInfluence will carry this mark into their contribution to the monitor.

There are 3 ways to influence the value of a monitor:
*1 the attribute influenceSlide will affect the monitor's value in a fashion proportional to the time passed in the zone. This is how the classical fortress operates. This is the same as saying influenceSlide * duration of the current game time step.
*2 the attribute influenceAdd will affect the monitor's value by this amount. This is NOT affected by time.
*3 the attribute influenceSet will set the monitor's value immediatly to this value.

These can of course be used simulteanously. It is important here that
attributes that are not desired should not be defined, rather than
defined at a default value.

Ex:
<pre><User ...>
...
<MonitorInfluence name="monitorFortressRed" marked="true" influenceSlide="0.5"/>

<MonitorInfluence name="monitorFortressGreen" marked="true" influenceAdd="2"/>

<MonitorInfluence name="monitorFortressBlue" influenceSet="0.0" />

</User></pre>

== Quiz ==
Respond on the forums after reading through this entire page with any ideas or questions of your own.(Optional)

1 Are you able to express some new ideas with it?

2 Do you see items that could be added, either now or as a later
version that could improve its value?

3 Anything else?

-ph

== Examples ==
An example might help you get through the mess of the description

Its blue vs red Each team has zones in opposing corners which are interconnected. As they get conquered, they jump toward the center.

For your convenience:
MAP_FILE philippeqc/zone/DoubleZoneJumping-1.aamap.xml

Code:
<pre><?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map-0.3.1-a.dtd">
<Resource type="aamap" name="DoubleZoneJumping" version="1" author="philippeqc" category="zone">


<pre> <Map version="2">

<World>
<Field>
<Spawn x="50" y="245" xdir="1" ydir="0" />
<Spawn x="450" y="255" 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>
<Zone name="zRed1">
<ShapeCircle radius="49" red="1.0" green="0.1" blue="0.1">
<Point x="50" y="50"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="-0.25" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="0.5" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Zone name="zRed2">
<ShapeCircle radius="49" red="1.0" green="0.1" blue="0.1">
<Point x="450" y="450"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="-0.25" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="0.5" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Monitor name="mRed" init="0.0" drift="-0.1" >
<InRange low="0.0" high="0.30">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="100" y="100"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="400" y="400"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.4" high="0.60">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="150" y="150"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="350" y="350"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.7" high="1.0">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="200" y="200"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="300" y="300"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<OnOver value="1">
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<Target target="self">
<Effect effect="point" count="2" score="7"/>
</Target>
<ZoneInfluence name="zRed1">
<Radius radius="-1" />
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Radius radius="-1" />
</ZoneInfluence>
</User>
</EffectGroup>
</OnOver>
</Monitor>



<Zone name="zBlue1">
<ShapeCircle radius="49" red="0.10" green="0.10" blue="1.0">
<Point x="50" y="450"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="0.3" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="-0.3" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Zone name="zBlue2">
<ShapeCircle radius="49" red="0.10" green="0.10" blue="1.0">
<Point x="450" y="50"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="0.3" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="-0.3" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Monitor name="mBlue" init="0.0" drift="-0.1" >
<InRange low="0.0" high="0.30">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="100" y="400"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="400" y="100"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.4" high="0.60">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="150" y="350"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="350" y="150"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.7" high="1.0">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="200" y="300"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="300" y="200"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<OnOver value="1">
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<Target target="self">
<Effect effect="point" count="2" score="7"/>
</Target>
<ZoneInfluence name="zBlue1">
<Radius radius="-1" />
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Radius radius="-1" />
</ZoneInfluence>
</User>
</EffectGroup>
</OnOver>
</Monitor>

</Field>
</World>
</Map>
</Resource></pre>

Ex:
Code:

<pre><Zone name="redFortress">
<ShapeCircle radius="29" red="0.988" green="0.059" blue="0.753"/>
<Point x="50" y="50"/>
</ShapeCircle>
...
</Zone></pre>

is now

Code:
<pre><Zone name="redFortress">
<ShapeCircle radius="29" >
<Color red="0.988" green="0.059" blue="0.753" alpha="0.0"/>
<Point x="50" y="50"/>
</ShapeCircle>
...
</Zone></pre>

Also added Color as a child of ZoneInfluence:
Code:
<pre> <ZoneInfluence name="blueFortress">
<Radius radius="-1" />
<Color red="0.988" green="0.059" blue="0.753" alpha="0.0"/>
</ZoneInfluence></pre>

This map has 4 zones that activate one another. Only one should be present, and when not there, they are put outside of the arena. They are activated in a crossed fashion.

Code:
<pre><?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map.dtd">
<Resource type="aamap" name="zone" version="d" author="philippeqc" category="">

<Map version="2">

<World>
<Field>
<Spawn x="50" y="245" xdir="1" ydir="0" />
<Spawn x="450" y="255" 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>

<Zone name="SW">
<ShapeCircle radius="29" >
<Point x="50" y="50"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="SW">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="NE">
<Point x="450" y="450"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="NE">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="NE">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="NW">
<Point x="50" y="450"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="NW">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="NW">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="SE">
<Point x="450" y="50"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="SE">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="SE">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="SW">
<Point x="50" y="50"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>
</Field>
</World>
</Map>
</Resource></pre>

Its a really crude idea, that has been retaken in a much better way by wrt. But it show some things that can be done (influencing individual zones, and using ZoneInfluence from one zone to affect another).

Targets have a count:
Code:
The target has an attribute count that will limit the number of time
it is called. Not having the attribute or setting it to -1 means infinite.

-ph

Zones v2

2007-06-06T12:22:37Z

Philippeqc: /* ZoneInfluence */

== Preamble ==

You will note that the examples below dont sound that fun. I'd like to think its because my creative power went into building a good system, and now there is little left to put on examples. But I'm sure you will find interesting ways to use the mechanisms in here. My goal with this was to be able to have zones that could have different effect depending on who would use them. For example, having a fortress that team Blue could conquer, but only 2 of the players of team Red could actually defend. The other Red could still circle it and block the enemy, but they could not lower its value actively. Everything described here works. There are still glitches small and not so small. The code is in my private branch, but feel free to grab a local copy if you want to play with it.

The format is anything but closed. I'd like to hear your opinion on it too (yes it is a PITA to write, but if you have a constructive remark about that, I'd like to know it)

-ph

Most of this is from a forum post by philippeqc. I reworded some stuff and formatted a bit for the wiki. Some stuff might have gotten lost or reworded wrongly so cross refrence with the post if the wording gets hazy and/or just to double check @ http://forums.armagetronad.net/viewtopic.php?p=77491#77491. Some stuff might be in the wrong place. --[[User:Your mom|Your mom]] 11:42, 30 July 2006 (CDT)

== Zone element ==

Individual zones may have a name. Entering a name is optional, and re-using a name will be considered to mean "add/override with the following information". Dont rely on this behavior for anything, in other words '''Dont re-use the same name.''' All zones need a shape defined. At the moment only one shape exists, the ShapeCircle. More shapes are planned in the future and are ToDo

Ex:
<Zone name="redFortress">
<ShapeCircle radius="29">
<Point x="50" y="50"/>
<Color red="0.988" green="0.059" blue="0.753" />
</ShapeCircle>

</Zone>

== Rules and EffectGroups ==

A zone can have up to 4 different "rules" (need better name ToDo). Enter, Inside, Leave, Outside. It classifies when the held elements should be inspected. Inside each of the "rules", one can define EffectGroups. EffectGroup(s) are the fundamental building blocks of this new system. It associate owners with consequences. Note that ownership is part of effectGroup(s), ''NOT'' the zone. So a zone may have multiple effectGroup(s), each with unique or interlapping owners. There are 2 types of owners: owner (individuals) and ownerTeam (every member of a team). It is possible to define 0,1 or many for each items.

''HACK:
ATM, only owner is supported, and it must be an exact match with a
player's name to associated the effect.
The real solution will translate the labels used to players based on
some other logic depending on "game type". This is to be defined
later.''

''HACK:
It should be possible to associate individual with teams in some part
of the map. In this text, I will user lowercase color name + number for
individual, and uppercase color name for teams. So the individual
red1, red7 and red90210 should be considered as players of the team
RED. I will also allow myself to insert _description_ in names to help
the reader when appropriate.''

Ex:
<pre><Zone name="redFortress">
<ShapeCircle ...>
...
</ShapeCircle>
<Enter>
<EffectGroup owner="red1,red2" ownerTeam="BLUE,YELLOW">
...
</EffectGroup>
<EffectGroup owner="" ownerTeam="RED">
...
</EffectGroup>
</Enter>
<Leave>
<EffectGroup owner="green7" ownerTeam="">
...
</EffectGroup>
</Leave>
</Zone></pre>

== User element ==

Inside the EffectGroup, elements User are set. This element offers different readily made rules to determine if a player in the "rule" condition for the zone, is allowed to be considered a user. This is decided based from the following information: owner, ownerTeam and the player matching the rule. Two other conditions can be set for a player to be considered a valid user: positive and marked. These element are of type Triad. The possible values are true, false and ignore. We will come back to these later. If the current player is found to be valid, the processing will continue to the child elements. Otherwise, nothing happens. A valid user will be called triggerer from now on.

The following users are currently implemented:
* all: Anybody can be considered a valid user,
* owner: only a player direcly in the owner list can be considered a valid user,
* ownerTeam: only a player member of a team mentionned in the ownerTeam list can be considered a valid user,
* allButOwner only a player NOT mentioned in the owner list can be considered a valid user,
* allButTeamOwner only a player NOT member of a team mentioned in the ownerTeam list can be considered a valid user, (TO COME, NOT IMPLEMENTED YET)
* anotherTeammate only a player in the same team as one of the individual owner can be considered a valid user (TO COME, NOT IMPLEMENTED YET)

Ex:
<pre><EffectGroup owner="red1,red2" ownerTeam="BLUE,YELLOW">
<User user="all" >
... 
</User>
<User user="allButOwner" >
... 
</User>
</EffectGroup>
<EffectGroup owner="" ownerTeam="RED">
<User user="owner" >
... 
</User>
<User user="ownerTeam" >
... 
</User>
</EffectGroup></pre>

Inside a User element, it is possible to make use of 3 different
elements. Target, ZoneInfluence and MonitorInfluence.

=== Target ===

The Target element will take the information of the valid user, and
calculate who will receive the effect of the zone. Depending on the
described target rule to use and the state of the game, the calculated
target can be from no players to everybody in game.

The currently implemented target rules are :

*self : the triggerer himself
*teammate : a randomly selected teammate of the triggerer
*team : all the member of the team of the triggerer
*all : everybody in the game
*allButSelf : everybody in the game BUT the triggerer
*another : a randomly selected player that is not the triggerer
*ownerTeamTeammate : a randomly selected player member of one of the teams mentioned in the teamOwner list.
*owner : all the players owning the effectGroup
*ownerteam : all the players member of the team owning the effectGroup
*ownerteamteammate : a single player member from a owning team
*anydead : any single dead player
*alldead : all the dead players
*singledeadowner : one of the owners that is dead
*anotherteammatedead : a single player member of the team of the triggerer that is dead
*anothernotteammatedead : a single player that is not member of the team of the triggerer and that is dead
<nowiki>
*Much more are detailed in a document named zones.txt hidden somewhere
on the forum.</nowiki>

Once the targets are selected, they all are applied all the effects
described under the Target element.

Nota: In a User element, it is possible to user any amount of Target,
ZoneInfluence and MonitorInfluence.

Ex:
<pre><User user="ownerTeam" >
<Target target="self">
... 
</Target>
<Target target="another">
... 
</Target>
</User></pre>

== Effect ==

The Effect element hold specific effects. The attribute count can limit the number of times a specific effect can be used. By default, the count is unlimited.

valid effect currently implemented are:
*win : win the round
*death : kill the target(s)
*point : give points to the target(s)
*respawnplayer : Respawns target(s)
*brakerecharge : Refills target(s) cycle brake
*rubberrecharge : Refills target(s) cycle rubber
*setting : has 2 attributes ; settingName & settingValue

new attribute for all effects: description

When the effect is triggered, the message is displayed on the console. Somehow I'm not able to do the "parsing" similar to when points are given (player x received y points because he is sooo leet). That should come.

When point is use, an attribute score will mention the amount of point
to give.

<pre><Target target="self">
<Effect effect="point" score="3" count="2">
... 
</Effect>
<Effect ...>
...
</Effect>
</Target></pre>

ex:
<pre><Effect effect="setting" settingName="cycle_speed" settingValue="100" /></pre>

=== ZoneInfluence ===

Inside the User element, the element ZoneInfluence and MonitorInfluence are use to affect back game element. ZoneInfluence allows to affect a zone in play. The name attribute must match exactly a zone's name elsewhere in the map.

The possible thing to affect on a zone are:
*Rotation with attribute rotationBaseAngle, rotationValueAngle, rotationBaseSpeed and rotationValueSpeed
*Radius with attribute radius
*Point with attribute x and y

Ex:
<pre><User user="all">
<ZoneInfluence name="redFortress">
<Rotation rotationBaseSpeed="0.3" rotationValueSpeed="0.5" />
<Radius radius="50"/>
<Point x="100" y="100" />
</ZoneInfluence>
<ZoneInfluence name="blueFortress">
<Radius radius="-1" />
</ZoneInfluence>
</User></pre>

=== MonitorInfluence ===

Monitors are simple valiables that can be affected by interaction with different zones. The old "fortress" zone is to be considered as a zone where being inside slowly influence its monitor. Monitors are to be inserted in the map at the same level as Zone. Monitor have a name that is used to refer to from the MonitorInfluence, a initial value, and a drift, that slowly move the value, low and high, which clamp the monitor's value between their owns.

<pre><Field>
...
<Monitor name="monitorFortressRed" init="0.2" drift="-0.1" low="0.0" high="1.0">
... 
</Monitor>
...
</Field></pre>

The Monitor as different rules that can be used to inspect and react on its value. They are OnOver, OnUnder, InRange and OutsideRange. Any amount of rules can be used in a monitor.

*OnOver has an attribute named value and will be used when the monitor's value exceed it,
*OnUnder has an attribute named value and will be used when the monitor's value is under it,
*InRange has attributes low and high and will be used when the monitor's value fall between both
*OutRange has attributes low and high and will be used when the monitor's value is not falling between both

The monitors' rules are similar to the zone's rule in that they hold EffectGroups that are inspected when the rule conditions are met.

What differs a Monitor from a zone regarding to EffectGroup is who are considered players to be inspected as users. Anyone who contributed to a monitor during a game time step is registered, along with if the contribution was positive (conquering) or negative (defending), and if they where marked. This information is passed along up to the User element. There it can be used on additional tests to determine a valid user.

<pre><Monitor name="monitorFortressRed" init="0.2" drift="-0.1" low="0.0" high="1.0">
<OnOver value="1.0">
<EffectGroup ...>
<User user="..." positive="true" marked="ignore">
... 
</User>
<User ...>
...
</User>
</EffectGroup>
</OnOver>
</Monitor></pre>

==== User ====

The User element always have these attributes, but outside of an EffectGroup from a Monitor, this is always ignored.

MonitorInfluence element is the one where one describe how to affect a monitor. It has an attribute name to point to the monitor to influence. It has a marked attribute which is a Triad, ie: allows for the value true, false or ignore. Players using this MonitorInfluence will carry this mark into their contribution to the monitor.

There are 3 ways to influence the value of a monitor:
*1 the attribute influenceSlide will affect the monitor's value in a fashion proportional to the time passed in the zone. This is how the classical fortress operates. This is the same as saying influenceSlide * duration of the current game time step.
*2 the attribute influenceAdd will affect the monitor's value by this amount. This is NOT affected by time.
*3 the attribute influenceSet will set the monitor's value immediatly to this value.

These can of course be used simulteanously. It is important here that
attributes that are not desired should not be defined, rather than
defined at a default value.

Ex:
<pre><User ...>
...
<MonitorInfluence name="monitorFortressRed" marked="true" influenceSlide="0.5"/>

<MonitorInfluence name="monitorFortressGreen" marked="true" influenceAdd="2"/>

<MonitorInfluence name="monitorFortressBlue" influenceSet="0.0" />

</User></pre>

== Quiz ==
Respond on the forums after reading through this entire page with any ideas or questions of your own.(Optional)

1 Are you able to express some new ideas with it?

2 Do you see items that could be added, either now or as a later
version that could improve its value?

3 Anything else?

-ph

== Examples ==
An example might help you get through the mess of the description

Its blue vs red Each team has zones in opposing corners which are interconnected. As they get conquered, they jump toward the center.

For your convenience:
MAP_FILE philippeqc/zone/DoubleZoneJumping-1.aamap.xml

Code:
<pre><?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map-0.3.1-a.dtd">
<Resource type="aamap" name="DoubleZoneJumping" version="1" author="philippeqc" category="zone">


<pre> <Map version="2">

<World>
<Field>
<Spawn x="50" y="245" xdir="1" ydir="0" />
<Spawn x="450" y="255" 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>
<Zone name="zRed1">
<ShapeCircle radius="49" red="1.0" green="0.1" blue="0.1">
<Point x="50" y="50"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="-0.25" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="0.5" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Zone name="zRed2">
<ShapeCircle radius="49" red="1.0" green="0.1" blue="0.1">
<Point x="450" y="450"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="-0.25" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="0.5" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Monitor name="mRed" init="0.0" drift="-0.1" >
<InRange low="0.0" high="0.30">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="100" y="100"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="400" y="400"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.4" high="0.60">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="150" y="150"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="350" y="350"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.7" high="1.0">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="200" y="200"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="300" y="300"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<OnOver value="1">
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<Target target="self">
<Effect effect="point" count="2" score="7"/>
</Target>
<ZoneInfluence name="zRed1">
<Radius radius="-1" />
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Radius radius="-1" />
</ZoneInfluence>
</User>
</EffectGroup>
</OnOver>
</Monitor>



<Zone name="zBlue1">
<ShapeCircle radius="49" red="0.10" green="0.10" blue="1.0">
<Point x="50" y="450"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="0.3" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="-0.3" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Zone name="zBlue2">
<ShapeCircle radius="49" red="0.10" green="0.10" blue="1.0">
<Point x="450" y="50"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="0.3" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="-0.3" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Monitor name="mBlue" init="0.0" drift="-0.1" >
<InRange low="0.0" high="0.30">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="100" y="400"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="400" y="100"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.4" high="0.60">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="150" y="350"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="350" y="150"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.7" high="1.0">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="200" y="300"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="300" y="200"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<OnOver value="1">
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<Target target="self">
<Effect effect="point" count="2" score="7"/>
</Target>
<ZoneInfluence name="zBlue1">
<Radius radius="-1" />
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Radius radius="-1" />
</ZoneInfluence>
</User>
</EffectGroup>
</OnOver>
</Monitor>

</Field>
</World>
</Map>
</Resource></pre>

Ex:
Code:

<pre><Zone name="redFortress">
<ShapeCircle radius="29" red="0.988" green="0.059" blue="0.753"/>
<Point x="50" y="50"/>
</ShapeCircle>
...
</Zone></pre>

is now

Code:
<pre><Zone name="redFortress">
<ShapeCircle radius="29" >
<Color red="0.988" green="0.059" blue="0.753" alpha="0.0"/>
<Point x="50" y="50"/>
</ShapeCircle>
...
</Zone></pre>

Also added Color as a child of ZoneInfluence:
Code:
<pre> <ZoneInfluence name="blueFortress">
<Radius radius="-1" />
<Color red="0.988" green="0.059" blue="0.753" alpha="0.0"/>
</ZoneInfluence></pre>

This map has 4 zones that activate one another. Only one should be present, and when not there, they are put outside of the arena. They are activated in a crossed fashion.

Code:
<pre><?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map.dtd">
<Resource type="aamap" name="zone" version="d" author="philippeqc" category="">

<Map version="2">

<World>
<Field>
<Spawn x="50" y="245" xdir="1" ydir="0" />
<Spawn x="450" y="255" 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>

<Zone name="SW">
<ShapeCircle radius="29" >
<Point x="50" y="50"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="SW">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="NE">
<Point x="450" y="450"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="NE">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="NE">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="NW">
<Point x="50" y="450"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="NW">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="NW">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="SE">
<Point x="450" y="50"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="SE">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="SE">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="SW">
<Point x="50" y="50"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>
</Field>
</World>
</Map>
</Resource></pre>

Its a really crude idea, that has been retaken in a much better way by wrt. But it show some things that can be done (influencing individual zones, and using ZoneInfluence from one zone to affect another).

Targets have a count:
Code:
The target has an attribute count that will limit the number of time
it is called. Not having the attribute or setting it to -1 means infinite.

-ph

Zones v2

2007-06-06T09:37:40Z

Philippeqc: Layed the rotationValueSpeed attribute to the Rotation element

== Preamble ==

You will note that the examples below dont sound that fun. I'd like to think its because my creative power went into building a good system, and now there is little left to put on examples. But I'm sure you will find interesting ways to use the mechanisms in here. My goal with this was to be able to have zones that could have different effect depending on who would use them. For example, having a fortress that team Blue could conquer, but only 2 of the players of team Red could actually defend. The other Red could still circle it and block the enemy, but they could not lower its value actively. Everything described here works. There are still glitches small and not so small. The code is in my private branch, but feel free to grab a local copy if you want to play with it.

The format is anything but closed. I'd like to hear your opinion on it too (yes it is a PITA to write, but if you have a constructive remark about that, I'd like to know it)

-ph

Most of this is from a forum post by philippeqc. I reworded some stuff and formatted a bit for the wiki. Some stuff might have gotten lost or reworded wrongly so cross refrence with the post if the wording gets hazy and/or just to double check @ http://forums.armagetronad.net/viewtopic.php?p=77491#77491. Some stuff might be in the wrong place. --[[User:Your mom|Your mom]] 11:42, 30 July 2006 (CDT)

== Zone element ==

Individual zones may have a name. Entering a name is optional, and re-using a name will be considered to mean "add/override with the following information". Dont rely on this behavior for anything, in other words '''Dont re-use the same name.''' All zones need a shape defined. At the moment only one shape exists, the ShapeCircle. More shapes are planned in the future and are ToDo

Ex:
<Zone name="redFortress">
<ShapeCircle radius="29">
<Point x="50" y="50"/>
<Color red="0.988" green="0.059" blue="0.753" />
</ShapeCircle>

</Zone>

== Rules and EffectGroups ==

A zone can have up to 4 different "rules" (need better name ToDo). Enter, Inside, Leave, Outside. It classifies when the held elements should be inspected. Inside each of the "rules", one can define EffectGroups. EffectGroup(s) are the fundamental building blocks of this new system. It associate owners with consequences. Note that ownership is part of effectGroup(s), ''NOT'' the zone. So a zone may have multiple effectGroup(s), each with unique or interlapping owners. There are 2 types of owners: owner (individuals) and ownerTeam (every member of a team). It is possible to define 0,1 or many for each items.

''HACK:
ATM, only owner is supported, and it must be an exact match with a
player's name to associated the effect.
The real solution will translate the labels used to players based on
some other logic depending on "game type". This is to be defined
later.''

''HACK:
It should be possible to associate individual with teams in some part
of the map. In this text, I will user lowercase color name + number for
individual, and uppercase color name for teams. So the individual
red1, red7 and red90210 should be considered as players of the team
RED. I will also allow myself to insert _description_ in names to help
the reader when appropriate.''

Ex:
<pre><Zone name="redFortress">
<ShapeCircle ...>
...
</ShapeCircle>
<Enter>
<EffectGroup owner="red1,red2" ownerTeam="BLUE,YELLOW">
...
</EffectGroup>
<EffectGroup owner="" ownerTeam="RED">
...
</EffectGroup>
</Enter>
<Leave>
<EffectGroup owner="green7" ownerTeam="">
...
</EffectGroup>
</Leave>
</Zone></pre>

== User element ==

Inside the EffectGroup, elements User are set. This element offers different readily made rules to determine if a player in the "rule" condition for the zone, is allowed to be considered a user. This is decided based from the following information: owner, ownerTeam and the player matching the rule. Two other conditions can be set for a player to be considered a valid user: positive and marked. These element are of type Triad. The possible values are true, false and ignore. We will come back to these later. If the current player is found to be valid, the processing will continue to the child elements. Otherwise, nothing happens. A valid user will be called triggerer from now on.

The following users are currently implemented:
* all: Anybody can be considered a valid user,
* owner: only a player direcly in the owner list can be considered a valid user,
* ownerTeam: only a player member of a team mentionned in the ownerTeam list can be considered a valid user,
* allButOwner only a player NOT mentioned in the owner list can be considered a valid user,
* allButTeamOwner only a player NOT member of a team mentioned in the ownerTeam list can be considered a valid user, (TO COME, NOT IMPLEMENTED YET)
* anotherTeammate only a player in the same team as one of the individual owner can be considered a valid user (TO COME, NOT IMPLEMENTED YET)

Ex:
<pre><EffectGroup owner="red1,red2" ownerTeam="BLUE,YELLOW">
<User user="all" >
... 
</User>
<User user="allButOwner" >
... 
</User>
</EffectGroup>
<EffectGroup owner="" ownerTeam="RED">
<User user="owner" >
... 
</User>
<User user="ownerTeam" >
... 
</User>
</EffectGroup></pre>

Inside a User element, it is possible to make use of 3 different
elements. Target, ZoneInfluence and MonitorInfluence.

=== Target ===

The Target element will take the information of the valid user, and
calculate who will receive the effect of the zone. Depending on the
described target rule to use and the state of the game, the calculated
target can be from no players to everybody in game.

The currently implemented target rules are :

*self : the triggerer himself
*teammate : a randomly selected teammate of the triggerer
*team : all the member of the team of the triggerer
*all : everybody in the game
*allButSelf : everybody in the game BUT the triggerer
*another : a randomly selected player that is not the triggerer
*ownerTeamTeammate : a randomly selected player member of one of the teams mentioned in the teamOwner list.
*owner : all the players owning the effectGroup
*ownerteam : all the players member of the team owning the effectGroup
*ownerteamteammate : a single player member from a owning team
*anydead : any single dead player
*alldead : all the dead players
*singledeadowner : one of the owners that is dead
*anotherteammatedead : a single player member of the team of the triggerer that is dead
*anothernotteammatedead : a single player that is not member of the team of the triggerer and that is dead
<nowiki>
*Much more are detailed in a document named zones.txt hidden somewhere
on the forum.</nowiki>

Once the targets are selected, they all are applied all the effects
described under the Target element.

Nota: In a User element, it is possible to user any amount of Target,
ZoneInfluence and MonitorInfluence.

Ex:
<pre><User user="ownerTeam" >
<Target target="self">
... 
</Target>
<Target target="another">
... 
</Target>
</User></pre>

== Effect ==

The Effect element hold specific effects. The attribute count can limit the number of times a specific effect can be used. By default, the count is unlimited.

valid effect currently implemented are:
*win : win the round
*death : kill the target(s)
*point : give points to the target(s)
*respawnplayer : Respawns target(s)
*brakerecharge : Refills target(s) cycle brake
*rubberrecharge : Refills target(s) cycle rubber
*setting : has 2 attributes ; settingName & settingValue

new attribute for all effects: description

When the effect is triggered, the message is displayed on the console. Somehow I'm not able to do the "parsing" similar to when points are given (player x received y points because he is sooo leet). That should come.

When point is use, an attribute score will mention the amount of point
to give.

<pre><Target target="self">
<Effect effect="point" score="3" count="2">
... 
</Effect>
<Effect ...>
...
</Effect>
</Target></pre>

ex:
<pre><Effect effect="setting" settingName="cycle_speed" settingValue="100" /></pre>

=== ZoneInfluence ===

Inside the User element, the element ZoneInfluence and MonitorInfluence are use to affect back game element. ZoneInfluence allows to affect a zone in play. The name attribute must match exactly a zone's name elsewhere in the map.

The possible thing to affect on a zone are:
*Rotation with attribute rotationBaseSpeed, rotationValueSpeed and rotationAcceleration
*Radius with attribute radius
*Point with attribute x and y

Ex:
<pre><User user="all">
<ZoneInfluence name="redFortress">
<Rotation rotationBaseSpeed="1" rotationValueSpeed="0.5" rotationAcceleration="0.0" />
<Radius radius="50"/>
<Point x="100" y="100" />
</ZoneInfluence>
<ZoneInfluence name="blueFortress">
<Radius radius="-1" />
</ZoneInfluence>
</User></pre>

=== MonitorInfluence ===

Monitors are simple valiables that can be affected by interaction with different zones. The old "fortress" zone is to be considered as a zone where being inside slowly influence its monitor. Monitors are to be inserted in the map at the same level as Zone. Monitor have a name that is used to refer to from the MonitorInfluence, a initial value, and a drift, that slowly move the value, low and high, which clamp the monitor's value between their owns.

<pre><Field>
...
<Monitor name="monitorFortressRed" init="0.2" drift="-0.1" low="0.0" high="1.0">
... 
</Monitor>
...
</Field></pre>

The Monitor as different rules that can be used to inspect and react on its value. They are OnOver, OnUnder, InRange and OutsideRange. Any amount of rules can be used in a monitor.

*OnOver has an attribute named value and will be used when the monitor's value exceed it,
*OnUnder has an attribute named value and will be used when the monitor's value is under it,
*InRange has attributes low and high and will be used when the monitor's value fall between both
*OutRange has attributes low and high and will be used when the monitor's value is not falling between both

The monitors' rules are similar to the zone's rule in that they hold EffectGroups that are inspected when the rule conditions are met.

What differs a Monitor from a zone regarding to EffectGroup is who are considered players to be inspected as users. Anyone who contributed to a monitor during a game time step is registered, along with if the contribution was positive (conquering) or negative (defending), and if they where marked. This information is passed along up to the User element. There it can be used on additional tests to determine a valid user.

<pre><Monitor name="monitorFortressRed" init="0.2" drift="-0.1" low="0.0" high="1.0">
<OnOver value="1.0">
<EffectGroup ...>
<User user="..." positive="true" marked="ignore">
... 
</User>
<User ...>
...
</User>
</EffectGroup>
</OnOver>
</Monitor></pre>

==== User ====

The User element always have these attributes, but outside of an EffectGroup from a Monitor, this is always ignored.

MonitorInfluence element is the one where one describe how to affect a monitor. It has an attribute name to point to the monitor to influence. It has a marked attribute which is a Triad, ie: allows for the value true, false or ignore. Players using this MonitorInfluence will carry this mark into their contribution to the monitor.

There are 3 ways to influence the value of a monitor:
*1 the attribute influenceSlide will affect the monitor's value in a fashion proportional to the time passed in the zone. This is how the classical fortress operates. This is the same as saying influenceSlide * duration of the current game time step.
*2 the attribute influenceAdd will affect the monitor's value by this amount. This is NOT affected by time.
*3 the attribute influenceSet will set the monitor's value immediatly to this value.

These can of course be used simulteanously. It is important here that
attributes that are not desired should not be defined, rather than
defined at a default value.

Ex:
<pre><User ...>
...
<MonitorInfluence name="monitorFortressRed" marked="true" influenceSlide="0.5"/>

<MonitorInfluence name="monitorFortressGreen" marked="true" influenceAdd="2"/>

<MonitorInfluence name="monitorFortressBlue" influenceSet="0.0" />

</User></pre>

== Quiz ==
Respond on the forums after reading through this entire page with any ideas or questions of your own.(Optional)

1 Are you able to express some new ideas with it?

2 Do you see items that could be added, either now or as a later
version that could improve its value?

3 Anything else?

-ph

== Examples ==
An example might help you get through the mess of the description

Its blue vs red Each team has zones in opposing corners which are interconnected. As they get conquered, they jump toward the center.

For your convenience:
MAP_FILE philippeqc/zone/DoubleZoneJumping-1.aamap.xml

Code:
<pre><?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map-0.3.1-a.dtd">
<Resource type="aamap" name="DoubleZoneJumping" version="1" author="philippeqc" category="zone">


<pre> <Map version="2">

<World>
<Field>
<Spawn x="50" y="245" xdir="1" ydir="0" />
<Spawn x="450" y="255" 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>
<Zone name="zRed1">
<ShapeCircle radius="49" red="1.0" green="0.1" blue="0.1">
<Point x="50" y="50"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="-0.25" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="0.5" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Zone name="zRed2">
<ShapeCircle radius="49" red="1.0" green="0.1" blue="0.1">
<Point x="450" y="450"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="-0.25" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="0.5" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Monitor name="mRed" init="0.0" drift="-0.1" >
<InRange low="0.0" high="0.30">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="100" y="100"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="400" y="400"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.4" high="0.60">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="150" y="150"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="350" y="350"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.7" high="1.0">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="200" y="200"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="300" y="300"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<OnOver value="1">
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<Target target="self">
<Effect effect="point" count="2" score="7"/>
</Target>
<ZoneInfluence name="zRed1">
<Radius radius="-1" />
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Radius radius="-1" />
</ZoneInfluence>
</User>
</EffectGroup>
</OnOver>
</Monitor>



<Zone name="zBlue1">
<ShapeCircle radius="49" red="0.10" green="0.10" blue="1.0">
<Point x="50" y="450"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="0.3" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="-0.3" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Zone name="zBlue2">
<ShapeCircle radius="49" red="0.10" green="0.10" blue="1.0">
<Point x="450" y="50"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="0.3" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="-0.3" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Monitor name="mBlue" init="0.0" drift="-0.1" >
<InRange low="0.0" high="0.30">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="100" y="400"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="400" y="100"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.4" high="0.60">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="150" y="350"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="350" y="150"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.7" high="1.0">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="200" y="300"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="300" y="200"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<OnOver value="1">
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<Target target="self">
<Effect effect="point" count="2" score="7"/>
</Target>
<ZoneInfluence name="zBlue1">
<Radius radius="-1" />
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Radius radius="-1" />
</ZoneInfluence>
</User>
</EffectGroup>
</OnOver>
</Monitor>

</Field>
</World>
</Map>
</Resource></pre>

Ex:
Code:

<pre><Zone name="redFortress">
<ShapeCircle radius="29" red="0.988" green="0.059" blue="0.753"/>
<Point x="50" y="50"/>
</ShapeCircle>
...
</Zone></pre>

is now

Code:
<pre><Zone name="redFortress">
<ShapeCircle radius="29" >
<Color red="0.988" green="0.059" blue="0.753" alpha="0.0"/>
<Point x="50" y="50"/>
</ShapeCircle>
...
</Zone></pre>

Also added Color as a child of ZoneInfluence:
Code:
<pre> <ZoneInfluence name="blueFortress">
<Radius radius="-1" />
<Color red="0.988" green="0.059" blue="0.753" alpha="0.0"/>
</ZoneInfluence></pre>

This map has 4 zones that activate one another. Only one should be present, and when not there, they are put outside of the arena. They are activated in a crossed fashion.

Code:
<pre><?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map.dtd">
<Resource type="aamap" name="zone" version="d" author="philippeqc" category="">

<Map version="2">

<World>
<Field>
<Spawn x="50" y="245" xdir="1" ydir="0" />
<Spawn x="450" y="255" 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>

<Zone name="SW">
<ShapeCircle radius="29" >
<Point x="50" y="50"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="SW">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="NE">
<Point x="450" y="450"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="NE">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="NE">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="NW">
<Point x="50" y="450"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="NW">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="NW">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="SE">
<Point x="450" y="50"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="SE">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="SE">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="SW">
<Point x="50" y="50"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>
</Field>
</World>
</Map>
</Resource></pre>

Its a really crude idea, that has been retaken in a much better way by wrt. But it show some things that can be done (influencing individual zones, and using ZoneInfluence from one zone to affect another).

Targets have a count:
Code:
The target has an attribute count that will limit the number of time
it is called. Not having the attribute or setting it to -1 means infinite.

-ph

Map Making

2007-06-06T09:13:47Z

Philippeqc: Grouped all the tools together

There are ways to make maps, and there are ways to make maps.

== Tutorials ==

=== [[Making Maps for Beginners|A beginners tutorial]] ===

This is an alternative tutorial written by kyle and syllabear that's more intended for beginners who haven't dealt with XML before. It basically contains duplicate information to the page above, so for technical matters [[Making Maps by Hand]] should be consulted.

=== [[Making Maps by Hand|The complete description of the map format]] ===

This is the only supported way to make maps right now. It is a tutorial that is created by the Map Master himself and hopefully maintained by him (with everyone's help). It is your first and best resource to what exactly goes into a map, how to put it there, and how it works in the game. Even if you choose to use a graphical map maker, you still need to read this, so consider it required reading.

== Tools and Generators ==
* [[Acme]] — Acme is a currently experimental mostly-doesn't-work graphical map editor that's in Armagetron Advanced's cvs. If you'd like to fool with it, go to this page and read about it, but be warned, it mostly doesn't work.

* [[ArmaBell's MapEditor]] — ArmaBell's MapEditor is a currently experimental graphical Win32 map editor. If you'd like to fool with it, go to this page and read about it.

* [http://generalconsumption.org/armagetronad/ellipse-maker/ Ellipse Maker]
* [http://generalconsumption.org/armagetronad/svg2aamap/ SVG2AAMap] — Convert SVG documents to aamaps. See [[http://forums.armagetronad.net/viewtopic.php?t=6311 aaforums:6311]].

== Viewing Maps ==

[http://www.generalconsumption.org/armagetron/map-preview/ Map Previewer]

Nemostultae made a neat little web application that renders a map to a picture right in your browser. When used in conjunction with a text editor, it is a powerful tool to help make maps. In fact, the output of this page is currently considered required information if you want any server administrator to use your map on his server.

== [[Playing Maps]] ==

So you've made your killer map, now how do you play it?

Map Making

2007-06-06T09:11:38Z

Philippeqc: re-grouping

There are ways to make maps, and there are ways to make maps.

== Tutorials ==

=== [[Making Maps for Beginners|A beginners tutorial]] ===

This is an alternative tutorial written by kyle and syllabear that's more intended for beginners who haven't dealt with XML before. It basically contains duplicate information to the page above, so for technical matters [[Making Maps by Hand]] should be consulted.

=== [[Making Maps by Hand|The complete description of the map format]] ===

This is the only supported way to make maps right now. It is a tutorial that is created by the Map Master himself and hopefully maintained by him (with everyone's help). It is your first and best resource to what exactly goes into a map, how to put it there, and how it works in the game. Even if you choose to use a graphical map maker, you still need to read this, so consider it required reading.

== Tools and Generators ==
* [http://generalconsumption.org/armagetronad/ellipse-maker/ Ellipse Maker]
* [http://generalconsumption.org/armagetronad/svg2aamap/ SVG2AAMap] — Convert SVG documents to aamaps. See [[http://forums.armagetronad.net/viewtopic.php?t=6311 aaforums:6311]].

== Viewing Maps ==

[http://www.generalconsumption.org/armagetron/map-preview/ Map Previewer]

Nemostultae made a neat little web application that renders a map to a picture right in your browser. When used in conjunction with a text editor, it is a powerful tool to help make maps. In fact, the output of this page is currently considered required information if you want any server administrator to use your map on his server.

== [[Playing Maps]] ==

So you've made your killer map, now how do you play it?

Map Making

2007-06-06T09:09:23Z

Philippeqc: re-arranged summary for clearer grouping

There are ways to make maps, and there are ways to make maps.

== Making Maps ==

There are a number of resources available to help you make maps right now and start using them.

=== Tutorials ===

==== [[Making Maps for Beginners|A beginners tutorial]] ====

This is an alternative tutorial written by kyle and syllabear that's more intended for beginners who haven't dealt with XML before. It basically contains duplicate information to the page above, so for technical matters [[Making Maps by Hand]] should be consulted.

==== [[Making Maps by Hand|The complete description of the map format]] ====

This is the only supported way to make maps right now. It is a tutorial that is created by the Map Master himself and hopefully maintained by him (with everyone's help). It is your first and best resource to what exactly goes into a map, how to put it there, and how it works in the game. Even if you choose to use a graphical map maker, you still need to read this, so consider it required reading.

=== Map Making Tools ===

=== [[Acme]] ===

Acme is a currently experimental mostly-doesn't-work graphical map editor that's in Armagetron Advanced's cvs. If you'd like to fool with it, go to this page and read about it, but be warned, it mostly doesn't work.

=== [[ArmaBell's MapEditor]] ===

ArmaBell's MapEditor is a currently experimental graphical Win32 map editor. If you'd like to fool with it, go to this page and read about it.

== Tools and Generators ==
* [http://generalconsumption.org/armagetronad/ellipse-maker/ Ellipse Maker]
* [http://generalconsumption.org/armagetronad/svg2aamap/ SVG2AAMap] — Convert SVG documents to aamaps. See [[http://forums.armagetronad.net/viewtopic.php?t=6311 aaforums:6311]].

== Viewing Maps ==

[http://www.generalconsumption.org/armagetron/map-preview/ Map Previewer]

Nemostultae made a neat little web application that renders a map to a picture right in your browser. When used in conjunction with a text editor, it is a powerful tool to help make maps. In fact, the output of this page is currently considered required information if you want any server administrator to use your map on his server.

== [[Playing Maps]] ==

So you've made your killer map, now how do you play it?

Making Maps by Hand

2007-05-26T17:12:24Z

Philippeqc: Typo

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


<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 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 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 "/" (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
<pre>
<Resource name="Castle" type="aamap" version="1.1" author="philippeqc" category="examples">
...
</Resource>
</pre>

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

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

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

<pre>
<Map ...>
<Settings>
...
</Settings>
<World>
...
</World>
</Map>
</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. 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
<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 "<nowiki></nowiki>". 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 Filename Convention ===

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

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

;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 <code>unofficial/mailto/<Domain>@<User></code>.
: 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 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 Advanced 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 Advanced team recommend a <code>VERSION.MAJOR.MINOR</code> dot notation similar to those used for software's versions, any other notation can be
used, such as a simple numeral: <code>GlowStick-1.png, GlowStick-2.png, ...</code>. 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:
<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:
[[Resource repository]]

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

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


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

Making Maps by Hand

2007-05-26T17:11:21Z

Philippeqc: Description where the settings goes in the map format

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


<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 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 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 "/" (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
<pre>
<Resource name="Castle" type="aamap" version="1.1" author="philippeqc" category="examples">
...
</Resource>
</pre>

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

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

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

<pre>
<Map ...>
<Settings>
<Setting name="a" value="1"/>
<Setting name="b" value="2"/>
<Setting name="c" value="3"/>
</Settings>
<World>
...
</World>
</Map>
</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. 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
<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 "<nowiki></nowiki>". 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 Filename Convention ===

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

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

;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 <code>unofficial/mailto/<Domain>@<User></code>.
: 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 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 Advanced 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 Advanced team recommend a <code>VERSION.MAJOR.MINOR</code> dot notation similar to those used for software's versions, any other notation can be
used, such as a simple numeral: <code>GlowStick-1.png, GlowStick-2.png, ...</code>. 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:
<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:
[[Resource repository]]

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

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


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

PlayingFAQ

2007-05-01T12:55:40Z

Philippeqc: /* General terminology */

This FAQ relates to issues about installing, configuring and mostly playing the game. For issues specific about hosting, consult the [[HostingFAQ|Hosting server FAQ]]

= Installing the Game =

== Where can I download Armagetron Advanced? ==

That depends on what version you want to get. The current stable version is always available [http://www.armagetronad.net/downloads.php on the main web page] or [http://sourceforge.net/project/showfiles.php?group_id=110997 sourceforge]. The latest testing version on [http://beta.armagetronad.net AABeta].

== How do I install... ==
=== on Windows? ===

Find the exe file you downloaded from the question and answer above this one and double click on it. Answer all dialog boxes with Yes/Next/Finish, whatever applies. On Windows XP, when you first run the game and try to connect to the Internet, a firewall warning will pop up; set it to allow access.

=== on Mac OS? ===

Mount the dmg file, and drag the Armagetron Advanced application to your hard-drive.

=== on Linux? ===

That depends on the distribution you are running. Check out the [[Linux Distribution Field Report]] for details.

== I'm running Linux, but don't know whether it is 32 or 64 bit. How can I find out? ==

On a console/terminal, type <pre>echo $MACHTYPE</pre>
If the output starts with x86_64, you have a 64 bit system. If it starts with i386, i486, i586 or i686 or possibly just x86 or x86_32, you have a 32 bit system. For anything else, we don't provide binary packages, you have to build from source. If the output is blank, the method failed. Then, see whether you have got the directory /usr/lib64 on your system. If yes, you have a 64 bit system, if no, it's 32 bit.

== I run a non-Linux UNIX or Linux on hardware not supported by your binary packages or the binaries don't work, how do I install from source? ==

Basically, you fetch the .tbz2 source archive and do as the superuser root
<pre>tar -xjf <path to the tbz2 source archive you just fetched>
cd armagetronad-<VERSION>
./configure
make
make install</pre>
The configure script will tell you what you are missing. In this mode, you always need the 'development' packages of our dependencies on most distributions.
The [[Linux Distribution Field Report]] may have some hints. Ask us if you get stuck.

== I'm working on a Linux PC administered by someone else and don't have the root password, can I still install the game? ==

Yes. The "package" binary files can install everything in your home directory. If you have to build from source, proceed as in the last FAQ,
but pass '--prefix=$HOME/usr' to ./configure and run the game later with
'~/usr/bin/armagetronad', or run the game from the build directory with 'make run'.

== So, should I get the latest stable or latest development version? ==

If you're really asking this question and are not just browsing the FAQ, get the latest stable version.

== Ok, but there are still so many different files to get, which one is right for me? ==

See [[FAQ#Terminology]] for choosing between Client and Server download. If in doubt, choose the Client. If you're running a PC with Windows, get the exe format, GCC or VC6 should not matter (please report it if only one of them works for you). If you've got a Mac, get the dmg; there is a special build available for versions 10.2.8 of OS X. If you're running 32 bit Intel Linux, get the x86(_32) "package". If you're running 64 bit AMD Linux, get the x86_64 "package".

== Where are the server sources? ==

The server sources are the same as the client sources. You compile a server from them by giving the additional command line option '--disable-glout' to ./configure.

= Configuring =
== I heard about moviepacks (graphical modifications), how do I install them? ==

See [[Customizing the game]].

== How do I use a map? ==

Read [[Playing Maps]], and please try to tell us why this question is asked so often and followed by "I read the whole wiki!".

= Terminology =
== General terminology ==
=== What is rubber? ===
Rubber is a mecanism not unlike a cushion in front of your cycle that allows you to come closer to wall. The closer you move to a wall, the more rubber you consume. The faster you move when approching a wall, the more rubber you consume. If a cycle exceed its rubber limit at any time, it is considered to have crashed in the wall. Rubber normally is regained at a steady pace.

=== What is grinding? ===
The act of running very close to a cycle trace or sometime an arena wall to benefit from the wall acceleration effect.

=== What is double/tripple binding? ===
The act of associating multiple keys to the same action, such as turning. By pressing successively multiple keys it is possible to execute tight turns.

==== Is double/tripple binding a sin? ====
Though it is a side effect of the game support for different keyboard layout, some beleive that as it is supported by the game, it is a valid strategy. Others consider that is of bad taste and encourage players to learn to rapidly tap the same key instead.

=== What is camping? ===

==== Is camping a sin? ====

=== What is waiting for rubber? ===

== Game types terminology ==
=== What is Fortress? ===
Fortress is often seen in online playing. Each team has a zone assigned. The object is to capture the enemy zone while defending your own. It has been often observed that mildly skilled but effective team work outclass highly skilled but mildly organized team work on Fortress games.

=== What is CTF/Capture The Flag? ===
A game configuration where the objective it to capture and carry back to your base (often represented as a wide zone) the enemy flag while your own team flag is still at its starting position.

=== What is Sumo? ===
Stacked zone, often sharing the exact same location, and configured in a way that the zone decay conquers it. As all the players have to fight each other to get access to a place under the zones, the act often push out some players, which quickly die, in a manner that reminds sumo fighting.

== Network terminology ==
=== What is ping? ===
Ping is how long it takes for data to be sent from your computer to the server and back. Higher the ping, more lag.
==== How do I find my ping? ====
TODO

=== What is lag? ===
== Multi-player related terminlogy ==
=== What is the ladder? ===
TODO
=== What is tk/team kill? ===
Often seen at the start of round with many players on a team, a team kill is when a player, by its action or lack of, cause the death of a teammate. Considered a serious lack of respect.

=== What is gank? ===
The act of overtaking a zone, for example 2 vs 1, without fighting.

= Hosting from the client =

== What is a client? What is a server? What's the difference? ==

Simply put, the game client is the program you run on your computer. The game server runs on somebody else's computer. The difference between the two is like the difference between, say, a lawyer and his client. The lawyer would be the server, the one who knows all about law and stuff. So the difference is just like in real life where the terms come from. The client requests a service from someone who serves. In our case, that service is a game that is served from a machine running a program called a "server", but if you requested the same service from a person in a casino, you'd still be running a game client.

== My client can be a server, though, it says so right here. ==

That's not a question. In any case, the game client can act as a server if you press "Host Game" from the Internet Game menu. So technically the client is a client/server hybrid, but let's not get too technical.

== So are all game servers just clients where people pressed "Host Game"? ==

No. This is where people get really confused, even to the point where they complain to server operators for doing exactly this thing. No, most, if not all, game servers available through the master server run a special version of the program that has no graphical display, and no player can play on directly. That is the server, commonly called the "dedicated server". You can run it too, if you'd like. Server operators chose to run this instead of the regular game client because it has a number of modifications that make it work better as a regular server, just like a mail server or a web server. It is more convenient and makes for a more reliable game server to do so.

= Troubleshooting =

== ArmagetronAd takes most or all the CPU time, how come? ==

AA takes all the CPU time it needs to simulate and render the scene as fast as you'll allow it to. There are two conditions under which that makes it take almost everything that is available:
* You set your graphics card driver not to wait for VSync. AA will then run at the highest possible framerate and therefore also use all the CPU time available. If you enable the FPS display in the HUD options and it shows more than 100 FPS, then that's your problem.
* When it tells your video card driver to update the screen now, the driver goes into a special CPU-hogging mode until the command is completed, even though all it does is sit around and wait. Both NVidia and ATI drivers are guilty of this. In the "Performance Tweaks" submenu of the graphics settings, there is the "Flush" menu item where you can tweak AA to not issue the problematic command (with possible side effects).

== ArmagetronAd is unplayable on my AMD Dual Core X2 System (might affect other Dual Cores) ==

Symptoms:
*The console displays "Timer hick up"
*FPS are usually ok (above 30).
*might only occur in network games
*Game performance is very bad

At least three solutions for this problem are available:
* To fix this problem use your TaskManager to set ArmagetronAd.exe's cpu affinity to a single CPU.
* Disable Cool & Quite in BIOS
* Install the necessary Microsoft Hotfixes and depending on your System you might have to update your bios and drivers too.

Links (TODO replace links with links to better instructions!):
* [http://support.microsoft.com/default.aspx?scid=KB;en-us;896256 Microsoft Knowledge base Article about Q896256]
* [http://www.amd.com/en-us/Processors/TechnicalResources/0,,30_182_871_13118,00.html AMD Dual Core Optimizer] The fix is similiar to Microsofts, but only fixes a small part of it. The Microsoft patch also addresses power saving bugs (of Windows XP).

*Details: Armagetron Advanced 0.2.8.x(?) or later uses the high precision timer on Windows if available. (TODO confirm) This can be a problem on the new Dual Core Systems or malfunctioning Multiprocessor System. The Timer of each core runs at different speeds which results in a jumping timer! The AMD X2 Systems are affected because they have two separate timers for each CPU (Intels Core Duo CPUs share a single timer). The AMD X2 Systems are only affected with Cool & Quite power saving enabled otherwise both cores have the same timer speed. The Windows kernel schedules Armagetron Advanced between both cores which results in a jumping timer form Armagetron perspective.

= When all else fail =
What to do when consulting the documents provided on this wiki and consulting this FAQ still doesnt provide an answer.

== The Forums ==
The [[forums.armagetronad.net|forum]] is a message board where discussion about ArmagetronAd often take part. A great many problems have been discussed and solved there.

The forums is usefull for discussion that spawns under days and weeks. Should you require more immediate assistance, try contacting us on IRC.

=== What should I do to increase my chance of getting help? ===
First of all, use the search capacities of the forum. It is easy and powerfull, and often will turn your answer without delays.

Second, get your information right. A simple task from you will save many troubles to anyone trying to help you. Be detailed! Nobodyknows your specific setup, nor can guess it.

== IRC channel ==
TODO
[[IRC_Channel]]

MediaWiki:Sidebar

2007-04-29T07:01:24Z

Philippeqc:

PlayingFAQ

2007-04-28T15:30:44Z

Philippeqc: /* = How do I find my ping? */

This FAQ relates to issues about installing, configuring and mostly playing the game. For issues specific about hosting, consult the [[HostingFAQ|Hosting server FAQ]]

= Installing the Game =

== Where can I download Armagetron Advanced? ==

That depends on what version you want to get. The current stable version is always available [http://www.armagetronad.net/downloads.php on the main web page] or [http://sourceforge.net/project/showfiles.php?group_id=110997 sourceforge]. The latest testing version on [http://beta.armagetronad.net AABeta].

== How do I install... ==
=== on Windows? ===

Find the exe file you downloaded from the question and answer above this one and double click on it. Answer all dialog boxes with Yes/Next/Finish, whatever applies. On Windows XP, when you first run the game and try to connect to the Internet, a firewall warning will pop up; set it to allow access.

=== on Mac OS? ===

Mount the dmg file, and drag the Armagetron Advanced application to your hard-drive.

=== on Linux? ===

That depends on the distribution you are running. Check out the [[Linux Distribution Field Report]] for details.

== I'm running Linux, but don't know whether it is 32 or 64 bit. How can I find out? ==

On a console/terminal, type <pre>echo $MACHTYPE</pre>
If the output starts with x86_64, you have a 64 bit system. If it starts with i386, i486, i586 or i686 or possibly just x86 or x86_32, you have a 32 bit system. For anything else, we don't provide binary packages, you have to build from source. If the output is blank, the method failed. Then, see whether you have got the directory /usr/lib64 on your system. If yes, you have a 64 bit system, if no, it's 32 bit.

== I run a non-Linux UNIX or Linux on hardware not supported by your binary packages or the binaries don't work, how do I install from source? ==

Basically, you fetch the .tbz2 source archive and do as the superuser root
<pre>tar -xjf <path to the tbz2 source archive you just fetched>
cd armagetronad-<VERSION>
./configure
make
make install</pre>
The configure script will tell you what you are missing. In this mode, you always need the 'development' packages of our dependencies on most distributions.
The [[Linux Distribution Field Report]] may have some hints. Ask us if you get stuck.

== I'm working on a Linux PC administered by someone else and don't have the root password, can I still install the game? ==

Yes. The "package" binary files can install everything in your home directory. If you have to build from source, proceed as in the last FAQ,
but pass '--prefix=$HOME/usr' to ./configure and run the game later with
'~/usr/bin/armagetronad', or run the game from the build directory with 'make run'.

== So, should I get the latest stable or latest development version? ==

If you're really asking this question and are not just browsing the FAQ, get the latest stable version.

== Ok, but there are still so many different files to get, which one is right for me? ==

See [[FAQ#Terminology]] for choosing between Client and Server download. If in doubt, choose the Client. If you're running a PC with Windows, get the exe format, GCC or VC6 should not matter (please report it if only one of them works for you). If you've got a Mac, get the dmg; there is a special build available for versions 10.2.8 of OS X. If you're running 32 bit Intel Linux, get the x86(_32) "package". If you're running 64 bit AMD Linux, get the x86_64 "package".

== Where are the server sources? ==

The server sources are the same as the client sources. You compile a server from them by giving the additional command line option '--disable-glout' to ./configure.

= Configuring =
== I heard about moviepacks (graphical modifications), how do I install them? ==

See [[Customizing the game]].

== How do I use a map? ==

Read [[Playing Maps]], and please try to tell us why this question is asked so often and followed by "I read the whole wiki!".

= Terminology =
== General terminology ==
=== What is rubber? ===
Rubber is a mecanism not unlike a cushion in front of your cycle that allows you to come closer to wall. The closer you move to a wall, the more rubber you consume. The faster you move when approching a wall, the more rubber you consume. If a cycle exceed its rubber limit at any time, it is considered to have crashed in the wall. Rubber normally is regained at a steady pace.

=== What is grinding? ===
The act of running very close to a cycle trace or sometime an arena wall to benefit from the wall acceleration effect.

=== What is double/tripple binding? ===
The act of associating multiple keys to the same action, such as turning. By pressing successively multiple keys it is possible to execute tight turns.

==== Is double/tripple binding a sin? ====
Though it is a side effect of the game support for different keyboard layout, some beleive that as it is supported by the game, it is a valid strategy. Others consider that is of bad taste and encourage players to learn to rapidly tap the same key instead.

== Game types terminology ==
=== What is Fortress? ===
Fortress is often seen in online playing. Each team has a zone assigned. The object is to capture the enemy zone while defending your own. It has been often observed that mildly skilled but effective team work outclass highly skilled but mildly organized team work on Fortress games.

=== What is CTF/Capture The Flag? ===
A game configuration where the objective it to capture and carry back to your base (often represented as a wide zone) the enemy flag while your own team flag is still at its starting position.

=== What is Sumo? ===
Stacked zone, often sharing the exact same location, and configured in a way that the zone decay conquers it. As all the players have to fight each other to get access to a place under the zones, the act often push out some players, which quickly die, in a manner that reminds sumo fighting.

== Network terminology ==
=== What is ping? ===
==== How do I find my ping? ====
TODO

=== What is lag? ===
== Multi-player related terminlogy ==
=== What is the ladder? ===
TODO
=== What is tk/team kill? ===
Often seen at the start of round with many players on a team, a team kill is when a player, by its action or lack of, cause the death of a teammate. Considered a serious lack of respect.

=== What is gank? ===
The act of overtaking a zone, for example 2 vs 1, without fighting.

= Hosting from the client =

== What is a client? What is a server? What's the difference? ==

Simply put, the game client is the program you run on your computer. The game server runs on somebody else's computer. The difference between the two is like the difference between, say, a lawyer and his client. The lawyer would be the server, the one who knows all about law and stuff. So the difference is just like in real life where the terms come from. The client requests a service from someone who serves. In our case, that service is a game that is served from a machine running a program called a "server", but if you requested the same service from a person in a casino, you'd still be running a game client.

== My client can be a server, though, it says so right here. ==

That's not a question. In any case, the game client can act as a server if you press "Host Game" from the Internet Game menu. So technically the client is a client/server hybrid, but let's not get too technical.

== So are all game servers just clients where people pressed "Host Game"? ==

No. This is where people get really confused, even to the point where they complain to server operators for doing exactly this thing. No, most, if not all, game servers available through the master server run a special version of the program that has no graphical display, and no player can play on directly. That is the server, commonly called the "dedicated server". You can run it too, if you'd like. Server operators chose to run this instead of the regular game client because it has a number of modifications that make it work better as a regular server, just like a mail server or a web server. It is more convenient and makes for a more reliable game server to do so.

= Troubleshooting =

== ArmagetronAd takes most or all the CPU time, how come? ==

AA takes all the CPU time it needs to simulate and render the scene as fast as you'll allow it to. There are two conditions under which that makes it take almost everything that is available:
* You set your graphics card driver not to wait for VSync. AA will then run at the highest possible framerate and therefore also use all the CPU time available. If you enable the FPS display in the HUD options and it shows more than 100 FPS, then that's your problem.
* When it tells your video card driver to update the screen now, the driver goes into a special CPU-hogging mode until the command is completed, even though all it does is sit around and wait. Both NVidia and ATI drivers are guilty of this. In the "Performance Tweaks" submenu of the graphics settings, there is the "Flush" menu item where you can tweak AA to not issue the problematic command (with possible side effects).

== ArmagetronAd is unplayable on my AMD Dual Core X2 System (might affect other Dual Cores) ==

Symptoms:
*The console displays "Timer hick up"
*FPS are usually ok (above 30).
*might only occur in network games
*Game performance is very bad

At least three solutions for this problem are available:
* To fix this problem use your TaskManager to set ArmagetronAd.exe's cpu affinity to a single CPU.
* Disable Cool & Quite in BIOS
* Install the necessary Microsoft Hotfixes and depending on your System you might have to update your bios and drivers too.

Links (TODO replace links with links to better instructions!):
* [http://support.microsoft.com/default.aspx?scid=KB;en-us;896256 Microsoft Knowledge base Article about Q896256]
* [http://www.amd.com/en-us/Processors/TechnicalResources/0,,30_182_871_13118,00.html AMD Dual Core Optimizer] The fix is similiar to Microsofts, but only fixes a small part of it. The Microsoft patch also addresses power saving bugs (of Windows XP).

*Details: Armagetron Advanced 0.2.8.x(?) or later uses the high precision timer on Windows if available. (TODO confirm) This can be a problem on the new Dual Core Systems or malfunctioning Multiprocessor System. The Timer of each core runs at different speeds which results in a jumping timer! The AMD X2 Systems are affected because they have two separate timers for each CPU (Intels Core Duo CPUs share a single timer). The AMD X2 Systems are only affected with Cool & Quite power saving enabled otherwise both cores have the same timer speed. The Windows kernel schedules Armagetron Advanced between both cores which results in a jumping timer form Armagetron perspective.

= When all else fail =
What to do when consulting the documents provided on this wiki and consulting this FAQ still doesnt provide an answer.

== The Forums ==
The [[forums.armagetronad.net|forum]] is a message board where discussion about ArmagetronAd often take part. A great many problems have been discussed and solved there.

The forums is usefull for discussion that spawns under days and weeks. Should you require more immediate assistance, try contacting us on IRC.

=== What should I do to increase my chance of getting help? ===
First of all, use the search capacities of the forum. It is easy and powerfull, and often will turn your answer without delays.

Second, get your information right. A simple task from you will save many troubles to anyone trying to help you. Be detailed! Nobodyknows your specific setup, nor can guess it.

== IRC channel ==
TODO
[[IRC_Channel]]

PlayingFAQ

2007-04-28T15:30:16Z

Philippeqc: Added 6 elements and 3 definitions to the terminology. Also broke it down into categories

This FAQ relates to issues about installing, configuring and mostly playing the game. For issues specific about hosting, consult the [[HostingFAQ|Hosting server FAQ]]

= Installing the Game =

== Where can I download Armagetron Advanced? ==

That depends on what version you want to get. The current stable version is always available [http://www.armagetronad.net/downloads.php on the main web page] or [http://sourceforge.net/project/showfiles.php?group_id=110997 sourceforge]. The latest testing version on [http://beta.armagetronad.net AABeta].

== How do I install... ==
=== on Windows? ===

Find the exe file you downloaded from the question and answer above this one and double click on it. Answer all dialog boxes with Yes/Next/Finish, whatever applies. On Windows XP, when you first run the game and try to connect to the Internet, a firewall warning will pop up; set it to allow access.

=== on Mac OS? ===

Mount the dmg file, and drag the Armagetron Advanced application to your hard-drive.

=== on Linux? ===

That depends on the distribution you are running. Check out the [[Linux Distribution Field Report]] for details.

== I'm running Linux, but don't know whether it is 32 or 64 bit. How can I find out? ==

On a console/terminal, type <pre>echo $MACHTYPE</pre>
If the output starts with x86_64, you have a 64 bit system. If it starts with i386, i486, i586 or i686 or possibly just x86 or x86_32, you have a 32 bit system. For anything else, we don't provide binary packages, you have to build from source. If the output is blank, the method failed. Then, see whether you have got the directory /usr/lib64 on your system. If yes, you have a 64 bit system, if no, it's 32 bit.

== I run a non-Linux UNIX or Linux on hardware not supported by your binary packages or the binaries don't work, how do I install from source? ==

Basically, you fetch the .tbz2 source archive and do as the superuser root
<pre>tar -xjf <path to the tbz2 source archive you just fetched>
cd armagetronad-<VERSION>
./configure
make
make install</pre>
The configure script will tell you what you are missing. In this mode, you always need the 'development' packages of our dependencies on most distributions.
The [[Linux Distribution Field Report]] may have some hints. Ask us if you get stuck.

== I'm working on a Linux PC administered by someone else and don't have the root password, can I still install the game? ==

Yes. The "package" binary files can install everything in your home directory. If you have to build from source, proceed as in the last FAQ,
but pass '--prefix=$HOME/usr' to ./configure and run the game later with
'~/usr/bin/armagetronad', or run the game from the build directory with 'make run'.

== So, should I get the latest stable or latest development version? ==

If you're really asking this question and are not just browsing the FAQ, get the latest stable version.

== Ok, but there are still so many different files to get, which one is right for me? ==

See [[FAQ#Terminology]] for choosing between Client and Server download. If in doubt, choose the Client. If you're running a PC with Windows, get the exe format, GCC or VC6 should not matter (please report it if only one of them works for you). If you've got a Mac, get the dmg; there is a special build available for versions 10.2.8 of OS X. If you're running 32 bit Intel Linux, get the x86(_32) "package". If you're running 64 bit AMD Linux, get the x86_64 "package".

== Where are the server sources? ==

The server sources are the same as the client sources. You compile a server from them by giving the additional command line option '--disable-glout' to ./configure.

= Configuring =
== I heard about moviepacks (graphical modifications), how do I install them? ==

See [[Customizing the game]].

== How do I use a map? ==

Read [[Playing Maps]], and please try to tell us why this question is asked so often and followed by "I read the whole wiki!".

= Terminology =
== General terminology ==
=== What is rubber? ===
Rubber is a mecanism not unlike a cushion in front of your cycle that allows you to come closer to wall. The closer you move to a wall, the more rubber you consume. The faster you move when approching a wall, the more rubber you consume. If a cycle exceed its rubber limit at any time, it is considered to have crashed in the wall. Rubber normally is regained at a steady pace.

=== What is grinding? ===
The act of running very close to a cycle trace or sometime an arena wall to benefit from the wall acceleration effect.

=== What is double/tripple binding? ===
The act of associating multiple keys to the same action, such as turning. By pressing successively multiple keys it is possible to execute tight turns.

==== Is double/tripple binding a sin? ====
Though it is a side effect of the game support for different keyboard layout, some beleive that as it is supported by the game, it is a valid strategy. Others consider that is of bad taste and encourage players to learn to rapidly tap the same key instead.

== Game types terminology ==
=== What is Fortress? ===
Fortress is often seen in online playing. Each team has a zone assigned. The object is to capture the enemy zone while defending your own. It has been often observed that mildly skilled but effective team work outclass highly skilled but mildly organized team work on Fortress games.

=== What is CTF/Capture The Flag? ===
A game configuration where the objective it to capture and carry back to your base (often represented as a wide zone) the enemy flag while your own team flag is still at its starting position.

=== What is Sumo? ===
Stacked zone, often sharing the exact same location, and configured in a way that the zone decay conquers it. As all the players have to fight each other to get access to a place under the zones, the act often push out some players, which quickly die, in a manner that reminds sumo fighting.

== Network terminology ==
=== What is ping? ===
==== How do I find my ping? ===
=== What is lag? ===
== Multi-player related terminlogy ==
=== What is the ladder? ===
TODO
=== What is tk/team kill? ===
Often seen at the start of round with many players on a team, a team kill is when a player, by its action or lack of, cause the death of a teammate. Considered a serious lack of respect.

=== What is gank? ===
The act of overtaking a zone, for example 2 vs 1, without fighting.

= Hosting from the client =

== What is a client? What is a server? What's the difference? ==

Simply put, the game client is the program you run on your computer. The game server runs on somebody else's computer. The difference between the two is like the difference between, say, a lawyer and his client. The lawyer would be the server, the one who knows all about law and stuff. So the difference is just like in real life where the terms come from. The client requests a service from someone who serves. In our case, that service is a game that is served from a machine running a program called a "server", but if you requested the same service from a person in a casino, you'd still be running a game client.

== My client can be a server, though, it says so right here. ==

That's not a question. In any case, the game client can act as a server if you press "Host Game" from the Internet Game menu. So technically the client is a client/server hybrid, but let's not get too technical.

== So are all game servers just clients where people pressed "Host Game"? ==

No. This is where people get really confused, even to the point where they complain to server operators for doing exactly this thing. No, most, if not all, game servers available through the master server run a special version of the program that has no graphical display, and no player can play on directly. That is the server, commonly called the "dedicated server". You can run it too, if you'd like. Server operators chose to run this instead of the regular game client because it has a number of modifications that make it work better as a regular server, just like a mail server or a web server. It is more convenient and makes for a more reliable game server to do so.

= Troubleshooting =

== ArmagetronAd takes most or all the CPU time, how come? ==

AA takes all the CPU time it needs to simulate and render the scene as fast as you'll allow it to. There are two conditions under which that makes it take almost everything that is available:
* You set your graphics card driver not to wait for VSync. AA will then run at the highest possible framerate and therefore also use all the CPU time available. If you enable the FPS display in the HUD options and it shows more than 100 FPS, then that's your problem.
* When it tells your video card driver to update the screen now, the driver goes into a special CPU-hogging mode until the command is completed, even though all it does is sit around and wait. Both NVidia and ATI drivers are guilty of this. In the "Performance Tweaks" submenu of the graphics settings, there is the "Flush" menu item where you can tweak AA to not issue the problematic command (with possible side effects).

== ArmagetronAd is unplayable on my AMD Dual Core X2 System (might affect other Dual Cores) ==

Symptoms:
*The console displays "Timer hick up"
*FPS are usually ok (above 30).
*might only occur in network games
*Game performance is very bad

At least three solutions for this problem are available:
* To fix this problem use your TaskManager to set ArmagetronAd.exe's cpu affinity to a single CPU.
* Disable Cool & Quite in BIOS
* Install the necessary Microsoft Hotfixes and depending on your System you might have to update your bios and drivers too.

Links (TODO replace links with links to better instructions!):
* [http://support.microsoft.com/default.aspx?scid=KB;en-us;896256 Microsoft Knowledge base Article about Q896256]
* [http://www.amd.com/en-us/Processors/TechnicalResources/0,,30_182_871_13118,00.html AMD Dual Core Optimizer] The fix is similiar to Microsofts, but only fixes a small part of it. The Microsoft patch also addresses power saving bugs (of Windows XP).

*Details: Armagetron Advanced 0.2.8.x(?) or later uses the high precision timer on Windows if available. (TODO confirm) This can be a problem on the new Dual Core Systems or malfunctioning Multiprocessor System. The Timer of each core runs at different speeds which results in a jumping timer! The AMD X2 Systems are affected because they have two separate timers for each CPU (Intels Core Duo CPUs share a single timer). The AMD X2 Systems are only affected with Cool & Quite power saving enabled otherwise both cores have the same timer speed. The Windows kernel schedules Armagetron Advanced between both cores which results in a jumping timer form Armagetron perspective.

= When all else fail =
What to do when consulting the documents provided on this wiki and consulting this FAQ still doesnt provide an answer.

== The Forums ==
The [[forums.armagetronad.net|forum]] is a message board where discussion about ArmagetronAd often take part. A great many problems have been discussed and solved there.

The forums is usefull for discussion that spawns under days and weeks. Should you require more immediate assistance, try contacting us on IRC.

=== What should I do to increase my chance of getting help? ===
First of all, use the search capacities of the forum. It is easy and powerfull, and often will turn your answer without delays.

Second, get your information right. A simple task from you will save many troubles to anyone trying to help you. Be detailed! Nobodyknows your specific setup, nor can guess it.

== IRC channel ==
TODO
[[IRC_Channel]]

PlayingFAQ

2007-04-28T14:42:32Z

Philippeqc: Added Fortress and CTF to Terminology

This FAQ relates to issues about installing, configuring and mostly playing the game. For issues specific about hosting, consult the [[HostingFAQ|Hosting server FAQ]]

= Installing the Game =

== Where can I download Armagetron Advanced? ==

That depends on what version you want to get. The current stable version is always available [http://www.armagetronad.net/downloads.php on the main web page] or [http://sourceforge.net/project/showfiles.php?group_id=110997 sourceforge]. The latest testing version on [http://beta.armagetronad.net AABeta].

== How do I install... ==
=== on Windows? ===

Find the exe file you downloaded from the question and answer above this one and double click on it. Answer all dialog boxes with Yes/Next/Finish, whatever applies. On Windows XP, when you first run the game and try to connect to the Internet, a firewall warning will pop up; set it to allow access.

=== on Mac OS? ===

Mount the dmg file, and drag the Armagetron Advanced application to your hard-drive.

=== on Linux? ===

That depends on the distribution you are running. Check out the [[Linux Distribution Field Report]] for details.

== I'm running Linux, but don't know whether it is 32 or 64 bit. How can I find out? ==

On a console/terminal, type <pre>echo $MACHTYPE</pre>
If the output starts with x86_64, you have a 64 bit system. If it starts with i386, i486, i586 or i686 or possibly just x86 or x86_32, you have a 32 bit system. For anything else, we don't provide binary packages, you have to build from source. If the output is blank, the method failed. Then, see whether you have got the directory /usr/lib64 on your system. If yes, you have a 64 bit system, if no, it's 32 bit.

== I run a non-Linux UNIX or Linux on hardware not supported by your binary packages or the binaries don't work, how do I install from source? ==

Basically, you fetch the .tbz2 source archive and do as the superuser root
<pre>tar -xjf <path to the tbz2 source archive you just fetched>
cd armagetronad-<VERSION>
./configure
make
make install</pre>
The configure script will tell you what you are missing. In this mode, you always need the 'development' packages of our dependencies on most distributions.
The [[Linux Distribution Field Report]] may have some hints. Ask us if you get stuck.

== I'm working on a Linux PC administered by someone else and don't have the root password, can I still install the game? ==

Yes. The "package" binary files can install everything in your home directory. If you have to build from source, proceed as in the last FAQ,
but pass '--prefix=$HOME/usr' to ./configure and run the game later with
'~/usr/bin/armagetronad', or run the game from the build directory with 'make run'.

== So, should I get the latest stable or latest development version? ==

If you're really asking this question and are not just browsing the FAQ, get the latest stable version.

== Ok, but there are still so many different files to get, which one is right for me? ==

See [[FAQ#Terminology]] for choosing between Client and Server download. If in doubt, choose the Client. If you're running a PC with Windows, get the exe format, GCC or VC6 should not matter (please report it if only one of them works for you). If you've got a Mac, get the dmg; there is a special build available for versions 10.2.8 of OS X. If you're running 32 bit Intel Linux, get the x86(_32) "package". If you're running 64 bit AMD Linux, get the x86_64 "package".

== Where are the server sources? ==

The server sources are the same as the client sources. You compile a server from them by giving the additional command line option '--disable-glout' to ./configure.

= Configuring =
== I heard about moviepacks (graphical modifications), how do I install them? ==

See [[Customizing the game]].

== How do I use a map? ==

Read [[Playing Maps]], and please try to tell us why this question is asked so often and followed by "I read the whole wiki!".

= Terminology =
== What is rubber? ==
Rubber is a mecanism not unlike a cushion in front of your cycle that allows you to come closer to wall. The closer you move to a wall, the more rubber you consume. The faster you move when approching a wall, the more rubber you consume. If a cycle exceed its rubber limit at any time, it is considered to have crashed in the wall. Rubber normally is regained at a steady pace.

== What is grinding? ==
The act of running very close to a cycle trace or sometime an arena wall to benefit from the wall acceleration effect.

== What is double/tripple binding? ==
The act of associating multiple keys to the same action, such as turning. By pressing successively multiple keys it is possible to execute tight turns.

=== Is double/tripple binding a sin? ===
Though it is a side effect of the game support for different keyboard layout, some beleive that as it is supported by the game, it is a valid strategy. Others consider that is of bad taste and encourage players to learn to rapidly tap the same key instead.

== What is Fortress ==
Fortress is often seen in online playing. Each team has a zone assigned. The object is to capture the enemy zone while defending your own. It has been often observed that mildly skilled but effective team work outclass highly skilled but mildly organized team work on Fortress games.

== What is CTF/Capture The Flag ==
A game configuration where the objective it to capture and carry back to your base (often represented as a wide zone) the enemy flag while your own team flag is still at its starting position.

= Hosting from the client =

== What is a client? What is a server? What's the difference? ==

Simply put, the game client is the program you run on your computer. The game server runs on somebody else's computer. The difference between the two is like the difference between, say, a lawyer and his client. The lawyer would be the server, the one who knows all about law and stuff. So the difference is just like in real life where the terms come from. The client requests a service from someone who serves. In our case, that service is a game that is served from a machine running a program called a "server", but if you requested the same service from a person in a casino, you'd still be running a game client.

== My client can be a server, though, it says so right here. ==

That's not a question. In any case, the game client can act as a server if you press "Host Game" from the Internet Game menu. So technically the client is a client/server hybrid, but let's not get too technical.

== So are all game servers just clients where people pressed "Host Game"? ==

No. This is where people get really confused, even to the point where they complain to server operators for doing exactly this thing. No, most, if not all, game servers available through the master server run a special version of the program that has no graphical display, and no player can play on directly. That is the server, commonly called the "dedicated server". You can run it too, if you'd like. Server operators chose to run this instead of the regular game client because it has a number of modifications that make it work better as a regular server, just like a mail server or a web server. It is more convenient and makes for a more reliable game server to do so.

= Troubleshooting =

== ArmagetronAd takes most or all the CPU time, how come? ==

AA takes all the CPU time it needs to simulate and render the scene as fast as you'll allow it to. There are two conditions under which that makes it take almost everything that is available:
* You set your graphics card driver not to wait for VSync. AA will then run at the highest possible framerate and therefore also use all the CPU time available. If you enable the FPS display in the HUD options and it shows more than 100 FPS, then that's your problem.
* When it tells your video card driver to update the screen now, the driver goes into a special CPU-hogging mode until the command is completed, even though all it does is sit around and wait. Both NVidia and ATI drivers are guilty of this. In the "Performance Tweaks" submenu of the graphics settings, there is the "Flush" menu item where you can tweak AA to not issue the problematic command (with possible side effects).

== ArmagetronAd is unplayable on my AMD Dual Core X2 System (might affect other Dual Cores) ==

Symptoms:
*The console displays "Timer hick up"
*FPS are usually ok (above 30).
*might only occur in network games
*Game performance is very bad

At least three solutions for this problem are available:
* To fix this problem use your TaskManager to set ArmagetronAd.exe's cpu affinity to a single CPU.
* Disable Cool & Quite in BIOS
* Install the necessary Microsoft Hotfixes and depending on your System you might have to update your bios and drivers too.

Links (TODO replace links with links to better instructions!):
* [http://support.microsoft.com/default.aspx?scid=KB;en-us;896256 Microsoft Knowledge base Article about Q896256]
* [http://www.amd.com/en-us/Processors/TechnicalResources/0,,30_182_871_13118,00.html AMD Dual Core Optimizer] The fix is similiar to Microsofts, but only fixes a small part of it. The Microsoft patch also addresses power saving bugs (of Windows XP).

*Details: Armagetron Advanced 0.2.8.x(?) or later uses the high precision timer on Windows if available. (TODO confirm) This can be a problem on the new Dual Core Systems or malfunctioning Multiprocessor System. The Timer of each core runs at different speeds which results in a jumping timer! The AMD X2 Systems are affected because they have two separate timers for each CPU (Intels Core Duo CPUs share a single timer). The AMD X2 Systems are only affected with Cool & Quite power saving enabled otherwise both cores have the same timer speed. The Windows kernel schedules Armagetron Advanced between both cores which results in a jumping timer form Armagetron perspective.

= When all else fail =
What to do when consulting the documents provided on this wiki and consulting this FAQ still doesnt provide an answer.

== The Forums ==
The [[forums.armagetronad.net|forum]] is a message board where discussion about ArmagetronAd often take part. A great many problems have been discussed and solved there.

The forums is usefull for discussion that spawns under days and weeks. Should you require more immediate assistance, try contacting us on IRC.

=== What should I do to increase my chance of getting help? ===
First of all, use the search capacities of the forum. It is easy and powerfull, and often will turn your answer without delays.

Second, get your information right. A simple task from you will save many troubles to anyone trying to help you. Be detailed! Nobodyknows your specific setup, nor can guess it.

== IRC channel ==
TODO
[[IRC_Channel]]

MediaWiki:Sidebar

2007-04-28T14:24:52Z

Philippeqc: Was lacking the hosting getting started link

MediaWiki:Sidebar

2007-04-28T14:23:58Z

Philippeqc: Re-organisation to clearly differ between playing and hosting items

PlayingFAQ

2007-04-28T14:20:12Z

Philippeqc: /* = on Windows? */

This FAQ relates to issues about installing, configuring and mostly playing the game. For issues specific about hosting, consult the [[HostingFAQ|Hosting server FAQ]]

= Installing the Game =

== Where can I download Armagetron Advanced? ==

That depends on what version you want to get. The current stable version is always available [http://www.armagetronad.net/downloads.php on the main web page] or [http://sourceforge.net/project/showfiles.php?group_id=110997 sourceforge]. The latest testing version on [http://beta.armagetronad.net AABeta].

== How do I install... ==
=== on Windows? ===

Find the exe file you downloaded from the question and answer above this one and double click on it. Answer all dialog boxes with Yes/Next/Finish, whatever applies. On Windows XP, when you first run the game and try to connect to the Internet, a firewall warning will pop up; set it to allow access.

=== on Mac OS? ===

Mount the dmg file, and drag the Armagetron Advanced application to your hard-drive.

=== on Linux? ===

That depends on the distribution you are running. Check out the [[Linux Distribution Field Report]] for details.

== I'm running Linux, but don't know whether it is 32 or 64 bit. How can I find out? ==

On a console/terminal, type <pre>echo $MACHTYPE</pre>
If the output starts with x86_64, you have a 64 bit system. If it starts with i386, i486, i586 or i686 or possibly just x86 or x86_32, you have a 32 bit system. For anything else, we don't provide binary packages, you have to build from source. If the output is blank, the method failed. Then, see whether you have got the directory /usr/lib64 on your system. If yes, you have a 64 bit system, if no, it's 32 bit.

== I run a non-Linux UNIX or Linux on hardware not supported by your binary packages or the binaries don't work, how do I install from source? ==

Basically, you fetch the .tbz2 source archive and do as the superuser root
<pre>tar -xjf <path to the tbz2 source archive you just fetched>
cd armagetronad-<VERSION>
./configure
make
make install</pre>
The configure script will tell you what you are missing. In this mode, you always need the 'development' packages of our dependencies on most distributions.
The [[Linux Distribution Field Report]] may have some hints. Ask us if you get stuck.

== I'm working on a Linux PC administered by someone else and don't have the root password, can I still install the game? ==

Yes. The "package" binary files can install everything in your home directory. If you have to build from source, proceed as in the last FAQ,
but pass '--prefix=$HOME/usr' to ./configure and run the game later with
'~/usr/bin/armagetronad', or run the game from the build directory with 'make run'.

== So, should I get the latest stable or latest development version? ==

If you're really asking this question and are not just browsing the FAQ, get the latest stable version.

== Ok, but there are still so many different files to get, which one is right for me? ==

See [[FAQ#Terminology]] for choosing between Client and Server download. If in doubt, choose the Client. If you're running a PC with Windows, get the exe format, GCC or VC6 should not matter (please report it if only one of them works for you). If you've got a Mac, get the dmg; there is a special build available for versions 10.2.8 of OS X. If you're running 32 bit Intel Linux, get the x86(_32) "package". If you're running 64 bit AMD Linux, get the x86_64 "package".

== Where are the server sources? ==

The server sources are the same as the client sources. You compile a server from them by giving the additional command line option '--disable-glout' to ./configure.

= Configuring =
== I heard about moviepacks (graphical modifications), how do I install them? ==

See [[Customizing the game]].

== How do I use a map? ==

Read [[Playing Maps]], and please try to tell us why this question is asked so often and followed by "I read the whole wiki!".

= Terminology =
== What is rubber? ==
Rubber is a mecanism not unlike a cushion in front of your cycle that allows you to come closer to wall. The closer you move to a wall, the more rubber you consume. The faster you move when approching a wall, the more rubber you consume. If a cycle exceed its rubber limit at any time, it is considered to have crashed in the wall. Rubber normally is regained at a steady pace.

== What is grinding? ==
The act of running very close to a cycle trace or sometime an arena wall to benefit from the wall acceleration effect.

== What is double/tripple binding? ==
The act of associating multiple keys to the same action, such as turning. By pressing successively multiple keys it is possible to execute tight turns.

=== Is double/tripple binding a sin? ===
Though it is a side effect of the game support for different keyboard layout, some beleive that as it is supported by the game, it is a valid strategy. Others consider that is of bad taste and encourage players to learn to rapidly tap the same key instead.

= Hosting from the client =

== What is a client? What is a server? What's the difference? ==

Simply put, the game client is the program you run on your computer. The game server runs on somebody else's computer. The difference between the two is like the difference between, say, a lawyer and his client. The lawyer would be the server, the one who knows all about law and stuff. So the difference is just like in real life where the terms come from. The client requests a service from someone who serves. In our case, that service is a game that is served from a machine running a program called a "server", but if you requested the same service from a person in a casino, you'd still be running a game client.

== My client can be a server, though, it says so right here. ==

That's not a question. In any case, the game client can act as a server if you press "Host Game" from the Internet Game menu. So technically the client is a client/server hybrid, but let's not get too technical.

== So are all game servers just clients where people pressed "Host Game"? ==

No. This is where people get really confused, even to the point where they complain to server operators for doing exactly this thing. No, most, if not all, game servers available through the master server run a special version of the program that has no graphical display, and no player can play on directly. That is the server, commonly called the "dedicated server". You can run it too, if you'd like. Server operators chose to run this instead of the regular game client because it has a number of modifications that make it work better as a regular server, just like a mail server or a web server. It is more convenient and makes for a more reliable game server to do so.

= Troubleshooting =

== ArmagetronAd takes most or all the CPU time, how come? ==

AA takes all the CPU time it needs to simulate and render the scene as fast as you'll allow it to. There are two conditions under which that makes it take almost everything that is available:
* You set your graphics card driver not to wait for VSync. AA will then run at the highest possible framerate and therefore also use all the CPU time available. If you enable the FPS display in the HUD options and it shows more than 100 FPS, then that's your problem.
* When it tells your video card driver to update the screen now, the driver goes into a special CPU-hogging mode until the command is completed, even though all it does is sit around and wait. Both NVidia and ATI drivers are guilty of this. In the "Performance Tweaks" submenu of the graphics settings, there is the "Flush" menu item where you can tweak AA to not issue the problematic command (with possible side effects).

== ArmagetronAd is unplayable on my AMD Dual Core X2 System (might affect other Dual Cores) ==

Symptoms:
*The console displays "Timer hick up"
*FPS are usually ok (above 30).
*might only occur in network games
*Game performance is very bad

At least three solutions for this problem are available:
* To fix this problem use your TaskManager to set ArmagetronAd.exe's cpu affinity to a single CPU.
* Disable Cool & Quite in BIOS
* Install the necessary Microsoft Hotfixes and depending on your System you might have to update your bios and drivers too.

Links (TODO replace links with links to better instructions!):
* [http://support.microsoft.com/default.aspx?scid=KB;en-us;896256 Microsoft Knowledge base Article about Q896256]
* [http://www.amd.com/en-us/Processors/TechnicalResources/0,,30_182_871_13118,00.html AMD Dual Core Optimizer] The fix is similiar to Microsofts, but only fixes a small part of it. The Microsoft patch also addresses power saving bugs (of Windows XP).

*Details: Armagetron Advanced 0.2.8.x(?) or later uses the high precision timer on Windows if available. (TODO confirm) This can be a problem on the new Dual Core Systems or malfunctioning Multiprocessor System. The Timer of each core runs at different speeds which results in a jumping timer! The AMD X2 Systems are affected because they have two separate timers for each CPU (Intels Core Duo CPUs share a single timer). The AMD X2 Systems are only affected with Cool & Quite power saving enabled otherwise both cores have the same timer speed. The Windows kernel schedules Armagetron Advanced between both cores which results in a jumping timer form Armagetron perspective.

= When all else fail =
What to do when consulting the documents provided on this wiki and consulting this FAQ still doesnt provide an answer.

== The Forums ==
The [[forums.armagetronad.net|forum]] is a message board where discussion about ArmagetronAd often take part. A great many problems have been discussed and solved there.

The forums is usefull for discussion that spawns under days and weeks. Should you require more immediate assistance, try contacting us on IRC.

=== What should I do to increase my chance of getting help? ===
First of all, use the search capacities of the forum. It is easy and powerfull, and often will turn your answer without delays.

Second, get your information right. A simple task from you will save many troubles to anyone trying to help you. Be detailed! Nobodyknows your specific setup, nor can guess it.

== IRC channel ==
TODO
[[IRC_Channel]]

PlayingFAQ

2007-04-28T14:19:38Z

Philippeqc: First commit of FAQ specific to playing

This FAQ relates to issues about installing, configuring and mostly playing the game. For issues specific about hosting, consult the [[HostingFAQ|Hosting server FAQ]]

= Installing the Game =

== Where can I download Armagetron Advanced? ==

That depends on what version you want to get. The current stable version is always available [http://www.armagetronad.net/downloads.php on the main web page] or [http://sourceforge.net/project/showfiles.php?group_id=110997 sourceforge]. The latest testing version on [http://beta.armagetronad.net AABeta].

== How do I install... ==
=== on Windows? ==

Find the exe file you downloaded from the question and answer above this one and double click on it. Answer all dialog boxes with Yes/Next/Finish, whatever applies. On Windows XP, when you first run the game and try to connect to the Internet, a firewall warning will pop up; set it to allow access.

=== on Mac OS? ===

Mount the dmg file, and drag the Armagetron Advanced application to your hard-drive.

=== on Linux? ===

That depends on the distribution you are running. Check out the [[Linux Distribution Field Report]] for details.

== I'm running Linux, but don't know whether it is 32 or 64 bit. How can I find out? ==

On a console/terminal, type <pre>echo $MACHTYPE</pre>
If the output starts with x86_64, you have a 64 bit system. If it starts with i386, i486, i586 or i686 or possibly just x86 or x86_32, you have a 32 bit system. For anything else, we don't provide binary packages, you have to build from source. If the output is blank, the method failed. Then, see whether you have got the directory /usr/lib64 on your system. If yes, you have a 64 bit system, if no, it's 32 bit.

== I run a non-Linux UNIX or Linux on hardware not supported by your binary packages or the binaries don't work, how do I install from source? ==

Basically, you fetch the .tbz2 source archive and do as the superuser root
<pre>tar -xjf <path to the tbz2 source archive you just fetched>
cd armagetronad-<VERSION>
./configure
make
make install</pre>
The configure script will tell you what you are missing. In this mode, you always need the 'development' packages of our dependencies on most distributions.
The [[Linux Distribution Field Report]] may have some hints. Ask us if you get stuck.

== I'm working on a Linux PC administered by someone else and don't have the root password, can I still install the game? ==

Yes. The "package" binary files can install everything in your home directory. If you have to build from source, proceed as in the last FAQ,
but pass '--prefix=$HOME/usr' to ./configure and run the game later with
'~/usr/bin/armagetronad', or run the game from the build directory with 'make run'.

== So, should I get the latest stable or latest development version? ==

If you're really asking this question and are not just browsing the FAQ, get the latest stable version.

== Ok, but there are still so many different files to get, which one is right for me? ==

See [[FAQ#Terminology]] for choosing between Client and Server download. If in doubt, choose the Client. If you're running a PC with Windows, get the exe format, GCC or VC6 should not matter (please report it if only one of them works for you). If you've got a Mac, get the dmg; there is a special build available for versions 10.2.8 of OS X. If you're running 32 bit Intel Linux, get the x86(_32) "package". If you're running 64 bit AMD Linux, get the x86_64 "package".

== Where are the server sources? ==

The server sources are the same as the client sources. You compile a server from them by giving the additional command line option '--disable-glout' to ./configure.

= Configuring =
== I heard about moviepacks (graphical modifications), how do I install them? ==

See [[Customizing the game]].

== How do I use a map? ==

Read [[Playing Maps]], and please try to tell us why this question is asked so often and followed by "I read the whole wiki!".

= Terminology =
== What is rubber? ==
Rubber is a mecanism not unlike a cushion in front of your cycle that allows you to come closer to wall. The closer you move to a wall, the more rubber you consume. The faster you move when approching a wall, the more rubber you consume. If a cycle exceed its rubber limit at any time, it is considered to have crashed in the wall. Rubber normally is regained at a steady pace.

== What is grinding? ==
The act of running very close to a cycle trace or sometime an arena wall to benefit from the wall acceleration effect.

== What is double/tripple binding? ==
The act of associating multiple keys to the same action, such as turning. By pressing successively multiple keys it is possible to execute tight turns.

=== Is double/tripple binding a sin? ===
Though it is a side effect of the game support for different keyboard layout, some beleive that as it is supported by the game, it is a valid strategy. Others consider that is of bad taste and encourage players to learn to rapidly tap the same key instead.

= Hosting from the client =

== What is a client? What is a server? What's the difference? ==

Simply put, the game client is the program you run on your computer. The game server runs on somebody else's computer. The difference between the two is like the difference between, say, a lawyer and his client. The lawyer would be the server, the one who knows all about law and stuff. So the difference is just like in real life where the terms come from. The client requests a service from someone who serves. In our case, that service is a game that is served from a machine running a program called a "server", but if you requested the same service from a person in a casino, you'd still be running a game client.

== My client can be a server, though, it says so right here. ==

That's not a question. In any case, the game client can act as a server if you press "Host Game" from the Internet Game menu. So technically the client is a client/server hybrid, but let's not get too technical.

== So are all game servers just clients where people pressed "Host Game"? ==

No. This is where people get really confused, even to the point where they complain to server operators for doing exactly this thing. No, most, if not all, game servers available through the master server run a special version of the program that has no graphical display, and no player can play on directly. That is the server, commonly called the "dedicated server". You can run it too, if you'd like. Server operators chose to run this instead of the regular game client because it has a number of modifications that make it work better as a regular server, just like a mail server or a web server. It is more convenient and makes for a more reliable game server to do so.

= Troubleshooting =

== ArmagetronAd takes most or all the CPU time, how come? ==

AA takes all the CPU time it needs to simulate and render the scene as fast as you'll allow it to. There are two conditions under which that makes it take almost everything that is available:
* You set your graphics card driver not to wait for VSync. AA will then run at the highest possible framerate and therefore also use all the CPU time available. If you enable the FPS display in the HUD options and it shows more than 100 FPS, then that's your problem.
* When it tells your video card driver to update the screen now, the driver goes into a special CPU-hogging mode until the command is completed, even though all it does is sit around and wait. Both NVidia and ATI drivers are guilty of this. In the "Performance Tweaks" submenu of the graphics settings, there is the "Flush" menu item where you can tweak AA to not issue the problematic command (with possible side effects).

== ArmagetronAd is unplayable on my AMD Dual Core X2 System (might affect other Dual Cores) ==

Symptoms:
*The console displays "Timer hick up"
*FPS are usually ok (above 30).
*might only occur in network games
*Game performance is very bad

At least three solutions for this problem are available:
* To fix this problem use your TaskManager to set ArmagetronAd.exe's cpu affinity to a single CPU.
* Disable Cool & Quite in BIOS
* Install the necessary Microsoft Hotfixes and depending on your System you might have to update your bios and drivers too.

Links (TODO replace links with links to better instructions!):
* [http://support.microsoft.com/default.aspx?scid=KB;en-us;896256 Microsoft Knowledge base Article about Q896256]
* [http://www.amd.com/en-us/Processors/TechnicalResources/0,,30_182_871_13118,00.html AMD Dual Core Optimizer] The fix is similiar to Microsofts, but only fixes a small part of it. The Microsoft patch also addresses power saving bugs (of Windows XP).

*Details: Armagetron Advanced 0.2.8.x(?) or later uses the high precision timer on Windows if available. (TODO confirm) This can be a problem on the new Dual Core Systems or malfunctioning Multiprocessor System. The Timer of each core runs at different speeds which results in a jumping timer! The AMD X2 Systems are affected because they have two separate timers for each CPU (Intels Core Duo CPUs share a single timer). The AMD X2 Systems are only affected with Cool & Quite power saving enabled otherwise both cores have the same timer speed. The Windows kernel schedules Armagetron Advanced between both cores which results in a jumping timer form Armagetron perspective.

= When all else fail =
What to do when consulting the documents provided on this wiki and consulting this FAQ still doesnt provide an answer.

== The Forums ==
The [[forums.armagetronad.net|forum]] is a message board where discussion about ArmagetronAd often take part. A great many problems have been discussed and solved there.

The forums is usefull for discussion that spawns under days and weeks. Should you require more immediate assistance, try contacting us on IRC.

=== What should I do to increase my chance of getting help? ===
First of all, use the search capacities of the forum. It is easy and powerfull, and often will turn your answer without delays.

Second, get your information right. A simple task from you will save many troubles to anyone trying to help you. Be detailed! Nobodyknows your specific setup, nor can guess it.

== IRC channel ==
TODO
[[IRC_Channel]]

HostingFAQ

2007-04-28T14:19:14Z

Philippeqc: Commit of faq specific for hosting

This FAQ relates to issues specific to installing, configuring and administrating servers. For issues about playing the game or generally non-server specific, consult the [[PlayingFAQ|Playing FAQ]]

= Running a Server =

== Which should I run? The client in hosting mode, or the dedicated server? ==

Generally this depends on how long you want the server to run at a time. If you just want it running when you're playing, run the client in hosting mode, it's easier to deal with. If you're running at a LAN party, you might also want to run the client in hosting mode. But if you want to run a server that operates on the internet, reports to the master server, and runs 24 hours a day, 7 days a week (8 days in a leap week), then you should run the dedicated server.

More information can be found in the [[PlayingFAQ|playing FAQ]] about the difference between client hosting and dedicated server hosting.

== How to start the dedicated server ==

=== ... on Linux/Unix ===
This section needs to be written.

=== ... on MS Windows ===
This section needs to be written.

=== ... on Max OS X ===
There is a very easy way to run the dedicated server on Max OS:
# Open up Terminal ( Macintosh HD -> Applications -> Utilities -> Terminal )
# In the terminal window type (without the quotes & don't forget the space): 'cd '
# Drag the 'Armagetron Advanced Dedicated' folder into the terminal window
# Press Enter
# Drag the 'armagetronad-dedicated' file ( Armagetron Advanced Dedicated -> armagetronad-dedicated ) into the Terminal window
# Press Enter

== I've started the dedicated server, but I don't see it listed in the master server. What's wrong? ==

You need to add the line <pre>TALK_TO_MASTER 1</pre> to your configuration files to publish your server on the internet. The server needs to be up one or two minutes before it can appear in the server browser, the master server checks whether it is reachable before it gets published.

== I did that, but my server still is not listed. What else can be wrong? ==

Get your server's IP address; if it is running on the same computer you use for browsing right now, check http://www.whatismyip.com to get it. Fire up the Armagetronad client, enter the internet server browser, wait half a minute, exit the server browser, enter it again, and look for your server's IP. If it appears (having the list sorted by server name my pressing "right" once helps), you really want to ask [[FAQ#I see my server's IP in the master server browser, but it says "Unreachable". What's wrong?]]. Otherwise, this is the right section for you. This is also the right section if you see your server just fine, but nobody else does.

If your server is connected to the internet via a router box and not directly via a "modem" of sorts, it is likely that network packages from the internet can't get to your server because the router blocks them. You need to tell your router to forward UDP port 4534 (or whatever SERVER_PORT is set to) to the server. On [http://www.portforward.com], there are nice instructions how to do that for a lot of router models. If the UDP port 4534 thing confuses you, just follow [http://www.portforward.com/english/applications/port_forwarding/F-22Lightning3/F-22Lightning3index.htm these instructions for a different game] that uses a similar connection method. Of course, you need to find out what router model you have, some under-the-table-crawling and cable following may be required for that if you can't remember what you bought or got the router from your ISP.

== My server still isn't listed. This sucks, it's hard to find out where the problem is. What can I do? ==

See [[Server_Administration_Guide#Firewalls|Short Firewall Troubleshooting]] and [[Server_Administration_Guide#Port_forwarding|Short Port Forwarding Troubleshooting]], if this does not solve your problem, read on.

You can ask people to connect to your server directly by giving them [http://www.whatismyip.com your IP] and the port your server is running on. A perfect place to ask is our [[IRC_Channel|IRC]] channel(#armagetron on irc.freenode.org) because you'll get a real-time answer there. Less perfect is the support section of the [http://forums.armagetronad.net forums]; you'll need to make sure your server is up and running when people read your post, which can be well 48 hours after you post it. If people can't connect to your server that way, it means you probably need to set up port forwarding (see last question) correctly.

== Gaaa! This FAQ is useless! Can't YOU help me get my server up? ==

Sure. Post your trouble on the support section of the [http://forums.armagetronad.net forums]. Be sure to
* describe exactly what you already tried, and please don't just say "everything the FAQ told me"
* state the [http://www.whatismyip.com your IP] your server is running on, we need that to check the master server's logs
* state your port if you modified SERVER_PORT
* state your server's name, others need that to check for your server in the browser
* post the complete output of your server from the moment it is started
Without that info, we can't help.

Setting up a server is complicated sometimes; don't be too shy to admit you didn't understand some part of the process. A lot of trouble comes from people silently skipping steps they don't understand.

== I see my server's IP in the master server browser, but it says "Unreachable". What's wrong? ==

Probably the answer is "Nothing is wrong". A bug in some routers or the NAT specifications (at least, that's how Z-Man sees this) causes the response to the server query packet used in the server browser to come from the LAN address of your server, not the public address it was sent to. The packet gets ignored then. A workaround will be available in 0.2.8.3, but right now, that means most people can't see their own servers. Come to the IRC channel (#armagetron on irc.freenode.org) and ask people there if they can see your server.

= When all else fail =
What to do when consulting the documents provided on this wiki and consulting this FAQ still doesnt provide an answer.

== The Forums ==
The [[forums.armagetronad.net|forum]] is a message board where discussion about ArmagetronAd often take part. A great many problems have been discussed and solved there.

The forums is usefull for discussion that spawns under days and weeks. Should you require more immediate assistance, try contacting us on IRC.

=== What should I do to increase my chance of getting help? ===
First of all, use the search capacities of the forum. It is easy and powerfull, and often will turn your answer without delays.

Second, get your information right. A simple task from you will save many troubles to anyone trying to help you. Be detailed! Nobodyknows your specific setup, nor can guess it.

== IRC channel ==
TODO
[[IRC_Channel]]

PlayingGettingStarted

2007-04-28T11:18:06Z

Philippeqc: Original commit

{{Sections}} 

This document attempts to give the minimal set of knowledge required for a player to enjoy the game.

= Getting ready to play =
Once you start ArmagetronAd, the game will be launched in fullscreen. To be able to follow this document, press "f" to toggle between fullscreen and windowed mode.

== Select your preferred languages ==
Once the game is started, you will be asked to select your preferred language. Use the right and left arrows to change it. The secondary language is used when a translated text cannot be found in the primary language. Once selected, use the up and down arrows to move to Accept and press return.

== Hardware detection ==
A screen indicate the 3D hardware found. It us usually properly detected, so fell free to press return to continue. Even if not detected properly, you will still be able to play the game.
You should now be at the main menu, labeled "Armagetron Advance" with the items "Game", "Player Setup", "System Setup", "About" and "Exit Game". Remember this menu, it will be the navigation reference.

== How to move in the game ==
Before launching into play, here is the minimal keys you will need to know:
*To turn left, press either z, y or w
*To turn right, press x
*While playing, you can always activate the menu by pressing ESC. To stop playing, navigate to "Leave Grid"
*To navigating back to the main menu after leaving the grid, press ESC once more.
On most keyboard on the world, it should allow you to use the left most letter on the bottom row of your keyboard to turn left, and the second left most key to turn right.

== Start playing ==
In its basic form, the game will present you with battling AI. Avoid colliding with the various walls and use the trace you leave behind you to trap and kill the AI. After a few battles, leave the grid and return to this document.
To start playing, from the main menu:
*Select the first item, labeled "Game", and press enter.
*Select the first item, labeled "Local Game", in the new menu, and press enter.

= Rubber and Grinding =
Battling AI at near constant speed is quite a challenge, but barely allows to overtake a fleeting enemy or to sceal another in a closed area for them to die. These strategies and more are enabled through the usage of rubber and the technique of grinding. Together, they constitute the base of the play.

== [[Rubber]] ==
Rubber allows you to press yourself to a wall, preventing you from crashing into it for a very short period.

Rubber allows a cycle to near itself to a wall, as if a cushion was laid before it. Press too hard on the cushion and you hit the wall. Turn while you are pressing on it, and you will yourself tightly placed agains the wall, leaving little place for someone to follow.

Each time a cycle uses this cushion, its rubber reserve are consumed. If it reaches its limit, it hits the wall it was pressing on. Coming to a wall at greater speed with consume rubber faster, as pressing to end up tighter with the wall. Normally the cycle will regenerate its own rubber reserve with time.

== Grinding ==
Running a cycle parallel to nearby traces and sometimes walls will accelerate the cycle. The closer you are, the greater the acceleration you get. Useful when attempting to overtake an enemy. Driving between 2 traces will provide greater acceleration.

Use your gained speed advantage promptly, as with time your cycle will return to its regular speed. Each turn you make will further slow you.

== Learning Rubber and Grinding ==
The default setting of the game give very little rubber. To help you experiment with rubber, we will raise its limit. We will also lower the basic speed for the cycle so you can more carefully observe how rubber is consumed and practice grinding walls.

To change game settings, the console is used. The console is a simple text input field that allows you to redefine all the parameters of the game. It is accessible both during play and in any menu. To activate the console, press either the ^ key or the ` key. The text "Con:" should appear the bottom of the screen. There, type the parameter to affect followed by the value desired. The console is case insensitive, so typing "Cycle_speed 10", "cycle_speed 10" or CYCLE_SPEED 10" will produce the same result.

Now activate the console and write, without the quotes:
"cycle_speed 10"
This will reduce the speed at which the cycle tend to move, giving you more time to think and maneuver. Feel free to adjust to your preference.

The rubber meter is presented on the lower left part of the screen when you are playing. Note that by default the bar goes from 0 to 1, quite a small reserve of rubber. To change this, you will need to pass the command "cycle_rubber" (without the quotes) followed by a number.

Activate the console and write, without the quotes:
"cycle_rubber 10"
This will raise the rubber available to all the cycles. Feel free to adjust to your preference.

Once you have changed the cycle_speed and cycle_rubber settings, practice pressing your cycle agains traces and wall, and getting acceleration by grinding them. In the basic setup, no acceleration is gained from grinding the outer rim even though rubber is consumed when you press on it. Experiment and learn from those settings, but do not to used to them. Such a generous amount of rubber is not often seen on multi-player games.

It is to be noted that setting changes through the use of the console are not saved. When restarting the game, the original values will be restored.

=Zones=
Zones are the game elements used in ArmagetronAd. As zones can offer perculiar behavior, this section will give you a rough introduction to them.

== Win and Death Zones ==
The win and death zones offers instant win and instant death to any cycle who enters them.

To try them, you will be required to load a new map. To do this, from the console type map_file followed by the name of the map to be used. In this instance, the file name is AATeam/demo/win-1.aamap.xml, so at the console, type "map_file AATeam/demo/win-1.aamap.xml", without the quotes. If you dont have this map already on your system, the game will attempt to download it automatically, so you should probably be connected to Internet when you attempt this.

On the next round, the arena should hold a green win zone and a red death zone. Experiment with either zones. Note that for your convenience that there are no AI, as they are too subject to the zones. Also, your trace is not of a finite length, allowing you move freedom of movement.

== Conquest Zones ==
Zones can be configured so it is not the action of entering them that produce the effect, but rather by the cycle being inside the zone, often or a certain amount of time.

Using the console, type "map_file AATeam/demo/conquest-a-1.aamap.xml". This will load a map containing a single zone. You have to pass a total of 12 seconds in it in total to conquer it. As you conquer it, you should see it turning faster and faster onto itself, giving you a visual representation of the state of the conquest. Once conquered, the zone collapse and the round is won.

Now load the map named "AATeam/demo/conquest-b-1.aamap.xml". This time, your conquest of the zone gets eroded with time, meaning that if a partially conquered zone is left alone for a while, it will return to its original status and you will have to re start the conquest. Do not worry, the conquest rate is in your favor at a rate of 4:1. It would take 4 seconds outside of the zone to loose the conquest generated from 1 second inside the zone. Experiment with this zone until you are comfortable with the conquest and decay concepts. Note that when totally left alone, the zone simply turn at its lowerst original rate, indicating that the conquest of this zone has been reset to nothing.

This time the zone is configured in a way that it is the natural decay of the zone that conquers it. Left alone, the zone will naturally conquer itself and you will lose. To prevent this, passing time inside the zone will actually annulate the decay. Again, the odds are in your favor in a 4:1 rate. Each second passed inside will annulate 4 seconds of natural decay. So keep on your guards and do not wander too far. This map is named "AATeam/demo/conquest-c-1.aamap.xml".

In multi-player setups, the following names can be encountered:
- Fortress: Each team have to defend their own zone while trying to conquer the enemy's. The decay usually move the status of the zone toward non conquered.
- Sumo: Multiple zones surimposed with decay set to conquer the zone. Each player has to fight the other players for some space under the common zones in to prevent his own zone of being conquered, or face certain death.

= Multi player =
Beside rudimentary AI, the ArmagetronAd games allow you to compete again other player on the same computer, on a LAN or over Internet.

== Connecting to a LAN server ==
For the main menu, navigate to "Game". There select "Network Game" and then "LAN Game". The game will query the local network (LAN) for any server, and present them in a list.

It is possible to use the client to host a server. From the list of local servers, click on "Host Game" and then "Host Network Game". Your copy of ArmagetronAd will allow you to server as a server for other to connect to, while letting you join in the action. The server will run until you exit the menu.

== Connecting to an Internet server ==
For the main menu, navigate to "Game". There select "Network Game" followed by "Internet Game". The application will start querying different servers from all around the world and present you with a list of servers with a few details. It is strongly advised that you read the short description presented for each server at the bottom of your screen. It often gives you valuable information about the server you are about to join.

Selecting one will connect you to it. More information might be presented to you during the connection operation. Read it carefully as it often describe the type of game you are about to try. And dont forget to communicate with the other players present using the chat capacity of the game, available on the 's' key.

Internet access is of course required for this.

== Type of play ==
The dynamic of the game will be decided by the settings in use. These settings and resulting combinations are too various to cover here. Also, when connecting to a LAN based server or an Internet based one, the server will decide of the configuration.

One rough categorization is possible: Free for all versus Team Play.

When in doubt, do not hesitate to communicate with the other players. Chat capacity is associated with the key 's'.

=== Free for all ===
In this type of play, all the players compete agains each others. It is left to you to make the best use of your cunning, reflexes, experience and even ad-hoc alliances to raise yourself to the top.

=== Team Play ===
In this type of play, cooperation between members of a team will usually produce better results than having everybody trying to accomplish the same goals. Often, individualism will actually harm your team mates, and incite their fury toward you. Be observant when joining a server, your team mates might be relying on you and ignoring them might cause great troubles.

Zones v2

2007-04-17T18:22:15Z

Philippeqc: Updated the formating of the examples

== Preamble ==

You will note that the examples below dont sound that fun. I'd like to think its because my creative power went into building a good system, and now there is little left to put on examples. But I'm sure you will find interesting ways to use the mechanisms in here. My goal with this was to be able to have zones that could have different effect depending on who would use them. For example, having a fortress that team Blue could conquer, but only 2 of the players of team Red could actually defend. The other Red could still circle it and block the enemy, but they could not lower its value actively. Everything described here works. There are still glitches small and not so small. The code is in my private branch, but feel free to grab a local copy if you want to play with it.

The format is anything but closed. I'd like to hear your opinion on it too (yes it is a PITA to write, but if you have a constructive remark about that, I'd like to know it)

-ph

Most of this is from a forum post by philippeqc. I reworded some stuff and formatted a bit for the wiki. Some stuff might have gotten lost or reworded wrongly so cross refrence with the post if the wording gets hazy and/or just to double check @ http://forums.armagetronad.net/viewtopic.php?p=77491#77491. Some stuff might be in the wrong place. --[[User:Your mom|Your mom]] 11:42, 30 July 2006 (CDT)

== Zone element ==

Individual zones may have a name. Entering a name is optional, and re-using a name will be considered to mean "add/override with the following information". Dont rely on this behavior for anything, in other words '''Dont re-use the same name.''' All zones need a shape defined. At the moment only one shape exists, the ShapeCircle. More shapes are planned in the future and are ToDo

Ex:
<Zone name="redFortress">
<ShapeCircle radius="29">
<Point x="50" y="50"/>
<Color red="0.988" green="0.059" blue="0.753" />
</ShapeCircle>

</Zone>

== Rules and EffectGroups ==

A zone can have up to 4 different "rules" (need better name ToDo). Enter, Inside, Leave, Outside. It classifies when the held elements should be inspected. Inside each of the "rules", one can define EffectGroups. EffectGroup(s) are the fundamental building blocks of this new system. It associate owners with consequences. Note that ownership is part of effectGroup(s), ''NOT'' the zone. So a zone may have multiple effectGroup(s), each with unique or interlapping owners. There are 2 types of owners: owner (individuals) and ownerTeam (every member of a team). It is possible to define 0,1 or many for each items.

''HACK:
ATM, only owner is supported, and it must be an exact match with a
player's name to associated the effect.
The real solution will translate the labels used to players based on
some other logic depending on "game type". This is to be defined
later.''

''HACK:
It should be possible to associate individual with teams in some part
of the map. In this text, I will user lowercase color name + number for
individual, and uppercase color name for teams. So the individual
red1, red7 and red90210 should be considered as players of the team
RED. I will also allow myself to insert _description_ in names to help
the reader when appropriate.''

Ex:
<pre><Zone name="redFortress">
<ShapeCircle ...>
...
</ShapeCircle>
<Enter>
<EffectGroup owner="red1,red2" ownerTeam="BLUE,YELLOW">
...
</EffectGroup>
<EffectGroup owner="" ownerTeam="RED">
...
</EffectGroup>
</Enter>
<Leave>
<EffectGroup owner="green7" ownerTeam="">
...
</EffectGroup>
</Leave>
</Zone></pre>

== User element ==

Inside the EffectGroup, elements User are set. This element offers different readily made rules to determine if a player in the "rule" condition for the zone, is allowed to be considered a user. This is decided based from the following information: owner, ownerTeam and the player matching the rule. Two other conditions can be set for a player to be considered a valid user: positive and marked. These element are of type Triad. The possible values are true, false and ignore. We will come back to these later. If the current player is found to be valid, the processing will continue to the child elements. Otherwise, nothing happens. A valid user will be called triggerer from now on.

The following users are currently implemented:
* all: Anybody can be considered a valid user,
* owner: only a player direcly in the owner list can be considered a valid user,
* ownerTeam: only a player member of a team mentionned in the ownerTeam list can be considered a valid user,
* allButOwner only a player NOT mentioned in the owner list can be considered a valid user,
* allButTeamOwner only a player NOT member of a team mentioned in the ownerTeam list can be considered a valid user, (TO COME, NOT IMPLEMENTED YET)
* anotherTeammate only a player in the same team as one of the individual owner can be considered a valid user (TO COME, NOT IMPLEMENTED YET)

Ex:
<pre><EffectGroup owner="red1,red2" ownerTeam="BLUE,YELLOW">
<User user="all" >
... 
</User>
<User user="allButOwner" >
... 
</User>
</EffectGroup>
<EffectGroup owner="" ownerTeam="RED">
<User user="owner" >
... 
</User>
<User user="ownerTeam" >
... 
</User>
</EffectGroup></pre>

Inside a User element, it is possible to make use of 3 different
elements. Target, ZoneInfluence and MonitorInfluence.

=== Target ===

The Target element will take the information of the valid user, and
calculate who will receive the effect of the zone. Depending on the
described target rule to use and the state of the game, the calculated
target can be from no players to everybody in game.

The currently implemented target rules are :

*self : the triggerer himself
*teammate : a randomly selected teammate of the triggerer
*team : all the member of the team of the triggerer
*all : everybody in the game
*allButSelf : everybody in the game BUT the triggerer
*another : a randomly selected player that is not the triggerer
*ownerTeamTeammate : a randomly selected player member of one of the teams mentioned in the teamOwner list.
*owner : all the players owning the effectGroup
*ownerteam : all the players member of the team owning the effectGroup
*ownerteamteammate : a single player member from a owning team
*anydead : any single dead player
*alldead : all the dead players
*singledeadowner : one of the owners that is dead
*anotherteammatedead : a single player member of the team of the triggerer that is dead
*anothernotteammatedead : a single player that is not member of the team of the triggerer and that is dead
<nowiki>
*Much more are detailed in a document named zones.txt hidden somewhere
on the forum.</nowiki>

Once the targets are selected, they all are applied all the effects
described under the Target element.

Nota: In a User element, it is possible to user any amount of Target,
ZoneInfluence and MonitorInfluence.

Ex:
<pre><User user="ownerTeam" >
<Target target="self">
... 
</Target>
<Target target="another">
... 
</Target>
</User></pre>

== Effect ==

The Effect element hold specific effects. The attribute count can limit the number of times a specific effect can be used. By default, the count is unlimited.

valid effect currently implemented are:
*win : win the round
*death : kill the target(s)
*point : give points to the target(s)
*respawnplayer : Respawns target(s)
*brakerecharge : Refills target(s) cycle brake
*rubberrecharge : Refills target(s) cycle rubber
*setting : has 2 attributes ; settingName & settingValue

new attribute for all effects: description

When the effect is triggered, the message is displayed on the console. Somehow I'm not able to do the "parsing" similar to when points are given (player x received y points because he is sooo leet). That should come.

When point is use, an attribute score will mention the amount of point
to give.

<pre><Target target="self">
<Effect effect="point" score="3" count="2">
... 
</Effect>
<Effect ...>
...
</Effect>
</Target></pre>

ex:
<pre><Effect effect="setting" settingName="cycle_speed" settingValue="100" /></pre>

=== ZoneInfluence ===

Inside the User element, the element ZoneInfluence and MonitorInfluence are use to affect back game element. ZoneInfluence allows to affect a zone in play. The name attribute must match exactly a zone's name elsewhere in the map.

The possible thing to affect on a zone are:
*Rotation with attribute rotationSpeed and rotationAcceleration
*Radius with attribute radius
*Point with attribute x and y

Ex:
<pre><User user="all">
<ZoneInfluence name="redFortress">
<Rotation rotationSpeed="1" rotationAcceleration="-0.2" />
<Radius radius="50"/>
<Point x="100" y="100" />
</ZoneInfluence>
<ZoneInfluence name="blueFortress">
<Radius radius="-1" />
</ZoneInfluence>
</User></pre>

=== MonitorInfluence ===

Monitors are simple valiables that can be affected by interaction with different zones. The old "fortress" zone is to be considered as a zone where being inside slowly influence its monitor. Monitors are to be inserted in the map at the same level as Zone. Monitor have a name that is used to refer to from the MonitorInfluence, a initial value, and a drift, that slowly move the value, low and high, which clamp the monitor's value between their owns.

<pre><Field>
...
<Monitor name="monitorFortressRed" init="0.2" drift="-0.1" low="0.0" high="1.0">
... 
</Monitor>
...
</Field></pre>

The Monitor as different rules that can be used to inspect and react on its value. They are OnOver, OnUnder, InRange and OutsideRange. Any amount of rules can be used in a monitor.

*OnOver has an attribute named value and will be used when the monitor's value exceed it,
*OnUnder has an attribute named value and will be used when the monitor's value is under it,
*InRange has attributes low and high and will be used when the monitor's value fall between both
*OutRange has attributes low and high and will be used when the monitor's value is not falling between both

The monitors' rules are similar to the zone's rule in that they hold EffectGroups that are inspected when the rule conditions are met.

What differs a Monitor from a zone regarding to EffectGroup is who are considered players to be inspected as users. Anyone who contributed to a monitor during a game time step is registered, along with if the contribution was positive (conquering) or negative (defending), and if they where marked. This information is passed along up to the User element. There it can be used on additional tests to determine a valid user.

<pre><Monitor name="monitorFortressRed" init="0.2" drift="-0.1" low="0.0" high="1.0">
<OnOver value="1.0">
<EffectGroup ...>
<User user="..." positive="true" marked="ignore">
... 
</User>
<User ...>
...
</User>
</EffectGroup>
</OnOver>
</Monitor></pre>

==== User ====

The User element always have these attributes, but outside of an EffectGroup from a Monitor, this is always ignored.

MonitorInfluence element is the one where one describe how to affect a monitor. It has an attribute name to point to the monitor to influence. It has a marked attribute which is a Triad, ie: allows for the value true, false or ignore. Players using this MonitorInfluence will carry this mark into their contribution to the monitor.

There are 3 ways to influence the value of a monitor:
*1 the attribute influenceSlide will affect the monitor's value in a fashion proportional to the time passed in the zone. This is how the classical fortress operates. This is the same as saying influenceSlide * duration of the current game time step.
*2 the attribute influenceAdd will affect the monitor's value by this amount. This is NOT affected by time.
*3 the attribute influenceSet will set the monitor's value immediatly to this value.

These can of course be used simulteanously. It is important here that
attributes that are not desired should not be defined, rather than
defined at a default value.

Ex:
<pre><User ...>
...
<MonitorInfluence name="monitorFortressRed" marked="true" influenceSlide="0.5"/>

<MonitorInfluence name="monitorFortressGreen" marked="true" influenceAdd="2"/>

<MonitorInfluence name="monitorFortressBlue" influenceSet="0.0" />

</User></pre>

== Quiz ==
Respond on the forums after reading through this entire page with any ideas or questions of your own.(Optional)

1 Are you able to express some new ideas with it?

2 Do you see items that could be added, either now or as a later
version that could improve its value?

3 Anything else?

-ph

== Examples ==
An example might help you get through the mess of the description

Its blue vs red Each team has zones in opposing corners which are interconnected. As they get conquered, they jump toward the center.

For your convenience:
MAP_FILE philippeqc/zone/DoubleZoneJumping-1.aamap.xml

Code:
<pre><?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map-0.3.1-a.dtd">
<Resource type="aamap" name="DoubleZoneJumping" version="1" author="philippeqc" category="zone">


<pre> <Map version="2">

<World>
<Field>
<Spawn x="50" y="245" xdir="1" ydir="0" />
<Spawn x="450" y="255" 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>
<Zone name="zRed1">
<ShapeCircle radius="49" red="1.0" green="0.1" blue="0.1">
<Point x="50" y="50"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="-0.25" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="0.5" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Zone name="zRed2">
<ShapeCircle radius="49" red="1.0" green="0.1" blue="0.1">
<Point x="450" y="450"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="-0.25" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="0.5" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Monitor name="mRed" init="0.0" drift="-0.1" >
<InRange low="0.0" high="0.30">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="100" y="100"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="400" y="400"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.4" high="0.60">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="150" y="150"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="350" y="350"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.7" high="1.0">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="200" y="200"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="300" y="300"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<OnOver value="1">
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<Target target="self">
<Effect effect="point" count="2" score="7"/>
</Target>
<ZoneInfluence name="zRed1">
<Radius radius="-1" />
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Radius radius="-1" />
</ZoneInfluence>
</User>
</EffectGroup>
</OnOver>
</Monitor>



<Zone name="zBlue1">
<ShapeCircle radius="49" red="0.10" green="0.10" blue="1.0">
<Point x="50" y="450"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="0.3" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="-0.3" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Zone name="zBlue2">
<ShapeCircle radius="49" red="0.10" green="0.10" blue="1.0">
<Point x="450" y="50"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="0.3" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="-0.3" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Monitor name="mBlue" init="0.0" drift="-0.1" >
<InRange low="0.0" high="0.30">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="100" y="400"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="400" y="100"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.4" high="0.60">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="150" y="350"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="350" y="150"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.7" high="1.0">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="200" y="300"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="300" y="200"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<OnOver value="1">
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<Target target="self">
<Effect effect="point" count="2" score="7"/>
</Target>
<ZoneInfluence name="zBlue1">
<Radius radius="-1" />
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Radius radius="-1" />
</ZoneInfluence>
</User>
</EffectGroup>
</OnOver>
</Monitor>

</Field>
</World>
</Map>
</Resource></pre>

Ex:
Code:

<pre><Zone name="redFortress">
<ShapeCircle radius="29" red="0.988" green="0.059" blue="0.753"/>
<Point x="50" y="50"/>
</ShapeCircle>
...
</Zone></pre>

is now

Code:
<pre><Zone name="redFortress">
<ShapeCircle radius="29" >
<Color red="0.988" green="0.059" blue="0.753" alpha="0.0"/>
<Point x="50" y="50"/>
</ShapeCircle>
...
</Zone></pre>

Also added Color as a child of ZoneInfluence:
Code:
<pre> <ZoneInfluence name="blueFortress">
<Radius radius="-1" />
<Color red="0.988" green="0.059" blue="0.753" alpha="0.0"/>
</ZoneInfluence></pre>

This map has 4 zones that activate one another. Only one should be present, and when not there, they are put outside of the arena. They are activated in a crossed fashion.

Code:
<pre><?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map.dtd">
<Resource type="aamap" name="zone" version="d" author="philippeqc" category="">

<Map version="2">

<World>
<Field>
<Spawn x="50" y="245" xdir="1" ydir="0" />
<Spawn x="450" y="255" 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>

<Zone name="SW">
<ShapeCircle radius="29" >
<Point x="50" y="50"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="SW">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="NE">
<Point x="450" y="450"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="NE">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="NE">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="NW">
<Point x="50" y="450"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="NW">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="NW">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="SE">
<Point x="450" y="50"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="SE">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="SE">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="SW">
<Point x="50" y="50"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>
</Field>
</World>
</Map>
</Resource></pre>

Its a really crude idea, that has been retaken in a much better way by wrt. But it show some things that can be done (influencing individual zones, and using ZoneInfluence from one zone to affect another).

Targets have a count:
Code:
The target has an attribute count that will limit the number of time
it is called. Not having the attribute or setting it to -1 means infinite.

-ph

Zones v2

2007-04-17T18:19:57Z

Philippeqc: Updated the formating of the examples

== Preamble ==

You will note that the examples below dont sound that fun. I'd like to think its because my creative power went into building a good system, and now there is little left to put on examples. But I'm sure you will find interesting ways to use the mechanisms in here. My goal with this was to be able to have zones that could have different effect depending on who would use them. For example, having a fortress that team Blue could conquer, but only 2 of the players of team Red could actually defend. The other Red could still circle it and block the enemy, but they could not lower its value actively. Everything described here works. There are still glitches small and not so small. The code is in my private branch, but feel free to grab a local copy if you want to play with it.

The format is anything but closed. I'd like to hear your opinion on it too (yes it is a PITA to write, but if you have a constructive remark about that, I'd like to know it)

-ph

Most of this is from a forum post by philippeqc. I reworded some stuff and formatted a bit for the wiki. Some stuff might have gotten lost or reworded wrongly so cross refrence with the post if the wording gets hazy and/or just to double check @ http://forums.armagetronad.net/viewtopic.php?p=77491#77491. Some stuff might be in the wrong place. --[[User:Your mom|Your mom]] 11:42, 30 July 2006 (CDT)

== Zone element ==

Individual zones may have a name. Entering a name is optional, and re-using a name will be considered to mean "add/override with the following information". Dont rely on this behavior for anything, in other words '''Dont re-use the same name.''' All zones need a shape defined. At the moment only one shape exists, the ShapeCircle. More shapes are planned in the future and are ToDo

Ex:
<Zone name="redFortress">
<ShapeCircle radius="29">
<Point x="50" y="50"/>
<Color red="0.988" green="0.059" blue="0.753" />
</ShapeCircle>

</Zone>

== Rules and EffectGroups ==

A zone can have up to 4 different "rules" (need better name ToDo). Enter, Inside, Leave, Outside. It classifies when the held elements should be inspected. Inside each of the "rules", one can define EffectGroups. EffectGroup(s) are the fundamental building blocks of this new system. It associate owners with consequences. Note that ownership is part of effectGroup(s), ''NOT'' the zone. So a zone may have multiple effectGroup(s), each with unique or interlapping owners. There are 2 types of owners: owner (individuals) and ownerTeam (every member of a team). It is possible to define 0,1 or many for each items.

''HACK:
ATM, only owner is supported, and it must be an exact match with a
player's name to associated the effect.
The real solution will translate the labels used to players based on
some other logic depending on "game type". This is to be defined
later.''

''HACK:
It should be possible to associate individual with teams in some part
of the map. In this text, I will user lowercase color name + number for
individual, and uppercase color name for teams. So the individual
red1, red7 and red90210 should be considered as players of the team
RED. I will also allow myself to insert _description_ in names to help
the reader when appropriate.''

Ex:
<pre><Zone name="redFortress">
<ShapeCircle ...>
...
</ShapeCircle>
<Enter>
<EffectGroup owner="red1,red2" ownerTeam="BLUE,YELLOW">
...
</EffectGroup>
<EffectGroup owner="" ownerTeam="RED">
...
</EffectGroup>
</Enter>
<Leave>
<EffectGroup owner="green7" ownerTeam="">
...
</EffectGroup>
</Leave>
</Zone></pre>

== User element ==

Inside the EffectGroup, elements User are set. This element offers different readily made rules to determine if a player in the "rule" condition for the zone, is allowed to be considered a user. This is decided based from the following information: owner, ownerTeam and the player matching the rule. Two other conditions can be set for a player to be considered a valid user: positive and marked. These element are of type Triad. The possible values are true, false and ignore. We will come back to these later. If the current player is found to be valid, the processing will continue to the child elements. Otherwise, nothing happens. A valid user will be called triggerer from now on.

The following users are currently implemented:
* all: Anybody can be considered a valid user,
* owner: only a player direcly in the owner list can be considered a valid user,
* ownerTeam: only a player member of a team mentionned in the ownerTeam list can be considered a valid user,
* allButOwner only a player NOT mentioned in the owner list can be considered a valid user,
* allButTeamOwner only a player NOT member of a team mentioned in the ownerTeam list can be considered a valid user, (TO COME, NOT IMPLEMENTED YET)
* anotherTeammate only a player in the same team as one of the individual owner can be considered a valid user (TO COME, NOT IMPLEMENTED YET)

Ex:
<pre><EffectGroup owner="red1,red2" ownerTeam="BLUE,YELLOW">
<User user="all" >
... 
</User>
<User user="allButOwner" >
... 
</User>
</EffectGroup>
<EffectGroup owner="" ownerTeam="RED">
<User user="owner" >
... 
</User>
<User user="ownerTeam" >
... 
</User>
</EffectGroup></pre>

Inside a User element, it is possible to make use of 3 different
elements. Target, ZoneInfluence and MonitorInfluence.

=== Target ===

The Target element will take the information of the valid user, and
calculate who will receive the effect of the zone. Depending on the
described target rule to use and the state of the game, the calculated
target can be from no players to everybody in game.

The currently implemented target rules are :

*self : the triggerer himself
*teammate : a randomly selected teammate of the triggerer
*team : all the member of the team of the triggerer
*all : everybody in the game
*allButSelf : everybody in the game BUT the triggerer
*another : a randomly selected player that is not the triggerer
*ownerTeamTeammate : a randomly selected player member of one of the teams mentioned in the teamOwner list.
*owner : all the players owning the effectGroup
*ownerteam : all the players member of the team owning the effectGroup
*ownerteamteammate : a single player member from a owning team
*anydead : any single dead player
*alldead : all the dead players
*singledeadowner : one of the owners that is dead
*anotherteammatedead : a single player member of the team of the triggerer that is dead
*anothernotteammatedead : a single player that is not member of the team of the triggerer and that is dead
<nowiki>
*Much more are detailed in a document named zones.txt hidden somewhere
on the forum.</nowiki>

Once the targets are selected, they all are applied all the effects
described under the Target element.

Nota: In a User element, it is possible to user any amount of Target,
ZoneInfluence and MonitorInfluence.

Ex:
<pre><User user="ownerTeam" >
<Target target="self">
... 
</Target>
<Target target="another">
... 
</Target>
</User></pre>

== Effect ==

The Effect element hold specific effects. The attribute count can limit the number of times a specific effect can be used. By default, the count is unlimited.

valid effect currently implemented are:
*win : win the round
*death : kill the target(s)
*point : give points to the target(s)
*respawnplayer : Respawns target(s)
*brakerecharge : Refills target(s) cycle brake
*rubberrecharge : Refills target(s) cycle rubber
*setting : has 2 attributes ; settingName & settingValue

new attribute for all effects: description

When the effect is triggered, the message is displayed on the console. Somehow I'm not able to do the "parsing" similar to when points are given (player x received y points because he is sooo leet). That should come.

When point is use, an attribute score will mention the amount of point
to give.

<pre><Target target="self">
<Effect effect="point" score="3" count="2">
... 
</Effect>
<Effect ...>
...
</Effect>
</Target></pre>

ex:
<pre><Effect effect="setting" settingName="cycle_speed" settingValue="100" /></pre>

=== ZoneInfluence ===

Inside the User element, the element ZoneInfluence and MonitorInfluence are use to affect back game element. ZoneInfluence allows to affect a zone in play. The name attribute must match exactly a zone's name elsewhere in the map.

The possible thing to affect on a zone are:
*Rotation with attribute rotationSpeed and rotationAcceleration
*Radius with attribute radius
*Point with attribute x and y

Ex:
<pre><User user="all">
<ZoneInfluence name="redFortress">
<Rotation rotationSpeed="1" rotationAcceleration="-0.2" />
<Radius radius="50"/>
<Point x="100" y="100" />
</ZoneInfluence>
<ZoneInfluence name="blueFortress">
<Radius radius="-1" />
</ZoneInfluence>
</User></pre>

=== MonitorInfluence ===

Monitors are simple valiables that can be affected by interaction with different zones. The old "fortress" zone is to be considered as a zone where being inside slowly influence its monitor. Monitors are to be inserted in the map at the same level as Zone. Monitor have a name that is used to refer to from the MonitorInfluence, a initial value, and a drift, that slowly move the value, low and high, which clamp the monitor's value between their owns.

<pre><Field>
...
<Monitor name="monitorFortressRed" init="0.2" drift="-0.1" low="0.0" high="1.0">
... 
</Monitor>
...
</Field></pre>

The Monitor as different rules that can be used to inspect and react on its value. They are OnOver, OnUnder, InRange and OutsideRange. Any amount of rules can be used in a monitor.

*OnOver has an attribute named value and will be used when the monitor's value exceed it,
*OnUnder has an attribute named value and will be used when the monitor's value is under it,
*InRange has attributes low and high and will be used when the monitor's value fall between both
*OutRange has attributes low and high and will be used when the monitor's value is not falling between both

The monitors' rules are similar to the zone's rule in that they hold EffectGroups that are inspected when the rule conditions are met.

What differs a Monitor from a zone regarding to EffectGroup is who are considered players to be inspected as users. Anyone who contributed to a monitor during a game time step is registered, along with if the contribution was positive (conquering) or negative (defending), and if they where marked. This information is passed along up to the User element. There it can be used on additional tests to determine a valid user.

<pre><Monitor name="monitorFortressRed" init="0.2" drift="-0.1" low="0.0" high="1.0">
<OnOver value="1.0">
<EffectGroup ...>
<User user="..." positive="true" marked="ignore">
... 
</User>
<User ...>
...
</User>
</EffectGroup>
</OnOver>
</Monitor></pre>

==== User ====

The User element always have these attributes, but outside of an EffectGroup from a Monitor, this is always ignored.

MonitorInfluence element is the one where one describe how to affect a monitor. It has an attribute name to point to the monitor to influence. It has a marked attribute which is a Triad, ie: allows for the value true, false or ignore. Players using this MonitorInfluence will carry this mark into their contribution to the monitor.

There are 3 ways to influence the value of a monitor:
*1 the attribute influenceSlide will affect the monitor's value in a fashion proportional to the time passed in the zone. This is how the classical fortress operates. This is the same as saying influenceSlide * duration of the current game time step.
*2 the attribute influenceAdd will affect the monitor's value by this amount. This is NOT affected by time.
*3 the attribute influenceSet will set the monitor's value immediatly to this value.

These can of course be used simulteanously. It is important here that
attributes that are not desired should not be defined, rather than
defined at a default value.

Ex:
<pre><User ...>
...
<MonitorInfluence name="monitorFortressRed" marked="true" influenceSlide="0.5"/>

<MonitorInfluence name="monitorFortressGreen" marked="true" influenceAdd="2"/>

<MonitorInfluence name="monitorFortressBlue" influenceSet="0.0" />

</User></pre>

== Quiz ==
Respond on the forums after reading through this entire page with any ideas or questions of your own.(Optional)

1 Are you able to express some new ideas with it?

2 Do you see items that could be added, either now or as a later
version that could improve its value?

3 Anything else?

-ph

== Examples ==
An example might help you get through the mess of the description

Its blue vs red Each team has zones in opposing corners which are interconnected. As they get conquered, they jump toward the center.

For your convenience:
MAP_FILE philippeqc/zone/DoubleZoneJumping-1.aamap.xml

Code:
<pre><?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map-0.3.1-a.dtd">
<Resource type="aamap" name="DoubleZoneJumping" version="1" author="philippeqc" category="zone">


<pre> <Map version="2">

<World>
<Field>
<Spawn x="50" y="245" xdir="1" ydir="0" />
<Spawn x="450" y="255" 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>
<Zone name="zRed1">
<ShapeCircle radius="49" red="1.0" green="0.1" blue="0.1">
<Point x="50" y="50"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="-0.25" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="0.5" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Zone name="zRed2">
<ShapeCircle radius="49" red="1.0" green="0.1" blue="0.1">
<Point x="450" y="450"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="-0.25" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mRed" influenceSlide="0.5" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Monitor name="mRed" init="0.0" drift="-0.1" >
<InRange low="0.0" high="0.30">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="100" y="100"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="400" y="400"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.4" high="0.60">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="150" y="150"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="350" y="350"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.7" high="1.0">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zRed1">
<Point x="200" y="200"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Point x="300" y="300"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<OnOver value="1">
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<Target target="self">
<Effect effect="point" count="2" score="7"/>
</Target>
<ZoneInfluence name="zRed1">
<Radius radius="-1" />
</ZoneInfluence>
<ZoneInfluence name="zRed2">
<Radius radius="-1" />
</ZoneInfluence>
</User>
</EffectGroup>
</OnOver>
</Monitor>



<Zone name="zBlue1">
<ShapeCircle radius="49" red="0.10" green="0.10" blue="1.0">
<Point x="50" y="450"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="0.3" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="-0.3" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Zone name="zBlue2">
<ShapeCircle radius="49" red="0.10" green="0.10" blue="1.0">
<Point x="450" y="50"/>
</ShapeCircle>
<Inside>
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="0.3" marked="true"/>
</User>
</EffectGroup>
<EffectGroup owners="azure,cobalt,midnight,royal" teamOwners="">
<User user="owner">
<MonitorInfluence name="mBlue" influenceSlide="-0.3" marked="true"/>
</User>
</EffectGroup>
</Inside>
</Zone>

<Monitor name="mBlue" init="0.0" drift="-0.1" >
<InRange low="0.0" high="0.30">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="100" y="400"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="400" y="100"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.4" high="0.60">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="150" y="350"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="350" y="150"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<InRange low="0.7" high="1.0">
<EffectGroup owners="" teamOwners="">
<User user="all">
<ZoneInfluence name="zBlue1">
<Point x="200" y="300"/>
<Radius radius="49"/>
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Point x="300" y="200"/>
<Radius radius="49"/>
</ZoneInfluence>
</User>
</EffectGroup>
</InRange>
<OnOver value="1">
<EffectGroup owners="cerise,mauve,rust,sangria" teamOwners="">
<User user="owner">
<Target target="self">
<Effect effect="point" count="2" score="7"/>
</Target>
<ZoneInfluence name="zBlue1">
<Radius radius="-1" />
</ZoneInfluence>
<ZoneInfluence name="zBlue2">
<Radius radius="-1" />
</ZoneInfluence>
</User>
</EffectGroup>
</OnOver>
</Monitor>

</Field>
</World>
</Map>
</Resource></pre>

Ex:
Code:

<pre><Zone name="redFortress">
<ShapeCircle radius="29" red="0.988" green="0.059" blue="0.753"/>
<Point x="50" y="50"/>
</ShapeCircle>
...
</Zone></pre>

is now

Code:
<pre><Zone name="redFortress">
<ShapeCircle radius="29" >
<Color red="0.988" green="0.059" blue="0.753" alpha="0.0"/>
<Point x="50" y="50"/>
</ShapeCircle>
...
</Zone></pre>

Also added Color as a child of ZoneInfluence:
Code:
<pre> <ZoneInfluence name="blueFortress">
<Radius radius="-1" />
<Color red="0.988" green="0.059" blue="0.753" alpha="0.0"/>
</ZoneInfluence></pre>

This map has 4 zones that activate one another. Only one should be present, and when not there, they are put outside of the arena. They are activated in a crossed fashion.

Code:
<pre><?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE Resource SYSTEM "map.dtd">
<Resource type="aamap" name="zone" version="d" author="philippeqc" category="">

<Map version="2">

<World>
<Field>
<Spawn x="50" y="245" xdir="1" ydir="0" />
<Spawn x="450" y="255" 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>

<Zone name="SW">
<ShapeCircle radius="29" >
<Point x="50" y="50"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="SW">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="NE">
<Point x="450" y="450"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="NE">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="NE">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="NW">
<Point x="50" y="450"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="NW">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="NW">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="SE">
<Point x="450" y="50"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>

<Zone name="SE">
<ShapeCircle radius="29">
<Point x="-150" y="-150"/>
<Color red="0.988" green="0.059" blue="0.753">
</ShapeCircle>
<Enter>
<EffectGroup owners="" teamOwners="">
<User user="all">

<Target target="self">
<Effect effect="point" score="2" />
</Target>

<ZoneInfluence name="SE">
<Point x="-150" y="-150"/>
<Radius radius="29"/>
</ZoneInfluence>

<ZoneInfluence name="SW">
<Point x="50" y="50"/>
<Radius radius="29"/>
</ZoneInfluence>
</User>
</EffectGroup>
</Enter>
</Zone>
</Field>
</World>
</Map>
</Resource></pre>

Its a really crude idea, that has been retaken in a much better way by wrt. But it show some things that can be done (influencing individual zones, and using ZoneInfluence from one zone to affect another).

Targets have a count:
Code:
The target has an attribute count that will limit the number of time
it is called. Not having the attribute or setting it to -1 means infinite.

-ph

FAQ

2007-04-14T11:10:12Z

Philippeqc: /* Added description how to start the dedicated server on Max OS, copied from a post by DDMJ*/

Following is a list of Frequently Asked Questions. Obviously, this is what people ask us the most. Before asking a question, you should give this list a good read. If your question isn't answered here, then by all means come to [[IRC_Channel|IRC]] or the forums or something and ask it. However, if your question is answered here, don't be surprised if you get an abrupt or downright rude response.

While we try to give the best answers to the questions asked regardless of pretty much anything else, however there are some general guidelines to follow when asking questions not on this list:

* Don't ask stupidly. Ex: Why can't I get color on my walls? (Good example: How do I have a cycle and wall color that are different from each other?)
* Provide as much information as you have that's relevant to the question. Ex: Why doesn't my server work? (Good example: My server starts, then stops. Here's the errors from the console. Any idea why it's shutting down right away?)

For a more detailed discussion, check [http://www.catb.org/~esr/faqs/smart-questions.html this page], with two important points. First, the page linked is not in any way affiliated with Armagetron Advanced and therefore they '''can't answer your question'''. Second, the article is probably a bit more negative than it actually works around here. For the most part, if you can't ask the question in the smartest possible way, we'd rather you ask the best way that you can than live in the dark and suffer. Even if you're an idiot, we still want you to be a comfortable idiot.

If you think your question is actually a bug report and you've only just started with the game, chances are it's not. We'll not pretend the game is bug-free, but it is very stable and efficient. The chances that a new player to the game has discovered a previously unknown bug in a stable release are very very slim. Astronomically slim, in fact. In any case, if you wish to continue thinking you have done so, please start with a question that describes what you see and ends with "Is this expected behavior?" That's much more likely to get a satisfactory response than "This game sucks! It has this bug and that bug and it just doesn't work. I downloaded it today for the first time on my Windows box, do you not care about Windows?" Also, since you suspect you found a bug, include all the information a bug report should have. If you're unsure, please [http://www.chiark.greenend.org.uk/~sgtatham/bugs.html consult this page] for the best results. Note, the author of that page is also unaffiliated with Armagetron Advanced, and therefore he will reject any bug reports you send him about our program.

Finally, this FAQ, like all FAQs, is a work in progress. If it's not as big as you're used to seeing, it's because it's probably a younger FAQ than what you're used to seeing. That's ok. We'll add to it over time, and it'll get bigger and bigger until the server explodes with so many frequently asked questions that all of the developers decide to pitch in and buy a Caribbean island. Mmm, coconuts.
= What is Armagetronad =

[[About | Please read this.]]

= Terminology =

== What is a client? What is a server? What's the difference? ==

Simply put, the game client is the program you run on your computer. The game server runs on somebody else's computer. The difference between the two is like the difference between, say, a lawyer and his client. The lawyer would be the server, the one who knows all about law and stuff. So the difference is just like in real life where the terms come from. The client requests a service from someone who serves. In our case, that service is a game that is served from a machine running a program called a "server", but if you requested the same service from a person in a casino, you'd still be running a game client.

== My client can be a server, though, it says so right here. ==

That's not a question. In any case, the game client can act as a server if you press "Host Game" from the Internet Game menu. So technically the client is a client/server hybrid, but let's not get too technical.

== So are all game servers just clients where people pressed "Host Game"? ==

No. This is where people get really confused, even to the point where they complain to server operators for doing exactly this thing. No, most, if not all, game servers available through the master server run a special version of the program that has no graphical display, and no player can play on directly. That is the server, commonly called the "dedicated server". You can run it too, if you'd like. Server operators chose to run this instead of the regular game client because it has a number of modifications that make it work better as a regular server, just like a mail server or a web server. It is more convenient and makes for a more reliable game server to do so.

= Installing the Game =

== Where can I download Armagetron Advanced? ==

That depends on what version you want to get. The current stable version is always available [http://www.armagetronad.net/downloads.php on the main web page] or [http://sourceforge.net/project/showfiles.php?group_id=110997 sourceforge]. The latest testing version on [http://beta.armagetronad.net AABeta].

== I'm running Windows, how do I install? ==

Find the exe file you downloaded from the question and answer above this one and double click on it. Answer all dialog boxes with Yes/Next/Finish, whatever applies. On Windows XP, when you first run the game and try to connect to the Internet, a firewall warning will pop up; set it to allow access.

== So, should I get the latest stable or latest development version? ==

If you're really asking this question and are not just browsing the FAQ, get the latest stable version.

== Ok, but there are still so many different files to get, which one is right for me? ==

See [[FAQ#Terminology]] for choosing between Client and Server download. If in doubt, choose the Client. If you're running a PC with Windows, get the exe format, GCC or VC6 should not matter (please report it if only one of them works for you). If you've got a Mac, get the dmg; there is a special build available for versions 10.2.8 of OS X. If you're running 32 bit Intel Linux, get the x86(_32) "package". If you're running 64 bit AMD Linux, get the x86_64 "package".

== I'm running Linux, but don't know whether it is 32 or 64 bit. How can I find out? ==

On a console/terminal, type <pre>echo $MACHTYPE</pre>
If the output starts with x86_64, you have a 64 bit system. If it starts with i386, i486, i586 or i686 or possibly just x86 or x86_32, you have a 32 bit system. For anything else, we don't provide binary packages, you have to build from source. If the output is blank, the method failed. Then, see whether you have got the directory /usr/lib64 on your system. If yes, you have a 64 bit system, if no, it's 32 bit.

== I have a Mac, how do I install? ==

Mount the dmg file, and drag the Armagetron Advanced application to your hard-drive.

== I have Linux, how do I install a binary? ==

That depends on the distribution you are running. Check out the [[Linux Distribution Field Report]] for details.

== I run a non-Linux UNIX or Linux on hardware not supported by your binary packages or the binaries don't work, how do I install from source? ==

Basically, you fetch the .tbz2 source archive and do as the superuser root
<pre>tar -xjf <path to the tbz2 source archive you just fetched>
cd armagetronad-<VERSION>
./configure
make
make install</pre>
The configure script will tell you what you are missing. In this mode, you always need the 'development' packages of our dependencies on most distributions.
The [[Linux Distribution Field Report]] may have some hints. Ask us if you get stuck.

== I'm working on a Linux PC administered by someone else and don't have the root password, can I still install the game? ==

Yes. The "package" binary files can install everything in your home directory. If you have to build from source, proceed as in the last FAQ,
but pass '--prefix=$HOME/usr' to ./configure and run the game later with
'~/usr/bin/armagetronad', or run the game from the build directory with 'make run'.

== Where are the server sources? ==

The server sources are the same as the client sources. You compile a server from them by giving the additional command line option '--disable-glout' to ./configure.

== I heard about moviepacks (graphical modifications), how do I install them? ==

See [[Customizing the game]].

= Playing the Game =

== How do I use a map? ==

Read [[Playing Maps]], and please try to tell us why this question is asked so often and followed by "I read the whole wiki!".

= Troubleshooting =

== ArmagetronAd takes most or all the CPU time, how come? ==

AA takes all the CPU time it needs to simulate and render the scene as fast as you'll allow it to. There are two conditions under which that makes it take almost everything that is available:
* You set your graphics card driver not to wait for VSync. AA will then run at the highest possible framerate and therefore also use all the CPU time available. If you enable the FPS display in the HUD options and it shows more than 100 FPS, then that's your problem.
* When it tells your video card driver to update the screen now, the driver goes into a special CPU-hogging mode until the command is completed, even though all it does is sit around and wait. Both NVidia and ATI drivers are guilty of this. In the "Performance Tweaks" submenu of the graphics settings, there is the "Flush" menu item where you can tweak AA to not issue the problematic command (with possible side effects).

== ArmagetronAd is unplayable on my AMD Dual Core X2 System (might affect other Dual Cores) ==

Symptoms:
*The console displays "Timer hick up"
*FPS are usually ok (above 30).
*might only occur in network games
*Game performance is very bad

At least three solutions for this problem are available:
* To fix this problem use your TaskManager to set ArmagetronAd.exe's cpu affinity to a single CPU.
* Disable Cool & Quite in BIOS
* Install the necessary Microsoft Hotfixes and depending on your System you might have to update your bios and drivers too.

Links (TODO replace links with links to better instructions!):
* [http://support.microsoft.com/default.aspx?scid=KB;en-us;896256 Microsoft Knowledge base Article about Q896256]
* [http://www.amd.com/en-us/Processors/TechnicalResources/0,,30_182_871_13118,00.html AMD Dual Core Optimizer] The fix is similiar to Microsofts, but only fixes a small part of it. The Microsoft patch also addresses power saving bugs (of Windows XP).

*Details: Armagetron Advanced 0.2.8.x(?) or later uses the high precision timer on Windows if available. (TODO confirm) This can be a problem on the new Dual Core Systems or malfunctioning Multiprocessor System. The Timer of each core runs at different speeds which results in a jumping timer! The AMD X2 Systems are affected because they have two separate timers for each CPU (Intels Core Duo CPUs share a single timer). The AMD X2 Systems are only affected with Cool & Quite power saving enabled otherwise both cores have the same timer speed. The Windows kernel schedules Armagetron Advanced between both cores which results in a jumping timer form Armagetron perspective.

= Running a Server =

== Which should I run? The client in hosting mode, or the dedicated server? ==

Generally this depends on how long you want the server to run at a time. If you just want it running when you're playing, run the client in hosting mode, it's easier to deal with. If you're running at a LAN party, you might also want to run the client in hosting mode. But if you want to run a server that operates on the internet, reports to the master server, and runs 24 hours a day, 7 days a week (8 days in a leap week), then you should run the dedicated server.

== How to start the dedicated server ==

=== ... on Linux/Unix ===
This section needs to be written.

=== ... on MS Windows ===
This section needs to be written.

=== ... on Max OS X ===
There is a very easy way to run the dedicated server on Max OS:
*1. Open up Terminal ( Macintosh HD -> Applications -> Utilities -> Terminal )
*2. In the terminal window type (without the quotes & don't forget the space): 'cd '
*3. Drag the 'Armagetron Advanced Dedicated' folder into the terminal window
*4. Press Enter
*5. Drag the 'armagetronad-dedicated' file ( Armagetron Advanced Dedicated -> armagetronad-dedicated ) into the Terminal window
*6. Press Enter

== I've started the dedicated server, but I don't see it listed in the master server. What's wrong? ==

You need to add the line <pre>TALK_TO_MASTER 1</pre> to your configuration files to publish your server on the internet. The server needs to be up one or two minutes before it can appear in the server browser, the master server checks whether it is reachable before it gets published.

== I did that, but my server still is not listed. What else can be wrong? ==

Get your server's IP address; if it is running on the same computer you use for browsing right now, check http://www.whatismyip.com to get it. Fire up the Armagetronad client, enter the internet server browser, wait half a minute, exit the server browser, enter it again, and look for your server's IP. If it appears (having the list sorted by server name my pressing "right" once helps), you really want to ask [[FAQ#I see my server's IP in the master server browser, but it says "Unreachable". What's wrong?]]. Otherwise, this is the right section for you. This is also the right section if you see your server just fine, but nobody else does.

If your server is connected to the internet via a router box and not directly via a "modem" of sorts, it is likely that network packages from the internet can't get to your server because the router blocks them. You need to tell your router to forward UDP port 4534 (or whatever SERVER_PORT is set to) to the server. On [http://www.portforward.com], there are nice instructions how to do that for a lot of router models. If the UDP port 4534 thing confuses you, just follow [http://www.portforward.com/english/applications/port_forwarding/F-22Lightning3/F-22Lightning3index.htm these instructions for a different game] that uses a similar connection method. Of course, you need to find out what router model you have, some under-the-table-crawling and cable following may be required for that if you can't remember what you bought or got the router from your ISP.

== My server still isn't listed. This sucks, it's hard to find out where the problem is. What can I do? ==

See [[Server_Administration_Guide#Firewalls|Short Firewall Troubleshooting]] and [[Server_Administration_Guide#Port_forwarding|Short Port Forwarding Troubleshooting]], if this does not solve your problem, read on.

You can ask people to connect to your server directly by giving them [http://www.whatismyip.com your IP] and the port your server is running on. A perfect place to ask is our [[IRC_Channel|IRC]] channel(#armagetron on irc.freenode.org) because you'll get a real-time answer there. Less perfect is the support section of the [http://forums.armagetronad.net forums]; you'll need to make sure your server is up and running when people read your post, which can be well 48 hours after you post it. If people can't connect to your server that way, it means you probably need to set up port forwarding (see last question) correctly.

== Gaaa! This FAQ is useless! Can't YOU help me get my server up? ==

Sure. Post your trouble on the support section of the [http://forums.armagetronad.net forums]. Be sure to
* describe exactly what you already tried, and please don't just say "everything the FAQ told me"
* state the [http://www.whatismyip.com your IP] your server is running on, we need that to check the master server's logs
* state your port if you modified SERVER_PORT
* state your server's name, others need that to check for your server in the browser
* post the complete output of your server from the moment it is started
Without that info, we can't help.

Setting up a server is complicated sometimes; don't be too shy to admit you didn't understand some part of the process. A lot of trouble comes from people silently skipping steps they don't understand.

== I see my server's IP in the master server browser, but it says "Unreachable". What's wrong? ==

Probably the answer is "Nothing is wrong". A bug in some routers or the NAT specifications (at least, that's how Z-Man sees this) causes the response to the server query packet used in the server browser to come from the LAN address of your server, not the public address it was sent to. The packet gets ignored then. A workaround will be available in 0.2.8.3, but right now, that means most people can't see their own servers. Come to the IRC channel (#armagetron on irc.freenode.org) and ask people there if they can see your server.

[[Category:Game Help]]

FAQ

2007-04-02T08:00:14Z

Philippeqc: proper formating in place

Following is a list of Frequently Asked Questions. Obviously, this is what people ask us the most. Before asking a question, you should give this list a good read. If your question isn't answered here, then by all means come to irc or the forums or something and ask it. However, if your question is answered here, don't be surprised if you get an abrupt or downright rude response.

While we try to give the best answers to the questions asked regardless of pretty much anything else, however there are some general guidelines to follow when asking questions not on this list:

* Don't ask stupidly. Ex: Why can't I get color on my walls? (Good example: How do I have a cycle and wall color that are different from each other?)
* Provide as much information as you have that's relevant to the question. Ex: Why doesn't my server work? (Good example: My server starts, then stops. Here's the errors from the console. Any idea why it's shutting down right away?)

For a more detailed discussion, check [http://www.catb.org/~esr/faqs/smart-questions.html this page], with two important points. First, the page linked is not in any way affiliated with Armagetron Advanced and therefore they '''can't answer your question'''. Second, the article is probably a bit more negative than it actually works around here. For the most part, if you can't ask the question in the smartest possible way, we'd rather you ask the best way that you can than live in the dark and suffer. Even if you're an idiot, we still want you to be a comfortable idiot.

If you think your question is actually a bug report and you've only just started with the game, chances are it's not. We'll not pretend the game is bug-free, but it is very stable and efficient. The chances that a new player to the game has discovered a previously unknown bug in a stable release are very very slim. Astronomically slim, in fact. In any case, if you wish to continue thinking you have done so, please start with a question that describes what you see and ends with "Is this expected behavior?" That's much more likely to get a satisfactory response than "This game sucks! It has this bug and that bug and it just doesn't work. I downloaded it today for the first time on my Windows box, do you not care about Windows?" Also, since you suspect you found a bug, include all the information a bug report should have. If you're unsure, please [http://www.chiark.greenend.org.uk/~sgtatham/bugs.html consult this page] for the best results. Note, the author of that page is also unaffiliated with Armagetron Advanced, and therefore he will reject any bug reports you send him about our program.

Finally, this FAQ, like all FAQs, is a work in progress. If it's not as big as you're used to seeing, it's because it's probably a younger FAQ than what you're used to seeing. That's ok. We'll add to it over time, and it'll get bigger and bigger until the server explodes with so many frequently asked questions that all of the developers decide to pitch in and buy a Caribbean island. Mmm, coconuts.
= What is Armagetronad =

[[About | Please read this.]]

= Terminology =

== What is a client? What is a server? What's the difference? ==

Simply put, the game client is the program you run on your computer. The game server runs on somebody else's computer. The difference between the two is like the difference between, say, a lawyer and his client. The lawyer would be the server, the one who knows all about law and stuff. So the difference is just like in real life where the terms come from. The client requests a service from someone who serves. In our case, that service is a game that is served from a machine running a program called a "server", but if you requested the same service from a person in a casino, you'd still be running a game client.

== My client can be a server, though, it says so right here. ==

That's not a question. In any case, the game client can act as a server if you press "Host Game" from the Internet Game menu. So technically the client is a client/server hybrid, but let's not get too technical.

== So are all game servers just clients where people pressed "Host Game"? ==

No. This is where people get really confused, even to the point where they complain to server operators for doing exactly this thing. No, most, if not all, game servers available through the master server run a special version of the program that has no graphical display, and no player can play on directly. That is the server, commonly called the "dedicated server". You can run it too, if you'd like. Server operators chose to run this instead of the regular game client because it has a number of modifications that make it work better as a regular server, just like a mail server or a web server. It is more convenient and makes for a more reliable game server to do so.

= Installing the Game =

== Where can I download Armagetron Advanced? ==

That depends on what version you want to get. The current stable version is always available [http://www.armagetronad.net/downloads.php on the main web page] or [http://sourceforge.net/project/showfiles.php?group_id=110997 sourceforge]. The latest testing version on [http://beta.armagetronad.net AABeta].

== I'm running Windows, how do I install? ==

Find the exe file you downloaded from the question and answer above this one and double click on it. Answer all dialog boxes with Yes/Next/Finish, whatever applies. On Windows XP, when you first run the game and try to connect to the Internet, a firewall warning will pop up; set it to allow access.

== So, should I get the latest stable or latest development version? ==

If you're really asking this question and are not just browsing the FAQ, get the latest stable version.

== Ok, but there are still so many different files to get, which one is right for me? ==

See [[FAQ#Terminology]] for choosing between Client and Server download. If in doubt, choose the Client. If you're running a PC with Windows, get the exe format, GCC or VC6 should not matter (please report it if only one of them works for you). If you've got a Mac, get the dmg; there is a special buld available for versions 10.2.8 of OS X. If you're running 32 bit Intel Linux, get the x86(_32) "package". If you're running 64 bit AMD Linux, get the x86_64 "package".

== I'm running Linux, but don't know whether it is 32 or 64 bit. How can I find out? ==

On a console/terminal, type <pre>echo $MACHTYPE</pre>
If the output starts with x86_64, you have a 64 bit system. If it starts with i386, i486, i586 or i686 or possibly just x86 or x86_32, you have a 32 bit system. For anything else, we don't provide binary packages, you have to build from source. If the output is blank, the method failed. Then, see whether you have got the directory /usr/lib64 on your system. If yes, you have a 64 bit system, if no, it's 32 bit.

== I have a Mac, how do I install? ==

Mount the dmg file, and drag the Armagetron Advanced application to your hard-drive.

== I have Linux, how do I install a binary? ==

That depends on the distribution you are running. Check out the [[Linux Distribution Field Report]] for details.

== I run a non-Linux UNIX or Linux on hardware not supported by your binary packages or the binaries don't work, how do I install from source? ==

Basically, you fetch the .tbz2 source archive and do as the superuser root
<pre>tar -xjf <path to the tbz2 source archive you just fetched>
cd armagetronad-<VERSION>
./configure
make
make install</pre>
The configure script will tell you what you are missing. In this mode, you always need the 'development' packages of our dependencies on most distributions.
The [[Linux Distribution Field Report]] may have some hints. Ask us if you get stuck.

== I'm working on a Linux PC administered by someone else and don't have the root password, can I still install the game? ==

Yes. The "package" binary files can install everything in your home directory. If you have to build from source, proceed as in the last FAQ,
but pass '--prefix=$HOME/usr' to ./configure and run the game later with
'~/usr/bin/armagetronad', or run the game from the build directory with 'make run'.

== Where are the server sources? ==

The server sources are the same as the client sources. You compile a server from them by giving the additional command line option '--disable-glout' to ./configure.

== I heard about moviepacks (graphical modifications), how do I install them? ==

See [[Customizing the game]].

= Playing the Game =

== How do I use a map? ==

Read [[Playing Maps]], and please try to tell us why this question is asked so often and followed by "I read the whole wiki!".

= Troubleshooting =

== ArmagetronAd takes most or all the CPU time, how come? ==

AA takes all the CPU time it needs to simulate and render the scene as fast as you'll allow it to. There are two contitions under which that makes it take almost everything that is available:
* You set your graphics card driver not to wait for VSync. AA will then run at the highest possible framerate and therefore also use all the CPU time available. If you enable the FPS display in the HUD options and it shows more than 100 FPS, then that's your problem.
* When it tells your video card driver to update the screen now, the driver goes into a special CPU-hogging mode until the command is completed, even though all it does is sit around and wait. Both NVidia and ATI drivers are guilty of this. In the "Performance Tweaks" submenu of the graphics settings, there is the "Flush" menu item where you can tweak AA to not issue the problematic command (with possible side effects).

== ArmagetronAd is unplayable on my AMD Dual Core X2 System (might affect other Dual Cores) ==

Symtoms:
*The console displays "Timer hick up"
*FPS are usually ok (above 30).
*might only occur in network games
*Game performance is very bad

Atleast three solutions for this problem are available:
* To fix this problem use your TaskManager to set ArmagetronAd.exe's cpu affinity to a single CPU.
* Disable Cool & Quite in BIOS
* Install the neccessary Microsoft Hotfixes and depending on your System you might have to update your bios and drivers too.

Links (TODO replace links with links to better instructions!):
* [http://support.microsoft.com/default.aspx?scid=KB;en-us;896256 Microsoft Knowledgebase Articel about Q896256]
* [http://www.amd.com/en-us/Processors/TechnicalResources/0,,30_182_871_13118,00.html AMD Dual Core Optimizer] The fix is similiar to Microsofts, but only fixes a small part of it. The Microsoft patch also addresses power saving bugs (of Windows XP).

*Details: Armagetron Advanced 0.2.8.x(?) or later uses the high precision timer on Windows if avaiable. (TODO confirm) This can be a problem on the new Dual Core Systems or malfunctioning Multiprocessor System. The Timer of each core runs at different speeds which results in a jumping timer! The AMD X2 Systems are affected because they have two separate timers for each CPU (Intels Core Duo CPUs share a single timer). The AMD X2 Systems are only affected with Cool & Quite power saving enabled otherwise both cores have the same timer speed. The Windows kernel schedules Armagetron Advanced between both cores which results in a jumping timer form Armagetron perspective.

= Running a Server =

== Which should I run? The client in hosting mode, or the dedicated server? ==

Generally this depends on how long you want the server to run at a time. If you just want it running when you're playing, run the client in hosting mode, it's easier to deal with. If you're running at a LAN party, you might also want to run the client in hosting mode. But if you want to run a server that operates on the internet, reports to the master server, and runs 24 hours a day, 7 days a week (8 days in a leap week), then you should run the dedicated server.

== I've started the dedicated server, but I don't see it listed in the master server. What's wrong? ==

You need to add the line <pre>TALK_TO_MASTER 1</pre> to your configuration files to publish your server on the internet. The server needs to be up one or two minutes before it can appear in the server browser, the master server checks whether it is reachable before it gets published.

== I did that, but my server still is not listed. What else can be wrong? ==

Get your server's IP address; if it is running on the same computer you use for browsing right now, check http://www.whatismyip.com to get it. Fire up the Armagetronad client, enter the internet server browser, wait half a minute, exit the server browser, enter it again, and look for your server's IP. If it appears (having the list sorted by server name my pressing "right" once helps), you really want to ask [[FAQ#I see my server's IP in the master server browser, but it says "Unreachable". What's wrong?]]. Otherwise, this is the right section for you. This is also the right section if you see your server just fine, but nobody else does.

If your server is connected to the internet via a router box and not directly via a "modem" of sorts, it is likely that network packages from the internet can't get to your server because the router blocks them. You need to tell your router to forward UDP port 4534 (or whatever SERVER_PORT is set to) to the server. On [http://www.portforward.com], there are nice instructions how to do that for a lot of router models. If the UDP port 4534 thing confuses you, just follow [http://www.portforward.com/english/applications/port_forwarding/F-22Lightning3/F-22Lightning3index.htm these instructions for a different game] that uses a similar connection method. Of course, you need to find out what router model you have, some under-the-table-crawling and cable following may be required for that if you can't remember what you bought or got the router from your ISP.

== My server still isn't listed. This sucks, it's hard to find out where the problem is. What can I do? ==

See [[Server_Administration_Guide#Firewalls|Short Firewall Troubleshooting]] and [[Server_Administration_Guide#Port_forwarding|Short Port Forwarding Troubleshooting]], if this does not solve your problem, read on.

You can ask people to connect to your server directly by giving them [http://www.whatismyip.com your IP] and the port your server is running on. A perfect place to ask is our IRC channel(#armagetron on irc.freenode.org) because you'll get a real-time answer there. Less perfect is the support section of the [http://forums.armagetronad.net forums]; you'll need to make sure your server is up and running when people read your post, which can be well 48 hours after you post it. If people can't connect to your server that way, it means you probably need to set up port forwarding (see last question) correctly.

== Gaaa! This FAQ is useless! Can't YOU help me get my server up? ==

Sure. Post your trouble on the support section of the [http://forums.armagetronad.net forums]. Be sure to
* describe exactly what you already tried, and please don't just say "everything the FAQ told me"
* state the [http://www.whatismyip.com your IP] your server is running on, we need that to check the master server's logs
* state your port if you modified SERVER_PORT
* state your server's name, others need that to check for your server in the browser
* post the complete output of your server from the moment it is started
Without that info, we can't help.

Setting up a server is complicated sometimes; don't be too shy to admit you didn't understand some part of the process. A lot of trouble comes from people silently skipping steps they don't understand.

== I see my server's IP in the master server browser, but it says "Unreachable". What's wrong? ==

Probably the answer is "Nothing is wrong". A bug in some routers or the NAT specifications (at least, that's how Z-Man sees this) causes the response to the server query packet used in the server browser to come from the LAN address of your server, not the public address it was sent to. The packet gets ignored then. A workaround will be available in 0.2.8.3, but right now, that means most people can't see their own servers. Come to the IRC channel (#armagetron on irc.freenode.org) and ask people there if they can see your server.

[[Category:Game Help]]

FAQ

2007-04-02T07:59:24Z

Philippeqc: Added item ArmagetronAd takes most or all the CPU time, how come?

Following is a list of Frequently Asked Questions. Obviously, this is what people ask us the most. Before asking a question, you should give this list a good read. If your question isn't answered here, then by all means come to irc or the forums or something and ask it. However, if your question is answered here, don't be surprised if you get an abrupt or downright rude response.

While we try to give the best answers to the questions asked regardless of pretty much anything else, however there are some general guidelines to follow when asking questions not on this list:

* Don't ask stupidly. Ex: Why can't I get color on my walls? (Good example: How do I have a cycle and wall color that are different from each other?)
* Provide as much information as you have that's relevant to the question. Ex: Why doesn't my server work? (Good example: My server starts, then stops. Here's the errors from the console. Any idea why it's shutting down right away?)

For a more detailed discussion, check [http://www.catb.org/~esr/faqs/smart-questions.html this page], with two important points. First, the page linked is not in any way affiliated with Armagetron Advanced and therefore they '''can't answer your question'''. Second, the article is probably a bit more negative than it actually works around here. For the most part, if you can't ask the question in the smartest possible way, we'd rather you ask the best way that you can than live in the dark and suffer. Even if you're an idiot, we still want you to be a comfortable idiot.

If you think your question is actually a bug report and you've only just started with the game, chances are it's not. We'll not pretend the game is bug-free, but it is very stable and efficient. The chances that a new player to the game has discovered a previously unknown bug in a stable release are very very slim. Astronomically slim, in fact. In any case, if you wish to continue thinking you have done so, please start with a question that describes what you see and ends with "Is this expected behavior?" That's much more likely to get a satisfactory response than "This game sucks! It has this bug and that bug and it just doesn't work. I downloaded it today for the first time on my Windows box, do you not care about Windows?" Also, since you suspect you found a bug, include all the information a bug report should have. If you're unsure, please [http://www.chiark.greenend.org.uk/~sgtatham/bugs.html consult this page] for the best results. Note, the author of that page is also unaffiliated with Armagetron Advanced, and therefore he will reject any bug reports you send him about our program.

Finally, this FAQ, like all FAQs, is a work in progress. If it's not as big as you're used to seeing, it's because it's probably a younger FAQ than what you're used to seeing. That's ok. We'll add to it over time, and it'll get bigger and bigger until the server explodes with so many frequently asked questions that all of the developers decide to pitch in and buy a Caribbean island. Mmm, coconuts.
= What is Armagetronad =

[[About | Please read this.]]

= Terminology =

== What is a client? What is a server? What's the difference? ==

Simply put, the game client is the program you run on your computer. The game server runs on somebody else's computer. The difference between the two is like the difference between, say, a lawyer and his client. The lawyer would be the server, the one who knows all about law and stuff. So the difference is just like in real life where the terms come from. The client requests a service from someone who serves. In our case, that service is a game that is served from a machine running a program called a "server", but if you requested the same service from a person in a casino, you'd still be running a game client.

== My client can be a server, though, it says so right here. ==

That's not a question. In any case, the game client can act as a server if you press "Host Game" from the Internet Game menu. So technically the client is a client/server hybrid, but let's not get too technical.

== So are all game servers just clients where people pressed "Host Game"? ==

No. This is where people get really confused, even to the point where they complain to server operators for doing exactly this thing. No, most, if not all, game servers available through the master server run a special version of the program that has no graphical display, and no player can play on directly. That is the server, commonly called the "dedicated server". You can run it too, if you'd like. Server operators chose to run this instead of the regular game client because it has a number of modifications that make it work better as a regular server, just like a mail server or a web server. It is more convenient and makes for a more reliable game server to do so.

= Installing the Game =

== Where can I download Armagetron Advanced? ==

That depends on what version you want to get. The current stable version is always available [http://www.armagetronad.net/downloads.php on the main web page] or [http://sourceforge.net/project/showfiles.php?group_id=110997 sourceforge]. The latest testing version on [http://beta.armagetronad.net AABeta].

== I'm running Windows, how do I install? ==

Find the exe file you downloaded from the question and answer above this one and double click on it. Answer all dialog boxes with Yes/Next/Finish, whatever applies. On Windows XP, when you first run the game and try to connect to the Internet, a firewall warning will pop up; set it to allow access.

== So, should I get the latest stable or latest development version? ==

If you're really asking this question and are not just browsing the FAQ, get the latest stable version.

== Ok, but there are still so many different files to get, which one is right for me? ==

See [[FAQ#Terminology]] for choosing between Client and Server download. If in doubt, choose the Client. If you're running a PC with Windows, get the exe format, GCC or VC6 should not matter (please report it if only one of them works for you). If you've got a Mac, get the dmg; there is a special buld available for versions 10.2.8 of OS X. If you're running 32 bit Intel Linux, get the x86(_32) "package". If you're running 64 bit AMD Linux, get the x86_64 "package".

== I'm running Linux, but don't know whether it is 32 or 64 bit. How can I find out? ==

On a console/terminal, type <pre>echo $MACHTYPE</pre>
If the output starts with x86_64, you have a 64 bit system. If it starts with i386, i486, i586 or i686 or possibly just x86 or x86_32, you have a 32 bit system. For anything else, we don't provide binary packages, you have to build from source. If the output is blank, the method failed. Then, see whether you have got the directory /usr/lib64 on your system. If yes, you have a 64 bit system, if no, it's 32 bit.

== I have a Mac, how do I install? ==

Mount the dmg file, and drag the Armagetron Advanced application to your hard-drive.

== I have Linux, how do I install a binary? ==

That depends on the distribution you are running. Check out the [[Linux Distribution Field Report]] for details.

== I run a non-Linux UNIX or Linux on hardware not supported by your binary packages or the binaries don't work, how do I install from source? ==

Basically, you fetch the .tbz2 source archive and do as the superuser root
<pre>tar -xjf <path to the tbz2 source archive you just fetched>
cd armagetronad-<VERSION>
./configure
make
make install</pre>
The configure script will tell you what you are missing. In this mode, you always need the 'development' packages of our dependencies on most distributions.
The [[Linux Distribution Field Report]] may have some hints. Ask us if you get stuck.

== I'm working on a Linux PC administered by someone else and don't have the root password, can I still install the game? ==

Yes. The "package" binary files can install everything in your home directory. If you have to build from source, proceed as in the last FAQ,
but pass '--prefix=$HOME/usr' to ./configure and run the game later with
'~/usr/bin/armagetronad', or run the game from the build directory with 'make run'.

== Where are the server sources? ==

The server sources are the same as the client sources. You compile a server from them by giving the additional command line option '--disable-glout' to ./configure.

== I heard about moviepacks (graphical modifications), how do I install them? ==

See [[Customizing the game]].

= Playing the Game =

== How do I use a map? ==

Read [[Playing Maps]], and please try to tell us why this question is asked so often and followed by "I read the whole wiki!".

= Troubleshooting =

== ArmagetronAd takes most or all the CPU time, how come? ==

AA takes all the CPU time it needs to simulate and render the scene as fast as you'll allow it to. There are two contitions under which that makes it take almost everything that is available:
- You set your graphics card driver not to wait for VSync. AA will then run at the highest possible framerate and therefore also use all the CPU time available. If you enable the FPS display in the HUD options and it shows more than 100 FPS, then that's your problem.
- When it tells your video card driver to update the screen now, the driver goes into a special CPU-hogging mode until the command is completed, even though all it does is sit around and wait. Both NVidia and ATI drivers are guilty of this. In the "Performance Tweaks" submenu of the graphics settings, there is the "Flush" menu item where you can tweak AA to not issue the problematic command (with possible side effects).

== ArmagetronAd is unplayable on my AMD Dual Core X2 System (might affect other Dual Cores) ==

Symtoms:
*The console displays "Timer hick up"
*FPS are usually ok (above 30).
*might only occur in network games
*Game performance is very bad

Atleast three solutions for this problem are available:
* To fix this problem use your TaskManager to set ArmagetronAd.exe's cpu affinity to a single CPU.
* Disable Cool & Quite in BIOS
* Install the neccessary Microsoft Hotfixes and depending on your System you might have to update your bios and drivers too.

Links (TODO replace links with links to better instructions!):
* [http://support.microsoft.com/default.aspx?scid=KB;en-us;896256 Microsoft Knowledgebase Articel about Q896256]
* [http://www.amd.com/en-us/Processors/TechnicalResources/0,,30_182_871_13118,00.html AMD Dual Core Optimizer] The fix is similiar to Microsofts, but only fixes a small part of it. The Microsoft patch also addresses power saving bugs (of Windows XP).

*Details: Armagetron Advanced 0.2.8.x(?) or later uses the high precision timer on Windows if avaiable. (TODO confirm) This can be a problem on the new Dual Core Systems or malfunctioning Multiprocessor System. The Timer of each core runs at different speeds which results in a jumping timer! The AMD X2 Systems are affected because they have two separate timers for each CPU (Intels Core Duo CPUs share a single timer). The AMD X2 Systems are only affected with Cool & Quite power saving enabled otherwise both cores have the same timer speed. The Windows kernel schedules Armagetron Advanced between both cores which results in a jumping timer form Armagetron perspective.

= Running a Server =

== Which should I run? The client in hosting mode, or the dedicated server? ==

Generally this depends on how long you want the server to run at a time. If you just want it running when you're playing, run the client in hosting mode, it's easier to deal with. If you're running at a LAN party, you might also want to run the client in hosting mode. But if you want to run a server that operates on the internet, reports to the master server, and runs 24 hours a day, 7 days a week (8 days in a leap week), then you should run the dedicated server.

== I've started the dedicated server, but I don't see it listed in the master server. What's wrong? ==

You need to add the line <pre>TALK_TO_MASTER 1</pre> to your configuration files to publish your server on the internet. The server needs to be up one or two minutes before it can appear in the server browser, the master server checks whether it is reachable before it gets published.

== I did that, but my server still is not listed. What else can be wrong? ==

Get your server's IP address; if it is running on the same computer you use for browsing right now, check http://www.whatismyip.com to get it. Fire up the Armagetronad client, enter the internet server browser, wait half a minute, exit the server browser, enter it again, and look for your server's IP. If it appears (having the list sorted by server name my pressing "right" once helps), you really want to ask [[FAQ#I see my server's IP in the master server browser, but it says "Unreachable". What's wrong?]]. Otherwise, this is the right section for you. This is also the right section if you see your server just fine, but nobody else does.

If your server is connected to the internet via a router box and not directly via a "modem" of sorts, it is likely that network packages from the internet can't get to your server because the router blocks them. You need to tell your router to forward UDP port 4534 (or whatever SERVER_PORT is set to) to the server. On [http://www.portforward.com], there are nice instructions how to do that for a lot of router models. If the UDP port 4534 thing confuses you, just follow [http://www.portforward.com/english/applications/port_forwarding/F-22Lightning3/F-22Lightning3index.htm these instructions for a different game] that uses a similar connection method. Of course, you need to find out what router model you have, some under-the-table-crawling and cable following may be required for that if you can't remember what you bought or got the router from your ISP.

== My server still isn't listed. This sucks, it's hard to find out where the problem is. What can I do? ==

See [[Server_Administration_Guide#Firewalls|Short Firewall Troubleshooting]] and [[Server_Administration_Guide#Port_forwarding|Short Port Forwarding Troubleshooting]], if this does not solve your problem, read on.

You can ask people to connect to your server directly by giving them [http://www.whatismyip.com your IP] and the port your server is running on. A perfect place to ask is our IRC channel(#armagetron on irc.freenode.org) because you'll get a real-time answer there. Less perfect is the support section of the [http://forums.armagetronad.net forums]; you'll need to make sure your server is up and running when people read your post, which can be well 48 hours after you post it. If people can't connect to your server that way, it means you probably need to set up port forwarding (see last question) correctly.

== Gaaa! This FAQ is useless! Can't YOU help me get my server up? ==

Sure. Post your trouble on the support section of the [http://forums.armagetronad.net forums]. Be sure to
* describe exactly what you already tried, and please don't just say "everything the FAQ told me"
* state the [http://www.whatismyip.com your IP] your server is running on, we need that to check the master server's logs
* state your port if you modified SERVER_PORT
* state your server's name, others need that to check for your server in the browser
* post the complete output of your server from the moment it is started
Without that info, we can't help.

Setting up a server is complicated sometimes; don't be too shy to admit you didn't understand some part of the process. A lot of trouble comes from people silently skipping steps they don't understand.

== I see my server's IP in the master server browser, but it says "Unreachable". What's wrong? ==

Probably the answer is "Nothing is wrong". A bug in some routers or the NAT specifications (at least, that's how Z-Man sees this) causes the response to the server query packet used in the server browser to come from the LAN address of your server, not the public address it was sent to. The packet gets ignored then. A workaround will be available in 0.2.8.3, but right now, that means most people can't see their own servers. Come to the IRC channel (#armagetron on irc.freenode.org) and ask people there if they can see your server.

[[Category:Game Help]]

Send DTD on the resource repository through ssh

2006-08-07T20:25:39Z

Philippeqc: How to send a DTD on the resource repository through ssh

This node is only of use for a very smart target. Be advised.

The various steps

a) Ask Luke-Jr for an account
b) provide a certificate to Luke-Jr to avoid password login (optional)
b) ssh hachi.dashjr.org
c) sudo -u armagetronad cp /tmp/somefile.dtd /var/www/armagetron/resource/resource/AATeam/somefile.dtd

or rather

tar cf - <in file> | ssh philippeqc@hachi.dashjr.org "tar xf -; sudo -u armagetronad cp <in file> /var/www/armagetron/resource/resource/AATeam/<out file>"

Spawn points

2006-06-22T19:21:32Z

Philippeqc:

Need to investigate:
--------
[quote]3) Respawn points can be identified by an attribute. For
example respawning inside a fortress zone is pretty dangerous as
it's usually crowed, so the designer might add "respawn points"
for each team farther away from it.[/quote]
Point take, I'll investigate methods to specify if a specific
Spanw is for "game start only" "respawn only" or both.
--------

Controling the spawn points from the map:

joda.bot, tell me if you understand properly and if you agree with
that stuff.

2 new "fields" have to be introduced to properly control spawn
points. A teamId and a personId. They are independant series, ie:
teamId="3" is not refering to the same 3 as personId="3".

the id's have 2 tasks.
First, they associate spawn points that are equaly owned. 2 or
more spawn points sharing an identical id of the same type can be
used by the same owner, and only that owner.
Second, they associate players and teams with certain game
elements. If a game element has an id reference to a personId or a
teamId, it is considered to be owned by said team or person. At
the moment, this is only used in the context of Zones.

Association:
A team should be associated at least one teamId. A player should
be associated at least one playerId. Should this be impossible to
furfill, the behavior the behavior for teams and players that did
not received their respective id's is undefined.

The map can link a playerId to a teamId. A playerId is not
required to be linked to a teamId. A teamId can have multiple
playerId linked to it. Assigning the same playerId to multiple
teamId is not allowed, and a map showing this behavior will be
automatically rejected.

A team associated to a specific teamId will take ownership of all
the items with said teamId. A teamId can be owned at most by a
single team. A team can grab multiple teamId. While it is
recommended to do this only when it is possible to balance the
teamId's equally among all teams, there are no restrictions on
it. When multiple teamId's are grabbed by the same team, they are
considered to operate under the same teamId for logic purpose.
Items that have a teamId that is not grabbed by any team are
considered not to have any teamId, ie. to be common items.
Players grabs playerId in the same fashion.

There are no requirement on the method used to assign a teamId to
a team, or a playerId to a player, be it for the first id, or when
assigning multiple id's to the same grabber.

Spawning:
Members of the same team should be placed on spawn points of the
same teamId. Should a team has more members than available spawn
points, two options are possible. First, the wingman configuration
could be used to distribute them. Second, the excess members of
the team can be placed on spawn points that aren't associated to
any team. This decision need to be controlled by an external factor.

A player can be placed on any spawn point that it owns. A player
cannot be placed on a spawn point owned by another player. Should
a player re-spawn during the game, two alternatives are
possible. First, the player is respawned at the same position that
it was at game start. Second, if other spawn points are possible,
a new one is selected by an undetermined method. If no other spawn
points are available, the old one is reused. This need to be
controled by an external factor.

Items:
Items such as Zones can be linked to a teamId and a playerId. If
an Item links to a teamId or a playerId, such id MUST be defined
as part of the map. Maps not respecting this will be automatically
rejected. Such linking affect the behavior of the Item, and can be
specific of the type of Item.

(Uncertain: an Item can be linked to multiple playerId or teamId?)

Items keep their owner through the match, even if the player or
all the members of a team are dead.

Syntax in the map:

A team element may contain player elements and spawn elements.
A player element may contain spawn elements.
The id's need not to follow any rule other than to be unique in
their own series.

(Uncertain: need to confirm for the id's)

Two different ways to write the XML. One with hierarchy, one flat
with attribute. Need to pick one.

<team teamid="1">
<spawn .../>
<spawn .../>
<spawn .../>
</team>
<team teamid="A">
<player playerid="Joe">
<spawn ... />
<spawn ... />
</player>
<player playerid="lemon">
<spawn .../>
<spawn .../>
</player>
<spawn .../>
<spawn .../>
</team>
<player playerid="5">
<spawn .../>
<spawn .../>
</player>
<player playerid="boat">
<spawn .../>
<spawn .../>
</player>
<spawn .../>
<spawn .../>
<spawn .../>

vs

<spawn ... teamId="3" playerId="6"/>
<spawn ... teamId="3" />
<spawn ... playerId="7"/>
<spawn ... teamId="1"/>
<spawn ... teamId="1"/>
<spawn ... teamId="1"/>
<spawn ... teamId="A"/>
<spawn ... teamId="A" playerId="Joe"/>
<spawn ... teamId="A" playerId="Joe"/>
<spawn ... teamId="A" playerId="lemon"/>
<spawn ... teamId="A" playerId="lemon"/>
<spawn ... teamId="A" />
<spawn ... teamId="A" />
<spawn ... playerid="5"/>
<spawn ... playerid="5"/>
<spawn ... playerid="boat"/>
<spawn ... playerid="boat"/>
<spawn .../>
<spawn .../>
<spawn .../>

Development Docs

2006-06-22T19:20:12Z

Philippeqc: /* Stuff in CVS HEAD */

{{Sections}} 

This is documentation for developers or for people who just want to hack on the code. It is not intended to replace the automatic API documentation generated by doxygen (we do have a doxyfile, right?), but is intended to supplement those documents with additional information that may not necessarily appear in the API docs. It is also not intended as a substitute for good commenting tactics. And finally, it is a place to put planning documentation (like the stuff Philippe writes), proposals, RFC-type material, and so forth. But not the roadmap, we use Sourceforge's tracker for that.

== Set Up Your System ==

* [[Windows Development System]]
* [[Working with SVN]]
* [[Cross-compiler]]

== Stuff That's Current ==

* [[Config Item Purposes]]
* [[Project Dependency Structure]]
* [[Debug Recording]]
* [[Error Handling]]

== Stuff in SVN HEAD ==

* [[Embedded Web Server]]
* [[Map/Config Rotation]]
* [[Particle System]]
* [[Joda's Team Code]]
* [[New Sound Engine]]
* [[Spawm points]]

* [[Cockpit Tutorial]] | [[Cockpits list]]

== Data File Handling ==

* [[Config Files]]
* [[Resource System]]
* [[Statistical Collections Database]] (fancy way of saying "stat files")

== Stuff That's Real but doesn't fit above ==

* [[Experimental Map Features]]

== Wishlist, or Stuff that's planned ==

(Might not be planned, but this is it)

* [[Scripted GUI Notes]]
* [[Authentication]]

== History ==

This is stuff that's of historical significance to the project. It's very difficult to remember where you're going if you don't remember where you came from, right? This is technical stuff. Community history should have its own section.

* [[What Went Wrong in Armagetron]]

{{Sections}}

Making Maps by Hand

2006-01-08T19:09:02Z

Philippeqc: /* Wall */

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


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

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


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

Making Maps by Hand

2005-11-25T19:26:40Z

Philippeqc: The description of the parameter logicalBox was on multiple lines

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


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

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


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

Playing Maps

2005-11-20T21:30:48Z

Philippeqc: Removed MAP_URI

So you've made your map and now you'd like to play it? Unfortunately, at this time the game doesn't have a nice graphical interface for choosing maps from what's installed. So you'll have to get your elbows a little dirty and hack into config files to do it. Luckily it's not that hard.

== Place Your Map ==

First you need to place your map. Each platform has a different place for you to put it, so you need to make a decision about it right away. The first decision to make is "Should this map be playable for all users on the system?" If the answer is "yes", then you need to install it in the game's system resources directory. If the answer is "no", then you need to install it in your user's resource directory for the game. The actual locations of these files is system-dependent and on some platforms depends on where you installed the game.

You generally want to create a new directory underneath your resource directory to hold you own special maps. This directory should be named according to the author of the maps in it. Please be careful to avoid an ambiguous nickname by checking if someone is already using that name on the [[resource repository]]. When you browse your local resource directory you may notice that there's a special directory called <code>automatic</code>. You shouldn't fool with it. If you've played a server with a map you particularly liked, and you'd like to use that map for your own local game, then you should move the map from it's location in the <code>automatic</code> directory and put it immediately beneath the <code>resource</code> directory. Examples (Linux given, others requested):

* /home/Lucifer/.armagetronad/resource/Lucifer/crack_pipe-0.1.xml

=== System Resource Directory (default) ===

* '''Linux''' - /usr/share/games/armagetronad/resource
* '''Windows''' - C:\Program Files\Armagetron Advanced\resource
* '''Mac OS X''' - Armagetron Advanced.app/Contents/Resources/resource

=== User's Resource Directory (default) ===

* '''Linux''' - <home>/.armagetronad/resource
** ''Example'': /home/Joe/.armagetronad/resource
* '''Windows''' - <appdata>\Armagetron\resource
** ''Example'': C:\Documents and Settings\Joe\Application Data\Armagetron\resource
* '''Mac OS X''' - <home>/Library/Application Support/Armagetron Advanced/resource
** ''Example'': /Users/Joe/Library/Application Support/Armagetron Advanced/resource

== Setting the Config ==

The file you need to modify depends on whether or not you want the map to be available for all users of the system. If you want the map available for all users of the system, then you need to modify the file <code>settings.cfg</code> in the appropriate directory (paths given below). If you only want you to be able to play the map on your system, or if you don't have administrative privileges on your machine, then you'll need to modify <code>autoexec.cfg</code> in your home directory. You'll have to create that file, it does not exist on a fresh installation.

The modification you need to make is to add a line that looks like this, based on the example given above:

* MAP_FILE Lucifer/crack_pipe-0.1.xml

That's it. Note that the path is relative to the <code>resource</code> directory. The game will scan your user's resource directory, and then the system resource directory. If it doesn't find the map after scanning those places it will try to fetch the map from the resource repository.
Since you're most likely working locally, this shouldn't be necessary.

=== System Configuration File Paths (default) ===

* '''Linux''' - /usr/etc/games/armagetronad/settings.cfg
* '''Windows''' - C:\Program Files\Armagetron Advanced\config\settings.cfg
* '''Mac OS X''' - Armagetron Advanced.app/Contents/Resources/settings.cfg

=== User Configuration File Paths (default) ===

* '''Linux''' - <home>/.armagetronad/var/autoexec.cfg
* '''Windows''' - <appdata>\Armagetron\var\autoexec.cfg
* '''Mac OS X''' - <home>/Library/Application Support/Armagetron Advanced/autoexec.cfg

=== Choosing a Map Download URI ===
If using a location other than the official resource repository is desired (for example, for a LAN game where not all players have internet access), you can specify it using 2 different methods:

* MAP_FILE Lucifer/crack_pipe-0.1.xml(http://www.davefancella.com/maps/crack_pipe-0.1.xml)
* RESOURCE_REPOSITORY http://aabeta.dashjr.org/resource/

Note that to use the RESOURCE_REPOSITORY variable, the website must provide the files under the regular file path. In this case, the file http://aabeta.dashjr.org/resource/Lucifer/crack_pipe-0.1.xml would need to exist.

Note that while specifying a URI for the map is optional when it has been submitted to the official resource repository, you must '''always''' specify the map filepath in MAP_FILE.

Console Commands

2005-11-20T21:27:12Z

Philippeqc: Removed MAP_URI

== List of Commands ==

This list was generated by starting Armagetron Advanced version 0.2.8_beta3 with the <code>--doc</code> option.

<pre>Available console commands/config file settings:

ADMIN_PASS Password for the basic in game admin
AI_IQ IQ of the AI opponents
ALLOW_CAM_1_0 Allow/forbid the different camera modes
ALLOW_CAM_1_1 Allow/forbid the different camera modes
ALLOW_CAM_1_2 Allow/forbid the different camera modes
ALLOW_CAM_1_3 Allow/forbid the different camera modes
ALLOW_CAM_1_4 Allow/forbid the different camera modes
ALLOW_CAM_1_5 Allow/forbid the different camera modes
ALLOW_CAM_1_6 Allow/forbid the different camera modes
ALLOW_CAM_2_0 Allow/forbid the different camera modes
ALLOW_CAM_2_1 Allow/forbid the different camera modes
ALLOW_CAM_2_2 Allow/forbid the different camera modes
ALLOW_CAM_2_3 Allow/forbid the different camera modes
ALLOW_CAM_2_4 Allow/forbid the different camera modes
ALLOW_CAM_2_5 Allow/forbid the different camera modes
ALLOW_CAM_2_6 Allow/forbid the different camera modes
ALLOW_CAM_3_0 Allow/forbid the different camera modes
ALLOW_CAM_3_1 Allow/forbid the different camera modes
ALLOW_CAM_3_2 Allow/forbid the different camera modes
ALLOW_CAM_3_3 Allow/forbid the different camera modes
ALLOW_CAM_3_4 Allow/forbid the different camera modes
ALLOW_CAM_3_5 Allow/forbid the different camera modes
ALLOW_CAM_3_6 Allow/forbid the different camera modes
ALLOW_CAM_4_0 Allow/forbid the different camera modes
ALLOW_CAM_4_1 Allow/forbid the different camera modes
ALLOW_CAM_4_2 Allow/forbid the different camera modes
ALLOW_CAM_4_3 Allow/forbid the different camera modes
ALLOW_CAM_4_4 Allow/forbid the different camera modes
ALLOW_CAM_4_5 Allow/forbid the different camera modes
ALLOW_CAM_4_6 Allow/forbid the different camera modes
ALLOW_ENEMIES_SAME_CLIENT If set to 1, this allows two players that play on the same client to fight for points with each other.
ALLOW_ENEMIES_SAME_IP If set to 1, this allows two players that apparently come from the same machine to fight for points with each other.
ALLOW_TEAM_NAME_COLOR Allow a team to be named after a color
ALLOW_TEAM_NAME_PLAYER Allow a team to be named after the leading player
ALLOW_VOTING If set to 1, voting will be allowed for players.
ALLOW_VOTING_SPECTATOR If set to 1, voting will be allowed for spectators.
ALPHA_BLEND Enable alpha blending
ARENA_AXES arena_axes_help
ARENA_AXES_OVERRIDE arena_axes_override_help
ARMAGETRON_LAST_SCREENMODE Last screen resolution
ARMAGETRON_LAST_SCREENMODE_H armagetron_last_screenmode_h_help
ARMAGETRON_LAST_SCREENMODE_W armagetron_last_screenmode_w_help
ARMAGETRON_LAST_WINDOWSIZE Last Window size
ARMAGETRON_LAST_WINDOWSIZE_H armagetron_last_windowsize_h_help
ARMAGETRON_LAST_WINDOWSIZE_W armagetron_last_windowsize_w_help
ARMAGETRON_SCREENMODE Screen resolution
ARMAGETRON_SCREENMODE_H armagetron_screenmode_h_help
ARMAGETRON_SCREENMODE_W armagetron_screenmode_w_help
ARMAGETRON_WINDOWSIZE Window size
ARMAGETRON_WINDOWSIZE_H armagetron_windowsize_h_help
ARMAGETRON_WINDOWSIZE_W armagetron_windowsize_w_help
AUTO_AIS Automatically spawn AI players?
AUTO_INCAM_1 Automatically switch to internal camera in a maze
AUTO_INCAM_2 Automatically switch to internal camera in a maze
AUTO_INCAM_3 Automatically switch to internal camera in a maze
AUTO_INCAM_4 Automatically switch to internal camera in a maze
AUTO_IQ Automatically adjust AI IQ?
BACKWARD_COMPATIBILITY Maximum number of old protocol versions to support.
BAN Bans the specified player from the server (kicks him first) for a variable time in minutes.
BAN_IP Bans the spedified IP address from the server for a variable time.
BAN_LIST Prints a list of currently banned IPs.
BIG_BROTHER Did we already send the big brother information?
BOOKMARK_10_ADDRESS bookmark_10_address_help
BOOKMARK_10_NAME bookmark_10_name_help
BOOKMARK_10_PORT bookmark_10_port_help
BOOKMARK_1_ADDRESS bookmark_1_address_help
BOOKMARK_1_NAME bookmark_1_name_help
BOOKMARK_1_PORT bookmark_1_port_help
BOOKMARK_2_ADDRESS bookmark_2_address_help
BOOKMARK_2_NAME bookmark_2_name_help
BOOKMARK_2_PORT bookmark_2_port_help
BOOKMARK_3_ADDRESS bookmark_3_address_help
BOOKMARK_3_NAME bookmark_3_name_help
BOOKMARK_3_PORT bookmark_3_port_help
BOOKMARK_4_ADDRESS bookmark_4_address_help
BOOKMARK_4_NAME bookmark_4_name_help
BOOKMARK_4_PORT bookmark_4_port_help
BOOKMARK_5_ADDRESS bookmark_5_address_help
BOOKMARK_5_NAME bookmark_5_name_help
BOOKMARK_5_PORT bookmark_5_port_help
BOOKMARK_6_ADDRESS bookmark_6_address_help
BOOKMARK_6_NAME bookmark_6_name_help
BOOKMARK_6_PORT bookmark_6_port_help
BOOKMARK_7_ADDRESS bookmark_7_address_help
BOOKMARK_7_NAME bookmark_7_name_help
BOOKMARK_7_PORT bookmark_7_port_help
BOOKMARK_8_ADDRESS bookmark_8_address_help
BOOKMARK_8_NAME bookmark_8_name_help
BOOKMARK_8_PORT bookmark_8_port_help
BOOKMARK_9_ADDRESS bookmark_9_address_help
BOOKMARK_9_NAME bookmark_9_name_help
BOOKMARK_9_PORT bookmark_9_port_help
BRAKE_GAUGE_LOCX brake_gauge_locx_help
BRAKE_GAUGE_LOCY brake_gauge_locy_help
BRAKE_GAUGE_SIZE brake_gauge_size_help
BROWSER_CONTACTLOSS browser_contactloss_help
BROWSER_NUM_QUERIES browser_num_queries_help
BROWSER_QUERIES_SIMULTANEOUS browser_queries_simultaneous_help
BROWSER_QUERY_DELAY_GLOBAL browser_query_delay_global_help
BROWSER_QUERY_DELAY_SINGLE browser_query_delay_single_help
BROWSER_QUERY_FILTER browser_query_filter_help
BUG_RIP bug_rip_help
BUG_TRANSPARENCY Unsupported: make all rim walls semi-transparent by rendering them without occlusion tests
BUG_TRANSPARENCY_DEMAND Unsupported: use transparency instead of lowering walls
BUG_TUNNEL bug_tunnel_help
CAMCENTER_1 Center internal camera on driving direction
CAMCENTER_2 Center internal camera on driving direction
CAMCENTER_3 Center internal camera on driving direction
CAMCENTER_4 Center internal camera on driving direction
CAMERA_CUSTOM_BACK Position of the custom camera: how much is it moved back from the cycle?
CAMERA_CUSTOM_PITCH Position of the custom camera: how much does it look up/down?
CAMERA_CUSTOM_RISE Position of the custom camera: how much is it moved up from the cycle?
CAMERA_FOLLOW_START_X Start position of the fixed external camera
CAMERA_FOLLOW_START_Y Start position of the fixed external camera
CAMERA_FOLLOW_START_Z Start position of the fixed external camera
CAMERA_FORBID_CUSTOM Forbids the use of the custom camera on all clients
CAMERA_FORBID_FOLLOW Forbids the use of the fixed external camera on all clients
CAMERA_FORBID_FREE Forbids the use of the free camera on all clients
CAMERA_FORBID_IN Forbids the use of the internal camera on all clients
CAMERA_FORBID_SERVER_CUSTOM camera_forbid_server_custom_help
CAMERA_FORBID_SMART Forbids the use of the internal camera on all clients
CAMERA_FREE_START_X Start position of the free camera
CAMERA_FREE_START_Y Start position of the free camera
CAMERA_FREE_START_Z Start position of the free camera
CAMERA_SERVER_CUSTOM_BACK Position of the custom camera: how much is it moved back from the cycle?
CAMERA_SERVER_CUSTOM_PITCH Position of the custom camera: how much does it look up/down?
CAMERA_SERVER_CUSTOM_RISE Position of the custom camera: how much is it moved up from the cycle?
CAMERA_SMART_GLANCE_CUSTOM use custom camera settings when glancing with the smart camera
CAMERA_SMART_START_X Start position of the smart camera
CAMERA_SMART_START_Y Start position of the smart camera
CAMERA_SMART_START_Z Start position of the smart camera
CAMERA_VISIBILITY_CLIP_SPEED Speed with wich the visibility targets is brought into view
CAMERA_VISIBILITY_EXTENSION Distance (measured in seconds, gets multiplied by speed) of the visibility targets from the watched object
CAMERA_VISIBILITY_LOWER_WALL If set to 1, walls are lowerd when they block the view and the camera is not moved
CAMERA_VISIBILITY_LOWER_WALL_SMART Like CAMERA_VISIBILITY_LOWER_WALL, but special setting for the smart camera
CAMERA_VISIBILITY_RECOVERY_SPEED The speed the external visibility targets recovers from wall hits
CAMERA_VISIBILITY_SIDESKEW Extra forward component of the sideways visibility targets
CAMERA_VISIBILITY_WALL_DISTANCE The distance the visibility targets keep from walls
CAMWOBBLE_1 Lets the internal camera move with your cycle
CAMWOBBLE_2 Lets the internal camera move with your cycle
CAMWOBBLE_3 Lets the internal camera move with your cycle
CAMWOBBLE_4 Lets the internal camera move with your cycle
CENTER_MESSAGE Prints a big message on the screen of all connected clients.
CHECK_ERRORS Listen to errors claiming a video mode does not exist
CLIENT_PORT Port we try to connect to
CM_LOCY cm_locy_help
COLORDEPTH Color depth to use (0: 16 1: desktop 2: 24)
COLOR_B_1 Cycle and wall color, blue component.
COLOR_B_2 Cycle and wall color, blue component.
COLOR_B_3 Cycle and wall color, blue component.
COLOR_B_4 Cycle and wall color, blue component.
COLOR_G_1 Cycle and wall color, green component.
COLOR_G_2 Cycle and wall color, green component.
COLOR_G_3 Cycle and wall color, green component.
COLOR_G_4 Cycle and wall color, green component.
COLOR_R_1 Cycle and wall color, red component.
COLOR_R_2 Cycle and wall color, red component.
COLOR_R_3 Cycle and wall color, red component.
COLOR_R_4 Cycle and wall color, red component.
COLOR_STRINGS Print colored strings
CONSOLE_MESSAGE Prints a message on the console of all connected clients.
CUSTOM_SCREEN_ASPECT Custom screen aspect ratio ( pixel width/pixel height)
CUSTOM_SCREEN_HEIGHT Custom screen size
CUSTOM_SCREEN_WIDTH Custom screen size
CUSTOM_SERVER_NAME Name of the server to connect to
CYCLE_ACCEL Wall acceleration factor
CYCLE_ACCEL_ENEMY Multiplicator to CYCLE_ACCEL for your enemies' walls
CYCLE_ACCEL_ENEMY_OVERRIDE cycle_accel_enemy_override_help
CYCLE_ACCEL_OFFSET Minimum numeric wall distance, must be positive
CYCLE_ACCEL_RIM Multiplicator to CYCLE_ACCEL for the rim walls
CYCLE_ACCEL_RIM_OVERRIDE cycle_accel_rim_override_help
CYCLE_ACCEL_SELF Multiplicator to CYCLE_ACCEL for your own wall
CYCLE_ACCEL_SELF_OVERRIDE cycle_accel_self_override_help
CYCLE_ACCEL_SLINGSHOT Multiplicator to the total effect of CYCLE_ACCEL, if the cycle is between its own wall and another wall
CYCLE_ACCEL_SLINGSHOT_OVERRIDE cycle_accel_slingshot_override_help
CYCLE_ACCEL_TEAM Multiplicator to CYCLE_ACCEL for your temmates' walls
CYCLE_ACCEL_TEAM_OVERRIDE cycle_accel_team_override_help
CYCLE_AVOID_OLDCLIENT_BAD_SYNC If set to 1, old clients will not get sync messages in situations that are known to confuse them
CYCLE_BRAKE Brake intensity
CYCLE_BRAKE_DEPLETE Rate at which the brake reservoir depletes when you are braking
CYCLE_BRAKE_REFILL Rate at which the brake reservoir refills when you are not braking
CYCLE_DELAY Minimum time between turns (must be greater than 0)
CYCLE_DELAY_TIMEBASED Turn delays will be based on the time since the last turn if this is 1 (default) and the distance if this is 0. Intermediate values and values out of these bounds are supported as well.
CYCLE_DELAY_TIMEBASED_OVERRIDE cycle_delay_timebased_override_help
CYCLE_FAIR_ANTILAG If set to 1, this deactivates the anti lag-sliding code when old clients are connected
CYCLE_MAX_REFCOUNT Maximum allowed reference count on cycles before they self destruct. This setting is to protect against performance related DOS attacks.
CYCLE_PACKETLOSS_TOLERANCE Cycle death is prevented as long as the player's failure to turn can be explained by the loss of this many network packets. Enabling this allows cheating.
CYCLE_PING_RUBBER Additional niceness for high ping players
CYCLE_RUBBER Niceness factor to allow you drive really close to a wall
CYCLE_RUBBER_DELAY cycle_rubber_delay_help
CYCLE_RUBBER_DELAY_BONUS cycle_rubber_delay_bonus_help
CYCLE_RUBBER_DELAY_BONUS_OVERRIDE cycle_rubber_delay_bonus_override_help
CYCLE_RUBBER_DELAY_OVERRIDE cycle_rubber_delay_override_help
CYCLE_RUBBER_LEGACY cycle_rubber_legacy_help
CYCLE_RUBBER_MALUS_TIME cycle_rubber_malus_time_help
CYCLE_RUBBER_MALUS_TURN cycle_rubber_malus_turn_help
CYCLE_RUBBER_MALUS_TURN_OVERRIDE cycle_rubber_malus_turn_override_help
CYCLE_RUBBER_MINADJUST When adjusting to or 180ing into a wall, allow going closer by at least this amount (relative to the last distance)
CYCLE_RUBBER_MINADJUST_OVERRIDE cycle_rubber_minadjust_override_help
CYCLE_RUBBER_MINDISTANCE The minimal distance rubber code keeps you from the wall in front of you
CYCLE_RUBBER_MINDISTANCE_LEGACY Extra factor for minimal distance to walls enforced by the rubber code, active when peers with the rip bug are connected
CYCLE_RUBBER_MINDISTANCE_OVERRIDE cycle_rubber_mindistance_override_help
CYCLE_RUBBER_MINDISTANCE_PREPARATION Timescale in seconds a cycle's last turn time is compared with to determine the effect of CYCLE_RUBBER_MINDISTANCE_UNPREPARED.
CYCLE_RUBBER_MINDISTANCE_PREPARATION_OVERRIDE cycle_rubber_mindistance_preparation_override_help
CYCLE_RUBBER_MINDISTANCE_RATIO Additional distance to CYCLE_RUBBER_MINDISTANCE for every length unit of the wall you have in front of you
CYCLE_RUBBER_MINDISTANCE_RATIO_OVERRIDE cycle_rubber_mindistance_ratio_override_help
CYCLE_RUBBER_MINDISTANCE_RESERVOIR Addidional distance if you have an empty rubber meter (gets faded out gradually as you use up all your rubber)
CYCLE_RUBBER_MINDISTANCE_RESERVOIR_OVERRIDE cycle_rubber_mindistance_reservoir_override_help
CYCLE_RUBBER_MINDISTANCE_UNPREPARED Additional distance for unprepared grinds; it gets applied when the cycle's last turn was just a fraction of a second ago and faded out preparation times larger than CYCLE_RUBBER_MINDISTANCE_PREPARATION.
CYCLE_RUBBER_MINDISTANCE_UNPREPARED_OVERRIDE cycle_rubber_mindistance_unprepared_override_help
CYCLE_RUBBER_SPEED Logarithmic speed of wall approximation when rubber is in effect (every second, you get closer to the wall by a factor of ~0.4^{this value})
CYCLE_RUBBER_SPEED_OVERRIDE cycle_rubber_speed_override_help
CYCLE_RUBBER_TIME cycle_rubber_time_help
CYCLE_RUBBER_TIMEBASED Rubber usage is based on distance travelled if this is 0 (default) and the time passed if this is 1. Intermediate values and values out of these bounds are supported as well.
CYCLE_RUBBER_TIMEBASED_OVERRIDE cycle_rubber_timebased_override_help
CYCLE_RUBBER_TIME_OVERRIDE cycle_rubber_time_override_help
CYCLE_SMOOTH_MIN_SPEED cycle_smooth_min_speed_help
CYCLE_SMOOTH_THRESHOLD Only syncs that differ from your position by less than this amount (measured in speed) will be handled smoothly, bigger differences will be applied instantly.
CYCLE_SMOOTH_TIME Timescale for smoothing options. Increasing this will make interpolation smoother, but less accurate. Decreasing it will make network synchronization jumpy.
CYCLE_SOUND_SPEED Sound speed divisor
CYCLE_SPEED Basic speed of your cycle if you drive straight and not close to walls
CYCLE_SPEED_DECAY_ABOVE Rate of cycle speed approaching the value of CYCLE_SPEED from above
CYCLE_SPEED_DECAY_ABOVE_OVERRIDE cycle_speed_decay_above_override_help
CYCLE_SPEED_DECAY_BELOW Rate of cycle speed approaching the value of CYCLE_SPEED from below
CYCLE_SPEED_DECAY_BELOW_OVERRIDE cycle_speed_decay_below_override_help
CYCLE_START_SPEED Initial cycle speed
CYCLE_SYNC_FF Speed of simulation of the extrapolating sync; decrease for lower CPU load, but higher effective ping
CYCLE_SYNC_FF_STEPS Number of extrapolation simulation timesteps each real timestep; increase for better accuracy
CYCLE_SYNC_INTERVAL_ENEMY Time in seconds between server-client updates of enemy cycles
CYCLE_SYNC_INTERVAL_SELF Time in seconds between server-client updates of enemy cycles owned by the client itself
CYCLE_TIME_TOLERANCE Maximum time difference of execution of turns on server and client (for clients that send timing information)
CYCLE_TIME_TOLERANCE_OVERRIDEcycle_time_tolerance_override_help
CYCLE_TURN_SPEED_FACTOR cycle_turn_speed_factor_help
CYCLE_TURN_SPEED_FACTOR_OVERRIDE cycle_turn_speed_factor_override_help
CYCLE_WALL_NEAR Maximum accelerating wall distance
DEDICATED_IDLE After running this time (in hours), the dedicated server takes the next chance to quit.
DITHER Use dithering
DOUBLEBIND_TIME Time in seconds during which no two different keyboard events can trigger the same action
DOUBLEBIND_TIME_OVERRIDE doublebind_time_override_help
ENEMIES_LOCX enemies_locx_help
ENEMIES_LOCY enemies_locy_help
ENEMIES_SIZE enemies_size_help
EXPLOSION explosion_help
EXPLOSION_RADIUS Blast radius of the cycle explosions
EXTRAPOLATOR_SYNC extrapolator_sync_help
FADEOUT_NAME_DELAY Time the player names are shown. Set to 0 if you don't want to show them at all or -1 if you want to show them always.
FAILED_ATTEMPTS Number of failed attemts to initialize graphics mode
FASTEST_LOCX fastest_locx_help
FASTEST_LOCY fastest_locy_help
FASTEST_SIZE fastest_size_help
FAST_FORWARD_MAXSTEP Maximum recording time between rendered frames in fast forward mode
FAST_FORWARD_MAXSTEP_REAL Maximum real time between rendered frames in fast forward mode
FAST_FORWARD_MAXSTEP_REL Maximum fraction of the time left until the end of FF mode between rendered frames
FAV_NUM_PER_TEAM_PLAYER_1 The favorite number of players per team for this player
FAV_NUM_PER_TEAM_PLAYER_2 The favorite number of players per team for this player
FAV_NUM_PER_TEAM_PLAYER_3 The favorite number of players per team for this player
FAV_NUM_PER_TEAM_PLAYER_4 The favorite number of players per team for this player
FINISH_TYPE What happens when the last human is dead?
FIRST_USE Is this the first time you use Armagetron Advanced?
FLOOR_BLUE Floor color
FLOOR_DETAIL Floor detail settings
FLOOR_GREEN Floor color
FLOOR_MIRROR Floor mirror mode
FLOOR_MIRROR_INT Intensity of the floor mirror effect
FLOOR_RED Floor color
FORTRESS_CONQUEST_DECAY_RATE fortress_conquest_decay_rate_help
FORTRESS_CONQUEST_RATE fortress_conquest_rate_help
FORTRESS_DEFEND_RATE fortress_defend_rate_help
FULLSCREEN Fullscreen or windowed mode?
GAMEOBJECT_MOVE_TIMEOUT gameobject_move_timeout_help
GAME_TIMEOUT Base timeout for game state synchronisation; gives appoximately the maximum time between rounds.
GAME_TYPE Type of game played
GL_EXTENSIONS OpenGL system information
GL_RENDERER OpenGL system information
GL_VENDOR OpenGL system information
GL_VERSION OpenGL system information
GRID_SIZE Distance between gridlines
GRID_SIZE_MOVIEPACK Distance between gridlines when moviepack is active
HIGH_RIM Draw high rim walls
INCLUDE Includes the following file
INFINITY_PLANE Use infinite points (Does not work properly on most Windows systems)
INSTANT_CHAT_STRING_1_1 Instant chat available with hotkeys
INSTANT_CHAT_STRING_1_10 Instant chat available with hotkeys
INSTANT_CHAT_STRING_1_11 Instant chat available with hotkeys
INSTANT_CHAT_STRING_1_12 Instant chat available with hotkeys
INSTANT_CHAT_STRING_1_2 Instant chat available with hotkeys
INSTANT_CHAT_STRING_1_3 Instant chat available with hotkeys
INSTANT_CHAT_STRING_1_4 Instant chat available with hotkeys
INSTANT_CHAT_STRING_1_5 Instant chat available with hotkeys
INSTANT_CHAT_STRING_1_6 Instant chat available with hotkeys
INSTANT_CHAT_STRING_1_7 Instant chat available with hotkeys
INSTANT_CHAT_STRING_1_8 Instant chat available with hotkeys
INSTANT_CHAT_STRING_1_9 Instant chat available with hotkeys
INSTANT_CHAT_STRING_2_1 Instant chat available with hotkeys
INSTANT_CHAT_STRING_2_10 Instant chat available with hotkeys
INSTANT_CHAT_STRING_2_11 Instant chat available with hotkeys
INSTANT_CHAT_STRING_2_12 Instant chat available with hotkeys
INSTANT_CHAT_STRING_2_2 Instant chat available with hotkeys
INSTANT_CHAT_STRING_2_3 Instant chat available with hotkeys
INSTANT_CHAT_STRING_2_4 Instant chat available with hotkeys
INSTANT_CHAT_STRING_2_5 Instant chat available with hotkeys
INSTANT_CHAT_STRING_2_6 Instant chat available with hotkeys
INSTANT_CHAT_STRING_2_7 Instant chat available with hotkeys
INSTANT_CHAT_STRING_2_8 Instant chat available with hotkeys
INSTANT_CHAT_STRING_2_9 Instant chat available with hotkeys
INSTANT_CHAT_STRING_3_1 Instant chat available with hotkeys
INSTANT_CHAT_STRING_3_10 Instant chat available with hotkeys
INSTANT_CHAT_STRING_3_11 Instant chat available with hotkeys
INSTANT_CHAT_STRING_3_12 Instant chat available with hotkeys
INSTANT_CHAT_STRING_3_2 Instant chat available with hotkeys
INSTANT_CHAT_STRING_3_3 Instant chat available with hotkeys
INSTANT_CHAT_STRING_3_4 Instant chat available with hotkeys
INSTANT_CHAT_STRING_3_5 Instant chat available with hotkeys
INSTANT_CHAT_STRING_3_6 Instant chat available with hotkeys
INSTANT_CHAT_STRING_3_7 Instant chat available with hotkeys
INSTANT_CHAT_STRING_3_8 Instant chat available with hotkeys
INSTANT_CHAT_STRING_3_9 Instant chat available with hotkeys
INSTANT_CHAT_STRING_4_1 Instant chat available with hotkeys
INSTANT_CHAT_STRING_4_10 Instant chat available with hotkeys
INSTANT_CHAT_STRING_4_11 Instant chat available with hotkeys
INSTANT_CHAT_STRING_4_12 Instant chat available with hotkeys
INSTANT_CHAT_STRING_4_2 Instant chat available with hotkeys
INSTANT_CHAT_STRING_4_3 Instant chat available with hotkeys
INSTANT_CHAT_STRING_4_4 Instant chat available with hotkeys
INSTANT_CHAT_STRING_4_5 Instant chat available with hotkeys
INSTANT_CHAT_STRING_4_6 Instant chat available with hotkeys
INSTANT_CHAT_STRING_4_7 Instant chat available with hotkeys
INSTANT_CHAT_STRING_4_8 Instant chat available with hotkeys
INSTANT_CHAT_STRING_4_9 Instant chat available with hotkeys
KEEP_WINDOW_ACTIVE keep_window_active_help
KEYBOARD Keyboard settings
KICK Kicks the specified player from the server.
KILL kill_help
LADDER_GAIN_EXTRA Ping dependent ladder extra score for the winner
LADDER_LOSE_MIN_ON_LOAD Minimum of you ladder score lost on each load
LADDER_LOSE_PERCENT_ON_LOAD Percentage of your ladder score lost on each load
LADDER_MIN_BET Minimum score you put in the ladder pot
LADDER_PERCENT_BET Percentage of your score you put in the ladder pot
LADDER_TAX Percentage of the ladder pot the IRS takes
LAG_O_METER Draw Lag-O-Meter in network play
LANGUAGE_FIRST The language Armagetron Advanced will use
LANGUAGE_SECOND Fallback language if the first language is not available
LAST_CHECK_ERRORS Listen to errors claiming a video mode does not exist, last successful init
LAST_COLORDEPTH Color depth, last successful init
LAST_FULLSCREEN Fullscreen or windowed mode, last successful init
LAST_ZDEPTH z buffer depth, last successful init
LIMIT_ROUNDS End the match after this number of rounds
LIMIT_SCORE End the match when a player reaches this score
LIMIT_TIME End the match after this number of minutes
LINE_ANTIALIAS Enable line antialiasing
LOWER_SKY Draw lower sky plane
MAP_FILE map_file_help
MAP_FILE_OVERRIDE map_file_override_help
MAX_CLIENTS Maximum number of network clients to accept
MAX_CLIENTS_SAME_IP_HARD Maximum number of network clients to accept from the same IP; more logins will be ignored
MAX_CLIENTS_SAME_IP_SOFT Maximum number of network clients to accept from the same IP; more logins will get kicked when the server is full
MAX_IN_RATE Maximum network input rate
MAX_OUT_RATE Maximum network output rate
MAX_PLAYERS_SAME_IP maximum number of players from the same IP (note that each client can legally host up to four players)
MAX_VOTES The maximum number of total votes that can be active at any given moment.
MAX_VOTES_PER_VOTER The maximum number of votes suggested by each voter that can be active at any given moment.
MESSAGE_OF_DAY_1 Message sent to clients
MESSAGE_OF_DAY_2 Message sent to clients
MESSAGE_OF_DAY_3 Message sent to clients
MESSAGE_OF_DAY_4 Message sent to clients
MESSAGE_OF_DAY_5 Message sent to clients
MIN_PLAYERS Minimum number of players
MIN_VOTERS Number of voters that need to be online to enable voting.
MOUSE_GRAB Grab the mouse pointer, so it can't leave the window
MOVIEPACK Use the moviepack if available
MOVIEPACK_FLOOR_BLUE Floor color
MOVIEPACK_FLOOR_GREEN Floor color
MOVIEPACK_FLOOR_RED Floor color
MOVIEPACK_WALL_STRETCH The distance of the vertical lines on the moviepack walls
NAME_TEAM_AFTER_PLAYER_1 If set, the team is named after the leading player
NAME_TEAM_AFTER_PLAYER_2 If set, the team is named after the leading player
NAME_TEAM_AFTER_PLAYER_3 If set, the team is named after the leading player
NAME_TEAM_AFTER_PLAYER_4 If set, the team is named after the leading player
NETWORK_AUTOBAN_FACTOR Autoban players for NETWORK_AUTOBAN_FACTOR * ( kph - NETWORK_AUTOBAN_OFFSET ) minutes when they get kicked; kph is the average number of kicks per hour they get.
NETWORK_AUTOBAN_MAX_KPH Maximal value of the kicks per hour; larger values are smoothly clamped.
NETWORK_AUTOBAN_OFFSET Autoban players for NETWORK_AUTOBAN_FACTOR * ( kph - NETWORK_AUTOBAN_OFFSET ) minutes when they get kicked; kph is the average number of kicks per hour they get.
NETWORK_MIN_BAN When a client's connection is blocked because he's banned, make him banned for at least this many seconds.
NEW_FEATURE_DELAY Disable features that only came in during the last X protocol versions.
NEW_TEAM_ALLOWED Is it currently allowed to create a new team?
NUM_AIS Number of AI players
PASSWORD Password setting
PASSWORD_STORAGE Determines where your passwords are stored: 1 means on harddisk (dangerous), 0 in memory and -1 means they are not stored at all.
PERSP_CORRECT Enable perspective correction
PING_CHARITY How much ping are you willing to take over from your opponent?
PING_LOCX ping_locx_help
PING_LOCY ping_locy_help
PING_SIZE ping_size_help
PLAYERS players_help
PLAYER_1 Player name
PLAYER_2 Player name
PLAYER_3 Player name
PLAYER_4 Player name
PNG_SCREENSHOT png_screenshot_help
POLY_ANTIALIAS Enable polygon antialiasing
PREDICT_OBJECTS predict cycle movement in network play
REAL_ARENA_SIZE_FACTOR The currently active arena size. Leave it alone! Change size_factor instead.
REAL_CYCLE_SPEED_FACTOR The currently active cycle speed multiplier. Leave it alone! Change speed_factor instead.
RECORDING_DEBUGLEVEL Level of additonal information in recording file.
RESOURCE_REPOSITORY_CLIENT resource_repository_client_help
RESOURCE_REPOSITORY_SERVER resource_repository_server_help
ROUND_CENTER_MESSAGE Big message sent to clients after every round
ROUND_CONSOLE_MESSAGE_1 Message sent to clients after every round
ROUND_CONSOLE_MESSAGE_2 Message sent to clients after every round
ROUND_CONSOLE_MESSAGE_3 Message sent to clients after every round
ROUND_CONSOLE_MESSAGE_4 Message sent to clients after every round
ROUND_CONSOLE_MESSAGE_5 Message sent to clients after every round
RUBBER_GAUGE_LOCX rubber_gauge_locx_help
RUBBER_GAUGE_LOCY rubber_gauge_locy_help
RUBBER_GAUGE_SIZE rubber_gauge_size_help
SAY Dedicated server only: let the server administator say something.
SCORE_DEATHZONE What you get for hitting the Death Zone
SCORE_DIE What you get for dying
SCORE_KILL What you get for killing someone
SCORE_LOCX score_locx_help
SCORE_LOCY score_locy_help
SCORE_SIZE score_size_help
SCORE_SUICIDE What you get for stupidly dying
SCORE_WIN What you get for winning a round
SERVER_DNS server_dns_help
SERVER_IP server_ip_help
SERVER_NAME Name of this server
SERVER_PORT Port this server listens on
SETTING_LEGACY_BEHAVIOR_ANNOYING Default legacy behavior for settings that only cause minor annoyances on old clients, like enemy cycles stopping for .1 seconds after each turn. Example: CYCLE_RUBBER_MINDISTANCE
SETTING_LEGACY_BEHAVIOR_BREAKING Default legacy behavior for settings that absolutely break the client and make play impossible. Example of an affected setting: MAP_FILE
SETTING_LEGACY_BEHAVIOR_BUMPYDefault legacy behavior for settings that allow play on old clients in principle, but with severe limitations (cycles bouncing around, player commands not executed on time). Example: CYCLE_DELAY_TIMEBASED
SETTING_LEGACY_BEHAVIOR_CHEATING Default legacy behavior for settings where the default behavior could be considered cheating if nondefault was set. Example: DOUBLEBIND_TIME
SETTING_LEGACY_BEHAVIOR_VISUAL Default legacy behavior for settings that only affect status displays and visuals, not game physics. Example: CYCLE_RUBBER_* (the client displays the rubber meter, but it's not used for anything)
SHOW_BRAKE show_brake_help
SHOW_ENEMIES show_enemies_help
SHOW_FASTEST show_fastest_help
SHOW_FPS Enable fps display
SHOW_HUD show_hud_help
SHOW_OWN_NAME Should your name be displayed above your cycle on your screen?
SHOW_PING show_ping_help
SHOW_RUBBER show_rubber_help
SHOW_SCORE show_score_help
SHOW_SPEED show_speed_help
SHOW_TIME show_time_help
SILENCE_ALL If set to 1, all chat messages will be omitted.
SIZE_FACTOR Arena size modifier
SKY_WOBBLE Sky animation
SMOOTH_SHADING Enable smooth shading
SOFTWARE_RENDERER Is the OpenGL renderer not hadware accelerated?
SOUND_BUFFER_SHIFT Buffer size multiplier
SOUND_QUALITY Sound quality [0=off, 3=high]
SOUND_SOURCES Number of sound sources to be heard at the same time
SPAM_AUTOKICK Spam score that causes you to get kicked instantly.
SPAM_MAXLEN Maximal length of chat message.
SPAM_MAXLEN_OVERRIDE spam_maxlen_override_help
SPAM_PENALTY Number of seconds to silence a spammer.
SPAM_PROTECTION Harshness of spam protection; determines min delay between chat messages accepted.
SPAM_PROTECTION_CHAT Extra factor for SPAM_PROTECTION for chat messages.
SPAM_PROTECTION_VOTE Extra factor for SPAM_PROTECTION for votes.
SPARKS Draw sparks when going too close to a wall
SPECTATOR_MODE_1 Sets spectator mode for this player
SPECTATOR_MODE_2 Sets spectator mode for this player
SPECTATOR_MODE_3 Sets spectator mode for this player
SPECTATOR_MODE_4 Sets spectator mode for this player
SPEED_FACTOR Speed modifier for the cycles
SPEED_GAUGE_LOCX speed_gauge_locx_help
SPEED_GAUGE_LOCY speed_gauge_locy_help
SPEED_GAUGE_SIZE speed_gauge_size_help
SP_AI_IQ IQ of the AI opponents in single player mode
SP_AUTO_AIS Automatically spawn AI players in single player mode?
SP_AUTO_IQ Automatically adjust AI IQ in single player mode?
SP_EXPLOSION_RADIUS Blast radius of the cycle explosions in single player mode
SP_FINISH_TYPE What happens when the last human is dead in single player mode?
SP_GAME_TYPE Type of game played in single player mode
SP_LIMIT_ROUNDS End the match after this number of rounds in single player mode
SP_LIMIT_SCORE End the match when a player reaches this score in single player mode
SP_LIMIT_TIME End the match after this number of minutes in single player mode
SP_MIN_PLAYERS Minimum number of players in single player mode
SP_NUM_AIS Number of AI players in single player mode
SP_SCORE_WIN What you get for winning a round in single player mode
SP_SIZE_FACTOR Arena size modifier
SP_SPEED_FACTOR Speed modifier for the cycles
SP_TEAMS_MAX Maximum number of teams in single player mode
SP_TEAMS_MIN Minimum number of teams in single player mode
SP_TEAM_BALANCE_ON_QUIT Balance teams on player quit in single player mode?
SP_TEAM_BALANCE_WITH_AIS Balance teams with AI players in single player mode?
SP_TEAM_MAX_IMBALANCE Maximum allowed temporary team imbalance in single player mode
SP_TEAM_MAX_IMBALANCE_PERM Maximum allowed permanent team imbalance in single player mode
SP_TEAM_MAX_PLAYERS Maximum number of players per team in single player mode
SP_TEAM_MIN_PLAYERS Minimum number of players per team in single player mode
SP_WALLS_LENGTH Length of the cycle walls in meters; negative values will make the walls infinite.
SP_WALLS_STAY_UP_DELAY Number of seconds the walls stay up after a player died; negative values will keep them up forever.
SP_WIN_ZONE_MIN_LAST_DEATH Minimum number of seconds since the last death before the instant win zone is activated in single player mode
SP_WIN_ZONE_MIN_ROUND_TIME Minimum number of seconds the round has to be going on before the instant win zone is activated in single player mode
START_CAM_1 Initial Camera
START_CAM_2 Initial Camera
START_CAM_3 Initial Camera
START_CAM_4 Initial Camera
START_FOV_1 Initial field of vision
START_FOV_2 Initial field of vision
START_FOV_3 Initial field of vision
START_FOV_4 Initial field of vision
START_NEW_MATCH Initiates a new match
SWAP_MODE Determines the commands used to sync graphics and input. 0: do nothing, 1: call glFlush(), 2: call glFinish().
TALK_TO_MASTER Announce this server on the internet?
TEAMS_MAX Maximum number of teams
TEAMS_MIN Minimum number of teams
TEAM_BALANCE_ON_QUIT Balance teams on player quit?
TEAM_BALANCE_WITH_AIS Balance teams with AI players?
TEAM_MAX_IMBALANCE Maximum allowed temporary team imbalance
TEAM_MAX_IMBALANCE_PERM Maximum allowed permanent team imbalance
TEAM_MAX_PLAYERS Maximum number of players per team
TEAM_MIN_PLAYERS Minimum number of players per team
TEXTURES_HI Use high color textures
TEXTURE_MODE_0 Floor Texture:
TEXTURE_MODE_1 Wall Textures:
TEXTURE_MODE_2 Object Textures:
TEXTURE_MODE_3 Font:
TEXT_OUT Enable console text output
TOPOLOGY_POLICE The topology police does posteriori checks to determine whether game moves were legal.
UNBAN_IP Revokes the ban of the specified IP address.
UPPER_SKY Draw upper sky plane
URL HTTP URI assiciated with a server
USE_DISPLAYLISTS Use display lists for rendering the cycles?
VIEWPORT_CONF Viewport configuration; decides how many players can play on this computer
VIEWPORT_TO_PLAYER_1 Assign this viewport to a player
VIEWPORT_TO_PLAYER_2 Assign this viewport to a player
VIEWPORT_TO_PLAYER_3 Assign this viewport to a player
VIEWPORT_TO_PLAYER_4 Assign this viewport to a player
VOTING_BIAS Add virtual voters that oppose every change.
VOTING_DECAY One non-voter is ignored everytime this many secons pass.
VOTING_KICK_TIME The minimum time in seconds between two kick votes against the same player.
VOTING_PRIVACY Controls logging of voting process. 2: nothing gets logged 1: vote submission is logged for the server admin 0: voting is logged for the server admin -1: vote submission is made public -2: everything is made public
VOTING_SPAM_ISSUE The spam level of issuing a vote.
VOTING_SPAM_REJECT The spam level of getting your vote rejected.
VOTING_START_DECAY Number of seconds after that the non-voters start to get ignored.
VOTING_TIMEOUT Votes older than this time out and are rejected.
WALLS_LENGTH Length of the cycle walls in meters; negative values will make the walls infinite.
WALLS_STAY_UP_DELAY Number of seconds the walls stay up after a player died; negative values will keep them up forever.
WHITE_SPARKS white_sparks_help
WIN_ZONE_DEATHS A value of 1 turns it into a death zone.
WIN_ZONE_EXPANSION Expansion speed of the instant win zone
WIN_ZONE_INITIAL_SIZE win_zone_initial_size_help
WIN_ZONE_MIN_LAST_DEATH Minimum number of seconds since the last death before the instant win zone is activated
WIN_ZONE_MIN_ROUND_TIME Minimum number of seconds the round has to be going on before the instant win zone is activated
WIN_ZONE_RANDOMNESS Randomness factor of the initial win zone position. 0 fixes it at the arena center, 1 spreads the zone all over it.
WRAP_MENU If set, you leave a menu to the top and reenter it at the bottom.
ZDEPTH z buffer depth to use (0: 16 1: from color depth 2: 32)
ZTRICK Performance tweak; does not work on most Windows systems
</pre>

Embedded Web Server

2005-11-20T21:26:36Z

Philippeqc: Removed MAP_URI

The embedded web server is intended to provide a default installation of the dedicated server that is capable of serving its own resources to clients, providing a statistics page for players, and providing a remote administration function for administrators. It's not intended to replace in-game admin, of course, but to supplement it. As additional stuff gets added, it should be possible to add things to the web interface like managing tournaments and other things I'm not thinking of right now.

== shttpd ==

The web server uses a neat little program called shttpd. It's a program written with the intent of being an embeddable webserver and is used on some routers. It has a very liberal license that is compatible with the GPL, allowing us to include it in the game. It's a C API that supports callbacks, CGI, and some other things.

== Serving Resources ==

This is only partially implemented. I added to the web server the ability to put multiple mount points under the web root so that we can put the <code>resource</code> directory under the web root. There's a couple of things here left to implement. Mainly the game server needs to be able to tell clients a proper URL for resources that uses this web server. Then there needs to be some config items for administrators to use to configure the web server's resource service.

It is this need that primarily introduces the requirement that the webserver be available in the regular client distribution. When a player wants to host a game from his machine using his game client, he should have this web server available to serve ''his'' resources.

=== How the embedded server will interact with the resource server ===

TODO

== Player Web Pages ==

This is only half-baked right now. We have several options.

* CGI
The CGI doesn't currently work in our embedded setup. This needs some troubleshooting. We should support it since it's there and server admins will probably want to be able to use it, even if we don't. In any case, we can provide an interface for players by writing simple CGI scripts, or even writing some C++ programs to do it if we don't want to introduce a scripting dependency for this.

* Callbacks
This is the most likely way we'll go in the foreseeable future. Using the callback interface of the webserver, we can provide pages generated by C++ code in the armagetronad-dedicated process.

* Python
After we have embedded Python, this is the most logical way to go, in which case we will likely still have the scripts executed inside the armagetronad-dedicated process, they'll just be Python scripts instead of C++ code.

== Administrator Web Pages ==

So I created a callback for the /admin url. Smile So after you have it running you can visit http://YOURSERVERWITHPORT/admin?cmd=SOMECOMMAND&value=VALUE

And that command will be executed. Smile I'm going to look next hopefully into putting some protection on that url so a user and pass will be required, hopefully configurable somewhere. Smile But I figured that would be a good start to see if I could do it, anyway.

== Configuring the Web Server ==

TODO

== Old Stuff (left here for reference) ==

''Remainder taken from the forums''

In any case, the web interface now uses its config file. It's still a little messy in one spot, but I'll clean it up. I logged in to the dedicated server with a game client and then hit the web server and noticed no problems with the polling or anything. Since I set the web server to compile in multi-threaded mode, it should start a new thread for every page request, so they shouldn't be served from within the game loop, although the polling for new connections is done in the game loop. (This is what has so far saved me from having to make the uWebInterface class start its own thread)

----

For the repository thing, there's a reason I don't want to make a configuration option for the embedded web server as a repository. It should happen automatically. I.e. you set MAP_FILE and if you set no repository, the embedded web server should serve it automatically, and it should already know where the file is located and the client shoudl request it properly. But you want to support the resource repository, where if the client doesn't have the map, it knows about the resource repository. So, to support both scenarios, a simple flag should tell the server to tell the client to look at the resource repository instead.

This isn't mutually exclusive with the RESOURCE_REPOSITORY item you've mentioned, because a third and perfectly valid scenario is for the server to direct the client to a different resource repository that's not the central repository you're building.

----

Let's see. Sets the webroot to the repository directory. I have a small problem here. I'd like to make it work with cgi scripts and let server admins stick their own scripts on there if they have a cli php or python. If I set the webroot to the repository directory, then server admins have to put web interface files in it. We have to also, for images and stuff. If I set the webroot to something else, I need the resource repository under it. A copy isn't quite right, and there isn't (yet) any way to specify a callback for a specific directory, only for a specific url. I looked at modifying the web server for that and didn't find the solution, but of course I've only just started looking at the web server code.

So I created a callback for the /admin url. Smile So after you have it running you can visit http://YOURSERVERWITHPORT/admin?cmd=SOMECOMMAND&value=VALUE

And that command will be executed. Smile I'm going to look next hopefully into putting some protection on that url so a user and pass will be required, hopefully configurable somewhere. Smile But I figured that would be a good start to see if I could do it, anyway.

----

I think we can have the master tell the server what it's external IP address is, and then it could assemble a URI from that. For the sake of having it Right, I'd be happy to have that, but it still has to work even if there's no master server to give up this information. Wink (Especially considering it needs to work in a default installation, and a default installation has talk_to_master 0 set)

----

Ok, I'm done for the night. Here's what else I added:

www-root directory for web interface files. Probably I'll be adding an admin directory to it which will provide the admin functions I've been working towards, but it's not there yet.

Stuff to tDirectories that's probably wrong. Sad I admit I was quite confused reading that file. I want a call to tDirectories to a method just like GetDirPath() for resources, but I want it to return the path for www-root.

I also ran into a minor problem. Smile I'd like the build system to somehow copy the files under www-root to the build directory, wherever it's at. I'm at something of a loss for that, probably because I need to go to bed.

Still need to add the config option that tells the client to get resources from the embedded webserver and then the code to the client that actually does it. Anything else in this area is dressing. But as it stands right now, the URI should be http://SERVER:PORT/resource/PATH/TO/RESOURCE as Luke-Jr requested. So the client needs to know what the PORT is as well. To add that the way I was wanting I need to transfer the webserver config items to nSettingItems as appropriate, others to other types of course, and then add a series of calls in uWebInterface::Initialize() to initialize the webserver with them, and remove the webserver's call to open its own config file, adding that instead to the dedicated server itself. Most of the options should just stay the same as in the webserver, but some need to be changed (PORT being one of them, it's taken, and too ambiguous anyway).

''Other than that, I'm not too far off from having a basic web-based admin GUI for the server and also having it serve up its own resources. Technically it can already do that if you put the right MAP_URI in your config file for it.'' This is no longer true. MAP_URI has been removed, as it is possible to write the MAP_FILE as "directory/file (http://some.server.com/another_directory/file; http://alternative.server.com/alternative_dir/file)". Also, I think there are 2 resource repository configuration items, one for the client, one for the server. IIRC, the server could point to its onw web server this way.

ANd, in the process there's no telling what I broke. Hopefully not much, because tDirectories is the only file I've touched outside of uWebInterface and the shttpd files.

Server Administration Guide

2005-11-20T19:18:40Z

Philippeqc: Removed MAP_URI

Setting up a server for Armagetron Advanced isn't terribly difficult, but there are a few things you need to consider when you do it. Taking a few minutes to figure out what you're trying to do will save you a whole lot of headache/heartache later on when people start playing your server.

== Starting out ==

Before you consider what OS you're going to use, what version of the game to run, and so forth, you should figure out a few basic parameters of the server. Here are some you should consider.

=== Private or Public? ===
The setting <code>TALK_TO_MASTER</code> is off by default. To make your server public (available on the master server list), you must turn on this setting. If it is off, players will only be able to connect to your server through the [[Server Bookmarks]] using your IP address.

=== Moderated? ===

Armagetron Advanced supports a limited but expanding set of in game administration commands(in 0.2.8, it will be a fairly comprehensive set). The catch is that you can only have one administration password. So in order to make moderators on your server, all you have to do is give out the administration password.

The alternative is to use the voting features that are intended to allow players to moderate the server as they see fit.

You can go either way, of course. It's entirely up to you.

=== Round or Match ===

There are plenty of ways to setup scoring on a server. A common setting is one point for each kill. While this scoring method encourages competitive play, it's not always desirable. On some servers, just surviving to the end of the round is quite an accomplishment, and you may wish to reward players for doing so. Too much of a reward will encourage players to just screw around instead of fighting.

You should also consider if you even want the standard gladiator-style fighting. It's certainly possible to set up scoring to allow for different games, such as [[Roulette]], and to encourage different playing styles. So just take a few minutes to think about it. It'll pay off in the end, because the default game server settings aren't necessarily the most popular scoring rules, and unless you really want the default scoring, you could lose most of your audience in the first two hours of operation if you didn't think about scoring.

== Setting Up ==

So now you've figured out what kind of server you want and how you want people to play on it, and you want to know how to set it up and optionally make it available on the master server browser. Setting up is fairly straightforward.

=== Install the Server ===

First you need to install the server. It's common to think of any given "server" as a special machine built by old women in third-world countries, but actually, a "server" is just any machine that makes a "service" available to other users. In this case, you're going to install software on a computer, possibly your desktop computer, that will make a game service available for other users to use.

So first you need to acquire the package called "armagetronad-dedicated". If you're using Linux, get one that says "linux" on it. For Windows, get the one that has ".exe" on the end of it. For Mac OS X, there's one with a ".dmg" extension for you. Usually the CPU architecture and OS are embedded in the filename, so pick the right one and install it.

We won't go into too many details here about installation, consult the regular documentation for how to install the server for your architecture.

=== Test the Server ===

After installing the server, the first thing you should do is test it. So start it up. If you're in Linux, you will want to become the superuser and type, in a terminal, "/etc/init.d/armagetronad-dedicated start". If you're in Windows, find the icon in your Start menu and click it. Then fire up a client and see if you can connect to it as a LAN game (under Network Game). If you can do this, then you have successfully tested the server. Now you need to shut it down. In Windows, go to the console window for the server (it opens when you start the game) and type "QUIT". In Linux, just do "/etc/init.d/armagetronad-dedicated stop".

=== Secure the Server ===

There isn't really a lot to do here, but you should consider how you want to secure the machine. If you think it will be necessary to ban certain players, then a firewall is your only option. You will need a firewall that allows you to deny connections from users by IP address. It's not foolproof, but it's the only thing that is possible right now to ban players.

If you want your server to be known on the internet, you will probably need to open a port in your router. The default port is 4534, and you need to open it for "udp". Instructions on how to configure this on your router are beyond the scope of this document, you should consult your owner's manual for further information.

Contrarily, if you do not want internet players to be able to use your server, you will need to make sure your router prevents such players but making the port mentioned above inaccessible through the router.

== Make your Settings ==

At this point you should have a good idea of what kind of server you're going to run and you should also have a working server running, but you don't yet have the server you set out to build. Now you need to configure the server itself.

The server is very flexible. As of the 0.2.8 release, you have pretty complete control over the simulation, and you also have some settings that you can configure the game rules a bit. So now all you need to do is make the settings, right? Wrong. :) First you need to understand how the settings are loaded and in what order.

=== Finding the Settings ===
* Linux -> <code>/etc/games/armagetronad-dedicated</code>
* Mac OS X -> <code>~/Library/Application Support/Armagetron Advanced</code>
* Windows -> <code>C:\program files\armagetronad</code>

Here are the files you will find (Note: this is for the 0.2.8 server, older servers vary):

;aiplayers.cfg
:This file contains the information used to determine the AI player names and skills. You can edit this file to make a more customized set of AI players, but make sure to take backups. When you upgrade or reinstall the server this file will be overwritten.

;default.cfg
:This file contains a reasonable set of defaults and shouldn't be edited.

;master.srv
:This file contains the location of the master server and connection parameters. You can edit it, but then your server won't be able to communicate with the master server that everyone uses, so only do so if you really know what you're doing and have a good reason to do it.

;rc.config
:This file is used to configure the UNIX daemon. It may not be present in Windows/Mac OS X.

;settings.cfg
:This file contains the basic set of settings used by both the client and the server. You should not edit this file.

;settings_dedicated.cfg
:This file contains an extended set of settings used by the dedicated server. You should not edit this file either.

So where should you make your changes? There are 4 files that were not listed, but they are the files you should edit! Why aren't they listed? ''You'' are supposed to make them, using a regular text editor. So, open settings_dedicated.cfg and copy the appropriate lines into the following files:

;autoexec.cfg
:I don't know what this is for, I don't use it. (Lucifer)

;server_info.cfg
:You should put server policy settings here, as well as the SERVER_NAME and connection information.

;settings_custom.cfg
:This is the file that should contain game rule and simulation settings. If you obey the convention for <code>server_info.cfg</code> and <code>settings_custom.cfg</code>, your server will not only be easier to maintain, but also easier to exchange settings with other administrators.

;everytime.cfg
:This file is loaded and processed every round. In a running server, that means you can use this file to change settings on the fly. It also means you can put special information using console commands here. For example:

<code>
SAY Server stats at http://www.armagetronadstats.com/
</code>

...will display "Admin: Server stats at http://www.armagetronadstats.com/" between every round. Very useful! You can also put:

<code>
INCLUDE settings_custom.cfg
</code>

...and your settings_custom.cfg file will be reloaded every round. Not particularly useful, but it can be helpful when you need to tweak simulation settings.

=== Making your own Settings ===

The most common settings to change affect game logic, scoring, and some basic simulation such as cycle speed, acceleration, and so forth.

==== Simulation Settings ====
;EXPLOSION_RADIUS
:Blast radius of cycle explosions. Set to 0 to have no explosion radius (obviously).
;WALLS_LENGTH
:Cycle trail length. Set to -1 to have infinite trails.
;WALLS_STAY_UP_DELAY
:Cycle trail stay up this long after the cycle's destruction, measured in seconds.
;SPEED_FACTOR
:Cycle speed factor. Increase this by two to double the speed
;CYCLE_RUBBER
:This affects grinding. Higher numbers allow players to get closer to walls before crashing. It's intended to be used solely to correct for lag, but it's usually not used that way.

==== Map Settings ====
;ARENA_AXES
:Sets the number of possible driving directions (used only when map is axes-independent, otherwise the map overwrite this value)
;MAP_FILE
:This describe how to retreive a map. It uses a special syntax to allow to describe the location of the map on the local disk and a possible list of network based location, such as web url, where to retreive the file. The syntax is "[./][directory[/directory[...]]]/filename [(fulluri[; fulluri[; fulluri[...]]])]". By default, missing files are looked up by the client on the central resource repository. If one of more URI are given in the MAP_FILE, they will be queried before going to the resource repository.

==== Game Rules ====

;SCORE_WIN
:Points you gain for being last one alive. Also known as "camping points"
;SCORE_SUICIDE
:Points you gain for every stupid death (race into the rim/your own wall). It is added, so negative numbers are appropriate here unless you want to reward people for being stupid.
;SCORE_KILL
:Points you gain for everyone racing into your wall.
;SCORE_DIE
:Points you gain for every time you race into someone else's wall. Like SCORE_SUICIDE, you should make this a negative number unless you want to reward people for sucking.

;LIMIT_SCORE
:Score limit. When a player reaches this score, the match ends and that player wins. Ties are resolved by playing another round until one player has more points than the rest.
;LIMIT_ROUNDS
:Max number of rounds to play. When this is reached, the highest-scoring player is named the winner.
;LIMIT_TIME
:Max time (in minutes). When this is reached, the highest-scoring player is named the winner of the match.

Here is a pretty common setup:

<pre>
SCORE_WIN 0
SCORE_SUICIDE 0
SCORE_KILL 1
SCORE_DIE 0

LIMIT_SCORE 10
LIMIT_ROUNDS 40
LIMIT_TIME 30
</pre>

This is the scoring system used on servers like Swampland, the old Tigers Network servers, and the goshdarn clones that are floating around. It basically means you have to get 10 points by killing other players to win the match. Breakfast in Hell used a variation:

<pre>
SCORE_WIN 0
SCORE_SUICIDE 0
SCORE_KILL 1
SCORE_DIE 0

LIMIT_SCORE 1000
LIMIT_ROUNDS 40
LIMIT_TIME 7
</pre>

You still had to kill people to win, but the match was limited to 7 minutes. After 7 minutes, a winner was declared. The Crack Pipe still uses these settings at the time of writing but may change in the future.

'''This isn't a complete list!'''

There are a whole slew of configuration items available. Since the config items are the same as console commands, you can see a pretty complete list on the [[Console Commands]] page.

== Finishing Up ==

The last thing you need to figure out is usually the first thing you know. Do you want this server to be known by the master server? If so, you need to add this line to your settings_custom.cfg:

<code>
TALK_TO_MASTER 1
</code>

Note: in previous versions, this was the default, but as of 0.2.8, the default will be to not talk to master. You will have to manually set that, so make it the last thing you do before starting the server up for play.

Of course, when that's all done, you need to start the server. Use the same procedure already referenced.

== Conclusion ==

This article is the basic "How to setup a game server" article. After reading through this article and getting your server running, the best thing you can do is to play your server for awhile, talk to other administrators, and so forth. Find out what people want, or figure out what you want. Tweak your settings however you'd like, it's your server. When you feel like you've got the hang of running a server, check out the [[Advanced Server Administration Guide]] for more cool things you can do with your server.

In the meantime, have fun!

Making Maps by Hand

2005-11-13T16:41:44Z

Philippeqc: Removed the Todo's

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


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

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


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

Making Maps by Hand

2005-11-13T16:18:59Z

Philippeqc: Major on Field's logical box. Minor on: example for Map and World, link to config details in Setting, best practice about arena size, </pre> in Zones examples

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


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

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


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

== TODO: ==

* how to submit resource (why is this todo? it's covered in Resource Repository --Luke-Jr)
* Extension

Making Maps by Hand

2005-11-13T14:50:46Z

Philippeqc: Added example to Resource and partial examples for Zones

To correct:
- '''dtd version name'''
- '''map version'''
- '''pre-intro text'''
- '''concept''' might be the wrong word, people might interpret it
as "the concept used for the map is to give a feeling of claustrophobia"
- text about commisioner is pure crap

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


<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. 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 '''TODO'''.

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.

== 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 following 2 paragraph are post map-0.2.8_beta3 and 0.2.8_beta3.

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

This is not a hard rule of any sort. 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.

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

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


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

== TODO: ==

* how to submit resource (why is this todo? it's covered in Resource Repository --Luke-Jr)
* Extension

Making Maps by Hand

2005-11-13T14:18:25Z

Philippeqc: Added some examples for Zones, and now all examples aren't numbered,

To correct:
- '''dtd version name'''
- '''map version'''
- '''pre-intro text'''
- '''concept''' might be the wrong word, people might interpret it
as "the concept used for the map is to give a feeling of claustrophobia"
- text about commisioner is pure crap

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


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

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. 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 '''TODO'''.

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.

== 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 following 2 paragraph are post map-0.2.8_beta3 and 0.2.8_beta3.

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

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.

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

This is not a hard rule of any sort. 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.

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

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


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

== TODO: ==

* how to submit resource (why is this todo? it's covered in Resource Repository --Luke-Jr)
* Extension

Making Maps by Hand

2005-11-13T13:25:24Z

Philippeqc: Filled Header section

To correct:
- '''dtd version name'''
- '''map version'''
- '''pre-intro text'''
- '''concept''' might be the wrong word, people might interpret it
as "the concept used for the map is to give a feeling of claustrophobia"
- text about commisioner is pure crap

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


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

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. 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 '''TODO'''.

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.

== 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 following 2 paragraph are post map-0.2.8_beta3 and 0.2.8_beta3.

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 6.1.2 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 6.1.2 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 6.2.1 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 6.2.2 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 example 6.2.3 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.

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

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 6.2.4: 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.3.1:
<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.3.1, in degrees:
<pre>
<Axes number="6">
<Axis angle="210"/>
<Axis angle="270"/>
<Axis angle="330"/>
<Axis angle="30"/>
<Axis angle="90"/>
<Axis angle="150"/>
</Axes>
</pre>

This defines 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.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>

or, in degrees:
<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 6.3.3:
<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 7.1:
<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.
<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 8.1:
<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.

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.

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.

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.

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.

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

This is not a hard rule of any sort. 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.

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

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


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

== TODO: ==

* how to submit resource (why is this todo? it's covered in Resource Repository --Luke-Jr)
* Extension

Making Maps by Hand

2005-11-13T13:14:12Z

Philippeqc: Axis uses xdir and ydir, not x and y

To correct:
- '''dtd version name'''
- '''map version'''
- '''pre-intro text'''
- '''concept''' might be the wrong word, people might interpret it
as "the concept used for the map is to give a feeling of claustrophobia"
- text about commisioner is pure crap

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


<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 ==
Fill this part

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

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. 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 '''TODO'''.

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.

== 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 following 2 paragraph are post map-0.2.8_beta3 and 0.2.8_beta3.

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 6.1.2 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 6.1.2 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 6.2.1 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 6.2.2 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 example 6.2.3 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.

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

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 6.2.4: 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.3.1:
<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.3.1, in degrees:
<pre>
<Axes number="6">
<Axis angle="210"/>
<Axis angle="270"/>
<Axis angle="330"/>
<Axis angle="30"/>
<Axis angle="90"/>
<Axis angle="150"/>
</Axes>
</pre>

This defines 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.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>

or, in degrees:
<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 6.3.3:
<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 7.1:
<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.
<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 8.1:
<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.

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.

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.

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.

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.

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

This is not a hard rule of any sort. 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.

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

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


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

== TODO: ==

* how to submit resource (why is this todo? it's covered in Resource Repository --Luke-Jr)
* Extension

Making Maps by Hand

2005-11-11T19:20:34Z

Philippeqc: Axis uses xdir and ydir

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


<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 ==
Fill this part

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

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. 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 '''TODO'''.

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.

== 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 following 2 paragraph are post map-0.2.8_beta3 and 0.2.8_beta3.

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 x="1" y="1"/>
<Axis x="1" y="-1"/>
<Axis x="-1" y="-1"/>
<Axis x="-1" y="1"/>
</Axes>
</pre>

The Axis element uses the following fields:
;x
: This is size of the displacement along the x's for this axis
;y
: 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 x and y 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 x="225" length="1.4142"/>
<Axis x="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 x and a y of 1. The real length of the described Axis is
<math>\sqrt{x^2+y^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 6.1.2 Axes of size 2
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="2"/>
<Axis x="2" y="0"/>
<Axis x="0" y="-2"/>
<Axis x="-2" y="0"/>
</Axes>
</pre>

Example 6.1.2 Axes of size 0.5
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="0.5"/>
<Axis x="0.5" y="0"/>
<Axis x="0" y="-0.5"/>
<Axis x="-0.5" y="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 6.2.1 Rectangle of equal travel time
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="10"/>
<Axis x="1" y="0"/>
<Axis x="0" y="-10"/>
<Axis x="-1" y="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 6.2.2 Rectangle of compressed travel time
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="20"/>
<Axis x="1" y="0"/>
<Axis x="0" y="-20"/>
<Axis x="-1" y="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 example 6.2.3 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.

Example 6.2.3
<pre>
<Axes number="4" normalize="false">
<Axis x="0.5" y="0"/>
<Axis x="0" y="-3"/>
<Axis x="-0.5" y="0"/>
<Axis x="0" y="3"/>
</Axes>
</pre>

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 6.2.4: Parallelogram arena
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="1"/>
<Axis x="1" y="0.5"/>
<Axis x="0" y="-1"/>
<Axis x="-1" y="-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.3.1:
<pre>
<Axes number="6" normalize="true">
<Axis x="-0.5" y="-0.866025404"/>
<Axis x="-1" y="0"/>
<Axis x="-0.5" y="0.866025404"/>
<Axis x="0.5" y="0.866025404"/>
<Axis x="1" y="0"/>
<Axis x="0.5" y="-0.866025404"/>
</Axes>
</pre>

Example 6.3.1, in degrees:
<pre>
<Axes number="6">
<Axis angle="210"/>
<Axis angle="270"/>
<Axis angle="330"/>
<Axis angle="30"/>
<Axis angle="90"/>
<Axis angle="150"/>
</Axes>
</pre>

This defines 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.3.2:
<pre>
<Axes number="6" normalize="true">
<Axis x="-0.5" y="-0.866025404"/>
<Axis x="-0.5" y="0.866025404"/>
<Axis x="-1" y="0"/>
<Axis x="0.5" y="0.866025404"/>
<Axis x="0.5" y="-0.866025404"/>
<Axis x="1" y="0"/>
</Axes>
</pre>

or, in degrees:
<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 6.3.3:
<pre>
<Axes number="4" normalize="true">
<Axis x="1" y="0"/>
<Axis x="0" y="1"/>
<Axis x="-1" y="0"/>
<Axis x="0" y="-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 7.1:
<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.
<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 8.1:
<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.

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.

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.

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.

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.

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

This is not a hard rule of any sort. 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.

==== 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
x and y 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>

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


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

== TODO: ==

* how to submit resource (why is this todo? it's covered in Resource Repository --Luke-Jr)
* Extension

Making Maps by Hand

2005-11-11T18:54:19Z

Philippeqc: Corrected and completed the resource

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


<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 ==
Fill this part

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

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. 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 '''TODO'''.

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.

== 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 following 2 paragraph are post map-0.2.8_beta3 and 0.2.8_beta3.

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 x="1" y="1"/>
<Axis x="1" y="-1"/>
<Axis x="-1" y="-1"/>
<Axis x="-1" y="1"/>
</Axes>
</pre>

The Axis element uses the following fields:
;x
: This is size of the displacement along the x's for this axis
;y
: 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 x and y 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 x="225" length="1.4142"/>
<Axis x="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 x and a y of 1. The real length of the described Axis is
<math>\sqrt{x^2+y^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 6.1.2 Axes of size 2
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="2"/>
<Axis x="2" y="0"/>
<Axis x="0" y="-2"/>
<Axis x="-2" y="0"/>
</Axes>
</pre>

Example 6.1.2 Axes of size 0.5
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="0.5"/>
<Axis x="0.5" y="0"/>
<Axis x="0" y="-0.5"/>
<Axis x="-0.5" y="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 6.2.1 Rectangle of equal travel time
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="10"/>
<Axis x="1" y="0"/>
<Axis x="0" y="-10"/>
<Axis x="-1" y="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 6.2.2 Rectangle of compressed travel time
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="20"/>
<Axis x="1" y="0"/>
<Axis x="0" y="-20"/>
<Axis x="-1" y="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 example 6.2.3 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.

Example 6.2.3
<pre>
<Axes number="4" normalize="false">
<Axis x="0.5" y="0"/>
<Axis x="0" y="-3"/>
<Axis x="-0.5" y="0"/>
<Axis x="0" y="3"/>
</Axes>
</pre>

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 6.2.4: Parallelogram arena
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="1"/>
<Axis x="1" y="0.5"/>
<Axis x="0" y="-1"/>
<Axis x="-1" y="-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.3.1:
<pre>
<Axes number="6" normalize="true">
<Axis x="-0.5" y="-0.866025404"/>
<Axis x="-1" y="0"/>
<Axis x="-0.5" y="0.866025404"/>
<Axis x="0.5" y="0.866025404"/>
<Axis x="1" y="0"/>
<Axis x="0.5" y="-0.866025404"/>
</Axes>
</pre>

Example 6.3.1, in degrees:
<pre>
<Axes number="6">
<Axis angle="210"/>
<Axis angle="270"/>
<Axis angle="330"/>
<Axis angle="30"/>
<Axis angle="90"/>
<Axis angle="150"/>
</Axes>
</pre>

This defines 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.3.2:
<pre>
<Axes number="6" normalize="true">
<Axis x="-0.5" y="-0.866025404"/>
<Axis x="-0.5" y="0.866025404"/>
<Axis x="-1" y="0"/>
<Axis x="0.5" y="0.866025404"/>
<Axis x="0.5" y="-0.866025404"/>
<Axis x="1" y="0"/>
</Axes>
</pre>

or, in degrees:
<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 6.3.3:
<pre>
<Axes number="4" normalize="true">
<Axis x="1" y="0"/>
<Axis x="0" y="1"/>
<Axis x="-1" y="0"/>
<Axis x="0" y="-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 7.1:
<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.
<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 8.1:
<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.

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.

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.

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.

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.

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

This is not a hard rule of any sort. 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.

==== 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
x and y 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>

<Field>
<Axes number="4" normalize="false">
<Axis x="1" y="0"/>
<Axis x="-0.2" y="-1"/>
<Axis x="-1" y="0"/>
<Axis x="0.2" y="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>


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

== TODO: ==

* how to submit resource (why is this todo? it's covered in Resource Repository --Luke-Jr)
* Extension

User talk:Luke-Jr

2005-11-11T17:47:01Z

Philippeqc: Why there is a todo on "how to submit a resource"

the "how to submit a resource" is a todo because it is the text that was written before the big discussion about file format. Therefore, it need to be compared to the actual decision, and possibly expanded to include changes or extra details.

The only thing good about it is that its nearly what we agreed upon, so it should be minor as change.

Also, and very important, resource submitting should be in its own document. Now its only relating to maps, but it is for all resources after all.

-ph

Making Maps by Hand

2005-10-22T19:04:44Z

Philippeqc:

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


<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 ==
Fill this part

== Resource ==
This section is under development!

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.

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. 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 '''TODO'''.

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.

== 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 following 2 paragraph are post map-0.2.8_beta3 and 0.2.8_beta3.

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 x="1" y="1"/>
<Axis x="1" y="-1"/>
<Axis x="-1" y="-1"/>
<Axis x="-1" y="1"/>
</Axes>
</pre>

The Axis element uses the following fields:
;x
: This is size of the displacement along the x's for this axis
;y
: 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 x and y 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 x="225" length="1.4142"/>
<Axis x="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 x and a y of 1. The real length of the described Axis is
<math>\sqrt{x^2+y^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 6.1.2 Axes of size 2
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="2"/>
<Axis x="2" y="0"/>
<Axis x="0" y="-2"/>
<Axis x="-2" y="0"/>
</Axes>
</pre>

Example 6.1.2 Axes of size 0.5
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="0.5"/>
<Axis x="0.5" y="0"/>
<Axis x="0" y="-0.5"/>
<Axis x="-0.5" y="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 6.2.1 Rectangle of equal travel time
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="10"/>
<Axis x="1" y="0"/>
<Axis x="0" y="-10"/>
<Axis x="-1" y="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 6.2.2 Rectangle of compressed travel time
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="20"/>
<Axis x="1" y="0"/>
<Axis x="0" y="-20"/>
<Axis x="-1" y="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 example 6.2.3 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.

Example 6.2.3
<pre>
<Axes number="4" normalize="false">
<Axis x="0.5" y="0"/>
<Axis x="0" y="-3"/>
<Axis x="-0.5" y="0"/>
<Axis x="0" y="3"/>
</Axes>
</pre>

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 6.2.4: Parallelogram arena
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="1"/>
<Axis x="1" y="0.5"/>
<Axis x="0" y="-1"/>
<Axis x="-1" y="-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.3.1:
<pre>
<Axes number="6" normalize="true">
<Axis x="-0.5" y="-0.866025404"/>
<Axis x="-1" y="0"/>
<Axis x="-0.5" y="0.866025404"/>
<Axis x="0.5" y="0.866025404"/>
<Axis x="1" y="0"/>
<Axis x="0.5" y="-0.866025404"/>
</Axes>
</pre>

Example 6.3.1, in degrees:
<pre>
<Axes number="6">
<Axis angle="210"/>
<Axis angle="270"/>
<Axis angle="330"/>
<Axis angle="30"/>
<Axis angle="90"/>
<Axis angle="150"/>
</Axes>
</pre>

This defines 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.3.2:
<pre>
<Axes number="6" normalize="true">
<Axis x="-0.5" y="-0.866025404"/>
<Axis x="-0.5" y="0.866025404"/>
<Axis x="-1" y="0"/>
<Axis x="0.5" y="0.866025404"/>
<Axis x="0.5" y="-0.866025404"/>
<Axis x="1" y="0"/>
</Axes>
</pre>

or, in degrees:
<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 6.3.3:
<pre>
<Axes number="4" normalize="true">
<Axis x="1" y="0"/>
<Axis x="0" y="1"/>
<Axis x="-1" y="0"/>
<Axis x="0" y="-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 7.1:
<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.
<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 8.1:
<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.

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.

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.

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.

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.

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

This is not a hard rule of any sort. 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.

==== 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
x and y 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>

<Field>
<Axes number="4" normalize="false">
<Axis x="1" y="0"/>
<Axis x="-0.2" y="-1"/>
<Axis x="-1" y="0"/>
<Axis x="0.2" y="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>


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

== TODO: ==

* how to submit resource
* Extension

Making Maps by Hand

2005-10-22T19:03:45Z

Philippeqc: /* HexaTRON */

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


<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 ==
Fill this part

== Resource ==
This section is under development!

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.

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. 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 '''TODO'''.

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.

== 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 following 2 paragraph are post map-0.2.8_beta3 and 0.2.8_beta3.

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 x="1" y="1"/>
<Axis x="1" y="-1"/>
<Axis x="-1" y="-1"/>
<Axis x="-1" y="1"/>
</Axes>
</pre>

The Axis element uses the following fields:
;x
: This is size of the displacement along the x's for this axis
;y
: 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 x and y 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 x="225" length="1.4142"/>
<Axis x="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 x and a y of 1. The real length of the described Axis is
<math>\sqrt{x^2+y^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 6.1.2 Axes of size 2
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="2"/>
<Axis x="2" y="0"/>
<Axis x="0" y="-2"/>
<Axis x="-2" y="0"/>
</Axes>
</pre>

Example 6.1.2 Axes of size 0.5
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="0.5"/>
<Axis x="0.5" y="0"/>
<Axis x="0" y="-0.5"/>
<Axis x="-0.5" y="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 6.2.1 Rectangle of equal travel time
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="10"/>
<Axis x="1" y="0"/>
<Axis x="0" y="-10"/>
<Axis x="-1" y="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 6.2.2 Rectangle of compressed travel time
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="20"/>
<Axis x="1" y="0"/>
<Axis x="0" y="-20"/>
<Axis x="-1" y="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 example 6.2.3 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.

Example 6.2.3
<pre>
<Axes number="4" normalize="false">
<Axis x="0.5" y="0"/>
<Axis x="0" y="-3"/>
<Axis x="-0.5" y="0"/>
<Axis x="0" y="3"/>
</Axes>
</pre>

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 6.2.4: Parallelogram arena
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="1"/>
<Axis x="1" y="0.5"/>
<Axis x="0" y="-1"/>
<Axis x="-1" y="-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.3.1:
<pre>
<Axes number="6" normalize="true">
<Axis x="-0.5" y="-0.866025404"/>
<Axis x="-1" y="0"/>
<Axis x="-0.5" y="0.866025404"/>
<Axis x="0.5" y="0.866025404"/>
<Axis x="1" y="0"/>
<Axis x="0.5" y="-0.866025404"/>
</Axes>
</pre>

Example 6.3.1, in degrees:
<pre>
<Axes number="6">
<Axis angle="210"/>
<Axis angle="270"/>
<Axis angle="330"/>
<Axis angle="30"/>
<Axis angle="90"/>
<Axis angle="150"/>
</Axes>
</pre>

This defines 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.3.2:
<pre>
<Axes number="6" normalize="true">
<Axis x="-0.5" y="-0.866025404"/>
<Axis x="-0.5" y="0.866025404"/>
<Axis x="-1" y="0"/>
<Axis x="0.5" y="0.866025404"/>
<Axis x="0.5" y="-0.866025404"/>
<Axis x="1" y="0"/>
</Axes>
</pre>

or, in degrees:
<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 6.3.3:
<pre>
<Axes number="4" normalize="true">
<Axis x="1" y="0"/>
<Axis x="0" y="1"/>
<Axis x="-1" y="0"/>
<Axis x="0" y="-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 7.1:
<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.
<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 8.1:
<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.

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.

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.

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.

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.

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

This is not a hard rule of any sort. 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.

==== 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
x and y 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>

<Field>
<Axes number="4" normalize="false">
<Axis x="1" y="0"/>
<Axis x="-0.2" y="-1"/>
<Axis x="-1" y="0"/>
<Axis x="0.2" y="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>


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

== TODO: ==

* how to submit resource
* Extension

Making Maps by Hand

2005-10-22T19:03:31Z

Philippeqc: /* Parallelogram arena */

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


<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 ==
Fill this part

== Resource ==
This section is under development!

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.

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. 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 '''TODO'''.

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.

== 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 following 2 paragraph are post map-0.2.8_beta3 and 0.2.8_beta3.

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 x="1" y="1"/>
<Axis x="1" y="-1"/>
<Axis x="-1" y="-1"/>
<Axis x="-1" y="1"/>
</Axes>
</pre>

The Axis element uses the following fields:
;x
: This is size of the displacement along the x's for this axis
;y
: 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 x and y 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 x="225" length="1.4142"/>
<Axis x="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 x and a y of 1. The real length of the described Axis is
<math>\sqrt{x^2+y^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 6.1.2 Axes of size 2
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="2"/>
<Axis x="2" y="0"/>
<Axis x="0" y="-2"/>
<Axis x="-2" y="0"/>
</Axes>
</pre>

Example 6.1.2 Axes of size 0.5
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="0.5"/>
<Axis x="0.5" y="0"/>
<Axis x="0" y="-0.5"/>
<Axis x="-0.5" y="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 6.2.1 Rectangle of equal travel time
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="10"/>
<Axis x="1" y="0"/>
<Axis x="0" y="-10"/>
<Axis x="-1" y="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 6.2.2 Rectangle of compressed travel time
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="20"/>
<Axis x="1" y="0"/>
<Axis x="0" y="-20"/>
<Axis x="-1" y="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 example 6.2.3 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.

Example 6.2.3
<pre>
<Axes number="4" normalize="false">
<Axis x="0.5" y="0"/>
<Axis x="0" y="-3"/>
<Axis x="-0.5" y="0"/>
<Axis x="0" y="3"/>
</Axes>
</pre>

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 6.2.4: Parallelogram arena
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="1"/>
<Axis x="1" y="0.5"/>
<Axis x="0" y="-1"/>
<Axis x="-1" y="-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.3.1:
<pre>
<Axes number="6" normalize="true">
<Axis x="-0.5" y="-0.866025404"/>
<Axis x="-1" y="0"/>
<Axis x="-0.5" y="0.866025404"/>
<Axis x="0.5" y="0.866025404"/>
<Axis x="1" y="0"/>
<Axis x="0.5" y="-0.866025404"/>
</Axes>
</pre>

Example 6.3.1, in degrees:
<pre>
<Axes number="6">
<Axis angle="210"/>
<Axis angle="270"/>
<Axis angle="330"/>
<Axis angle="30"/>
<Axis angle="90"/>
<Axis angle="150"/>
</Axes>
</pre>

This defines 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.3.2:
<pre>
<Axes number="6" normalize="true">
<Axis x="-0.5" y="-0.866025404"/>
<Axis x="-0.5" y="0.866025404"/>
<Axis x="-1" y="0"/>
<Axis x="0.5" y="0.866025404"/>
<Axis x="0.5" y="-0.866025404"/>
<Axis x="1" y="0"/>
</Axes>
</pre>

or, in degrees:
<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 6.3.3:
<pre>
<Axes number="4" normalize="true">
<Axis x="1" y="0"/>
<Axis x="0" y="1"/>
<Axis x="-1" y="0"/>
<Axis x="0" y="-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 7.1:
<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.
<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 8.1:
<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.

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.

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.

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.

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.

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

This is not a hard rule of any sort. 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.

==== 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
x and y 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>

<Field>
<Axes number="4" normalize="false">
<Axis x="1" y="0"/>
<Axis x="-0.2" y="-1"/>
<Axis x="-1" y="0"/>
<Axis x="0.2" y="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_beta3">
<World>
<Field>


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

== TODO: ==

* how to submit resource
* Extension

Making Maps by Hand

2005-10-22T15:59:34Z

Philippeqc: One too many version field in the Resource element

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


<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 ==
Fill this part

== Resource ==
This section is under development!

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.

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. 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 '''TODO'''.

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.

== 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 following 2 paragraph are post map-0.2.8_beta3 and 0.2.8_beta3.

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 x="1" y="1"/>
<Axis x="1" y="-1"/>
<Axis x="-1" y="-1"/>
<Axis x="-1" y="1"/>
</Axes>
</pre>

The Axis element uses the following fields:
;x
: This is size of the displacement along the x's for this axis
;y
: 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 x and y 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 x="225" length="1.4142"/>
<Axis x="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 x and a y of 1. The real length of the described Axis is
<math>\sqrt{x^2+y^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 6.1.2 Axes of size 2
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="2"/>
<Axis x="2" y="0"/>
<Axis x="0" y="-2"/>
<Axis x="-2" y="0"/>
</Axes>
</pre>

Example 6.1.2 Axes of size 0.5
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="0.5"/>
<Axis x="0.5" y="0"/>
<Axis x="0" y="-0.5"/>
<Axis x="-0.5" y="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 6.2.1 Rectangle of equal travel time
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="10"/>
<Axis x="1" y="0"/>
<Axis x="0" y="-10"/>
<Axis x="-1" y="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 6.2.2 Rectangle of compressed travel time
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="20"/>
<Axis x="1" y="0"/>
<Axis x="0" y="-20"/>
<Axis x="-1" y="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 example 6.2.3 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.

Example 6.2.3
<pre>
<Axes number="4" normalize="false">
<Axis x="0.5" y="0"/>
<Axis x="0" y="-3"/>
<Axis x="-0.5" y="0"/>
<Axis x="0" y="3"/>
</Axes>
</pre>

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 6.2.4: Parallelogram arena
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="1"/>
<Axis x="1" y="0.5"/>
<Axis x="0" y="-1"/>
<Axis x="-1" y="-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.3.1:
<pre>
<Axes number="6" normalize="true">
<Axis x="-0.5" y="-0.866025404"/>
<Axis x="-1" y="0"/>
<Axis x="-0.5" y="0.866025404"/>
<Axis x="0.5" y="0.866025404"/>
<Axis x="1" y="0"/>
<Axis x="0.5" y="-0.866025404"/>
</Axes>
</pre>

Example 6.3.1, in degrees:
<pre>
<Axes number="6">
<Axis angle="210"/>
<Axis angle="270"/>
<Axis angle="330"/>
<Axis angle="30"/>
<Axis angle="90"/>
<Axis angle="150"/>
</Axes>
</pre>

This defines 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.3.2:
<pre>
<Axes number="6" normalize="true">
<Axis x="-0.5" y="-0.866025404"/>
<Axis x="-0.5" y="0.866025404"/>
<Axis x="-1" y="0"/>
<Axis x="0.5" y="0.866025404"/>
<Axis x="0.5" y="-0.866025404"/>
<Axis x="1" y="0"/>
</Axes>
</pre>

or, in degrees:
<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 6.3.3:
<pre>
<Axes number="4" normalize="true">
<Axis x="1" y="0"/>
<Axis x="0" y="1"/>
<Axis x="-1" y="0"/>
<Axis x="0" y="-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 7.1:
<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.
<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 8.1:
<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.

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.

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.

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.

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.

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

This is not a hard rule of any sort. 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.

==== 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
x and y 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_beta3">

<World>

<Field>
<Axes number="4" normalize="false">
<Axis x="1" y="0"/>
<Axis x="-0.2" y="-1"/>
<Axis x="-1" y="0"/>
<Axis x="0.2" y="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_beta3">
<World>
<Field>


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

== TODO: ==

* how to submit resource
* Extension

Making Maps by Hand

2005-10-22T15:58:43Z

Philippeqc: Updated to version 0.2.8_beta3

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


<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 ==
Fill this part

== Resource ==
This section is under development!

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.

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. 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 '''TODO'''.

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.

== 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 following 2 paragraph are post map-0.2.8_beta3 and 0.2.8_beta3.

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 x="1" y="1"/>
<Axis x="1" y="-1"/>
<Axis x="-1" y="-1"/>
<Axis x="-1" y="1"/>
</Axes>
</pre>

The Axis element uses the following fields:
;x
: This is size of the displacement along the x's for this axis
;y
: 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 x and y 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 x="225" length="1.4142"/>
<Axis x="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 x and a y of 1. The real length of the described Axis is
<math>\sqrt{x^2+y^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 6.1.2 Axes of size 2
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="2"/>
<Axis x="2" y="0"/>
<Axis x="0" y="-2"/>
<Axis x="-2" y="0"/>
</Axes>
</pre>

Example 6.1.2 Axes of size 0.5
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="0.5"/>
<Axis x="0.5" y="0"/>
<Axis x="0" y="-0.5"/>
<Axis x="-0.5" y="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 6.2.1 Rectangle of equal travel time
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="10"/>
<Axis x="1" y="0"/>
<Axis x="0" y="-10"/>
<Axis x="-1" y="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 6.2.2 Rectangle of compressed travel time
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="20"/>
<Axis x="1" y="0"/>
<Axis x="0" y="-20"/>
<Axis x="-1" y="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 example 6.2.3 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.

Example 6.2.3
<pre>
<Axes number="4" normalize="false">
<Axis x="0.5" y="0"/>
<Axis x="0" y="-3"/>
<Axis x="-0.5" y="0"/>
<Axis x="0" y="3"/>
</Axes>
</pre>

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 6.2.4: Parallelogram arena
<pre>
<Axes number="4" normalize="false">
<Axis x="0" y="1"/>
<Axis x="1" y="0.5"/>
<Axis x="0" y="-1"/>
<Axis x="-1" y="-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.3.1:
<pre>
<Axes number="6" normalize="true">
<Axis x="-0.5" y="-0.866025404"/>
<Axis x="-1" y="0"/>
<Axis x="-0.5" y="0.866025404"/>
<Axis x="0.5" y="0.866025404"/>
<Axis x="1" y="0"/>
<Axis x="0.5" y="-0.866025404"/>
</Axes>
</pre>

Example 6.3.1, in degrees:
<pre>
<Axes number="6">
<Axis angle="210"/>
<Axis angle="270"/>
<Axis angle="330"/>
<Axis angle="30"/>
<Axis angle="90"/>
<Axis angle="150"/>
</Axes>
</pre>

This defines 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.3.2:
<pre>
<Axes number="6" normalize="true">
<Axis x="-0.5" y="-0.866025404"/>
<Axis x="-0.5" y="0.866025404"/>
<Axis x="-1" y="0"/>
<Axis x="0.5" y="0.866025404"/>
<Axis x="0.5" y="-0.866025404"/>
<Axis x="1" y="0"/>
</Axes>
</pre>

or, in degrees:
<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 6.3.3:
<pre>
<Axes number="4" normalize="true">
<Axis x="1" y="0"/>
<Axis x="0" y="1"/>
<Axis x="-1" y="0"/>
<Axis x="0" y="-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 7.1:
<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.
<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 8.1:
<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.

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.

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.

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.

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.

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

This is not a hard rule of any sort. 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.

==== 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
x and y 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_beta3">

<World>

<Field>
<Axes number="4" normalize="false">
<Axis x="1" y="0"/>
<Axis x="-0.2" y="-1"/>
<Axis x="-1" y="0"/>
<Axis x="0.2" y="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 version="0.2.8_beta3" name="HexaTRON" version="0.2" author="Luke-Jr" category="HexaTRON">

<Map version="0.2.8_beta3">
<World>
<Field>


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

== TODO: ==

* how to submit resource
* Extension