Cockpit Reference

This page describes all the cockpit-related features available in the 0.4-cockpit branch. It has not been merged into 0.4 yet. The current features are explained on the Cockpit Tutorial page.

The boilerplate
 <!DOCTYPE Resource SYSTEM "cockpit.dtd">   Widgets go here  

The attributes of the  tag form the path your cockpit will have to be placed at:

author/category/name-version.aacockpit.xml

If category is omitted or empty, the resource will be straight under the author directory. It can contain forward slashes, in which case the file will be several directories deep. See also Testing Resources.

A few rules and recommendations:
 * Don't use spaces/
 * Don't use dashes in the name.
 * Use numbers or dotted numbers for your version. For example, you could use,   or  . Make the version number increase as you publish updates and be consistent with the number of dots in it.
 * Be consistent with your author name.

Inside the  tag is where the widgets go. A widget is an element on the HUD. Do not change the version on that tag. It may be used to introduce backward-compatibility changes in the future.

Common Attributes
These attributes can be applied to any widget like such:

 

camera
Specifies which cameras, separated by spaces, the widget should be shown in. If omitted, it is shown on all cameras. If it starts with a circumflex accent, then the widget will be shown in all cameras except those specified. Here are the accepted camera names:

Position and Size
Cockpit widgets are positioned with up to 4 tags:
 * 1)   designates an anchor relative to the total output area. -1,-1 is the lower-left corner of the output, 1,1 is the higher-left corner.
 * 2)   positions the widget, relative to the anchor you defined. One unit in a direction is the same amount of pixels than one unit in any other direction.
 * 3)   gives the size of the widget. The units are also squares of pixels.
 * 4)   defines what point in the widget corresponds to the point that was positionned with the two first tags. If unspecified, it defaults to the center of the widget.

Anchor and Position
Not all players play Armagetron on the same kind of display. Some play it on a 4:3 resolution, while others use 16:9 or 16:10. Or they could be playing splitscreen, causing each player's cockpit to be 2:3 or 32:9. While those last two cases are a bit extreme, your cockpit has to be able to adapt to 4:3 or 16:9 without trouble. Armagetron used to have one coordinate system that went from -1 to 1 horizontally and from -1 to 0.5 vertically. It was tailored for 4:3 outputs so to adapt cockpits for 16:9 it would just squish the cockpit vertically to fit.

This is no longer the case. Usually cockpit widgets are put near corners or edges of the output area. To help you do that, the  tag lets you tell Armagetron just that. For instance:



Setting the anchor at -1,-1 tells Armagetron that you are about to put your widget near the bottom left-hand side of the output. If you put it at 1,1, then you'd be in the upper right-hand side. Here is the coordinate space used for the anchor tag, on 4:3 and 16:9 outputs, respectively:



It will always scale to have x=-1 at the left, x=1 at the right, y=-1 at the bottom and y=1 at the top of the output. If you do not set an anchor, compatibility mode will be implicitly triggered on the widget.

Once you have an anchor set, you can position your widget relative to it. The difference is that 's coordinate space always has a 1:1 ratio between width and height units.



0,0 is at the anchor you defined and the output is 2 units wide. Here, the blue elements symbolize the total output area and the anchor coordinates. The red elements show the coordinate space for the position. As you can see from the dashed square, it does not get resized vertically. If you were to write:

 

You would be telling Armagetron to position your widget close to the bottom left-hand corner, a fraction away from the edge of the output. It would be at an equal distance from the left and bottom edge of the screen, regardless of the output's aspect ratio.

Size and Align
The  and   tags have so far positioned a point on the screen.

an area of the screen to the point with its  and   attributes:



This will give the widget an area that is a quarter of the width of the screen and is 5:4 in aspect ratio. The coordinate space for the size is the same as for the  tag. The size is measured from edge to edge, with most widgets occupying exactly this space. Captions do not count towards it and can be on the outside of it.

is a convenience tag that lets you redefine how the widget aligns with its set position. It positions a point relative to the widget body, like  sets a point relative to the output area.

Adjusting position and size depending on aspect ratio
The  tag also accepts   and   attributes. When the widget is processed, its  and   are multiplied by a factor. This factor is determined by dividing the output height by its width, then clamping that value so that it is at least 's value and at most  's value. Those attributes both default to 1, so that no change is made by default.

For instance, a widget is positioned and sized like this:

   

If the output size is 1024x768(or any 4:3 aspect output), the factor is. This is over the  parameter, so it becomes. That factor then multiplies the  and   tags. The above code would be equivalent to, in this case:

 <Position x="0" y="0.07" /> <Align x="0" y="-1" /> <Size x="0.35" y="0.35" />

If the output size is 1280x800(or any 16:10 aspect output), the factor is. This is between the adjust parameters, so it is unchanged. It is then used to multiply the position and size:

<Anchor x="0" y="-1" /> <Position x="0" y="0.0625" /> <Align x="0" y="-1" /> <Size x="0.3125" y="0.3125" />

Compatibility mode
Compatibility mode is activated on a widget when it either:


 * has no  tag,
 * has an  tag with its   attribute set to.

When it is activated, the game will emulate the old coordinate system used for positioning widgets, and emulate quirks within the widgets themselves.

Old coordinate system
In the old coordinate system, 's coordinate system resizes to fit the output size so that   is at the bottom of the output,   is at the top of the output,   is at the left edge of the output, and   is at the right edge of the output. This coordinate system is shifted if using an  different than. operates on the same scale, but measures half the width and height of the object, as if from center to edge. 's  and   are ignored.

This is an illustration of the old coordinate system. Note that 0.5 on the y axis is always the top of the screen.



Label
The widget will always be aligned from the top left corner, the width will be halved and used to horizontally space cells, the height will be used as text size. Setting cell dimensions is unsupported and the table is locked in auto-sizing mode.

BarGauge
The gauge body will only occupy the top half of the allocated room, the other half being reserved for captions.

Camview
The widget will always be aligned from the bottom-left corner.