A to Z Scripting: Anatomy of a script

This section will teach some basic scripting literacy, first by defining a handful essential terms, then picking apart some basic scripts of slightly increasing complexity.

Basic terms

Script events	For purposes of this guide, a script event is a single action of some kind, i.e. waiting x seconds or triggering an entity. They are the basic building blocks of scripting.
Script function	For purposes of this guide, a script function is what one thinks of as a "script": a set of instructions. Usually this guide will refer to them simply as "scripts".
Scriptobject	This is a powerful set of scripts that are assigned to single entities. It allows creating entities with scripted behaviours, i.e. a candle holder that controls the skin, particle, lit state etc. of its candle.
Variables	Variables store a piece of data, such as an entity's name or a position, which can be modified or used by a script event. They are another basic building block, allowing a script to have variable effects and to store data for later use. Every variable needs to have a name and a data type.
Data types	This informs the engine whether a piece of data is a text (string), number (float), vector etc. Every variable and every input/output of a script event needs to have a data type.

Script events

Example: setOrigin()

This is a simple script event, in other words a single command. It teleports player1 (sets his origin) to the position '0 150 0'.

$player1.setOrigin('0 150 0');

Here's a closer look at its components:

• $player1.
  • This is the name of the player entity: player1.
  • The $ sign tells the script that this is the name of an entity in the map.
  • The . marks the end of the name.

• setOrigin('0 150 0')
  • This is the script event. It sets the origin of the entity to whatever value you enter into the input brackets.
  • Every new word in a script event's name starts capitalised. Scripting is case-sensitive, so this is an important detail.

• ;
  • A semicolon is needed to mark the end of a line of instructions. Forgetting these is a common mistake that stops the map from loading.

Example: wait()

This is another basic script event which instructs the script to wait for 3s:

sys.wait(3);

• sys.
  • This is shorthand for the system entity. No $ sign is used here because "sys" is the name of a variable that points to the system entity.
  • You always need to name an entity when you use a script event. Very generic events like "wait" typically use sys.

• wait(3)
  • This is the actual script event. The input is 3.
  • You always need to include input brackets, leaving them empty if the event doesn't need any input.

Scripts

Example: sending a message to the console

Script events need to be inside a script. The below script is as basic as it gets, containing a single script event:

void test_script()
{
	sys.println("Test message.");
}

• The top line creates a new script called test_script. Note that you don't need to end this line with ; because it's not an instruction.

• void
  • In the large majority of cases, a new script definition begins with void. This defines what type of result the script puts out to other scripts: "void" means nothing while i.e. "float" would mean a number.

• test_script()
  • This is the name of the script followed by mandatory input brackets. In this case they're empty, but for a script that should damage various entities by various amounts you could define an entity input and a float (number) input.

• {}
  • Curly brackets mark the beginning and end of the script itself. Script events go here.

• sys.println("Test message");
  • This is a script event which prints a text ("Test message") to the console and then leaves a line (ln). Leaving a line ensures that every text will be on its own line.

Example: simple cutscene

void simple_cutscene()			//a basic cutscene: fade to black, activate a speaker and fade back in
{
	sys.fadeOut('0 0 0', 2);		//fade to black (color vector '0 0 0') over 2s
	sys.wait(2);
	$camera.activate($player1);		//activate a camera to disable player controls

	sys.trigger($speaker_narrator);	        //trigger a speaker with a narrator's voice 
	sys.wait(10);				//narrator is speaking

	sys.fadeIn('0 0 0', 2);			//fade back in from a black screen over 2s
	$camera.activate($player1);		//return player controls as soon as the screen starts fading back in
}

• //
  • This is a comment for the reader: anything behind a double slash gets ignored. This is a useful habit for helping others and your future self understand how your script works.

• sys.fadeOut('0 0 0', 2);
  • This script event uses 2 different inputs:
    • '0 0 0' is a vector defining the color to which the screen should fade. Every number represents the intensity of red, green or blue color.
    • 2 is a float (number) defining how long the fadeout should take.

• sys.trigger($speaker_narrator);
  • This is a script event to trigger a specific entity called "speaker_narrator", which would simply be a speaker in the map with a custom soundshader.

• $camera.activate($player1);
  • This is an alternative way to trigger, aka activate, an entity. This is needed when you want one entity to be triggered by another entity. In this case, player1 is the activator who activates the camera. Another example would be the player activating a teleporter entity.

Next / previous article

• Next article: A to Z Scripting: More scripting basics
• Table of contents: A to Z Scripting