Difference between revisions of "Cockpit Tutorial"

From Armagetron
(→‎Map: widh and height don't need to be equeal anymore)
(→‎Label: Added information about tables)
Line 249: Line 249:
 
     </Label>
 
     </Label>
 
</pre>
 
</pre>
 +
 +
==== Tables ====
 +
 +
A table is much like a basic HTML table: It consists of rows, coulumns, and cells. Each cell can contain multiple <Text> or <GameData> nodes, they will just be concatenated. Here's an example of a table that shows the time, the framerate, and how long Armagetron Advanced is running:
 +
 +
<nowiki>      <Label camera="*" viewport="top">
 +
            <DataSet id="hours">
 +
                <AtomicData source="current_hours12h" minwidth="2" fill="0" />
 +
            </DataSet>
 +
            <DataSet id="minutes">
 +
                <AtomicData source="current_minutes" minwidth="2" fill="0" />
 +
            </DataSet>
 +
            <DataSet id="ampm">
 +
                <Conditional field="source" lvalue="current_hours" rvalue="12" operator="le">
 +
                    <IfTrue>
 +
                        <AtomicData source="AM" />
 +
                    </IfTrue>
 +
                    <IfFalse>
 +
                        <AtomicData source="PM" />
 +
                    </IfFalse>
 +
                </Conditional>
 +
            </DataSet>
 +
            <DataSet id="fps">
 +
                <AtomicData source="current_framerate" />
 +
            </DataSet>
 +
            <DataSet id="seconds">
 +
                <AtomicData source="time_since_start" />
 +
            </DataSet>
 +
            <Position x="0.4" y="0.45" />
 +
            <Size height="0.04" width="0.02" /> <!-- Size would be the font size in this case -->
 +
            <Caption location="top">
 +
                <Text value="Time/Fps/Timestamp" />
 +
            </Caption>
 +
            <Face>
 +
                <Table>
 +
                    <Row>
 +
                        <Cell><Text value="Time:" /></Cell>
 +
                        <Cell><GameData data="hours" /><Text value=":" /><GameData data="minutes" /><Text value=" " /><GameData data="ampm" /></Cell>
 +
                    </Row>
 +
                    <Row>
 +
                        <Cell><Text value="Framerate:" /></Cell>
 +
                        <Cell><GameData data="fps" /><Text value=" FPS" /></Cell>
 +
                    </Row>
 +
                    <Row>
 +
                        <Cell><Text value="Running for:" /></Cell>
 +
                        <Cell><GameData data="seconds" /><Text value=" Seconds" /></Cell>
 +
                    </Row>
 +
                </Table>
 +
            </Face>
 +
        </Label></nowiki>
  
 
=== Map ===
 
=== Map ===

Revision as of 08:52, 20 May 2006

This document describes canonically how to create a cockpit resource file. Hopefully it'll be easy to read, too.

'At this time, the material presented here is only partially implemented, if at all'

A Cockpit - The Concept

The cockpit is where you're sitting when you play the game. There is the concept of a virtual cockpit which is implemented in the internal camera view, but we'll ignore that, for the most part. Otherwise, the cockpit is where you're sitting and what you're using.

A cockpit resource file provides the layout of some of the visual items you see while you're playing. Traditionally, these were referred to as the HUD, and the HUD is still the main information that's carried in a cockpit file.

In the resource file, gauges and other things have been abstracted to a Widget. Each Widget is capable of displaying all of the information you're used to seeing, and is likely capable of displaying the same information in different formats...thanks to the cockpit resource file.

Overview of the Cockpit file

The cockpit file consists of two sections. Technically they're just one, but you don't really have to worry about that. The two sections are pretty simple. The first just hooks it into the resource system for the whole game, using tags and stuff you may already know from the map files. The second section contains all the beautful cockpit stuff.

In the Cockpit section you'll find a series of widget tags that contain data tags to hook the widget into some game data. There's a caption, some position and size parameters, and so forth. You can also specify background and foreground colors, with gradiants, and with graphics, to provide a really custom gauge. Additionally, widgets can be associated with a camera, or made for all cameras, with the option of excluding specific cameras, offering the possibility to give a completely custom view for each camera you use. All of this gets mixed together and rendered to screen as your cockpit.

A complete gauge, in concept, isn't necessary a single widget in the cockpit file. As an example, you might want to build a "Performance" gauge that includes ping, frames per second, cpu usage, overall system load, and bandwidth usage. That would require placing several widgets together, stacked on top of each other or on each other's sides, to build the conceptual Performance gauge you intend. Here, we'll use "gauge" to refer to a specific gauge and "widget" to refer to the larger conceptual gauge. Most widgets that you'll build will just be gauges, so it's not a big deal. (Note: At the time of writing, all of the data in the hypothetical Performance gauge isn't available to the cockpit, but the system is easily extensible and there's no reason to think it will never be available)

Within each gauge there are a series of tags that are used to define what it looks like, what data it uses, and so forth. The tags that are available vary from gauge to gauge, but the meaning of each tag never varies. Two gauges that are diametrically opposite to each other might interpret the tag differently, but it will still mean the same thing for both gauges. That's an important subtlety that you should keep in mind.

Construction of a Gauge

Each gauge is a layered affair. In technical terms, first the back of the gauge is painted. Then the middle is painted on top of the back, and finally the front is painted on top of the middle. This is intended to allow for complete configurability for each gauge. The middle layer is always the representation of the data, whatever it is. The back and front are equivalent in size and shape and are intended for window-dressing. By painting a texture with alpha-blended pixels it should be possible to reshape parts of the gauge and give it a unique appearance. Two gauges can be identical in all ways except which texture is used for the front and have very different appearances to the user.

Gauges that are text-driven are generally constructed on a table. While you don't have to use a table to build the gauge, the table allows you to organize it in rows and columns, which is the most useful way to organize data that you expect to read only in glances.

Each gauge has to specify which piece of data it displays, along with related pieces of data, and how to display them. This can vary dramatically! As an example, on the old HUD, in the rubber gauge, you saw a needle with some text to show the amount of rubber currently used. Then you had a minimum, which was 0, and a maximum, which varied from server to server. In the new rubber gauge you'll choose an appropriate widget and tell it where to get its minimum, its maximum, and its current data. Technically this is implemented with callbacks so that any data can be made available to be used by a gauge, even if it doesn't make sense to do so, and the callback name to use is what you'll give it in the cockpit file. If that doesn't make sense to you, don't worry about it. Just make sure to provide what's needed to show your gauge and be happy.

Every gauge supports an attribute called "camera". The camera attribute allows you to specify for which camera the gauge will appear. This in turn allows your cockpit to look/feel/be completely different depending on the user's camera. The primary purpose is to allow the internal camera to actually appear like you're inside the light cycle while providing minimal HUDs for the other cameras, and it's this purpose from which the name "cockpit" is derived. But you shouldn't let that block your creativity when you're creating your own nice cockpit. Note: This is not fully implemented yet

Finally all gauges support the viewport attribute. Possible values are "top" and "all", the latter being the default. "top" means that the widget will be rendered on top of the screen, "all" means it will be rendered for every player in multiplayer mode. Some data sources are only available in "all" mode, but you might not want a separate map for each player, so choose "top" then.

General Gauge Information

Every gauge supports an interpretation of some tags that are needed for every gauge. We'll discuss those here.

Data Source

The DataSet tag is a container that contains AtomicData tags. It defines all of the data that will be used to construct the gauge and may contain from 1 to 3 AtomicData tags within it. Here's an example:

   <DataSet>
       <AtomicData field="source" source="player_speed" />
       <AtomicData field="minimum" source="0" />
       <AtomicData field="maximum" source="max_speed" />
   </DataSet>

As you can see, each AtomicData tag contains two attributes, field and source. Field may be any of source, minimum, or maximum. Source determines where the data will be retrieved. If the contents of source match up with a known location of data, then that location will be called. If not, then the contents of source will be the data. This is easier to understand by just reading the snippet given, where "player_speed" will put the player's cycle's current speed in the field "source", but it will just put "0" in the field "minimum". This snippet is a speed gauge, and you can easily visualize a needle with 0 on the left, "max_speed" on the right, and the player's current speed marked by the needle itself as on the old HUD.

A DataSet can have an id associated with it that you can use to refer to it later for presentation. This is most important in a Label. Indeed, it's required in a Label but it doesn't really make sense in a NeedleGauge, does it?

Possible contents for data sources

Numbers
source="42", source="1.5"
Strings
source="Hello World!"
Configuration items
source="CYCLE_RUBBER"
Special Sources
player_rubber
The rubber that's used for the player currently being watched. Ranges from 0 to CYCLE_RUBBER.
current_ping
The ping time in milliseconds for the client.
player_speed
The speed of the cycle currently being watched.
max_speed
The theorethical maximum of the speed a cycle can reach according to the current settings.
player_brakes
The amount of brakes left. Ranges from 0 to 1.
enemies_alive
The number of enemies alive, from the view of the player the viewport belongs to.
friends_alive
The number of teammates alive, from the view of the player the viewport belongs to.
current_framerate
The current framerate in frames per second.
time_since_start
The time the game is running in seconds.
current_minutes
The time of the day in minutes.
current_hours
The time of the day in hours.
current_hours12h
The time of the day in hours (12- hour format).
current_seconds
The time of the day in seconds.
current_score
The score of the player the viewport belongs to.
top_score
The highest score.
fastest_speed
The speed of the fastest cycle.
fastest_name
The name of the player that's fastest right now.

Position and Size

Position and size are given by two tags, aptly "Position" and "Size". The point given by position represents the center of the gauge. Don't forget this! It's common for the position point of a widget to be the top left corner, but that is not the case. Here, it's the center of the gauge. An example says everything that needs to be said:

   <Position x="-0.165" y="-0.9" />
   <Size height="0.15" width="0.15" />

Positions and sizes are not in pixels, but in units of a special coordinate plane. The point at the bottom left is always (-1, -1) and the point at the bottom right is always (1, -1). So the x- coordinate always goes from -1 (left) to 1 (right).

The y- coordinate is chosen in a way so x and y have the same scale. (-1, 1) would refer to the point that is (width of your screen) up from the bottom edge. Of course, for most screens this means this point is off the screen.

This is an illustration of the coordinate system:

illustration of the coordinate system

Field Flags

Besides determining where the data should come from for a given field it is also necessary to tell the gauge whether or not to show that field. It's important to understand the distinction between using the data to draw the gauge and displaying the data on the gauge. The canonical example is the brake gauge displayed as a bar. In this example, minimum is always 0 and maximum is always 1, and current is always something in between. In order to compute the size of the gauge for the purpose of drawing the bar, you must have AtomicData for all three fields as discussed above. But you may not want to present that data. Maybe you just want to see the bar and nothing else. In that case, you need to deal with the field flags. How to actually use them is best seen in an example:

   <ShowCurrent value="true" />
   <ShowMaximum value="true" />
   <ShowMinimum value="true" />

Caption

Every gauge can have a caption. The caption need not be displayed. Again, an example says everything that needs to be said:

   <Caption location="bottom">
        <Text value="Speed" />
   </Caption>

Possible locations are top, bottom, and off. Location of "off" means the caption won't be displayed.

Layers

As previously discussed, each gauge is drawn with three layers. So far we've only talked about what is shown in the middle layer, the data layer. That is the gauge itself. In addition to the middle layer you have the background and foreground layers in which you can draw, and they are done with the aptly named Background and Foreground tags. You can put textures, solid colors, and gradients, or just leave the tag out completely if you don't need it. Here are some examples:

  • A solid foreground color, red, with no alpha transparency.
   <Foreground>
       <Solid>
           <Color r="1." g="0." b="0." alpha="1." />
       </Solid>
   </Foreground>
  • A lightly transparent 3-color gradient. The "at" parameter marks the borders between the colors and ranges from 0 to 1. The orientation determines how the gradient will be drawn.
   <Foreground>
       <Gradient orientation="horizontal">
           <Color r="0." g="1." b="1." alpha=".7" at="0" />
           <Color r="0." g="0." b="1." alpha=".7" at=".5" />
           <Color r="1." g="0." b="1." alpha=".7" at="0.8" />
       </Gradient>
   </Foreground>
There are three different types of gradients, indicated by the orientation attribute. Possible values are "horizontal" and "vertical" which will make horizontal or vertical gradients. A special value is "value" which will result in a solid area which changes color according to the value of the displayed data. The color with at="0" will be used at the minimum value and at="1" will be used at the maximum.

Available Gauges

Here are all of the available gauges, along with which tags are supported.

NeedleGauge

A needle gauge requires all three fields to exist in the DataSet tag. It supports all general tags. Here's an example speed gauge:

       <NeedleGauge camera="*">
           <DataSet>
               <AtomicData field="source" source="player_speed" />
               <AtomicData field="minimum" source="0" />
               <AtomicData field="maximum" source="max_speed" />
           </DataSet>
           <Position x="-0.165" y="-0.9" />
           <Size height="0.15" width="0.15" />
           <ShowCurrent value="true" />
           <ShowMaximum value="true" />
           <ShowMinimum value="true" />

<Text value="Speed" /> <Foreground> <Solid> <Color r="1." g="0." b="0." alpha="1." /> </Solid> </Foreground> </NeedleGauge>

BarGauge

A bar gauge requires all three fields to exist in the DataSet tag. It supports all general tags. Here's an example rubber gauge:

       <BarGauge camera="^in">
           <DataSet>
               <AtomicData field="source" source="player_rubber" />
               <AtomicData field="minimum" source="0" />
               <AtomicData field="maximum" source="cycle_rubber" />
           </DataSet>
           <Position x="-0.55" y="-0.9" />
           <Size height="0.05" width="0.15" />
           <ShowCurrent value="true" />
           <ShowMaximum value="true" />
           <ShowMinimum value="true" />

<Text value="Rubber" /> <Background> <Gradient orientation="value"> <Color r="0." g="1." b="0." alpha=".0" at="0." /> <Color r="0." g="1." b="0." alpha=".1" at=".3" /> <Color r="1." g="1." b="1." alpha=".2" at=".4" /> <Color r="1." g="1." b="1." alpha=".2" at="1." /> </Gradient> </Background> <Foreground> <Gradient orientation="value"> <Color r="0." g="1." b="0." alpha=".7" at="0." /> <Color r="0." g="1." b="0." alpha=".7" at=".3" /> <Color r="1." g="1." b="0." alpha=".7" at=".6" /> <Color r="1." g="0." b="0." alpha=".7" at=".8" /> <Color r="1." g="0." b="0." alpha=".7" at="1." /> </Gradient> </Foreground> </BarGauge>

Label

A label may have only one field in each DataSet tag and that field must be "source". It also requires each DataSet to have an id, which you will use to reference that data farther down. It supports any number of DataSets. In addition, you need a Face to describe how to build the Label. Here's an example for the enemies alive gauge:

    <Label camera="*">
        <DataSet id="enemies">
            <AtomicData field="source" source="enemies_alive" />
        </DataSet>
        <DataSet id="friends">
            <AtomicData field="source" source="friends_alive" />
        </DataSet>
        <Position x="0.06" y="-0.96" />
        <Size height="0.035" width="0.017" /> <!-- Size would be the font size in this case -->
        <Caption location="off">
            <Text value="Player Status" />
        </Caption>
        <Face>
            <Table>
                <Row>
                    <Cell><Text value="Enemies:" /></Cell>
                    <Cell><GameData data="enemies" /></Cell>
                    <Cell><Text value="Friends:" /></Cell>
                    <Cell><GameData data="friends" /></Cell>
                </Row>
            </Table>
        </Face>
    </Label>

Tables

A table is much like a basic HTML table: It consists of rows, coulumns, and cells. Each cell can contain multiple <Text> or <GameData> nodes, they will just be concatenated. Here's an example of a table that shows the time, the framerate, and how long Armagetron Advanced is running:

       <Label camera="*" viewport="top">
            <DataSet id="hours">
                <AtomicData source="current_hours12h" minwidth="2" fill="0" />
            </DataSet>
            <DataSet id="minutes">
                <AtomicData source="current_minutes" minwidth="2" fill="0" />
            </DataSet>
            <DataSet id="ampm">
                <Conditional field="source" lvalue="current_hours" rvalue="12" operator="le">
                    <IfTrue>
                        <AtomicData source="AM" />
                    </IfTrue>
                    <IfFalse>
                        <AtomicData source="PM" />
                    </IfFalse>
                </Conditional>
            </DataSet>
            <DataSet id="fps">
                <AtomicData source="current_framerate" />
            </DataSet>
            <DataSet id="seconds">
                <AtomicData source="time_since_start" />
            </DataSet>
            <Position x="0.4" y="0.45" />
            <Size height="0.04" width="0.02" /> <!-- Size would be the font size in this case -->
            <Caption location="top">
                <Text value="Time/Fps/Timestamp" />
            </Caption>
            <Face>
                <Table>
                    <Row>
                        <Cell><Text value="Time:" /></Cell>
                        <Cell><GameData data="hours" /><Text value=":" /><GameData data="minutes" /><Text value=" " /><GameData data="ampm" /></Cell>
                    </Row>
                    <Row>
                        <Cell><Text value="Framerate:" /></Cell>
                        <Cell><GameData data="fps" /><Text value=" FPS" /></Cell>
                    </Row>
                    <Row>
                        <Cell><Text value="Running for:" /></Cell>
                        <Cell><GameData data="seconds" /><Text value=" Seconds" /></Cell>
                    </Row>
                </Table>
            </Face>
        </Label>

Map

The Map is a very special gauge that displays a map of the arena. As a special gauge it has very special requirements. It supports Position, and Size, nothing else. Also, it will anchor its own aspect ratio, so it might not use the whole width or height you specified. The map will be as big as possible while keeping its aspect ratio and fitting in the width and height you specify.

Here's an example:

   <Map camera="*" viewport="top">
       <Position x="0.73" y="-0.72" />
           <Size height="0.25" width="0.25" />
   </Map>