Types

2.1   Null

Generally, anything not specified is assumed to be null (no value), but it can also be explicitly specified.

2.2   Boolean

Either true or false. Generally, if a boolean is not required, the assumed value is false.

2.3   Integer

A whole number, such as 0 or 42 or -9000.

2.4   Number

A number, optionally with a fractional component, such as 0.0 or 4.2 or -9000.

Usually, numbers in Antares have a resolution of (1/256). Fractional differences smaller than this may be ignored.

2.5   String

A piece of text. There are two ways to write a string: first, a short way, by putting the text in quotes "like this"; and second, by using > and | in an indented block:

> When using ">", blocks of text are wrapped together unless separated by
> two blank lines
>
> To add a single new line, use "|".
| This line isn’t wrapped with the previous one.

As of Antares 0.9.0, the game fonts are limited to MacRoman, so only the following characters should be used:

2.6   Array

A list of items. There are two ways to write an array: first, a short way, by putting the items in brackets ["like", "this"]; and second, by using * in an indented block:

* cardinal:  1
  ordinal:   "first"
* cardinal:  2
  ordinal:   "second"

2.7   Map

A sequence of keys and values. There are two ways to write a map: first, a short way, by putting the keys and values in braces {like: "this"}; and second, by using : in an indented block:

french:
  one:    "un"
  two:    "deux"
  three:  "trois"

Many Antares data types are maps, with their fields defined in a table like this:

For the above definition, this is one possible corresponding value:

name:  "Ambassador Thrntz"
at:    {x: 0, y: 0}
eats:
  leaves:  true

3.1   Duration

A string specifying a length of time. The four units of time in Antares are:

• hours (h)
• minutes (m), each ¹⁄₆₀ of an hour
• seconds (s), each ¹⁄₆₀ of a minute
• ticks (t), each ¹⁄₆₀ of a second

Most things in Antares run at a granularity of 3t or 0.05s, so differences shorter than that usually aren’t meaningful.

Fractional amounts of time are valid. 0.5m is the same as 30s, and 0.01h is the same as 36s. Antares can’t represent durations shorter than a tick, though, so 0.01s or 0.6t isn’t valid.

Combining multiple units is valid. 1m30s is the same as 1.5m.

The following are all valid durations:

* "0s"        # 0 seconds
* "1.5m"      # 1.5 minutes
* "1m30s"     # 1.5 minutes
* "1h2m3s4t"  # 1 hour + 2 minutes + 3 seconds + 4 ticks

3.2   Distance

A number indicating the distance between two points in space. When the game is zoomed to 1:1, distances correspond to pixels: a distance of 200 shows as a distance of 200 pixels.

3.3   Speed

A number indicating a change in distance over time, in units of px/t, or pixels-per-tick. When the game is zoomed to 1:1, an object moving at a speed of 5.0 px/t moves 5 pixels per tick, or 300 pixels per second.

3.4   Acceleration

A number indicating a change in speed over time, in units of px/t², or pixels-per-tick-squared. An object accelerating at 0.05 px/t² will increase its speed by 0.05 per tick, or 3.0 per second.

3.5   Angle

An integer in units of degrees, usually from 0 to 360. An angle of 0° means straight up or north. An angle of 90° means straight right or east.

3.6   Angular Speed

A number indicating a change in angle over time, in units of °/t, or degrees-per-tick. An object turning at 2.0°/t will change its direction by 2 degrees per tick, or 120 degrees per second, making a full rotation in 3 seconds.

3.7   Point

A map specifying a 2-dimensional location. Points have an x and a y component, both numbers (often distances or integers). The following are all valid points:

* {x: 0, y: 0}
* {x: 2.0, y: 0}
* {x: -1, y: -1.5}

Coordinates are mapped to quadrants as follows:

NW    N    NE
      ╷
   -x │ +x
   -y │ -y
W ────┼──── E
   -x │ +x
   +y │ +y
      ╵
SW    S    SE

3.8   Rect

A map specifying a 2-dimensional rectangle. Rects have left, top, right, and bottom components, all numbers (often distances or integers). In a non-empty rect, left < right and top < bottom. The following are all valid, non-empty rects:

* {left: 0, top: 0, right: 1, bottom: 1}
* {left: -100, top: -100, right: 100, bottom: 100}
* {left: 10.5, top: -3, right: 10.6, bottom: -2.5}

3.9   Range

A number, duration, or map specifying a range of values. If specified as a number or duration, then the range contains only that specific value. If specified as a map, then it is a half-open interval with a begin and end component, containing all values x such that begin ≤ x < end. The following are all valid ranges:

* 0
* {begin: "0s", end: "2.5m"}
* 5
* {begin: 5, end: 6}

If the range is integer-valued, then the last two ranges are equivalent, containing only 5 (and 5 is the preferred form). However, if they are number-valued, then {begin: 5, end: 6} also includes values like 5.5 and 5.923.

3.10   Counter

A map specifying one of a player’s three counters. Counters have two keys: player, the index of a player in the level, and which, the number of a counter, numbered from 0 to 2. The following are all valid counters:

* {player: 0, which: 0}  # First player’s first counter
* {player: 1, which: 2}  # Second player’s third counter
* {player: 2, which: 0}  # Third player’s first counter

In some cases, such as a score action, it may also be valid to omit player:

* {which: 0}  # The direct object’s owner’s first counter

3.11   Money

A number specifying an amount of cash. Players earn money from planets and stations that they own, and spend money to build ships. A player’s cash is shown on the right-hand side of the screen. Each of the 100 small green bars is worth ¤1, and each of the 7 large yellow bars is worth ¤100.

A player’s income is the sum of the earning of initials that they own, multiplied by their earning_power. A player earns their income every ten seconds of game time.

3.12   Hue

A string specifying a hue, such as “purple”. A hue may be combined with a shade (like “dark” or “very light”) to get a specific color (“dark purple” or “very light purple”). There are sixteen hues in Antares:

3.13   Color

A specific color. There are three ways to specify a color:

• As a string (black, white, or clear).
• As a map with r (red), g (green), and b (blue) components, plus optionally an a (alpha) component, all ranging from 0 to 255.
• As a map with a hue key and a shade ranging from 0 to 255.

The following are all valid colors:

* "white"
* {r: 255, g: 255, b: 255}  # same as "white"
* {gray: 255}               # same as "white"

* "clear"
* {r: 0, g: 0, b: 0, a: 0}  # same as "clear"

* {orange: 128}          # dark orange
* {r: 128, g: 64, b: 0}  # same dark orange

3.14   Tags

A map of booleans. This is used to mark different kinds of objects. An object has any tags mapped to true, and does not have any tags mapped to false or null. The following are all valid tag maps:

* {}
* {normal: true}
* {planet: true, cheese: true, edible: false}

Any string can be used, but these are the tags used in the factory scenario:

• asteroid: for regular asteroids (not the big green ones)
• boarder: for EVATs
• disabled: for CTF moors, after a jailbreak
• energizable: for anything an energy blob can provide energy to
• engineer: for engineering pods
• flak: for flak drones
• jumpgate: for the Jumpgate in Yo Ho Ho
• miner: for astrominers
• normal: for most objects
• normal-attacker: for most objects
• planet: for planets and moons
• prisoner: for Obiards in Shoplifter 1
• reactivator: for CTF moors, after a jailbreak
• rendezvous: for target locations, like shipyards or the UNS Ares
• rescue: for rescue ships in Shoplifter 1 and Shoplifter 2
• station: for space stations, like Bunker Stations and Outposts

3.15   Name

A string naming a resource (level, object, race, picture, sprite, sound, or music track). Names don’t include the top-level directory or extension, so if sfx/explosion/large is the name of an object, then Antares will look for an object at objects/sfx/explosion/large.pn. If it is the name of a sound, then Antares will look for a sound at pictures/sfx/explosion/large.aiff.

Antares first searches the current plugin for the named resource. If the plugin does not contain it, then it looks in the factory scenario.

3.16   Index

An integer naming a condition, initial, or player in the current level. The first entry is numbered 0, so if 3 is the index of an initial, then it refers to the fourth initial in the current level.

3.17   Object Reference

A map referencing an in-game object. It contains any one of the following fields:

The following are all valid object references:

* {initial: 0}   # The level’s first initial object
* {flagship: 1}  # The second player’s flagship
* {control: 0}   # The first player’s control object
* {target: 1}    # The second player’s target object

3.18   URL

A string containing a fully-specified URL. Generally, the URL scheme should be https (preferred) or http. URLs with other schemes may be ignored. The following are all valid URLs:

* "https://arescentral.org/antares/"
* "http://biggerplanet.com/ares"
* "mailto:antares-dev@arescentral.org"  # Probably ignored.