Difference between revisions of "Cockpit Reference"

From Armagetron
m (Added subsection skeleton for common attributes.)
(→‎Position and Size: Completed part of the Anchor/Position ref)
Line 41: Line 41:
  
 
===Position and Size===
 
===Position and Size===
 +
 +
Cockpit widgets are positioned with up to 4 tags:
 +
# <code><Anchor></code> 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.
 +
# <code><Position></code> 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.
 +
# <code><Align></code> defines what point in the widget is being positioned. If unspecified, it defaults to the center.
 +
# <code><Size></code> gives the size of the widget. The units are also squares of pixels.
 +
 +
====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 <code><Anchor></code> tag lets you tell Armagetron just that. For instance:
 +
 +
<Anchor x="-1" y="-1" />
 +
 +
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:
 +
 +
[[File:CockpitAnchor43.png|On a 4:3 output]] [[File:CockpitAnchor169.png|On a 16:9 output]]
 +
 +
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.
 +
 +
Once you have an anchor set, you can position your widget relative to it. The difference is that <code><Position></code> uses a different coordinate space. 0,0 is at the anchor you defined, the output is 2 units wide, and the units vertically are the same size as they are horizontally.
 +
 +
[[File:CockpitPosition.png|How Position's coordinate space works for the previous Anchor example.]]
  
 
===Background, Foreground and LineColor===
 
===Background, Foreground and LineColor===

Revision as of 01:00, 17 January 2013



Cockpit files can be used to customize the game's HUD in the current development builds and in the upcoming version 0.4.0.


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

<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE Resource SYSTEM "cockpit.dtd">

<Resource type="aacockpit" name="cockpit name" version="a version" author="your name" category="a category">
    <Cockpit version="0.0.1">
        Widgets go here
    </Cockpit>
</Resource>

The attributes of the <Resource> 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 1, 1.5 or 0.4.3. 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 <Cockpit> 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

camera

viewport

toggleSticky, toggleDefault

usetemplate

Common Tags

Position and Size

Cockpit widgets are positioned with up to 4 tags:

  1. <Anchor> 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. <Position> 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. <Align> defines what point in the widget is being positioned. If unspecified, it defaults to the center.
  4. <Size> gives the size of the widget. The units are also squares of pixels.

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 <Anchor> tag lets you tell Armagetron just that. For instance:

<Anchor x="-1" y="-1" />

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:

On a 4:3 output On a 16:9 output

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.

Once you have an anchor set, you can position your widget relative to it. The difference is that <Position> uses a different coordinate space. 0,0 is at the anchor you defined, the output is 2 units wide, and the units vertically are the same size as they are horizontally.

How Position's coordinate space works for the previous Anchor example.

Background, Foreground and LineColor

Caption

DataSet

Widgets

Rectangle

BarGauge and VerticalBarGauge

NeedleGauge

Label

Map

Camview

Related settings