A to Z Scripting: More scripting basics

More scripting basics

Working tidily

• Rule #1 is to keep your scripts tidy and well-commented so they're easy to follow. That includes making liberal use of the 'tab' key, which lets you quickly align your lines. Comparison:

//script for reading spawnargs that the mapper has set on a func_mover entity

//bad
vector mover_translate	= $wardrobe.getVectorKey("translate");
vector mover_rotate = $wardrobe.getVectorKey("rotate");
float mover_time = $wardrobe.getFloatKey("move_time");

//better
vector	mover_translate	= $wardrobe.getVectorKey("translate");
vector	mover_rotate	= $wardrobe.getVectorKey("rotate");
float	mover_time	= $wardrobe.getFloatKey("move_time");	//time taken to move

//script for constantly checking if an AI can see the player

//bad
void watch_for_player()
{
while(1)
{
if($lord_marlow.canSee($player1)
{
$lord_marlow.bark("snd_i_see_you");
return;
}
sys.wait(0.5);
}
}

//better
void watch_for_player()
{
	while($player1.getLocation() == $master_bedroom)	//for as long as the player is in the master bedroom...
	{
		if($lord_marlow.canSee($player1)		//check if Lord Marlow can see the player
		{
			$lord_marlow.bark("snd_i_see_you");	//if yes, make Marlow say something to the player
			return;					//then end this script
		}
		sys.wait(0.5);					//wait 0.5s before checking again
	}
}

General tips

• 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. You can't call a script or use a variable if the engine hasn't seen it defined yet.
• 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.
• Commenting can be done either by putting // in front of every line of comment, or by putting /* at the top and */ at the bottom. The latter is useful for multi-line comments or temporarily disabling a section of your script.

Data types

Data type indicates whether something is a text (string), number (float), vector etc. You will always want to be aware of this, since i.e. a script designed to apply a force vector won't work if you give it a string instead of a vector as input.

String	A string of letters/numbers, in other words plain text. It must always have double quotation marks. Example: “Text message 123”
Float	A float is a single number, decimals are allowed. Example: 15.2
Vector	A vector consists of 3 numbers, often used for 3D movements (x y z) or colors (red green blue). It must always have single quotation marks. Example: '0 90 0'
Boolean	Can be true or false. Easily replaced by floats (0 or 1). Example: TRUE
Void	No type. Commonly used for scripts or script events that have no output.
Entity	Indicates an entity, usually using the name as seen in DR. If it's a specific entity, instead of a variable, then a $ sign is required. Example: $player1
Subcategories of “entity”	You can be more specific and define an entity as, for example, an ai, light or tdm_elevator. These are names of scriptobjects, and by defining an entity like this you gain access to that scriptobject's internal variables and scripts. For an "ai", useful internal variables are i.e. whether the AI is alerted or knocked out. (see A to Z Scripting: Scripting with... - "AI flags" for more)

Variables

Variables are an important part of scripting. Each variable stores a piece of data, such as an entity's name or a position, which can then be modified or used by a script event. They allow a single script to have various effects, depending on the values of the variables.

Creating new variables

The first time the engine finds a variable in a script it needs to be given a data type. Afterwards you use just the name. Example:

vector teleportation_destination;						//create a new vector variable called "teleportation_destination"
...
$player1.setOrigin(teleportation_destination);

You may also want to assign an initial value. Otherwise, floats will default to 0, strings to "", vectors to '0 0 0' and entities to $null_entity. Example:

vector teleportation_destination = '44 68 122';

Another option is to define a variable using the output of a script event. 3 Examples:

vector teleportation_destination = $func_static_1.getOrigin();

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

float sound_duration = $entity1.startSound("snd_move", SND_CHANNEL_ANY, false);  //stores the duration of the sound that's been started

Where to create variables

It's important whether you create a variable inside of a script or outside.

If it's created inside of a script, only that script can use it. Also, every time you run the script the variable will reset to the value that you created it with. Example:

void count_targets()		//counts how many targets there are on a relay entity
{
	float number_of_targets = $trigger_relay_1.getNumTargets();
}

If it's created outside of a script, all scripts that come afterwards will be able to use it (remember that the engine reads from top to bottom). Note that you can't run script events outside of scripts. Example:

vector target_position = '48 93 222';

void move_to_position()
{
	$func_mover_1.speed(30);

$func_mover_1.moveToPos(target_position);

}

Example: puzzle with max 3 attempts

Say you wanted to give a player 3 attempts to solve an optional puzzle, with an option to reset his number of attempts:

float attempts_left = 3;		//the starting number of attempts the player can make, defined as a float

void attempt_failed()			//called every time the player fails an attempt
{
	attempts_left	= attempts_left - 1; 			//reduce the number of attempts left by 1

	if (attempts_left == 0) $puzzle.setFrobable(0);		//if no more attempts, make the puzzle entity unfrobable
}

void reset_attempts()				//calling this resets the player's attempts
{
	attempts_left = 3;

	$puzzle.setFrobable(1);			//also make sure the puzzle entity is frobable
}

Using the 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 grouped 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 entry:

scriptEvent float canSee(entity ent);

    no description

    Spawnclasses responding to this event: idAI

Interpretation:

• the script event canSee() is suitable for being called on AIs.
• an entity must be entered into its input bracket. The event calls this entity "ent", but this name doesn't matter to the scripter
• 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.

It might take some experimentation to figure out which entity the script event should be called on and which entity should go into the input 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);		//if you haven't defined the "guard_sees_player" variable yet

Next / previous article

• Next article: A to Z Scripting: Setting up the .script files
• Previous article: A to Z Scripting: Anatomy of a script
• Table of contents: A to Z Scripting