Appendix A: The Torque Game Engine Reference

Torque Console Script Command Reference

activateDirectInput()
Parameters:	none
Return:	nothing
Description:	Activates direct input device polling.
Usage:	activateDirectInput();

activateKeyboard()
Parameters:	none
Return:	numeric	1 = success, 0 = fail.
Description:	Enables DirectInput polling of the keyboard.
Usage:	%result = activateKeyboard();

activatePackage(name)
Parameters:	name	String containing the name of the package.
Return:	nothing
Description:	Tells Torque to start using the package specified by name.
Usage:	activatePackage(Show);

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");

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");

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");

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");

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");

alxIsPlaying(handle)
Parameters:	handle	Handle to audio object.
Return:	numeric	1 = true, 0 = false.
Description:	Queries if a handle is currently playing.
Usage:	%is Playing = 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);

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);

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();

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);

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);

CommandToServer(function [,arg1,…argn])
Parameters:	function	Function on the server to be executed.
	arg1,…argn	Arguments for the function.
Return:	nothing
Description:	Tells the server to execute the command specified by function, and passes it the arguments. On the server, the function is declared in the following format: function ServerCmdfunction(%client, arg1,…argn) { … } The identifier ServerCmd is prepended to the function name. The first parameter is always the handle of the client that sent the command, and the actual command arguments follow.
Usage:	CommandToServer('ToggleCamera');

Compile(fileName)
Parameters:	filename	String containing file name.
Return:	numeric	1 = success, 0 = fail.
Description:	Compiles the source script file filename.
Usage:	%result = Compile("/common/default.cs");

ContainerBoxEmpty(mask, loc, rad [,yrad, zrad])
Parameters:	mask	Object type mask.
	loc	Coordinate tuple.
	rad	Radius distance (or X-axis distance).
	yrad	Optional distance in Y-axis.
	zrad	Optional distance in Z-axis.
Return:	numeric
Description:	Returns true if any objects of given types exist in a sphere of the specified extent rad and false otherwise. If yrad is specified, then rad is the X-axis extent, and yrad is the Y-axis extent. If zrad is specified, it becomes the Z-axis extent.
Usage:	%isAny = ContainerBoxEmpty(ItemObjectType,"10.0 10.0 100.0", 100);

ContainerFindFirst(type, point, x, y, z)
Parameters:	type	The type mask of objects to find.
	point	Location of container.
	x,y,z	Numeric bounds of container specified. Not a string.
Return:	numeric	Handle of object found
Description:	Finds objects of type within the box specified with x,y,z at the given point. Returns the handle of the first object found.
Usage:	%objectHandle = ContainerFindFirst(type, point, x, y, z);

ContainerFindNext()
Parameters:	none
Return:	numeric	Handle of object found.
Description:	Find the next object in the container specified by immediately previous call to containerFindFirst, and get its handle.
Usage:	%objectHandle = ContainerFindNext();

ContainerRayCast (start, end, mask, [exclude])
Parameters:	start	Starting coordinate tuple.
	end	Ending coordinate tuple.
	mask	Object type mask.
	exclude	List of handles.
Return:	string	Hit list.
Description:	Finds a list of objects of type mask between the two cords supplied. A list of object handles can be included in the exempt parameter that will not be returned in the hit list.
Usage:	%tgt = ContainerRayCast (%cameraPoint, %rangeEnd, ItemObjectType);

ContainerSearchCurrDist()
Parameters:	none
Return:	numeric
Description:	Gets the current container search distance.
Usage:	%dist = ContainerSearchCurrDist();

ContainerSearchCurrRadiusDist()
Parameters:	none
Return:	numeric
Description:	Gets the current container search radius distance.
Usage:	%rad = ContainerSearchCurrRadiusDist();

ContainerSearchNext()
Parameters:	none
Return:	numeric
Description:	Gets the next object in a container search.
Usage:	%nc = ContainerSearchNext();

CreateCanvas(title)
Parameters:	title	String containing title of the window.
Return:	numeric	1 = success, 0 = fail.
Description:	Creates a graphics canvas in a window.
Usage:	%result = CreateCanvas("My Game");

DbgSetParameters (port, pw)
Parameters:	port	Connection port.
	pw	Password.
Return:	nothing
Description:	Initializes telnet debug connection request parameters.
Usage:	DbgSetParameters(1130, "games");

DeactivateDirectInput()
Parameters:	none
Return:	nothing
Description:	Disables DirectInput device polling (mouse, keyboard, joystick).
Usage:	DeactivateDirectInput();

DeactivateKeyboard()
Parameters:	none
Return:	nothing
Description:	Disables DirectInput polling of the keyboard.
Usage:	DeactivateKeyboard();

DeactivatePackage(name)
Parameters:	name	String containing the name of the package.
Return:	nothing
Description:	Tells Torque to stop using the package specified by name.
Usage:	DeactivatePackage(Show);

Debug()
Parameters:	none
Return:	nothing
Description:	Enables debug mode.
Usage:	Debug();

Debug_debugbreak()
Parameters:	none
Return:	nothing
Description:	Windows: Displays a crash dialog box.
	Linux: Causes a segfault.
Usage:	Debug_debugbreak();

Debug_testx86unixmutex()
Parameters:	none
Return:	nothing
Description:	Linux only:Check if OS can create a mutex.
Usage:	Debug_testx86unixmutex();

DecreaseFSAA()
Parameters:	none
Return:	nothing
Description:	Invokes DecreaseNPatch.
Usage:	DecreaseFSAA ()

DecreaseNPatch()
Parameters:	none
Return:	nothing
Description:	Decrements Npatch level by 1.
Usage:	DecreaseNPatch():

DeleteDataBlocks()
Parameters:	none
Return:	nothing
Description:	Unloads and removes all registered datablocks from the game.
Usage:	DeleteDataBlocks();

DeleteVariables(wildcard)
Parameters:	wildcard	Match string to specify variables.
Return:	nothing
Description:	Deletes global variables specified by wildcard. The wildcard string supports "*" to match any number of any characters and "?" to match any single character.
Usage:	DeleteVariables("*");

Detag(tstring)
Parameters:	tstring	Tagged string.
Return:	string	String value for the tagged string.
Description:	Detags a tagged string.
Usage:	%name = Detag(%test.name);

DisableMouse()
Parameters:	none
Return:	nothing
Description:	Disables DirectInput polling of the mouse device.
Usage:	DisableMouse();

DnetSetLogging(switch)
Parameters:	switch	1 (or true) = enable, 0 (or false) = disable.
Return:	nothing
Description:	Enables network packet logging to the console.
Usage:	DnetSetLogging(1);

DumpConsoleClasses()
Parameters:	none
Return:	nothing
Description:	Dumps all registered console classes to the console.
Usage:	DumpConsoleClasses();

DumpMemSnapshot(filename)
Parameters:	filename	String containing file name.
Return:	nothing
Description:	Dumps memory statistics to the file.
Usage:	DumpMemSnapshot("dump.txt");

DumpNetStringTable()
Parameters:	none
Return:	nothing
Description:	Dumps the NetStringTable stats to the console.
Usage:	DumpNetStringTable();

DumpResourceStats();
Parameters:	none
Return:	nothing
Description:	Dumps texture information to the console in the following format: path, resource, lockCount.
Usage:	DumpResourceStats();

DumpTextureStats()
Parameters:	none
Return:	nothing
Description:	Dumps texture information to the console in the following format: type, refCount, holding (yes or no), textureSpace, texFileName.
Usage:	DumpTextureStats();

Echo(text)
Parameters:	text	String.
Return:	nothing
Description:	Prints text to the console with standard font. Text can be formatted according to the string rules.
Usage:	Echo( "Hello World");

EchoInputState()
Parameters:	none
Return:	nothing
Description:	Displays the current state of DirectInput (mouse, keyboard, and joystick).
Usage:	EchoInputState();

EnableMouse()
Parameters:	none
Return:	numeric	1 = success, 0 = fail.
Description:	Enables DirectInput polling of the mouse device.
Usage:	%result = EnableMouse();

EnableWinConsole(switch)
Parameters:	switch	1 enables, 0 disables.
Return:	nothing
Description:	Displays the console window.
Usage:	EnableWinConsole(true);

Error(text)
Parameters:	text	String.
Return:	nothing
Description:	Prints text to the console with red font. Text can be formatted according to the string rules.
Usage:	Error("I'm sorry, Dave, I'm afraid I can't do that.");

Exec(fileName [, nocalls ])
Parameters:	filename	String containing file name.
	nocalls	When set to true, prevents functions from being called.
Return:	string
Description:	Compiles, executes functions, assigns variables, and loads packages and data blocks within the file filename. If nocalls is set to true, functions are not executed, but the other operations still take place.
Usage:	%result = Exec("/common/default.cs");