Mission Scripting Tutorial

Introduction

The Artemis mission script system is designed to be easy for anyone to use, even if they do not have knowledge of programming. As such, it is very limited in scope, and somewhat resembles Web scripting languages like JavaScript and PHP. In its native form, it is written as a markup language; to be precise, it is written in XML. The XML content is read into Artemis by a parser, and the defined commands are processed during the normal game cycle.

As an example, let us start with a simple mission script, showing the structure of the XML file, the XML tags and declarations, and the Artemis scripting commands that are defined by them:

<!-- mission_data is the big wrapper for all the parts of a mission -->

<mission_data version="2.4.0">

     <!-- all the things that exist at the start of the mission -->

     <start>

          <create type="player" x="50000" y="0" z="50000" name="Artemis"/>

          <create type="station" raceKeys="friendly" hullKeys="Deep Space base" x="25000" y="0" z="50000" name="World"/>

          <big_message title="HELLO WORLD!" subtitle1="an example mission script"/>

          <set_timer name="enemy_timer" seconds="20"/>

     </start>

     <!-- add enemy to attack World when the timer expires -->

     <event>

          <if_timer_finished name="enemy_timer"/>

          <if_variable name="attack1" comparator="!=" value="1"/>

          <set_variable name="attack1" value="1"/>

          <create type="enemy" raceKeys="Skaraan enemy" hullKeys="small" x="25000" y="0" z="25000" name="Hello" fleetnumber="1"/>
          <incoming_comms_text from="Hello">

               Hello, foolish Terrans!

          </incoming_comms_text>

     </event>

     <!-- end game when you destroy the enemy -->

     <event>

          <if_variable name="attack1" comparator="=" value="1"/>

          <if_fleet_count fleetnumber="1" comparator="<=" value="0"/>

          <end_mission/>

     </event>

</mission_data>

You may precede all of the above with an XML declaration, such as <?xml version="version="2.4.0" encoding="UTF-8"?>, Artemis will ignore it. As with all XML files, comments are delimited by the <!-- and --> tags; nothing inside those tags will be executed. The mission script then consists of a single large block, delimited by the <mission_data> and </mission_data> tags. The mission_data tag must come before any start or event blocks, and the file should end with /mission_data. The version attribute attached to the mission_data tag is ignored by the parser, but should be set to the version of Artemis that the script is written for.

Inside the Mission Data Block are the Start and Event blocks. Each defines one event, which the Artemis parser will process in order. The start block will be executed only once, when Artemis begins running, and should create all objects and initialize all variables that will be used by the script throughout the game. All following event blocks will be executed with each cycle of the Artemis game. At least once every second, Artemis will update all of its internal data and move the ships and other objects that make up the game, and then it will execute the entire script again, excluding the Start Block.

The following image is from the Artemis Mission Scripting Quick Start Guide by T.L. Ford, and captures the execution cycle. Credit for this image goes to T.L. Ford for putting that Quick Start Guide together. Even though it was originally written for Artemis 1.7, it still applies today:

In the example above, the start block creates two objects, using the <create> command. It first creates the player ship, the Artemis, and then creates a base station, which it names "World". The base is created at the same vertical location as the player ship (which begins in the middle of the sector) but to the left of it. It then displays a message on the Mainscreen, with the <big_message> command. Finally, it sets a timer to 20 seconds.

The next two event blocks create an enemy Skaraan, named "Hello", and end the mission when it is destroyed, respectively. The first event block also sends a message to the Comms console, warning the crew that the Skaraan is attacking. These three blocks are all that is needed to play a simple mission, although a normal mission would have a lot more enemy ships and possibly various objectives that the players will have to achieve before the game can continue. For instance, the players could be told to dock with another base station and pick up supplies to be delivered to the "World" station. When they docked with that station, a fleet of Kraliens and Skaraans could spawn, which the Artemis would have to fight through in order to make the delivery.

Event blocks are usually just called "events". As mentioned before, event blocks will be executed every cycle, looping endlessly until the game ends. Therefore, we need to set some condition that will determine whether the event block executes. Every event block should start with one or more "Conditions", which are commands that start with the "if_" prefix. Like the "if" commands in a scripting language like JavaScript, they allow the script to make decisions, and react to the players' actions. Each block of conditions are then followed by one or more "Actions", which are commands that do not start with "if_".

Multiple conditions are evaluated as if they connected by an "and" comparison. That is, the actions are only executed if ALL of the conditions are true. If any condition is false, the parser goes on to the next event. See the example to the left.

Note that the start block does not need conditions because it will only be executed once. It should only have actions. There should also not be any conditions after an action. While this is theoretically possible, putting a condition after an action can crash the game. If the condition turns out to be false, the game locks up. This might be corrected in the future, but for now it is best to avoid putting conditions after actions. A technique will be described later in this tutorial to process "or" or "if/then/else" conditions, but this will take more than one event.

Turning back to our example script, if it were not for the conditions, those two event blocks would loop infinitely. We need some way to ensure an event block is executed only once. Thus, our script uses a variable, "attack1", to control the execution of the events. If the variable "attack1" is not set to the value 1, the first block executes, setting the variable to 1. That means that block will be executed once and only once. The next block executes if "attack1" is set to the value 1. In that case, it checks if the enemy fleet (which has only one ship in it, the Skaraan) has been destroyed, and ends the game if it has.

The important point to remember here is that unlike a standard program or script, which is usually sequential and has to use complex concepts like event handling to respond to inputs, the Artemis mission script system is literally a set of event handlers, each of which are checked in every single cycle. Looping constructs are not needed in Artemis scripts, as looping is built into the system, and in fact it can be difficult to stop your code from looping. Maybe of the techniques described below are intended to handle looping, and ensure that each event is executed only when it is needed.

Scripting Syntax

As the example above demonstrates, the XML syntax of the Artemis mission script system can make it difficult to understand and read. The Artemis Mission Editor, a standalone program developed by players of Artemis, greatly simplifies the syntax of the system and breaks it down into event objects, using a graphical interface. For instance, the example above might look like the following in the Artemis Mission Editor (removing all graphics, and showing all events "expanded" instead of just one to a panel):

Start 

     Actions

          Create player at point (50000, 0, 50000) bearing <> degrees with name "Artemis" and race/hull keys <> <>

          Create station at point (25000, 0, 50000) bearing <> degrees with name "World" and race/hull keys "friendly" "Deep Space Base"

          Show big message on main screen with the title: "HELLO, WORLD!" and subtitles: "an example mission script"

          Set timer "enemy_timer" to 20 second(s)

Event 01

     Conditions

          Timer "enemy_timer" is finished

          Variable "attack1" != 1

     Actions

          Set variable "attack1" to 1

          Create enemy at point (25000, 0, 25000) bearing <> degrees with name "Hello" and race/hull keys "Skaraan enemy" "small"

          Show incoming Comms message from "Hello" with text "Hello, foolish Terrans!" 

Event 02

     Conditions

          Variable "attack1" = 1

          Fleet count of the fleet with number 1 <= 0

     Actions

          End mission

While this syntax is extremely readable, particularly for non-programmers, it does not resemble the original XML syntax closely enough, and also does not use the same commands. (For instance, "if_variable" is "Variable x=y".) So for the remainder of this guide, the following hybrid syntax will be used. This syntax will use the XML commands, removing the brackets and simplifying the attributes somewhat, eliminating the attribute name if it is "name" or "type". Events will be separated by a start or event tag, similar to the Artemis Mission Editor format above, but without a marker to separate conditions and actions. For example:

start

     create player "Artemis" point=(50000, 0, 50000) 

     create station "World" point=(25000, 0, 50000) raceKey="friendly" hullKey="Deep Space Base"

     big_message "HELLO WORLD!" subtitle1="an example mission script"

     set_timer enemy_timer seconds=20

event

     if_timer_finished enemy_timer

     if_variable attack1 != 1

     set_variable attack1 to 1

     create enemy "Hello" raceKeys="Skaraan enemy" hullKeys="small" point=(25000, 0, 25000) fleetnumber=1

     incoming_comms_text "Hello, foolish Terrans!" from="Hello"

event

     if_variable attack1 = 1

     if_fleet_count fleetnumber=1 <= 0

     end_mission

Note that from time to time you may encounter a mission that has attributes with names like "name_arme", "folder_arme" or id_arme". These attributes are not part of the Artemis mission script system; they are part of the Artemis Mission Editor. The Editor adds these tags to the XML script to keep track of things like event names, and folders and subfolders, which the Artemis script system does not do. It is interesting that the Artemis script system is so robust that these extra XML tags and attributes can be added to the file, and Artemis will ignore them. You could actually use a similar technique to save comments in a file, or even make it possible to parse your script with another application.

Variables

Next to commands, which are needed to interact with the Artemis game and change its behavior, the most important feature of the Artemis mission script system is the use of variables. Variables are values that are used by the script to store temporary values. They are not associated with objects in the game, like properties are; they are added to the game's processing by the script. This is what allows you to add new functionality to Artemis, emulating something like Tractor Beams or Jump Gates, which are not included as part of Artemis at this time.

Variables are created with the command <set_variable> and tested as part of a condition with <if_variable>. Like game objects, all variables must have a name, which identifies them. All variables must have a numeric value; they cannot be set to the value of a text string. Variables may be set to either a positive or a negative value. As of Artemis 2.6, variables default to a floating point value. (Prior to 2.6, If a variable was set to a constant that was not an integer, the fractional part would be truncated)

set_variable name="enemies" value="20"          (sets enemies to the value 20.0)

     set_variable name="distance" value="-1000"      (sets distance to the value -1000.0)

     set_variable name="pi" value="3.1416"           (sets pi to the value 3.1416)

To set a variable to an integer value, the variable must be declared with the attribute "integer" which takes the values "yes" or "no". You do not need to specify the "no" value for float variables, as that is the default. Integer values can be very important to a script, as it is easier to test equality for an integer value. All "state variables" and "counters" (described below) used by your script should be integer variables.

     set_variable name="count" value="10" integer="yes"         (sets count to the value 10)

If a variable is declared as a float (because the integer="yes" attribute is not present) and later is set again with the attribute integer="yes" defined, it will not be converted into an integer. Obviously, this will result in unexpected side effects. For this reason, it is important to declare all integer variables in your start block, and give them an initial value. Since it can be difficult to predict which commands will be executed first in the event blocks of a script, this will prevent your integer variables from accidentally being initialized as floats. Once a variable has been initialized as an integer, the set_variable command can be called on it again, and the integer="yes" attribute will not need to be specified.

Random numbers can also be generated and stored in a variable. Note that the random integer function cannot generate more than 32768 values. In other words, randomIntHigh cannot be more than randomIntLow+32768. If it is, the random integer will cap at randomIntLow+32768. The random float function, while it can generate any number, will only generate up to randomFloatHigh-1 if stored in an integer variable. Generating a number between 0 and 1, for instance, will only generate 0. That's because the chance of generating exactly 1 is infinitesimal, or even impossible. (It is not known if the random float function is an "open interval" or a "closed interval") 

set_variable name="rand1" randomIntLow="0" randomIntHigh="10" integer="yes"           (rand1 will be 0-10)

set_variable name="rand2" randomFloatLow="0" randomFloatHigh="3"                      (rand2 will be 0.00-2.99)

     set_variable name="rand3" randomFloatLow="0" randomFloatHigh="3" integer="yes"        (rand2 will be 0-2)

     set_variable name="randx" randomIntLow="25000" randomIntHigh="100000"                 (randx will be 25000.0-57768.0)

In general, the random int function should be used for ranges less than 30000, while random float should be used for extremely small ranges (stored as a float) or ranges greater than 30000. If you wanted to generate a random coordinate, for instance, it would be best to use random float, since the dimensions of a sector, 100000 by 100000, are greater than 32768. However, if you were generating coordinates in a small portion of a sector, such as around a base, you could use random int. You could also use expression evaluation to generate a coordinate and multiply it by 2. See below.

As noted above, variables are also extremely valuable in controlling the execution of event blocks. Variables like "attack1" in the example above, which is used to cause an event block to execute, are called "state variables". (They are also sometimes called "flags", especially if they have only two states, "on" and "off") State variables are used to control the flow of the story in a mission.  They determine when things are supposed to happen, and are helpful in keeping track of what objectives have been achieved.

Pressing F7 on the Artemis server will cause a window to open on the Mainscreen, showing a "debug mode" that is useful for debugging scripts. The first press of F7 will show which line of the script the game last executed, which can be helpful if the script seems to have locked up. The second press of F7 will display all defined timers and can be similarly used to determine if the script's timers are working properly.

The third press of F7 will show all variables the script has defined, which is even more useful. The value of the various variables used by the script can be monitored in this way to ensure the script is running correctly, or find out what is going wrong. The script author may wish to define certain variables to help report the state of the script, although the state variables will provide a lot of this information by default.

Continuing to press F7 will display all client keypresses detected by the script, a display of the Brain Stack for the currently selected ship on Science, and (in Artemis 2.4) a display of the Brain Stack of the selected monster. These features will be described in other parts of this tutorial.

Expression Evaluation 

Expression evaluation is a built in function attached to any value or property that has a numeric value. Put simply, anywhere you can type in a number, you can also type in a math expression such as (5 * 2 / 6.554). Expressions can include variable names, so it is possible to assign a value to one variable based on the value of another:

set_variable height randomIntLow=0 randomIntHigh=1000 integer="yes"

set_variable coordy to (height - 500)

set_object_property "World" property="positionY" to coordy

The specified code will generate an integer between 0 and 1000, subtract 500 from it to give a value between -500 and 500, and set the Y position of the station "World" to that height. All object properties (described below) are floating point values, so coordy will cover the value to a float before storing it in the object. As will be noted below, X and Z are the coordinates of the station, and Y is its height above the coordinate plane. (Or below, for negative values)

     set_variable floatvalue to 10.75                              (floatvalue will be set to 10.75)

     set_variable intvalue to (floatvalue + 10.75) integer="yes"   (intvalue will be 21, not 21.5)

     set_variable multvalue to (floatvalue / 2.5)                  (multvalue will be 4.3) 

Expression evaluation can use any of the operators "+", "-", "*" and "/". It can also use the precedence operators "( )" to determine the order of operations. No other operator characters are defined. While it is legal to have variable names that consist of only numbers and no letters, it is best to make sure all your variables start with a letter. For example, if you create a variable "123", and then evaluate the expression "123+2", the value of that expression is whatever is stored in "123" plus 2, not 125. This can cause unnecessary confusion.

Variables cannot hold text values.  For example, the following code would not work:

set_variable name="mytext" value="HELLO, WORLD!"           (will not work!)

Properties that accept text values do not allow arbitrary expression evaluation, but variable formatting is supported starting in Artemis 2.5.102. For example, the following code will display "Version 1.0" at the top of the Mainscreen:

set_variable name="myversion" value="1.0" 
big_message title="Version |myversion|" subtitle1="by me"

Naturally, you cannot set an object name to a variable, either. Random object names can only be generated by leaving the name attribute blank.

Object properties take floating point values instead of integer values. Some of these properties usually take a value between 0.0 and 1.0, meaning they cannot be stored in an integer variable. Although this is no longer a problem with the introduction of float variables in 2.6, some people may still wish to use "percentages" or other integer values to represent object properies from 0.0 to 1.0. To use variables with properties like this, it is necessary to use expression evaluation:

     set_variable beamdam randomIntLow="0" randomIntHigh="100" integer="yes"

     set_player_grid_damage value="(beamdam/100)" player_slot=0 systemType="systemBeam" countFrom="front" index="0" 

Since "beamdam" is an percentage, represented as an integer from 0 to 100, expression evaluation is used to turn it into a randomly generated percentage, and apply it to the ship's damage grid.

Note that expression evaluation is the only way to add to or subtract from a variable. There is no equivalent to the addto_object_property command, and expression evaluation is far more powerful, as it allows multiplication and division as well.

Game Objects and Properties

While variables allow a script to retain values and set conditions to control when an event executes, obviously a script must also interact with the Artemis game. The Artemis mission script system does this through "objects", which represent things like enemy ships, base stations, asteroids and minefields, and even the Artemis player ship itself. The following is a listing of the different types of objects:

Unnamed Objects

Nebulas

Asteroids

Mines

Drones

Named Objects

Stations

Shielded Ships

Player

Enemy

Neutral

Anomalies

Black Holes

Monsters

Generic Meshes

"Generic Mesh" is a special object available only in scripted missions. It is typically used to create a planet, a wrecked ship, a mysterious phenomenon, or some other feature that the players will not interact with, but which provides "atmosphere" for the mission. The generic mesh is the only way to add objects to the game that do not exist in the vesselData file or are hardcoded into the game. In that respect, the generic mesh is an extremely powerful feature, but it also comes with several important limitations. The use of the generic mesh will be covered elsewhere in this tutorial.

All named objects in the game have "properties" associated with them, which define that object's current state. For instance, properties can be used to access how much energy the player ship has left, and increase or decrease that energy. The properties associated with each type of named object will be covered in another part of the tutorial. Each named object will have at least one property, "name", that records that object's name. If a name is not specified, the game will usually assign a random name, of the form "X32". Unfortunately, a random name is not very useful in a script, because it is not known to the script author, and thus can't be used to retrieve the object.

Most properties have a positive integer value between 0 and some number, which is stored as a float. Some properties, like the Y coordinate, may take a negative value. A few properties will take a floating point value between 0.0 and 1.0. For the most part, any fractional value assigned to a property will be ignored or will be so small as to make no difference. (Such as in a coordinate)

Properties can be set with the command set_object_property, which allows a property to be set to a constant, a variable, or an Expression Evalutation. (See above) As of Artemis 2.7.5, there is a command get_object_property which can load a property into a float variable. This greatly increases the number of things a script can do, and eliminates the need to track properties with if_object_property, which was possible, but extremely tedious and complicated.

Note that Whales are sometimes considered unnamed objects and sometimes considered named objects. This is because they used to be a unique object and not monsters.

Player Ships and Starting a Scripted Game

Obviously, the most important game object in Artemis is the player ship. The player ship must be created before a scripted game can start. Prior to Artemis 2.3, the player ship had to be given a name, although that name could be overridden by the Helm console. The player ship was also created with Warp drive by default, preventing Jump drive from being used in scripted missions. The players of Artemis came up with a workaround, but it required that no player ship be created, and the server had to be started first, and all consoles would join and click "Ready To Play" while the server was running. This would cause the player ship to be created, in much the same way as a second or third player ship would be created, and it could have its own name and selection of Warp or Jump drive. This workaround was used in several mission scripts, including the TSN Sandbox and the sandbox used by the USN.

With Artemis 2.4, this workaround is no longer necessary. The player ship can be specified in the start block, or in any other event block that is called only once, with the following command. The important part of the command is the "player_slot" property, which is a new property unique to player ships:

create player point=(50000, 0, 50000) player_slot=0

In the example we began with, the player ship was assigned the name "Artemis", but this command is a much better alternative, as it does not assign a name. The name chosen by the Helm console for that ship will be used. Ship class, drive type and accent color can also be specified, or it can be left undefined, for Helm to select. This gives mission scripts a lot more flexibility in how player ships are handled,

Missions involving multiple ships have also become more flexible in Artemis 2.4. A mission script now has the option to force a second, third, or even more player ships, enabling the creation of stories that involve interaction between multiple ships. PvP missions are also possible. The following code will create three ships, which will all appear from the very beginning of the game, even if no players have clicked "Ready To Play" on those ships yet:

create player point=(50000, 0, 50000) player_slot=0

     create player point=(25000, 0, 25000) player_slot=1 

create player point=(75000, 0, 75000) player_slot=2

Note if no one has defined the ship for a given slot when the server is started, the game will create a TSN Light Cruiser with the default name for each. If you want to select your own ship, make sure Helm has logged in before the server has started. Helm does not even have to select "Ready To Play", as long as customization is finished for that ship slot. You will not be able to customize the ship after the game starts.

You can also force a name or class of ship, and that will override the player's choices.

     create player point=(50000, 0, 50000) player_slot=0 raceKeys="TSN" hullKeys="Light Cruiser" warp="yes"

Now, no matter what Helm selects, slot 0 will be given a TSN Light Cruiser with Warp drive. The players will be able to customize their accent color, though. (There is a property to set that as well, if desired)

Alternately, you can create a PvP scenario where the ships are on different sides:

create player point=(50000, 0, 50000) player_slot=0 side=1    (side 1 is the default player side)

     create player point=(50000, 0, 50000) player_slot=1 side=1

create player point=(50000, 0, 50000) player_slot=2 side=2    (additional sides should all be >1)

     create player point=(50000, 0, 50000) player_slot=3 side=2

Finally, if you don't want to force the players to have a certain number of ships, you can make any additional ships optional:

if_exists player_slot=2

(have this ship interact with the script)

You don't actually have to check if a ship exists if you just want multiple ships to be able to come and go as they please. If you do specify the creation of additional ships, Artemis will work as it did in previous versions, and create the ship when it logs into the game, ignoring it. If the mission objectives only require the destruction of the enemy ships, the game doesn't care if it is the first player ship that did it, or other player ships. But if you want to handle it when a ship is destroyed, and have the script react in some way, or you want to give the additional ships the ability to achieve an objective, or even if you just want the additional ships to interact with the script, like triggering an event when one docks with a station, you will either have to create the ship for that player_slot, or check if it exists.

In either case, you will typically have to duplicate your code for every player slot that you want to have interact with the script. For instance, to trigger an event when any ship docks with a station, you would have to write eight event blocks, one for each player slot. The event blocks might look like this:

event

     (we don't have to check if slot 0 exists if it was created above)

     if_docked player_slot=0

     set_timer enemy_timer seconds=20

event

     if_exists player_slot=1

     if_docked player_slot=1

     set_timer enemy_timer seconds=20

event

     if_exists player_slot=2

     if_docked player_slot=2

     set_timer enemy_timer seconds=20

event

     if_exists player_slot=3

     if_docked player_slot=3

     set_timer enemy_timer seconds=20

event

     if_exists player_slot=4

     if_docked player_slot=4

     set_timer enemy_timer seconds=20

event

     if_exists player_slot=5

     if_docked player_slot=5

     set_timer enemy_timer seconds=20

event

     if_exists player_slot=6

     if_docked player_slot=6

     set_timer enemy_timer seconds=20

event

     if_exists player_slot=7

     if_docked player_slot=7

     set_timer enemy_timer seconds=20

Now it doesn't matter how many ships are logged into your mission, or what slots they use. When any ship docks with any station, the timer will start to spawn enemies.

A player ship must be given a location when it is created. If you do not create a player ship, and instead check if it exists, you should relocate it to an acceptable starting position. Near one of the defined bases in the script is a good location.

Sector Coordinates

All objects in the sector must be located using the coordinates X, Y, and Z. Unlike Cartesian coordinates, Artemis uses X and Z for the primary coordinate plane, not X and Y. Artemis inherits this behavior from DeleD, the mesh editing program used to build Artemis's .dxs files. The X and Z coordinates range from 0 to 100000, while the Y coordinate ranges from -100000 to 100000, with 0 being the "median" height where all objects are located.

Although it is possible to set the Y coordinate for any object to any valid value, the player ships are only able to range from a Y coordinate of -500 to 500. A player ship created outside of that range will automatically move into the allowable range. Most game objects should also be constrained to the -500 to 500 range. For most scripts, the Y coordinate can be left at 0, although varying the height above the map can make a script more challenging. It can also be useful to place generic objects, particularly large ones, above or below the X/Z plane so ships are not blocked by them.

It is also important to note that the X coordinate runs from right to left, not left to right. Again, this is due to the way the coordinates are defined in DeleD. The coordinate (5000, 0, 5000) is at the upper right of the screen, and the coordinate (95000, 0, 95000) is to the lower left. Cartesian coordinates run the other way, X from left to right, and Y from bottom to top. So Artemis coordinates can be said to be in Cartesian Quadrant III, if you substitute Z for Y. This can help convert coordinate calculations to Artemis format.

The most common error encountered in writing scripts is probably assigning the wrong coordinate to a moved or created object. Setting a coordinate outside of the valid ranges will cause the game to crash, and display an error dialog. If this happens, check your script and make sure your coordinates are within the correct range. Remember that you can sometimes copy coordinates from one object to another with an offset, and this can force your object off of the screen.