How to use the scripting reference

The scripting reference lists all of the functions and types that is available to you through scripts but it's formatted in a way that is familiar to experienced programmers. This guide is for the rest of you. It will help you decipher the reference so that you can start experimenting with scripting even if you don't have the experience.

---

The function header

Here is an excerpt from the scripting reference, describing a function for playing sound:

It lets us know that there are two versions of the same function. It has a simple and an an extended version.

The first word in the header is the return type of the function, in this case "bool", which is a binary value (true or false). The function description lets us know that this must be true if the function executed successfully (i.e. a sound was played).

The function name is followed by parentheses and a list of input parameters. "string AssetName" tells us that the function takes a string and it should be the name of the asset to be played.

We call the function like this (where "My sound" is a valid audio asset name):

PlaySound("My sound");

... or we can take advantage of the return value, like this:

if (PlaySound("My sound") == false)
{
	// Sound wasn't played
}

Here's how the extended version can be used (50% volume, center balance):

PlaySound("My sound", 0.5f, 0);

---

Members versus properties

Some class members are marked as being properties. These differ from regular members in that you can not access them directly, but through internal property accessors. The only real consequence of this is that you will get an error message if you try to use compound assignment operators (+=, -=, *=, etc) on a property.

This is a member of the Object class. Because it's a property we are unable to do this:

obj.position += Vector2(100,50);

We need to explicitly get the property before we can add to it:

obj.position = obj.position + Vector2(100,50);