A full reference guide to all the commands and tokens that the scripting language understands follows. In each section the list of commands comes first, followed by notes and extra information about those commands.
* * * * * * *
* * * * * * *
If two groups "collide", then they are normally allowed to freely move over each other - after all, space has a third dimension. However, if a group collides with the group it is moving towards, it will not attempt to sit right on top of it:
Furthermore, if a number of frigates and/or capital ships are all trying to move towards the same target, they will attempt not to overlap each other.
* * * * * * *
Small weapons are always dealt with automatically rather than via AI scripts. Exactly how varies depending on the group type:
Big weapons will only fire if ordered to by an AI script. Note that you don't need to check "nenemy inbigrange" or similar every single time you ever order a group to fire, as commands to fire at enemies out of range are always ignored in any case. However, you may sometimes wish to check the range nonetheless if you wish to take an entirely different course of action if a specified enemy is not within range.
* * * * * * *
* * * * * * *
| # | Comment - ignore whatever follows and continue to the next line. |
| if | Evaluate expression that follows, if true carry out following command or block of commands, otherwise skip the next command or block of commands. |
| else | Only evaluate next command or block of commands if the last "if" evaluated false |
| elif | Only evaluate next command or block of commands if the last "if" evaluated false and the following expression evaluates to true. |
| : | Used after a function label, e.g. "offensive:" |
| @ | Scripts can make function calls by using an "at" symbol in front of a function name e.g. "@offensive". |
| return | returns to the line after the last @ function call. If there are no more @s to go back to, the script will stop processing until the next frame. |
Nesting if/else/elif statements is allowed.
* * * * * * *
| our | The group running the script |
| aenemy | "Any enemy" |
| afriend | "Any friend" |
| nenemy | "Nearest enemy" |
| nfriend | "Nearest friend" |
| nedge | "Nearest world edge", checks the nearest edge of the world/battle arena. The only piece of information you can test about "nedge" is distance. |
| northedge, eastedge, southedge, westedge | Checks the relevant edge of the world/battle arena. The only piece of information you can test about edges is their distance. |
| $g1, $g2 ... $g9, $g0 | You can "save" a group (including world edges) and then later on refer to that saved group. See the section on variables for more information |
| $globalg1, $globalg2 ... $globalg9, $globalg0 | You can "save" a group and then later on refer to that saved group. See the section on variables for more information |
AI scripts can evaluate information about the group running the AI script itself, or about other groups, be they friend or enemy. Merely evaluating a group on its own in an "if" statement makes no sense (e.g. "if aenemy"), you must further qualify the information you are after about the specified group.
The "saved" group types can be used anywhere you would otherwise use a "nearest" group type.
Note that the implementation of world edges as interchangeable with other group types is not yet complete, and so though you can save world edges in group variables and test their distance in if statements, you cannot currently specify a world edge that has to meet certain criteria. For instance, $g1 = nedge distance > 500 does not currently work, $g1 will simply be set to the nearest world edge.
* * * * * * *
| number | Number of units in group |
| health | The current total value of armour and shields for all units in group |
| shield | The current total value of shields only for all units in group |
| armour | The current total value of armour only for all units in group |
| maxhealth | The total health that the group started the battle with |
| maxshield | The total shield that the group started the battle with |
| maxarmour | The total armour that the group started the battle with |
| unitmaxshield | The shield that each unit in the group started the battle with |
| unitmaxarmour | The armour that each unit in the group started the battle with |
| speed | Maximum speed of group in pixels per frame. |
| distance | Distance from centre of that group to centre of group running script in pixels. In this game the area visible on the screen at any one time is 1024 by 768 pixels. |
| left | The number of units in the group remaining (i.e. that have yet to be destroyed). |
| misstarget | The number of missiles currently flying through space towards the group. |
| torptarget | The number of torpedos currently flying through space towards the group. |
| smallrange | The maximum range of the group's weapons classified as "small". |
| smallpower | The power of a single shot from the group with their weapon classified as "small". |
| bigrange | The maximum range of the group's weapons classified as "big". |
| bigpower | The power of a single shot from the group with their weapon classified as "big". |
| bigtype | The type of big weapon that the group possesses. This can be one of "none", "laser", "missile" or "torpedo". An example of useage: "fire nenemy bigtype == torpedo". |
| bigammo | The total amount of ammo the units in the group have left for their weapon classed as "big". If infinite, then this number is given as 100. |
| type | The type of group. This can be either "capitalship", "frigate" or "smallship". An example of useage: "fire nenemy type == capitalship". |
There are also some group information types that are special in that they don't give values that you can then compare to other values using "==", "<", etc. Instead, they are simply true or false - you don't write "if aenemy insmallrange == 1", but must instead simply write "if anenemy insmallrange":
| insmallrange | Checks whether the specified group is within small weapons range of the group running the script. Shorthand for "if groupx distance <= our smallrange". |
| inbigrange | Checks whether the specified group is within big weapons range of the group running the script. Shorthand for "if groupx distance <= our bigrange". |
| ourinsmallrange | Checks whether the group running the script is within small weapons range of the specified group. Shorthand for "if groupx distance <= groupx smallrange". |
| ourinbigrange | Checks whether the group running the script is within big weapons range of the specified group. Shorthand for "if groupx distance <= groupx bigrange". |
* * * * * * *
| numenemy | "Number of enemies" |
| numfriend | "Number of friends" |
As well as testing whether any group of a given type or the nearest group of a given type meet certain criteria, you can also count the number of groups of a given type that meet certain critera with "numenemy" and "numfriend". Currently you cannot use numx commands in if statements, you must instead first assign them to a variable. For instance, you could write:
main:
$1 = numfriend distance < 500
if $1 < 5
#there aren't many friends nearby
return
* * * * * * *
It is possible to to use if statements to check whether two groups (i.e. saved groups) refer to the same actual group. For instance, to find whether your first saved group is the same group as your second save group, you can write "if $g1 == $g2". You cannot combine stat specifiers with this sort of check, so for instance "if $g1 == nfriend health > 300" will not work.
* * * * * * *
| == | Evaluates whether a piece of information is equal to a value. Note TWO equals signs with no space in-between, a single equals sign means "set variable to following new value". |
| != | Evaluates whether a piece of information is NOT equal to a value. |
| > | Evaluates whether the information on the left hand side is greater than the value on the right hand side. |
| < | Evaluates whether the information on the left hand side is less than the value on the right hand side. |
| >= | Greater than or equal to. |
| <= | Less than or equal to. |
| !... | if an if/elif test begins with a "!" then rather than testing whether the following statement is true, it will instead test if the following statement is false. For instance, "if ! aenemy health > 500". |
| && | And - cannot be used in move/fire/patrol context |
| || | Or - cannot be used in move/fire/patrol context |
It is important to note that the meaning of logical operators varies greatly depending on their context
It is not currently possible to use brackets - i.e. ( and ) - to specify the order in which logical operations are carried out.
* * * * * * *
| + | Add |
| - | Subtract |
| * | Multiply |
| / | Divide |
| % | Modulo ("what is the remainder when I divide?") |
Arithmetic operations do not yet support the use of brackets, and furthermore there is no guarantee as to the order the operations will be carried out - so for instance 20 / 2 / 2 does not result in 5 as you might expect, because it is worked out as 20 / (2 / 2) and therefore the result is 20. You can use the script-set variables to carry out sums in stages if you really need to, but hopefully you won't need to carry out complicated sums.
* * * * * * *
There are two distinct types: the first sort holds numbers, whilst the second sort "saves" a group that you can then refer to again later on. They cannot be intermixed, and are used in different sorts of places.
| $1, $2 ... $9, $0 | As well as being compared to other variables in "if" statements like normal object information, these 10 variables can be changed by the script.
They are stored on a per-group, not per script basis. If more than one group uses the same script then they will each have their own separate variables, so if the script sets the variables for one unit using the script, the other group's variables will remain unchanged. There are only ten script-controlled variables per group, and their names cannot be changed. |
| $global1, $global2 ... $global9, $global0 | As above, script controlled variables. These 10 however are stored for your entire side, so if one group or script changes them they will be changed for every single group and script in your fleet. |
| $g1, $g2 ... $g9, $g0 | Whilst normal variables are used for saving numbers, these are used for saving a particular group (this includes world edges). They are stored on a per-group, not per script basis. Attempting to save a group which doesn't exist - e.g. "$g1 = nenemy size > 5000" - will result in the variable remaining unchanged. |
| $globalg1, $globalg2 ... $globalg9, $globalg0 | As above, except stored for your entire side. |
| = | Assign the value of a piece of information to a player-controlled variable, e.g: "$1 = nenemy size", or with a group save variable "$g1 = nenemy health > 50" |
| ++ | Add one to the value of a variable, e.g: "$1++". Note that "++$1" will not work, and also that you cannot combine ++ with other arithmetic. |
| -- | Subtract one from the value of a variable, e.g: "$1--" Note that "--$1" will not work, and also that you cannot combine -- with other arithmetic. |
Normal variables can store only positive integer numbers, which can be no larger than 99999. Don't try and put words or sentences or symbols or decimal points in them, all you can assign to them is specified piece of (nearest type) group information or a normal, non decimal number like 56, 293 or 0.
Meanwhile, saved group variables can store only a specified nearest group (including world edges) or another saved group variable - don't try to put numbers in them.
If you save a group which then died, moving towards or firing at that saved group will result in your group moving towards or firing at its last known position.
Normal variables are all set to 0 at the beginning of a battle.
"Saved" group variables can be set when you select your fleet, see the fleet selection documentation for details.
* * * * * * *
| random | A random number between 1 and 100. |
| $timer1, $timer2 ... $timer9, $timer0 | Each timer returns the number of frames that have passed since it was last reset with "starttimer". Stored on a per-group basis. |
| starttimer x | Starts timer number x, e.g. "starttimer 3". |
* * * * * * *
| move | Moves the group towards a target. |
| moveaway | Moves the group directly away from a target. |
| patrol | Orders the group to move towards another group. When your group gets within a specified range, it will start circling the target group. |
| fire | Orders the group to fire on another group. |
move and moveaway commands need one option specified (where to). "fire" commands have no options at all specified for small ships - a small ship group's fire target is always the same as their movement target. Frigate groups need a single option specified for fire commands (who to fire at). "patrol" commands need two options specified (the distance at which to move around the target group, and a target group).
If a group is issued multiple move, moveaway or patrol commands, then only the most recent movement-related command will have any effect.
* * * * * * *
| n[friend|enemy|edge] with optional specifiers, or a saved group variable | a group or world edge movement target |
| n, ne, e, se, s, sw, w, nw | Each specifier represents one of 8 compass points (yes I know compass directions don't really exist in space) and the group will move in that direction. Remember, capital letters are not allowed in AI scripts. |
"move" and "moveaway" group targets can be simply the nearest group on a certain side (e.g. "move nenemy"), or they can include additional specifiers seperated with a space. For example "move nenemy health < 200 firepower > 120". Moving towards an "any" type group is not possible.
* * * * * * *
| Anything that evaluates to a number - an integer, a script variable, a specified piece of information about a nearest type group, etc. |
The distance at which you desire to patrol the target group. |
Groups ordered to patrol another group will move towards the target group until their distance is equal to the distance specified. At this point they will begin circling the target group. If the target group moves away then the patrolling group will follow. If the target group gets closer to the patrolling group then the patrolling group will move away from the target until the specified distance is regained.
If a group patrolling round another group hits the edge of the world, it will start going back round its patrol target in the opposite direction.
The target can be an enemy group if you wish, though it usually makes more sense to use "move" rather than "patrol" to manage movement in relation to an enemy group as it gives you greater control.
Note that a patrolling group will not do anything special if it comes across an enemy group - if you wish a patrolling group to take some sort of action when it finds an enemy, you will have to script that action yourself.
* * * * * * *
| n[friend|enemy] with optional specifiers, or a saved group variable | the patrol target |
"patrol" group targets can be simply the nearest group on a certain side (e.g. "patrol 100 nenemy"), or they can include additional specifiers seperated with a space. For example "patrol 100 nenemy health < 200 firepower > 120". Patrolling around an "any" type group or around a compass direction is not possible.
* * * * * * *
| Small ship groups do not take options for fire commands. Frigates take n[friend|enemy|edge] with optional specifiers or a saved group variable. | Small ship groups always fire at their current movement target. Frigates must specify who they wish to fire at. |
For frigates, "fire" group targets can be simply the nearest group on a certain side (e.g. "fire nenemy"), or they can include additional specifiers seperated with a space. For example "fire nenemy health < 200 firepower > 120". Firing at an "any" type group is not possible.
Note you don't have to specify what sort of weapon you wish to fire: units can have only ever have one "big" weapon, whilst any "small" weapons they have are automatically dealt with by the game. Exactly how the firing of small and big weapons works depends on the weapon type, see the fleet selection documentation for details.
Note that there is nothing to stop you ordering groups to fire at groups that are out of range of your group. Groups that don't have the capability to follow the orders of an AI script will simply ignore the command.