A to Z Scripting: Scripting with...

This article has useful more specific information for scripting with various elements, such as AI, sounds and time.

Time

Overall, TDM's timekeeping isn't too precise, meaning that you should try to avoid measuring time in smaller increments than 0.1s.

waitFrame() events

The game engine runs, in theory, at 60 frames (or tics) per second, independently of the visual framerate. In practice, it appears that the exact duration of sys.waitFrame() is not constant.

wait() events

When you run a wait() event, the engine performs a check every frame to see whether the total time elapsed has surpassed the time it was instructed to wait. This means that if you use wait() with very small durations, the engine will probably overshoot that duration due to a lack of precision. So i.e. a sys.wait(0.02) might only complete after 2 frames, which might be around 0.03-0.05s

Timekeeping

The most effective way to keep track of time is to read the game clock with sys.getTime() and compare with previous readings. Example:

void move_mover()					//move a mover and keep track of how much time it needed
{
	float time_starting	= sys.getTime();	//read the game clock to see what time the mover started

	$func_mover_1.speed(50);
	$func_mover_1.moveToPos('150 0 0');

	sys.waitFor($func_mover_1);
	float time_elapsed = sys.getTime() - time_starting;	//read the game clock again and subtract the starting time to get time_elapsed
}

An alternative approach, incrementing a float variable in a looping script, has been found to be relatively inaccurate, i.e. a systematic error of 10%.

AIs

AI flags

AI flags are pre-made variables contained in the "ai" scriptobject. They contain useful information about an AI, such as how alerted it is, whether it has been knocked out, whether it can see an enemy and so on. The "player" scriptobject inherits from the "ai" scriptobject, so the flags are also available for getting the status of the player, a useful example would be AI_CROUCHING.

In order to access the AI flags of an entity, you first need to define the entity as an "ai" or "player". Examples:

ai guard = $guard_warehouse_1;
player player_self = $player1;			//try to avoid using "self" (unless you're writing a scriptobject), rather use i.e. "player_self"

Then you can use the flags like this:

if ((!guard.AI_KNOCKEDOUT) && (!guard.AI_DEAD)) guard.bark("snd_conversation");	//if the ai is neither KO nor dead, make him bark a line for a (monologue) conversation
if (player_self.AI_CROUCHING)								//check if the player is crouching

Here's a selection of useful AI flags. You can find an exhaustive listing of all AI_flags in the ai scriptobject, which is defined in tdm_base01.pk4 > script/tdm_ai.script > jump to "object ai".

boolean	AI_TALK;		//AI is talking
boolean	AI_DEAD;		//AI is dead
boolean	AI_KNOCKEDOUT;		//AI is knocked out
boolean	AI_ENEMY_VISIBLE;	//enemy is visible
boolean	AI_ENEMY_IN_FOV;	//enemy is in field of view
boolean	AI_CROUCH;		//AI is inspecting a corpse, or the player is crouched
boolean	AI_RUN;			//AI is running
float	AI_AlertIndex;		//goes from 0-5, 0 means completely idle and 5 is in combat. Derived from AlertLevel.
float	AI_AlertLevel;		//goes from 0-23, increases when the AI notices suspicious things and decays with time.

Sounds

Script events for sounds are slightly atypical and counter-intuitive to use, which is why they have their own section.

Ways of starting a sound

The preferred method to start a sound on an entity is to call startSound() on it:

startSound(string sound, float channel, float netSync);

Here's the rundown of the 3 inputs:

• "sound" is not the name of a soundshader, but of a spawnarg on the entity that begins with "snd_", i.e. "snd_extinguished"
• "channel" is the channel on which the sound should be played, allowing you to play multiple sounds in different channels on the same entity. You can enter the channel either as a string or a float. See "Sound channels"
• "netsync" should always be false. It might have to do with syncing sound in multiplayer.

Example:

$torch_1.startSound("snd_extinguish", SND_CHANNEL_ANY, false);

If a soundshader is stored in a spawnarg beginning with "snd_", it will automatically get cached for that entity when it spawns. This ensures that the sound is ready to play immediately. If it's not cached, you might hear a crackle before the sound plays if the engine can't load the sound quickly enough. This is called a cache miss.

Alternatively, you can use startSoundShader() to name a soundshader directly, without using a snd_ spawnarg. In that case, the sound should be cached in advance, as below:

$torch_1.cacheSoundShader("torch_extinguished");			//makes sure this soundshader won't pop when it's played for the first time
sys.waitFrame();							//give time for the cache to occur; probably even better would be to cache the sound at map start
$torch_1.startSoundShader("torch_extinguished", SND_CHANNEL_ANY);	//"torch_extinguished" would be the name of a soundshader in the TDM assets

Sound channels

You can play multiple sounds simultaneously on the same entity by playing them on different channels. Some channels may be reserved for important game sounds (i.e. ambient music, objective completions), so you might prefer using i.e. ...ANY, ...UNUSED or ...UNUSED_2

You may reference a channel either by its name or its ID number.

As a string	As a float
SND_CHANNEL_ANY	0
SND_CHANNEL_VOICE	1
SND_CHANNEL_VOICE2	2
SND_CHANNEL_BODY	3
SND_CHANNEL_BODY2	4
SND_CHANNEL_BODY3	5
SND_CHANNEL_WEAPON	6
SND_CHANNEL_ITEM	7
SND_CHANNEL_HEART	8
SND_CHANNEL_UNUSED	9
SND_CHANNEL_DEMONIC	10
SND_CHANNEL_UNUSED_2	11
SND_CHANNEL_AMBIENT	12
SND_CHANNEL_DAMAGE	13

Sound properties

When a sound is initiated via script, its properties (looping, min/max distances etc.) will be primarily controlled through settings in the soundshader.

Stopping sound

The script event for stopping a sound on an entity is stopSound(), with the channel as input. If you want all sounds on all channels to stop, use SND_CHANNEL_ANY as input.

AI barks

The correct term for a soundshader spoken by an AI is "bark", thus the script event bark() would be used to make an AI speak via script. Compared to i.e. startSound(), this has the advantage that lipsync is enabled and that the AI wouldn't randomly say something else at the same time. It does still work on dead or unconscious AIs, so you may want to check the AI_DEAD and AI_KNOCKEDOUT flags first (see "AI flags").

Inventory items

A detailed article on creating inventory items and scripting with them can be found here: Inventory

Cutscenes

Grayman has written an excellent tutorial series on making ingame cutscenes here: Cutscenes.

GUIs

GUIs use a different, in some ways more limited scripting system. You can find a detailed explanation of them on iddev.net.

Next / previous article

• Next article: A to Z Scripting: Special methods
• Previous article: A to Z Scripting: Looping a script
• Table of contents: A to Z Scripting