A to Z Scripting: Utility scripts

Utility scripts

Utility scripts are scripts, but they're designed to be used in a similar way to script events. Their main purpose is to save time and space by compressing commonly used pieces of generic scripting into a single line.

The difference to script events is that they aren't called on an entity. Example using the sign() utility script:

float sign_of_variable	= sign(-3);	//determine whether the number in the input brackets is positive or negative

Existing utility scripts

Various utility scripts can be found in tdm_base01.pk4 > script/tdm_util.script. Some of the most versatile have been included here:

//These scripts perform various mathematical operations

abs(float value) 		Gets the absolute value of the number you put in (in other words, makes any negative numbers positive)
sign(float value) 		Gets the sign of the number you put in (positive returns 1, negative returns -1)

//These scripts compute times in the future, based on the game clock and sys.getTime().

RandomTime( float delay )	 	Computes a random game time that is at least "delay" seconds in the future
RandomDelay( float min, float max ) 	Computes a random game time that is between "min" and "max" seconds in the future
DelayTime( float delay )		Computes the game time that is "delay" seconds in the future 

//These scripts gradually modify the _color of an entity, which makes sense on lights or models with colorme materials. Note that the script will wait while these fades take place, so you may want to run them in a separate script that runs at the same time as the main script

fadeOutEnt( entity ent, vector color, float totalTime )			//fade from "color" to black
fadeInEnt( entity ent, vector color, float totalTime )				//fade from black to "color"
crossFadeEnt( entity ent, vector source, vector dest, float totalTime )	//fade from color "source" to color "dest"

Writing your own utility scripts

Returning a value as ouput

Remember how most scripts start with void, such as void main()? That initial void defines the data type of the script's output. If you want your script to output something useful, like many script events do, then the first step is to change this to an appropriate data type. For a mathematical script, that could be a float or a vector. For a script that should find a particular kind of entity, it could be an entity.

You can then use "return" at any point in the script to deliver a variable as the output. This also terminates the script.

Example: utility script for calculating a remainder

float remainder(float numerator, float denominator)		//this script calculates the remainder of a division, putting out the result as a float
{
	float i		= abs(numerator/denominator);		//make everything positive and find the total number of divisions
	float diff	= i - sys.floor(i);			//find the remaining partial division

	i = diff * abs(denominator);				//find remainder
	i = sys.floor(i) * sign(numerator/denominator);		//ensure this is an integer and restore the correct sign

	return i;						//return the current value of "i" as the output of this script
}

Utility script in action:

float remainder1	= remainder(22, 5);			//remainder of dividing 22 by 5; store the result (2) as a variable

Next / previous article

• Next article: A to Z Scripting: Script addons for players
• Previous article: A to Z Scripting: Scriptobjects
• Table of contents: A to Z Scripting