Fundamental Scripting Guide

Author - Dragofer

This is a (work in progress) resource written primarily for mappers with no background in scripting or coding, though also more experienced scripters may find practical guidance in adapting to TDM's scripting system. This is the large majority of what I've picked up over the years through experimentation, looking at existing scripts and interacting with other forum members.

My aim is for the tutorial to be both comprehensive and down to earth, using many examples and avoiding unnecessary technical terms. There will be some overlap with existing wiki articles, since this aims to have everything in one place out of one hand.

The concept will be to start with teaching some basic script literacy, then introduce scripting principles one after another. Towards the end, practical examples

Anatomy of a script

This section will define essential terms, then look at some basic scripts of slightly increasing complexity to demonstrate what a script is made up of.

Basic terms

Script events	Script events are an action of some kind, i.e. waiting x seconds or triggering an entity. They are the basic building blocks of scripting.
Script function	This is the technically correct term for a "script". Script functions often contain multiple script events, and some can also be used like script events in other script functions. Usually this guide will refer to them simply as "scripts".
Scriptobject	This is a powerful set of scripts that are applied to single entities. This allows you to write code once, but let it apply to an unlimited number of entities without conflicts. An example is the tdm_light_holder scriptobject, which controls the skin, particle, lit state etc. of its candle.
Variables	Variables are another basic building block and allow a script to store data for further processing and to have variable effects. Each variable must be named and given a data type.
Data types	Every variable and every input/output of a script function needs to have a data type to inform the engine whether it should be read as a text, number, vector etc. Script functions won't work if they're given the wrong type of data.

Script events

Example script event: 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 must be called on an entity. For very generic events like "wait", sys is typically used, shorthand for system.

• wait(3)
  • This is the actual script event. Every script event must be accompanied by input brackets, even if they're left 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 script event: 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".

Scripts

Example script: rudimentary script for sending a message to the console

Script events can't work on their own, they need to be part of a script:

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 beginning and end of the body of the script.

• 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 script: simple cutscene

void simple_cutscene()
{
	sys.fadeOut('0 0 0', 2);		//fade to black (colour vector '0 0 0') in 2s
	sys.wait(2);				//wait 2s for the fadeOut
	sys.trigger($speaker_narrator);	        //trigger a speaker with a narrator's voice
	$camera.activate($player1);		//activate a camera to disable player controls

	sys.wait(10);				//wait narrator is speaking
	sys.fadeIn('0 0 0', 2);			//fade back in from a black screen in 2s
	$camera.activate($player1);		//return player controls
}

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.
  • An alternative way to comment, useful for mutli-line comments or temporarily disabling a section of the script, is to use /* at the beginning and */ at the end. This way you don't need to mark every single line as a comment.

• sys.fadeOut('0 0 0', 2);
  • This script event uses 2 different inputs:
    • '0 0 0' is a vector defining the colour to which the screen should fade. Every number represents the intensity of red, green or blue colour.
    • 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.

More scripting basics

General basics

• Scripting is case-sensitive.
• The scripting engine reads from top to bottom. That makes the order in which scripts and variables are arranged quite important.
• The $ sign instructs the engine to look for an entity ingame with that name. If there's no $ sign, the engine will instead look for a variable with that name in the scripts.

TDM Script Reference

The TDM Script Reference is an essential wiki resource for scripting, listing all available script events for the current version of TDM. All script events are listed twice: the first time they're sorted alphabetically, the second time they're sorted based on which kinds of entities they can be called on. By far not all script events have received manual descriptions, so sometimes you may need to experiment with them to properly figure them out.

Here is an example:

scriptEvent float canSee(entity ent);

    no description

    Spawnclasses responding to this event: idAI

Interpretation:

• the script event canSee() is suitable for being called on entities of type idAI, in other words an entity which has been defined as an "ai" in scripts.
• an entity must be entered into its input bracket.
• the script event returns a float. This means you could for example store the result of this check in a float variable and use that elsewhere in your scripting.

Actually using the script event may take some experimentation, mainly to see which entity the event should be called on and which entity should go into the brackets. In the end it could look something like this:

$guard_westwing_1.canSee($player1);

Alternatively, if you want to store the result as a variable (that we name "guard_sees_player") for later use:

float guard_sees_player = $guard_westwing_1.canSee($player1);

Troubleshooting

• Problem: after loading the map, the screen shows only a close-up of a random texture, can't move
  • This happens if you just started TDM, had a scripting error, fixed the error and tried to reload your map.
  • Fix: load into another map or restart TDM, then try to load the map again.