A to Z Scripting: Utility scripts

Utility scripts

Utility scripts are scripts that are 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

You may want to use "thread" when calling such a script, so that the main script doesn't wait for the called script to finish.

thread fadeOutEnt($lantern_1, $lantern_1.getColor(), 2);

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.

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 (absolute value)
{
	float i;
	do
	{
		i++;					//increment one at a time to find out how many full divisions can take place
	} while (numerator>denominator*i);

	i--;						//the last division is not whole, go back 1
	float remainder = numerator -denominator*i;	//calculate remainder

	return remainder;				//return remainder as output
}

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: Scriptobjects
• Previous article: A to Z Scripting: Special methods
• Table of contents: A to Z Scripting