Comments

Users can insert comments anywhere in a script. Comments are not executed like regular code. Instead, they can be used for documentation or to temporarily disable blocks of code.

JavaScript supports two types of comments:

• Single-line comments start with // and end when the line ends.

• Block comments start with /* and end with */. These can extend across multiple lines, or can be used within a single line.

Example:

// This is a single-line comment
/* This is a
 * multi-line
 * comment.*/

Calling Functions

A function takes in some parameters and returns a value. This lets you re-use pieces of code without re-writing everything.

Functions can be executed by using the function name, followed by parentheses. Any arguments should be placed inside of the parentheses.

For example, the script below calls the function notification.send with the argument "Hello, world!". This will bring up a notification that says “Hello, world!”:

notification.send("Hello, world!");

Some functions do not require any arguments, for example system.exit, which exits the runtime project. In a script, it would look like this:

system.exit();

Other functions require multiple arguments. In this case, arguments should be separated by commas.

For example, tag.write takes two arguments. The first argument is the tag name, and the second argument is the value to write. The script below writes the value 1 to the tag called "my_tag":

tag.write("my_tag", 1);

Declaring Variables

Variables let you store values and access them later in the script.

Variable names must not contain spaces, and must begin with either a letter or an underscore _. Variable names are case-sensitive.

Variables can be declared using the following format:

var variable_name;

To declare more than one variable, use a comma , between each variables:

var variable_name_1, variable_name_2, ... , variable_name_n;

Users can also define an initial value for the variable when declaring it using the following format:

var variable_name = 1;

If you do not specify an initial value, then the variable’s value is undefined.

A variable’s data type is determined automatically based on the value used to initialize it.

Using and Setting Variables

Once a variable has been declared, you can assign a new value to it using the assignment operator =. For example:

var a = 1; // a has value 1
a = 2;     // a now has value 2

Once a variable has a value, you can use the variable name to access that value. For example:

var tag_name = "my_tag";
var value = 1;
tag.write(tag_name, value);

This is the same as:

tag.write("my_tag", 1);

Operators, Expressions, and Parentheses

You can add, subtract, multiply, and use other operators on variables and other values. See the “Operators” section for more information.

1 + 2;  // 3 (addition)
1 - 2;  // -1 (subtraction)
1 * 2;  // 2 (multiplication)
1 / 2;  // 0.5 (division)
1 == 2; // false (equal to)
1 < 2;  // true (less than)
!true   // false (not)

Just like in mathematics, expressions can be combined and nested within each other. The values will be evaluated as soon as they are needed.
Parentheses can be used to group expressions together and to specify the order of operations. For example:

1 + (2 * 3)       // 7
(1 + 2) * 3       // 9
((1 + 2) * 3) - 4 // 5

Reading and Writing Tag Values

To get a tag’s current value, use tag.read. This function has one argument, which is the name of the tag, and returns the tag’s value.

var value = tag.read(“my_tag“);

To write a tag value, use tag.write. This takes in two arguments: the name of the tag and the value to write. There is no return value.

tag.write(“my_tag”, 1); // writes the value 1 to the tag "my_tag"

Tags within tag groups can be accessed using the / character. For example:

tag.write("outer_group/inner_group/my_tag", 1);

Semicolons

JavaScript uses semicolons to indicate the end of expressions. Using semicolons at the end of lines is not required, but is recommended for better organization and clarity:

some_function();
some_other_function();

This is the same as:

some_function()
some_other_function()

Semicolons allow you to perform multiple actions in one line of code without line breaks:

some_function();some_other_function;

Whitespace

JavaScript ignores whitespace characters like spaces, tabs, and line breaks.

For example, the two scripts below are equivalent:

var a = 1; if (tag.read("my_tag")) {a=0;}

var a = 1;
if (tag.read("my_tag")) {
  a = 0;
}