The Scripting Language for Decker Missions


The Java port of decker will support scripted missions. This page is a documentation of the scripting language. To get an idea of how it works have a look at the example missions.

Mission scripts are written as plain text and are saved in .txt files. You can use any text editor to edit mission scripts, provided it supports the ANSI character encoding.


Comments

Mission scripts may contain comments. If a line of text contains a // outside of a string, the // and the text following it on the same line is ignored. Below is an example.

// this is a comment within a mission script file


Variables

In a mission script you mainly set, use and change variables to describe the mission and how it affects the game world.

Variable names are case sensitive. foo_name and Foo_Name are regarded as different variables.

There are four groups of variables : Predefined player variables describe the person the player controls. Predefined mission variables describe the mission and cease to exist once the mission is over. Custom mission variables are created by a mission script ( they cease to exist once that mission is over ). Custom player variables are defined by a mission script ( they exist as long as the player for which they have been defined does ).

Variables may be assigned predefined values, integer values, string values, boolean values or structures. Some of the predefined values are UNDEFINED , AVAILABLE , INCOMPLETE , COMPLETED , FAILED , MEGACORP , ELECTRONICS , BANK , LAB , MEDICAL , MANUFACTURING , SCHOOL , OIL , GREEN , YELLOW , RED , SHUT_DOWN. true and false are the boolean values, any whole number in the range from -2147483648 to 2147483647 is an integer value, anything that starts and ends with a " is a string value.

Each variable has a value. A variable that has not been assigned a value has the value UNDEFINED unless it has some other value by default.

When assembling strings, variables containing predefined values show up as "X" within the assembled string, where X is the name of the predefined value ( the expression   "a "+FAILED+" mission"   would create the string "a FAILED mission" ).

The following examples assign the boolean value false, the integer value 5 and the string value "something" to the custom mission variables a, b and c, respectively.

a = true
b = 5
c = "something"

Custom variables are created when they are first used during the execution of a mission script. Custom player variables have the prefix player. to their name ( this makes them member variables of the player structure ). Custom mission variables have a normal name. Any name may be used for a custom variable, unless it has a predefined meaning or is used for a predefined variable. Variable names may only consist of latin characters ( a to z and A to Z ), digits and the character _ . Every variable name must contain at least one non-digit character. Custom player variables have the prefix player. to their name. Below are examples of valid and invalid custom variable names.

// the commands below create valid custom mission variables
a = true
5blips = 5
a_very_long_name = false

// the commands below create valid custom player variables
player.Duration = 7
player.is_ill = true


// the commands below don't work because the variable names are invalid

// custom variable names may only contain a . if it is part of the player. prefix
special.event = true
player.fun.item = "dildo"

// custom variable names may not contain special characters like ä, > and $ or spaces
häscher = true
lots_of_$ = 15000
two words = "two words"
a>b = 15


Predefined variables

The tables below list the predefined mission variables and player variables.

Mission variables
available May be assigned an expression. This expression is not evaluated and the result assigned to the variable as would usually happen. Instead the expression is assigned to the variable without evaluating it. Whenever the program tries to add a mission to the list of available missions, the expression contained in this variable is evaluated to see whether the mission may currently be made available
title Contains the mission title. It will be displayed in the list of available contracts.
description Contains the detailed mission description
target_system Contains the target system
goal[x]

x is an integer and must be in the range of 0 to 100. Every variable goal[x] may contain a mission goal. These will be used to determine whether a mission has been completed or failed. Valid mission goals are the structures of the types NO_RED_ALARM, CRASH_SYSTEM and CREATE_BACKDOOR , DOWNLOAD_FILE , ERASE_FILE and STEAL_AND_ERASE_FILE.

rating May contain an integer value that describes the difficulty of the mission. If no value is assigned the formula for calculating the difficulty of a random generated mission is used
deadline

May contain an integer value. If it does it corresponds to a date. The first of the following two expressions will set the deadline to the current day. The other sets the deadline to 5 days in the future

deadline = 0

deadline = 5

status

Describes the current status of the mission. Must hold one of the predefined values AVAILABLE, ACCEPTED, COMPLETED and FAILED ( a mission is failed if the player abandons it or the deadline has passed ). If this variable is changed from within the mission script the change will take effect in the game. You can force the player to accept a mission with the following command :

status = ACCEPTED

The variables below are of no use for most mission scripts
age The number of days the mission since the mission was created from the mission file available. Every mission starts with age 0 by default. The deadline passes when age becomes greater than the value of deadline.
failed_attempts The number of times the player has tried and failed to succeed in completing this mission. Set to 0 by default when the mission is created.
destroy_when_over This variable determines whether the mission is destroyed when its status becomes or is COMPLETED or FAILED ( and any triggers triggered by that event have been executed ). destroy_when_over may only be assigned boolean values. It has the value true by default.

 

Player variables
player.name Contains the name of the player
player.base_mission_rating The the rating of random generated missions is based on this value. If the player successfully finishes a mission of rating x, the base_mission_rating is set to x. If the player fails a mission, the base_mission_rating is decreased by one. The base_mission_rating always stays in an interval of 1 to 20.
player.health Contains the current health of the player on a scale of 0 to 20
player.mental_health

Contains the current mental health of the player on a scale of 0 to 20

player.lifestyle Contains the player's current lifestyle on a scale of 0 to 4. The lifestyle determines the level of the available shop items.
player.reputation_level Determined by the player's reputation. The reputation level is a value in the range of 0 to 20. It determines the title in the reputation field of the character data dialog.
The variable below is of no use for most mission scripts
player.reputation

The reputation is modified by successfully finishing missions and by failing missions. It determines the reputation_level. It holds an integer value and must be at least 0.


Structures

A structure is basically a collection of variables. Each structure has a type, and the member variables of a structure are specific for its type. A new structure is created when its type name occurs on the right side of the = command in the script. The type name must be followed by a block. Inside that block variables of the structure may be assigned values. Valid types are SYSTEM , FILE , POPUP , EDIT_FILE , DOWNLOAD_FILE , ERASE_FILE , STEAL_AND_ERASE_FILE , NO_RED_ALARM, CRASH_SYSTEM , CREATE_BACKDOOR , TIME_RESTRICTION.

If you want to access a member variable of a structure, you give the name of the variable that holds the structure, followed by a dot and the name of the member variable within the structure.

Below is an example of how an EDIT_FILE and a FILE structure is used in a script. If encountered in a script, this code will create a file and add the goal to edit that file to the mission. It will then change the goal's status to COMPLETED and change the name of the target file to "Product information".

goal[0] =
    EDIT_FILE
    {
        target =
            FILE
            {
                name = "( the file name will later be changed )"
                description = "Contains the product information you are looking for"
            }
    }

goal[0].status = COMPLETED
goal[0].target.name = "Product information"


Structure Types

Structure types fall into three categories, mission goals, objects from the game world and special structures. All structure types are described in detail below, starting with the special structures. The tables contain the member variables of each type.

 

POPUP

A POPUP describes a popup window. Popup windows may contain text and / or buttons. These are represented by the member variables of the POPUP structure. Every POPUP must have at least one button to be displayable.
text Contains the text that is displayed in the popup window
choice When the player presses one of the popup window's buttons, choice is assigned the value displayed on the button.
button[x] x may be any integer value from 0 to 100. Each variable button[x] may be assigned a value. For every button[x] that is not UNDEFINED a button is created and displayed in the popup window.

 

EDIT_FILE , DOWNLOAD_FILE , ERASE_FILE and STEAL_AND_ERASE_FILE

These structure types describe mission goals that target a file. The names of the types state what has to be done with the file to fulfill the goal. They all have the same member variables.
target Contains a FILE structure that describes the target file
status Contains the current status of the goal, which may either be INCOMPLETE, COMPLETED or FAILED
unfinished May contain a string that describes the status of the goal during a mission if the goal has not been completed or failed yet
completed May contain a string that describes the status of the goal during a mission if the goal has been completed
failed May contain a string that describes the status of the goal during a mission if the goal has been failed

 

NO_RED_ALARM, CRASH_SYSTEM and CREATE_BACKDOOR

These structure types describe mission goals. They all have the same member variables.

NO_RED_ALARM has the status COMPLETED until the player triggers a red alert. Triggering a red alert will change the status to FAILED.

CRASH_SYSTEM has the status INCOMPLETE until the player crashes the system. Crashing the target system will change the status to COMPLETED.

CREATE_BACKDOOR has the status INCOMPLETE if the player doesn't have a backdoor to the target system. It has the status COMLETED if he does.
status Contains the current status of the goal, which may either be INCOMPLETE, COMPLETED or FAILED
unfinished May contain a string that describes the status of the goal during a mission if the goal has not been completed or failed yet
completed May contain a string that describes the status of the goal during a mission if the goal has been completed
failed May contain a string that describes the status of the goal during a mission if the goal has been failed

 

TIME_RESTRICTION

A TIME_RESTRICTION structure describes a mission goal that sets a time restriction. It has the status INCOMPLETE if the start_time hasn't been reached yet, COMPLETED if the start_time has been reached or is undefined and the end_time hasn't been passed or is undefined, FAILED if any mission target is completed before the start_time is reached (if the start_time is defined) or any mission targed is INCOMPLETE or FAILED after the end_time has passed (if the end_time is defined).
start_time Holds an integer giving the mission time (in seconds) at which the first mission goal may be completed, if it is defined.
end_time Holds an integer giving the mission time (in seconds) until which all mission goals must be completed, if it is defined.
status Contains the current status of the goal, which may either be INCOMPLETE, COMPLETED or FAILED
unfinished May contain a string that describes the status of the goal during a mission if the goal has not been completed or failed yet
completed May contain a string that describes the status of the goal during a mission if the goal has been completed
failed May contain a string that describes the status of the goal during a mission if the goal has been failed

 

SYSTEM

Describes a system, the target_system for example. For a system to be valid, at least its name, rating and type must be defined.
name Holds the system's name
rating Holds the system's rating. This must be an integer value and it must be at least 1.
type

Holds the system's type. The system's type coresponds to the type of the corporation or facility it represents. It determines the types random files and random generated mission targets may have. Here's a detailed list of available predefined values for the system type :

MEGACORP              a meg corp
ELECTRONICS         electronics design / production
BANK                        banking
LAB                            laboratories
MEDICAL                  any medical
MANUFACTURING
SCHOOL                   a college or university
OIL                             a petrol company

status Holds the system's status. May be either GREEN, YELLOW, RED or SHUT_DOWN. The default value is GREEN.

 

FILE

Describes a single file.When a file is assigned to a mission goal and the file does not exist within the target_system yet, the file is added to a datastore in the target system.
name Holds the file name
description Holds a detailed description of the file
size May be assigned a positive integer value. Has a random positive integer value by default.


Expressions

You can use mathematical expressions to calculate values as you would in normal maths. The expression syntax is based on JavaScript ( almost identical to the C expression syntax ). The following table contains the operators which may be used within an expression, in order of precedence :

.

The result of a.b is the member variable b of the structure contained in a. The left operand of . must be a variable that contains a structure, the right operand must be the name of a member variable of the structure contained in the left variable.

The . operator is uique in that its result is a variable, not a value. This means you may use it everywhere where a variable is required. Although the = command requires a variable on the left, the line below is a correct use of the = command, if the structure contained in foo has a member variable called fighter :

foo.fighter = "yes"

  The . operator takes precedence over all other operators.

( ) Expressions within brackets are evaluated and then the whole bracket is replaced by that value.
* Multiply two integer values
/ Divide an integer value by a second integer value
+

Add two integer values. If the values are not both integers, they are turned into strings instead and the second string is appended to the first. Note that structures cannot be converted to strings, so this operator doesn't work for them.

- Substract an integer value from a second integer value
> Checks whether the left value is higher than the right value. If both values are integers, they are compared as integers. Otherwise they are first converted to strings and then compared. Note that structures cannot be converted to strings, so this operator doesn't work for them.
< Checks whether the left value is lower then the right value. If both values are integers, they are compared as integers. Otherwise they are first converted to strings and then compared. Note that structures cannot be converted to strings, so this operator doesn't work for them.
==

Checks whether the left value is equal to the right value. This symbol consists of two = . If both values are of the same type, they are compared without changing their type. Otherwise they are first converted to strings and then compared.

If at least one of the operands is a structure, == regards them as equal only if both operands are the same structure. They are not regarded as equal if only one operand is a structure, or the structures are of different structure types, or the operands are different structures of the same type, even if all their member variables have equal values.

!=

Checks whether the left value is different from the right value. If both values are of the same type, they are compared without changing their type. Otherwise they are first converted to strings and then compared.

If at least one of the operands is a structure, <> only regards them as not different if both operands are the same structure. They are regarded as different if only one operand is a structure, or the structures are of different structure types, or the operands are different structures of the same type, even if all their member variables have equal values.

>= Checks whether the left value is at least as high as the right value. If both values are integers, they are compared as integers. Otherwise they are first converted to strings and then compared. Note that structures cannot be converted to strings, so this operator doesn't work for them.
<= Checks whether the right value is at least as high as the left value. If both values are integers, they are compared as integers. Otherwise they are first converted to strings and then compared. Note that structures cannot be converted to strings, so this operator doesn't work for them.
&&

Do a logical AND with two boolean values. If the left operand has the value false, the right operand is not evaluated. This means the line below won't result in an error if my_system is UNDEFINED, because the right part of the expression containing the potential error is never evaluated.

if  my_system != UNDEFINED  &&  my_system.rating > 6< /p>

||

Do a logical OR with two boolean values. If the left operand is true, the right operand is not evaluated.

All other operators take precedence before the logical OR operator. Note that the = command is not an operator.

Beloware a few valid expressions. The = command assigns the value of the expression on the right to the variable on the left. After executing the commands in the given order, a will have the value 5 and b will have the value true ( if c is UNDEFINED ).

a = (2+1)*10/6
b = a+" and "+c == "5 and UNDEFINED"


Commands

There are five commands. = and trigger will be used in every script, if , while and display are only needed in special situations.

= assigns the value of the right side to the variable on the left. On the right may either be a mathematical expression or a structure definition.

trigger creates an event trigger. The command is followed by an expression which is evaluated every time something changes in the game, until the trigger ceases to exist. If it evaluates to the boolean value true, the trigger is destroyed and the block following the trigger command is executed.

if evaluates an expression and executes the following block if the expression has the boolean value true.

while evaluates an expression and executes the following block if the expression has the boolean value true. After executing the block, the script execution continues at the while expression, evaluating it again. This way the script execution loops through the block until the expression does not have the boolean value true anymore.

display is followed by a variable that contains a POPUP or by a POPUP definition. That POPUP is displayed in a popup window and the script execution halts until the popup window is closed. When the popup window is closed, the POPUP member variable choice is assigned the text on the button that was used to close the popup.

Contents

Comments

Variables

Predefined Variables

Structures

Structure Types

Expressions

Commands


Related Links

Decker Project Page

Official Decker Site

A Decker Review

Decker Development Page


Unrelated Links

Tube Blazer

Java Color Expansion

Asteroid Field

Blood Bowl League