A to Z Scripting: Ways of calling a script

TDM has many methods for calling scripts, some overlap with others but there are always subtle differences. Often you can combine systems such as the objective system with scripting in order to get results that wouldn't easily be possible with either system alone.

Some of the methods allow you to pass on to the script which entities were involved in calling the script as input variables. This allows you to write a single script which chooses to do different things depending on who activated it, i.e. you could have a portal chamber where each portal teleports the player to a different destination even though they all call the same script. You could set custom spawnargs on the entities and use them in the scripts.

From other scripts

To call a script from another script, simply write the name of the script followed by input brackets. The script will wait for the called script to finish.

void script2()
{
	script1();		//call script1, wait for script1 to finish
}

Alternatively, you can write "thread" in front. Both scripts will run simultaneously, because each one runs in its own thread.

void script2()
{
	thread script1();	//call script1, don't wait
}

You can only call scripts that the engine already knows about, so the called script (script1) needs to be higher up than the calling script (script2). If you're using general .script files (A to Z Scripting: Setting up the .script files), the same applies to the order in which you #include your .script files.

The main advantage of calling one script from another is that you can give as much input as you like - if the called script is designed to use input (see A to Z Scripting: Scripts that use input variables for more). Other methods can usually only provide 1 or 2 pieces of input: the entity that called the script (i.e. a trigger brush) and the entity that triggered the calling entity (i.e. a player or AI stepping into the trigger brush).

target_callscriptfunction

You can create an entity in DR called target_callscriptfunction and give it the spawnarg "call" with the name of the script without brackets, i.e. "call" "script1". Whenever this entity is triggered by something, i.e. a button, the script will be called.

These entities are among the most versatile ways to call a script because, with the spawnarg "foreach" "1", they can pass on 3 entities to the script:

one target of the callscriptfunction entity. The script will get repeated on each target, one by one (that's where "foreach" comes from)
the entity that triggered the callscriptfunction entity (aka the activator)(i.e. a button)
the name of the callscriptfunction entity itself

Basic example: simply calling a script with no input

void script1()
{
 	sys.println("script1 has been called.");
}

//spawnarg on the callscriptfunction entity:
"call" "script1"

Advanced example: teleportation script to teleport targeted entities in 2 directions

Here's a more complex example of a teleportation script that uses all 3 entities that a callscriptfunction can pass to a script:

void teleport_targets_away(entity ent_target, entity ent_button, entity ent_callscriptfunction)
{
	sys.println("the first entity (the target) is " + ent_target.getName());
	sys.println("the second entity (the button) is " + ent_button.getName());
	sys.println("the third entity (the callscriptfunction) is " + ent_callscriptfunction.getName());
 
	float teleportation_direction 	= ent_button.getFloatKey("direction");			//find the teleportation direction, stored on the button
	vector teleportation_vector	= ent_callscriptfunction.getVectorKey("vector");	//find the teleportation vector, stored on the callscriptfunction entity
	if (teleportation_direction == -1) teleportation_vector = -teleportation_vector;	//invert the teleportation vector if the direction is backwards

	ent_target.setOrigin(ent_target.getOrigin() + teleportation_vector);			//teleport the target
}

The setup in the map would be 2 buttons (1 per direction) targeting a callscriptfunction entity (carrying the teleportation vector as a spawnarg) which targets the entities you want to get teleported. The spawnargs are as follows:

callscriptfunction entity
- spawnarg: "foreach" "1" (so it repeats for every target and passes on its name and the button that triggered it)
- spawnarg: "call" "teleport_targets_away"
- custom spawnarg: "vector", with whatever teleportation vector you want i.e. "450 0 0"
2 buttons targeting the callscriptfunction entity
- one button with custom spawnarg: "direction" "1"
- the other with custom spawnarg: "direction" "-1"

The setup can be cloned as often as you want, just change the "vector" spawnarg and optionally the targets of the callscriptfunction entity each time.

Trigger brushes

Trigger brushes are a simple way to call scripts, activated when the player or an AI enters the volume of the brush. For AIs to work you need to set "anyTouch" "1" on the brush. The brush needs a spawnarg "call" with the name of the script without brackets, i.e. "call" "script1". They also trigger all their targets. See Triggers for details on the creation of trigger brushes and the various types.

Most trigger brushes are quite basic, so they can't pass the name of the entity that stepped into them or their own name to the script. The best you can do is target a callscriptfunction entity (see above) instead of calling the script directly on the brush: this way, the callscriptfunction will tell the script which brush was activated.

A more advanced type of trigger brush is trigger_touch, which detects all AIs/players/moveables in its volume and calls its script on each of them. More on their use in A to Z Scripting: Special methods.

Potential pitfalls with trigger brushes

AIs will stop activating trigger_multiple brushes if they become stationary.

Path nodes

Many Path Nodes trigger all of their targets whenever an AI reaches them. They can target a target_callscriptfunction entity in order to call a script.

Stim/Response

The Stim/Response system is very versatile, in particular when augmented with scripting.

Responses, i.e. to frobbing

In most cases, you'll likely be interested in only the "Response" tab of the S/R editor interface. This allows you to make an entity respond to certain stimuli, such as a frob, a trigger or water by executing various effects, such as running a script (no input possible). Many other effects are available from the dropdown list.

One common use is to make an entity frobable and give it a "Response" to frobbing with an effect to run a script. To do so, set the spawnarg "frobable" "1" on the entity to make it frobable. Then open the S/R editor, go to the Response tab, in the left half of the window add a "Frob" entry, in the right half of the window right-click and add an effect to "Run script", naming the script you want to run.

To make this single-use you could add another effect to either:

disable frobability of this entity, specifying _SELF as the entity
or deactivate the response to frobbing on _SELF. The ID of the frob stim is 0.

Stim and Response

Working with both the "stim" and "response" tabs of the editor lets you make scripts and other effects happen when two entities come near each other. A common example is a water arrow carrying a water stim being shot at a flame carrying a response to water ("extinguish").

Enabling a "stim" on an entity causes that entity to emit the stim to its surroundings. The settings allow you to finetune this, i.e. how often the stim gets emitted, the radius etc.

Meanwhile, using the "response" tab on another entity allows you to define what effects happen when this entity is reached by a stim of that type.

Creating a custom stim type is recommended, unless you explicitly want to do something with an existing stim like water or fire.

Action scripts

Entities can be given spawnargs that make them run scripts when certain actions are performed on them, such as frobbing or using. The value of the spawnarg is the name of the script. Example: "frob_action_script" "script1".

Like with trigger brushes (see earlier), these entities pass their own name to the script function. This allows you to reuse the same spawnarg & script on many entities.

frob_action_script	Calls the specified script when the entity is frobbed by the player.
use_action_script	Calls the specified script when the player uses an inventory item on the entity (i.e. uses a key on a door). The inventory item must be named in a "used_by" spawnarg on the entity. More info here: Tool, Key, custom used by inventory actions
equip_action_script	Calls the specified script when the player is holding the entity and uses it (i.e. eating a held apple by pressing enter).

Action scripts are able to tell which entity was frobbed/used/equipped.

Example: remove the entity when the player frobs it

void destroy_frobbed(entity ent_frobbed)
{
	ent_frobbed.remove();
}

Spawnarg on each entity that should be destroyable:
"frob_action_script" "destroy_frobbed"

Signals

Signals are events which can be setup to call a script. Examples of events are the entity being triggered, touched, removed or damaged (but not: frobbing). Some signals only work for movers i.e. when a mover is blocked or a door is closed/opened. See the Signals wiki article for a full list of available signals.

Entities using the signal system can pass on their own name to the script.

To use the signal system, you need to use a script event to instruct the entity to respond to a certain signal by running a certain script. Example:

sys.onSignal(SIG_TRIGGER, $func_static_1, "script1");

You may later want to disable this again. In that case:

sys.clearSignalThread(SIG_TRIGGER, $func_static_1);

Note that the signal system is old, so it doesn't support "frobbing", which is a TDM invention. Its SIG_USE doesn't appear to be useable in TDM either. Furthermore, it doesn't seem to pass which entity

SIG_TOUCH call its script whenever the player (or something else?) stands very close to the entity, and SIG_BLOCKED for as long as a func_mover is blocked. Note that the scripts get called several times per second, so you might want to clear the signal the first time the script runs and maybe reapply the signal after a certain delay.

Objective system

The Objectives Editor can be seen as a visual scripting editor. Not unsurprisingly it synergises well with scripting.

The main way to use the objective system for scripting is by specifying completion scripts and failure scripts for when an objective is completed or failed. Note that if the objective is reversible, it might call the scripts multiple times.

The objectives system allows you to do some things much more easily than with regular scripting, such as calling a script when reaching a certain page in a book (i.e. playing an ominous sound). Many maps use a mix of hidden objectives and scripts in order to achieve interesting scripted effects.

Location system

The location system (wiki page: Location Settings allows you to call scripts whenever the player enters or leaves specific locations.

It works by setting spawnargs on the info_location entity, with the value being the script's name:

"call_on_entry"
"call_on_exit"
"call_once_on_entry"
"call_once_on_exit"

On the scripting side of things, your script must always contain one entity variable in the input brackets, which will receive the name of the info_location entity involved.

void enter_location_streets(entity ent_location)

Basic example: start a conversation when the player enters a specific location

void start_conversation(entity ent_location)			//ent_location must be defined even if it's not used in the script
{
	sys.trigger($start_conversation_1);			//trigger an entity that starts the conversation
}

//conversation on the info_location entity
"call_once_on_entry" "start_conversation"

Intermediate example: play a sound once when the player finds one of several ways into the mansion

Say you wanted a special sound to play when the player finds his way into the mansion. You'd probably have several different entrances, each with their own location. You'd use "call_once_on_entry" on each location to call a script triggering the sound.

Since there are multiple locations and you only want the sound to play once, you also need to create a variable to store whether the sound has already played to stop further triggers of the sound.

boolean sound_has_played = false;			//stores whether the sound has played; create here as a global variable so it doesn't get recreated every time the script runs

void found_way_in(entity ent_location)
{
	if(!sound_has_played)
	{
		sys.trigger($speaker_found_way_in);		//trigger a speaker carrying the sound and "s_waitfortrigger" "1"
		sound_has_played = true;			//if other locations call this script, tell them the sound has already played
	}
}

//Spawnarg on all info_location entities that cover the entryways to the mansion
"call_once_on_entry" "found_way_in"

Advanced example: toggling fog particles depending on whether the player is inside or outside

Particles have a tendency of leaking through walls. If you have a map with lots of particle fog, you might want to manually switch them off whenever the player is inside. Preferrably the switch should happen somewhere where the player can't see the fog being toggled off.

Unlike lights with On() and Off(), there's no script event that specifically switches the func_emitters on or off (to my knowledge), you can only toggle them with triggering. So the script should create a new variable to store what state the emitters are in.

This script won't trigger all func_emitters individually, but rather a trigger_relay entity that in turn targets all the func_emitters. This saves a lot of lines.

This example relies heavily on conditionals to check which location the player is in and whether the fog needs to be toggled, see A to Z Scripting: Conditionals for more information.

boolean fog_is_on = true;		//fog starts on; create here as a global variable so it doesn't get recreated every time toggle_fog() is called

void toggle_fog(entity ent_location)
{
	//if fog is on and player goes inside, toggle off the fog and update fog_is_on to false
	if ( (fog_is_on) && (ent_location == ( $location_manor_entry1 || $location_manor_entry2 || $location_manor_entry3 ) ) )
	{
		sys.trigger($relay_fogs);	//trigger_relay targeting all fog func_emitters
		fog_is_on = false;
	}

	//if fog is off and player goes outside, toggle on the fog and update fog_is_on to true
	else if ( (!fog_is_on) && (ent_location == ( $location_manor_garden1 || $location_manor_garden2 || $location_manor_garden3 ) ) )
	{
		sys.trigger($relay_fogs);
		fog_is_on = true;
	}
}

//Spawnargs on the info_location entities (i.e. location_manor_entry1, location_manor_garden2)
"call_on_entry" "toggle_fog"

I've chosen not to use call_on_exit because that would call the script also if the player leaves the entrance locations to go deeper into the mansion. There's no need for that.

Conversation system

There's no direct way to call a script from a conversation, but you can tell one of the actors to activate a callscriptfunction entity.

From the console

This is only for testing purposes because you will no longer be able to save the game after calling a script from the console. The command is the same as when calling a script from another script, i.e.

name_of_script();
thread name_of_script();

Next / previous article

Next article: A to Z Scripting: Getting map information
Previous article: A to Z Scripting: Setting up the .script files
Table of contents: A to Z Scripting