User variables are the primary means of storing and processing information. User variables are named locations that store values (also called data). As the creator of a robot, you decide how many user variables you need and their names. All variables are global. Global means that a variable can be accessed and changed from anywhere within a robot's code. A variable that is first used in one section can be accessed from other sections as well.

User variable names must start with a letter (A-Z). Variable names may contain numbers (1-9), but they may not start with a number. Any name may be used for variables except the names of sections or system variables. Capitalization is ignored by Robot Battle. A user variable named "TESTING" is that same as "testing". To improve readability, most people use a consistent case for each variable name.

Variable Creation and Scope

User variables are normally created by placing them on the left side of the assignment (=) statement. Actually, any command that takes an lvalue type parameter (such as copy) can create user variables, but usually they are created with the assignment statement. All user variable have global scope. That means a variable created in one section can be accessed in all other sections as well. In the example below, the first assignment creates myvar and assigns it a value of 10. The second assignment changes the value of myvar to 20 but does not create a new variable since myvar already exists.

At the start of each game before any instructions are run, Robot Battle examines a robot's code, creating and initializing all variables on the left side of the assignment statement. If a robot reads the value of a variable before an assignment statement is actually run, the variable will have a value of zero. Relying on this behavior can cause confusion, however. It is best to always assign a value to a variable before using it.

Variables that have been stored with the store command have an initial value equal to the value that was stored in a previous game. It is normal to read the values of variables stored in previous games before they have been assigned values in the current game.

Variable Types

User variables can contain either numeric values or string values.

Although numeric values are tracked internally with 15 digits of precision, the game's user interface and logs only display up to 6 digits of precision. Even six digits of precision is more than robots usually need.

As with most computer languages, real number mathematics can be slightly inaccurate. Testing for equality after performing calculations may produce unexpected results. For example, acos( cos(20) ) may yield 19.9999 rather than 20. Use the round command if this causes problems.

Variable Structure

Each user variable consists of three distinct components.

1. Root value
2. Array variables
3. Property variables

When learning about array and property variables, it is often helpful to write test code that uses arrays and properties. Then load this robot in a match and examine the variables in the Inspector window. The Inspector window lets you explore the resulting structure of the variables.

Root Value

All variables have one root value. The root value of a variable is the value assigned directly to the variable's name. The root value of a variable is used most often in a robot's code. In fact, using the root value is so common it is normally just called the variable's value (without saying "root"). The code below assigns the root value of myvar to 20.

Array variables

Every variable can also contain an array. An array is a sequence of user variables (also called "elements") that are accessed by a numeric index. The numeric index specifies which variable in the sequence should be accessed. A special square brackets notation is used to specify the numeric index. This notation is shown below and is the same in most computer languages:

Array variables are created by placing them on the left side of the assignment (=) statement. In the code above, 2 array variables (or elements) are added to the myvar variable. The first variable has an index of 0 while the second variable has an index of 1. The first element of an array always has an index of zero. This may seem odd at first, but it makes sense if you think of the array index as an offset from the first element rather than a counter.

The following is a list of important array qualities:

Arrays never have gaps. If you skip elements in the sequence by assigning to a higher index, the skipped variables are automatically created and assigned values of 0. In the example below the variable at offset 5 (which is the 6th element in the array) is assigned a string value of "hi". If the array elements preceding test[5] had not already been created, this line causes their creation and assigns values of 0. The second line therefore adds 0 to the print log.

If an array element has not be created, attempting to read its value causes an error. This is true for all user variables. The code below causes an error because myvar[2] does not exist.

Array elements are separate from the root value of a variable. In the example below, setting myvar[0] to 10 has no affect on the root value of myvar. The two print commands add 9 and 10 to the print log respectively.

Every element of an array is a complete user variable itself. Like all user variables, array elements have three components; a root value, array variables, and property variables. This means array elements can have array and property variables themselves. In the code below, myvar is a normal user variable. Like all variables, myvar can have array variables. The second line below creates the array variable myvar[0]. This is itself a full fledged user variable and like all variables, myvar[0] can have array variables. The third line creates the array variable myvar[0][0].

Each array has only one dimension. There are no true multi-dimensional arrays in Robot Battle. It is easy to make arrays look multi-dimensional, however, by adding arrays to arrays as shown in this example.

The example above does not create a 4x4 square of variables. It creates a jagged multi-dimensional array. The code above is equivalent to the code below.

Both of these code samples create a variable named a with the following structure (shown without values):

    a[0][1][2][3]
              [0]
              [1]
              [2]
              [3]


An array index can be a full numeric expression. You can even use arrays in the index expression. In the code below, the first line assigns a value of 10 to the fourth array element (which is myvar[3]). The second line assigns a value of 22 to the eleventh array element (which is myvar[10]).

Property variables

Every variable can also contain properties. Properties are named user variables that exists within another variable. A special period (or dot) notation is used to access the properties within a variable. This notation is shown below and is the same in most computer languages:

Property variables are created by placing them on the left side of the assignment (=) statement. In the code above, 2 property variables are added to the myvar variable. The first property is named prop and has a value of 10 while the second is named other and has a value of 20.
 

The following is a list of important qualities of properties:

If a property has not be created, attempting to read its value causes an error. This is true for all user variables. The code below causes an error because myvar.testing does not exist.

Properties are separate from the root value of a variable. In the example below, setting myvar.prop to 10 has no affect on the root value of myvar. The two print commands add 9 and 10 to the print log respectively.

Every property is a complete user variable itself. Like all user variables, properties have three components; a root value, array variables, and property variables. This means properties can have array and property variables themselves. In the code below, myvar is a normal user variable. Like all variables, myvar can have properties. The second line creates the property variable myvar.prop. This is itself a full fledged variable and like all variables, myvar.prop can have array elements. The third line creates the array element myvar.prop[0]. Once again, myvar.prop[0] is a full fledged variable and like all variables can have properties. The last line creates the property variable myvar.prop[0].hey

The square bracket array notation can also be used with string expressions to create and access properties. In many computer languages this is called an associative array. Associative arrays can be used when a robot will know the name of a property when it is running in a match, but not when you are creating the robot. In practice, this feature is not often needed in Robot Battle. In the example below the first line assigns a value of 10 to the property "hi". The second line adds 10 to the print log. The third and fourth lines show how the property name can be a full expression. The fifth line adds 20 to the print log.
 

See Also

assignment (=), countarray, setarraycount, countprops, getpropname, hasprop, copy, isequal, clear, clearprops, cleararray, operators