A to Z Scripting: Anatomy of a script

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: wait()

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

sys.wait(3);

Here's a closer look at its components:

• sys.
  • Every script event needs to be used on an entity. Very generic events like "wait" are typically used on sys, which is shorthand for the system entity.

• wait(3)
  • This is the actual script event. Every script event must be accompanied by input brackets, even if they're empty. In this case, "3" is the input.

• ;
  • 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: setOrigin()

This is another simple script event. It's called on player1 and teleports (sets the origin of) him to the position '0 150 0'.

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

• $player1.
  • Notice the $ sign: this means the script engine should look for a specific entity in the game with that name. The player is always called "player1".

• setOrigin('0 150 0')
  • Every new word in a script event's name starts capitalised. Scripting is case-sensitive, so this is an important detail.

Scripts

Example: sending a message to the console

Script events can't work on their own, they 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.");
}

• 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. In the large majority of cases you'd use void.

• test_script()
  • This is the name of the script: "test_script".
  • Like with script events, input brackets are mandatory for scripts, even if the script doesn't use them. For a script that should damage various entities by various amounts, you could define an entity input and a float (number) input.
  • Note that no semicolon is needed at the end of this top line.

• {}
  • Curly brackets mark the body of the script. Script events go here.

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

Example: simple cutscene

void simple_cutscene()
{
	sys.fadeOut('0 0 0', 2);		//fade to black (color vector '0 0 0') in 2s
	sys.wait(2);				//wait 2s for the fadeOut
	$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);				//wait while the narrator is speaking
	sys.fadeIn('0 0 0', 2);			//fade back in from a black screen in 2s
	$camera.activate($player1);		//return player controls as soon as the screen starts fading back in
}

This scripts a basic cutscene: fade to black, activate a speaker, fade back in. At both ends a camera is toggled so that the player can't move while the screen is black.

• //
  • 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, instead of "sys". 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