3D Game Programming All In One (2004)

668 Appendix A ■ The Torque Game Engine Reference

AddCardProfile (vendor, renderer, safeMode, lockArray, subImage, fogTexture, noEnvColor, clipHigh, deleteContext, texCompress, interiorLock, skipFirstFog, only16, noArraysAlpha, profile)

Parameters:	vendor	Name of card vendor.
	renderer	Name of renderer.
	safeMode	true or false
	lockArray	true or false
	subImage	true or false
	fogTexture	true or false
	noEnvColor	true or false
	clipHigh	true or false
	deleteContext	true or false
	texCompress	true or false
	interiorLock	true or false
	skipFirstFog	true or false
	only16	true or false
	noArraysAlpha	true or false
	profile	Name of profile.
Return:	nothing

Description: Creates a profile of features of a video card for later reference.

Usage: AddCardProfile(%vendor, %renderer, true, true, true, true, true, false, false, true, true, false, false, false,"")

addMaterialMapping( material, sound, color)

Parameters:	material	Name string to identify the material.
	sound	Name of sound profile to attach to material.
	color	Color specification to attach to material.
Return:	nothing
Description:	Adds sound and dust color to specified material.
Usage:	addMaterialMapping("sand", "sound:0", "color:0.3 0.3 0.5 0.4 0.0" );

Team LRN

Torque Console Script Command Reference 669

AddOSCardProfile(vendor,renderer,allowOpenGL,allowD3D,preferOpenGL)

Parameters:	vendor	Name of card vendor.
	Renderer	Name of renderer.
	AllowOpenGL	true or false
	allowD3D	true or false
	preferOpenGL	true or false
Return:	nothing
Description:	Stores certain aspects of a video card for later usage.
Usage:	AddOSCardProfile(%vendor,%renderer,true,true,true);

AddTaggedString (string)

Parameters:	string	Normal string to be added.
Return:	numeric	The tag.
Description:	Adds a string to the tagged string list (NetStringTable).
Usage:	%tagname = AddTaggedString(%name);

AiConnect(id)

Parameters:	id	ID reference number (0 to 20) of the AI bot.
Return:	numeric	New object handle.
Description:	Creates a new uncontrolled AI connection. The AI is treated the same as a player.
Usage:	AiConnect(1);

alGetString(ALenum)

Parameters:	string	The enum string. Choices:
		"AL_VENDOR"
		"AL_VERSION"
		"AL_RENDERER"
		"AL_EXTENSIONS"
Return:	string
Description:	Obtains the string specified.
Usage:	%vendor =	alGetString("AL_VENDOR");

Team LRN

670 Appendix A ■ The Torque Game Engine Reference

alListener3f(ALenum, [ "x y z" ] | [ x,y,z ])

Parameters:	ALenum	The enum string. Choices:
		"AL_VELOCITY"
		"AL_POSITION"
		"AL_DIRECTION"
	"x y z"	The string contains a tuple indicating where to place the
		enumed property in 3D world space.
	x,y,z	(alternative) If "x y z" isn't used, then this is a tuple indicating
		where to place the audio object in 3D world space. Note: These
		are three numerics, not a string!
Return:	nothing
Description:	Sets the ALenum to value for the listener (the player, who "hears" a sound).
Usage:	alListener3f("AL_GAIN_LINEAR", $pref::Audio::masterVolume );

AllowConnections(switch)

Parameters:	switch	1 (or true) = enable, 0 (or false) = disable.
Return:	nothing
Description:	Enables and disables connections to the game server.
Usage:	AllowConnections(true);

alxCreateSource( { profile, [x,y,z] } | { description, filename, [x,y,z] } )

Parameters:	profile	Descriptor string.
	x,y,z	If profile is used, this is a tuple indicating where to place the
		audio object. Note: These are three numerics, not a string!
	description	(alternative) If profile isn't used, then this is an audio object
		description string.
	filename	If description is used, then this string specifies the audio file to
		use for the sound.
	x,y,z	If description is used, this is a tuple indicating where to place
		the audio object. Note: These are three numerics, not a string!
Return:	numeric	Handle to audio object.
Description:	Loads an audio source file into memory, and initializes it for use.
Usage:	$handle =alxCreateSource("Audio0","~/data/sounds/test.wav");

Team LRN

Torque Console Script Command Reference 671

alxGetChannelVolume(channel)

Parameters:	channel	Channel ID number.
Return:	numeric
Description:	Queries the volume of channel.
Usage:	%vol = alxGetChannelVolume(%channel);

alxGetListener3f(ALenum)

Parameters:	ALenum	The enum string. Choices:
		"AL_VELOCITY"
		"AL_POSITION"
		"AL_DIRECTION"
Return:	numeric
Description:	Queries the value of the ALenum.
Usage:	%direction = alxGetListener3f("AL_DIRECTION");

alxGetListenerf(ALenum)

Parameters:	ALenum	The enum string. Choices:
		"AL_GAIN"
		"AL_GAIN_LINEAR"
Return:	numeric
Description:	Queries the value of the ALenum.
Usage:	%gain = alxGetListenerf("AL_GAIN");

alxGetListeneri(ALenum)

Parameters:	ALenum	The enum string. Choices:
		"AL_CONE_INNER_ANGLE"
		"AL_CONE_OUTER_ANGLE"
		"AL_LOOPING"
		"AL_STREAMING"
		"AL_BUFFER"
Return:	numeric
Description:	Queries the value of the ALenum.
Usage:	%looping = alxGetListeneri("AL_LOOPING");

Team LRN

672 Appendix A ■ The Torque Game Engine Reference

alxGetSource3f(handle, ALenum)

Parameters:	handle	Handle to audio object.
	ALenum	The enum string. Choices:
		"AL_VELOCITY"
		"AL_POSITION"
		"AL_DIRECTION"
Return:	string	"x y z".
Description:	Obtains the value of ALenum for the specified handle.
Usage:	%pos = alxGetSource3f(%handle[%sender], "AL_POSITION");

alxGetSourcef(handle, ALenum)

Parameters:	handle	Handle to audio object.
	ALenum	The enum string. Choices:
		"AL_PITCH"
		"AL_REFERENCE_DISTANCE"
		"AL_MAX_DISTANCE"
		"AL_CONE_OUTER_GAIN"
		"AL_GAIN"
		"AL_GAIN_LINEAR"
Return:	numeric
Description:	Obtains the value of ALenum for the specified handle.
Usage:	%gain = alxGetSourcef(%handle[%sender], "AL_GAIN");

alxGetSourcei(handle, ALenum)

Parameters:	handle	Handle to audio object.
	ALenum	The enum string. Choices:
		"AL_CONE_INNER_ANGLE"
		"AL_CONE_OUTER_ANGLE"
		"AL_LOOPING"
		"AL_STREAMING"
		"AL_BUFFER"
Return:	numeric
Description:	Obtains the value of ALenum for the specified handle.
Usage:	%pitch = alxGetSourcei((%handle[%sender], "AL_PITCH");

Team LRN

Torque Console Script Command Reference 673

alxIsPlaying(handle)

Parameters:	handle	Handle to audio object.
Return:	numeric	1 = true, 0 = false.
Description:	Queries if a handle is currently playing.
Usage:	%isPlaying = alxIsPlaying(%handle);

alxListener(ALenum,value)

Parameters:	ALenum	The enum string. Choices:
		"AL_GAIN"
		"AL_GAIN_LINEAR"
	value	Numeric gain value.
Return:	nothing
Description:	Sets the ALenum to value for the Listener (the player, who "hears" a sound).
Usage:	alxListener("AL_GAIN_LINEAR", %vol );

alxPlay( [ handle ] | [ profile [, x,y,z ] ] )

Parameters:	handle	Handle to audio object.
	profile	(alternative) Descriptor string.
	x,y,z	If profile is used, this is a tuple indicating where to place the
		audio object. Note: These are three numerics, not a string! (optional)
Return:	numeric	Returns object handle if profile is used.
Description:	Begins audio playback with audio object specified by handle. Alternatively, if
	profile is used, this function creates an object, begins playback at optional x,y,z
	coordinates, and then returns a handle to the created object.
Usage:	%handle0 = alxCreateSource("Audio0", "~/data/sounds/test.wav");
	alxPlay(%handle0);
	%handle1 = alxPlay("Audio1", "100, 100, 10");

alxSetChannelVolume(channel, volume)

Parameters:	channel	Channel ID number.
	volume	Volume value.
Return:	numeric	1 = success, 0 = fail.
Description:	Sets the channel to volume.
Usage:	%result = alxSetChannelVolume(%channel, %volume);

Team LRN

674 Appendix A ■ The Torque Game Engine Reference

alxSource3f(handle,ALenum, [ "x y z" ] | [ x,y,z ] )

Parameters:	handle	Handle to audio object.
	ALenum	The enum string. Choices:
		"AL_VELOCITY"
		"AL_POSITION"
		"AL_DIRECTION"
	"x y z"	String containing a tuple indicating where to place the
		enumed property in 3D world space.
	x,y,z	(alternative) If "xyz" isn't used, then this is a tuple indicating
		where to place the audio object in 3D world space. Note: These
		are three numerics, not a string!
Return:	nothing
Description:	Sets ALenum for the specified handle to 3D.
Usage:	alxSource3f(%handle[%sender], "AL_POSITION", "100 100 20");

alxSourcef(handle, ALenum, value)

Parameters:	handle	Handle to audio object.
	ALenum	The enum string. Choices:
		"AL_PITCH"
		"AL_REFERENCE_DISTANCE"
		"AL_MAX_DISTANCE"
		"AL_CONE_OUTER_GAIN"
		"AL_GAIN"
		"AL_GAIN_LINEAR"
	value	Numeric (floating point) value to set ALenum to.
Return:	nothing
Description:	Sets ALenum for the specified handle to the floating point value.
Usage:	alxSourcef(%handle[%sender], "AL_GAIN", %gain);

Team LRN

			Torque Console Script Command Reference		675
	alxSourcei(handle, ALenum, value)
	Parameters:	handle	Handle to audio object.
		ALenum	The enum string. Choices:
			"AL_CONE_INNER_ANGLE"
			"AL_CONE_OUTER_ANGLE"
			"AL_LOOPING"
			"AL_STREAMING"
			"AL_BUFFER"
		value	Numeric value to set ALenum to.
	Return:	nothing
	Description:	Sets ALenum for the specified handle to the floating point value.
	Usage:	alxSourcei(%handle[%sender], "AL_LOOPING", true);
	alxStop(handle)
	Parameters:	handle	Handle to audio object.
	Return:	nothing
	Description:	Stops the playback from handle.
	Usage:	alxStop(%handle[%sender]);
	alxStopAll()
	Parameters:	none
	Return:	nothing
	Description:	Stops the playback on all registered channels.
	Usage:	alxStopAll();
	Backtrace()
	Parameters:	none
	Return:	nothing
	Description:	Enables echo of script call stack to console.
	Usage:	Backtrace();

Team LRN

676	Appendix A ■		The Torque Game Engine Reference
		BuildTaggedString(string, format)
		Parameters:	string	Normal string to be added.
			format	Format specifying string.
		Return:	string
		Description:	Builds and adds a tagged string using string with specified format.
		Usage:	%tagstring = BuildTaggedString(%name, %format);
		CalcExplosionCoverage(location, handle, mask)
		Parameters:	location	Where the target object is.
			handle	Target object.
			mask	Object type mask of objects that may block the explosion.
		Return:	numeric	1 = affected, 0 = unaffected.
		Description:	Determines if an object at a location was affected by an explosion. Listed object
			types will be taken into consideration in the calculation, if they would block the
			explosion force.
		Usage:	%coverage = CalcExplosionCoverage(%location, %targetObject,
			$TypeMasks::InteriorObjectType | $TypeMasks::TerrainObjectType
				| $TypeMasks::VehicleObjectType);
		Call(function [,args ...])
		Parameters:	function	String containing name of function.
			args	Zero or more arguments as needed by function.
		Return:	string	Function's return value embedded in a string.
		Description:	Executes the function with the name function with supplied arguments, args.
		Usage:	%result = Call(%func, %arg1, %arg2);
		Cancel(id)
		Parameters:	id	ID number of supposed event.
		Return:	nothing
		Description:	Cancels the event specified by id.
		Usage:	cancel($eventid);

Team LRN

Torque Console Script Command Reference 677

CancelServerQuery()

Parameters: none Return: nothing

Description: Cancels the current query and drops anything outstanding in the ping list.

Usage: CancelServerQuery();

ClearTextureHolds()

Parameters:	none
Return:	numeric	Amount of memory released.
Description:	Releases any textures not being used, and frees the memory.
Usage:	%clearedMem=ClearTextureHolds();

CollapseEscape(text)

Parameters:	text	String.
Return:	string	The resultant string.
Description:	Removes escaped characters in text. For example, \\n becomes \n.
Usage:	%coltext = CollapseEscape(%text);

CommandToClient(client, function [,arg1,...argn])

Parameters:	client	Handle of target client.
	function	Function on the server to be executed.
	arg1,...argn	Arguments for the function.
Return:	nothing
Description:	Tells client to execute the command specified by function, and passes it the
	arguments. On the client, the function is declared in the following format:
	function ClientCmdfunction(arg1,...argn) { … }
	The identifier ClientCmd is prepended to the function name.
Usage:	CommandToClient( %client, 'SyncClock', %time);

Team LRN