ActionMap Class Reference
[Input Management]

ActionMaps assign platform input events to console commands. More...

Inheritance diagram for ActionMap:

Public Member Functions
bool	bind (string device, string action, string command)
	Associates a function to an input event.
bool	bind (string device, string action, string flag, string deadZone, string scale, string command)
	Associates a function and input parameters to an input event.
bool	bindCmd (string device, string action, string makeCmd, string breakCmd="")
	Associates a make command and optional break command to a specified input device action.
bool	bindObj (string device, string action, string command, SimObjectID object)
	Associates a function to an input event for a specified class or object.
bool	bindObj (string device, string action, string flag, string deadZone, string scale, string command, SimObjectID object)
	Associates a function to an input event for a specified class or object.
string	getBinding (string command)
	Gets the ActionMap binding for the specified command.
string	getCommand (string device, string action)
	Gets ActionMap command for the device and action.
string	getDeadZone (string device, string action)
	Gets the Dead zone for the specified device and action.
float	getScale (string device, string action)
	Get any scaling on the specified device and action.
bool	isInverted (string device, string action)
	Determines if the specified device and action is inverted.
void	pop ()
	Pop the ActionMap off the ActionMap stack.
void	push ()
	Push the ActionMap onto the ActionMap stack.
void	save (string fileName=NULL, bool append=false)
	Saves the ActionMap to a file or dumps it to the console.
bool	unbind (string device, string action)
	Removes the binding on an input device and action.
bool	unbindObj (string device, string action, string obj)
	Remove any object-binding on an input device and action.

Detailed Description

ActionMaps assign platform input events to console commands.

Any platform input event can be bound in a single, generic way. In theory, the game doesn't need to know if the event came from the keyboard, mouse, joystick or some other input device. This allows users of the game to map keys and actions according to their own preferences. Game action maps are arranged in a stack for processing so individual parts of the game can define specific actions. For example, when the player jumps into a vehicle it could push a vehicle action map and pop the default player action map.

Creating an ActionMap

The input system allows for the creation of multiple ActionMaps, so long as they have unique names and do not already exist. It's a simple three step process.

1. Check to see if the ActionMap exists 2. Delete it if it exists 3. Instantiate the ActionMap

The following is an example of how to create a new ActionMap:

Example:

if ( isObject( moveMap ) )
   moveMap.delete();
new ActionMap(moveMap);

Binding Functions

Once you have created an ActionMap, you can start binding functionality to events. Currently, Torque 3D supports the following devices out of the box

Mouse

Keyboard

Joystick/Gamepad

Xbox 360 Controller

The two most commonly used binding methods are bind() and bindCmd(). Both are similar in that they will bind functionality to a device and event, but different in how the event is interpreted. With bind(), you specify a device, action to bind, then a function to be called when the event happens.

Example:

// Simple function that prints to console
// %val - Sent by the device letting the user know
// if an input was pressed (true) or released (false)
function testInput(%val)
{
   if(%val)
     echo("Key is down");
   else
     echo("Key was released");
}

// Bind the 'K' key to the testInput function
moveMap.bind(keyboard, "k", testInput);

bindCmd is an alternative method for binding commands. This function is similar to bind(), except two functions are set to be called when the event is processed.

One will be called when the event is activated (input down), while the other is activated when the event is broken (input release). When using bindCmd(), pass the functions as strings rather than the function names.

Example:

// Print to the console when the spacebar is pressed
function onSpaceDown()
{
   echo("Space bar down!");
}

// Print to the console when the spacebar is released
function onSpaceUp()
{
   echo("Space bar up!");
}

// Bind the commands onSpaceDown and onSpaceUp to spacebar events
moveMap.bindCmd(keyboard, "space", "onSpaceDown();", "onSpaceUp();");

Switching ActionMaps

Let's say you want to have different ActionMaps activated based on game play situations. A classic example would be first person shooter controls and racing controls in the same game. On foot, spacebar may cause your player to jump. In a vehicle, it may cause some kind of "turbo charge". You simply need to push/pop the ActionMaps appropriately:

First, create two separate ActionMaps:

Example:

// Create the two ActionMaps
if ( isObject( moveMap ) )
   moveMap.delete();
new ActionMap(moveMap);

if ( isObject( carMap ) )
   carMap.delete();
new ActionMap(carMap);

Next, create the two separate functions. Both will be bound to spacebar, but not the same ActionMap:

Example:

// Print to the console the player is jumping
function playerJump(%val)
{
   if(%val)
     echo("Player jumping!");
}

// Print to the console the vehicle is charging
function turboCharge()
{
   if(%val)
     echo("Vehicle turbo charging!");
}

You are now ready to bind functions to your ActionMaps' devices:

Example:

// Bind the spacebar to the playerJump function
// when moveMap is the active ActionMap
moveMap.bind(keyboard, "space", playerJump);

// Bind the spacebar to the turboCharge function
// when carMap is the active ActionMap
carMap.bind(keyboard, "space", turboCharge);

Finally, you can use the push() and pop() commands on each ActionMap to toggle activation. To activate an ActionMap, use push():

Example:

// Make moveMap the active action map
// You should now be able to activate playerJump with spacebar
moveMap.push();

To switch ActionMaps, first pop() the old one. Then you can push() the new one:

Example:

// Deactivate moveMap
moveMap.pop();

// Activate carMap
carMap.push();

Member Function Documentation

bool ActionMap::bind	(	string	device,
		string	action,
		string	command
	)

Associates a function to an input event.

When the input event is raised, the specified function will be called.

Parameters:

	device	The input device, such as mouse or keyboard.
	action	The input event, such as space, button0, etc.
	command	The function to bind to the action. Function must have a single boolean argument.

Returns:: True if the binding was successful, false if the device was unknown or description failed.

Example:

// Simple function that prints to console
// %val - Sent by the device letting the user know
// if an input was pressed (true) or released (false)
function testInput(%val)
{
   if(%val)
     echo("Key is down");
   else
     echo("Key was released");
}

// Bind the 'K' key to the testInput function
moveMap.bind(keyboard, k, testInput);

bool ActionMap::bind	(	string	device,
		string	action,
		string	flag,
		string	deadZone,
		string	scale,
		string	command
	)

Associates a function and input parameters to an input event.

When the input event is raised, the specified function will be called. Modifier flags may be specified to process dead zones, input inversion, and more.

Valid modifier flags:

R - Input is Ranged.
S - Input is Scaled.
I - Input is inverted.
D - Dead zone is present.
N - Input should be re-fit to a non-linear scale.

Parameters:

	device	The input device, such as mouse or keyboard.
	action	The input event, such as space, button0, etc.
	flag	Modifier flag assigned during binding, letting event know there are additional parameters to consider.
	deadZone	Restricted region in which device motion will not be acknowledged.
	scale	Modifies the deadZone region.
	command	The function bound to the action. Must take in a single argument.

Returns:: True if the binding was successful, false if the device was unknown or description failed.

Example:

// Simple function that adjusts the pitch of the camera based on the mouse's movement along the X axis.
function testPitch(%val)
{
   %pitchAdj = getMouseAdjustAmount(%val);
    $mvPitch += %pitchAdj;
}

// Bind the mouse's X axis to the testPitch function
// DI is flagged, meaning input is inverted and has a deadzone
%this.bind( mouse, "xaxis", "DI", "-0.23 0.23", testPitch );

bool ActionMap::bindCmd	(	string	device,
		string	action,
		string	makeCmd,
		string	breakCmd = `""`
	)

Associates a make command and optional break command to a specified input device action.

Must include parenthesis and semicolon in the make and break command strings.

Parameters:

	device	The device to bind to. Can be a keyboard, mouse, joystick or gamepad.
	action	The device action to bind to. The action is dependant upon the device. Specify a key for keyboards.
	makeCmd	The command to execute when the device/action is made.
	breakCmd	[optional] The command to execute when the device or action is unmade.

Returns:: True the bind was successful, false if the device was unknown or description failed.

Example:

// Print to the console when the spacebar is pressed
function onSpaceDown()
{
   echo("Space bar down!");
}

// Print to the console when the spacebar is released
function onSpaceUp()
{
   echo("Space bar up!");
}

// Bind the commands onSpaceDown() and onSpaceUp() to spacebar events

moveMap.bindCmd(keyboard, "space", "onSpaceDown();", "onSpaceUp();");

bool ActionMap::bindObj	(	string	device,
		string	action,
		string	command,
		SimObjectID	object
	)

Associates a function to an input event for a specified class or object.

You must specify a device, the action to bind, a function, and an object to be called when the event happens. The function specified must be set to receive a single boolean value passed.

Parameters:

	device	The input device, such as mouse or keyboard.
	action	The input event, such as space, button0, etc.
	command	The function bound to the action.
	object	The object or class bound to the action.

Returns:: True if the binding was successful, false if the device was unknown or description failed.

Example:

moveMap.bindObj(keyboard, "numpad1", "rangeChange", %player);

bool ActionMap::bindObj	(	string	device,
		string	action,
		string	flag,
		string	deadZone,
		string	scale,
		string	command,
		SimObjectID	object
	)

Associates a function to an input event for a specified class or object.

You must specify a device, the action to bind, a function, and an object to be called when the event happens. The function specified must be set to receive a single boolean value passed. Modifier flags may be specified to process dead zones, input inversion, and more.

Valid modifier flags:

R - Input is Ranged.
S - Input is Scaled.
I - Input is inverted.
D - Dead zone is present.
N - Input should be re-fit to a non-linear scale.

Parameters:

	device	The input device, such as mouse or keyboard.
	action	The input event, such as space, button0, etc.
	flag	Modifier flag assigned during binding, letting event know there are additional parameters to consider.
	deadZone	[Required only when flag is set] Restricted region in which device motion will not be acknowledged.
	scale	[Required only when flag is set] Modifies the deadZone region.
	command	The function bound to the action.
	object	The object or class bound to the action.

Returns:: True if the binding was successful, false if the device was unknown or description failed.

Example:

// Bind the mouse's movement along the x-axis to the testInput function of the Player class
// DSI is flagged, meaning input is inverted, has scale and has a deadzone
%this.bindObj( mouse, "xaxis", "DSI", %deadZone, %scale, "testInput", %player );

string ActionMap::getBinding ( string command )

Gets the ActionMap binding for the specified command.

Use getField() on the return value to get the device and action of the binding.

Parameters:

command

The function to search bindings for.

Returns:: The binding against the specified command. Returns an empty string("") if a binding wasn't found.

Example:

// Find what the function "jump()" is bound to in moveMap
%bind = moveMap.getBinding( "jump" );

if ( %bind !$= "" )
{
// Find out what device is used in the binding
   %device = getField( %bind, 0 );

// Find out what action (such as a key) is used in the binding
   %action = getField( %bind, 1 );
}

See also:: getField

string ActionMap::getCommand	(	string	device,
		string	action
	)

Gets ActionMap command for the device and action.

Parameters:

	device	The device that was bound. Can be a keyboard, mouse, joystick or a gamepad.
	action	The device action that was bound. The action is dependant upon the device. Specify a key for keyboards.

Returns:: The command against the specified device and action.

Example:

// Find what function is bound to a device's action
// In this example, "jump()" was assigned to the space key in another script
%command = moveMap.getCommand("keyboard", "space");

// Should print "jump" in the console
echo(%command)

string ActionMap::getDeadZone	(	string	device,
		string	action
	)

Gets the Dead zone for the specified device and action.

Parameters:

	device	The device that was bound. Can be a keyboard, mouse, joystick or a gamepad.
	action	The device action that was bound. The action is dependant upon the device. Specify a key for keyboards.

Returns:: The dead zone for the specified device and action. Returns "0 0" if there is no dead zone or an empty string("") if the mapping was not found.

Example:

%deadZone = moveMap.getDeadZone( "gamepad", "thumbrx");

float ActionMap::getScale	(	string	device,
		string	action
	)

Get any scaling on the specified device and action.

Parameters:

	device	The device that was bound. Can be keyboard, mouse, joystick or gamepad.
	action	The device action that was bound. The action is dependant upon the device. Specify a key for keyboards.

Returns:: Any scaling applied to the specified device and action.

Example:

%scale = %moveMap.getScale( "gamepad", "thumbrx");

bool ActionMap::isInverted	(	string	device,
		string	action
	)

Determines if the specified device and action is inverted.

Should only be used for scrolling devices or gamepad/joystick axes.

Parameters:

	device	The device that was bound. Can be a keyboard, mouse, joystick or a gamepad.
	action	The device action that was bound. The action is dependant upon the device. Specify a key for keyboards.

Returns:: True if the specified device and action is inverted.

Example:

%if ( moveMap.isInverted( "mouse", "xaxis"))
   echo("Mouse's xAxis is inverted");

void ActionMap::pop ( )

Pop the ActionMap off the ActionMap stack.

Deactivates an ActionMap and removes it from the stack.

Example:

// Deactivate moveMap
moveMap.pop();

See also:: ActionMap

void ActionMap::push ( )

Push the ActionMap onto the ActionMap stack.

Activates an ActionMap and placees it at the top of the ActionMap stack.

Example:

// Make moveMap the active action map
moveMap.push();

See also:: ActionMap

void ActionMap::save	(	string	fileName = `NULL`,
		bool	append = `false`
	)

Saves the ActionMap to a file or dumps it to the console.

Parameters:

	fileName	The file path to save the ActionMap to. If a filename is not specified the ActionMap will be dumped to the console.
	append	Whether to write the ActionMap at the end of the file or overwrite it.

Example:

// Write out the actionmap into the config.cs file
moveMap.save( "scripts/client/config.cs" );

bool ActionMap::unbind	(	string	device,
		string	action
	)

Removes the binding on an input device and action.

Parameters:

	device	The device to unbind from. Can be a keyboard, mouse, joystick or a gamepad.
	action	The device action to unbind from. The action is dependant upon the device. Specify a key for keyboards.

Returns:: True if the unbind was successful, false if the device was unknown or description failed.

Example:

moveMap.unbind("keyboard", "space");

bool ActionMap::unbindObj	(	string	device,
		string	action,
		string	obj
	)

Remove any object-binding on an input device and action.

Parameters:

	device	The device to bind to. Can be keyboard, mouse, joystick or gamepad.
	action	The device action to unbind from. The action is dependant upon the device. Specify a key for keyboards.
	obj	The object to perform unbind against.

Returns:: True if the unbind was successful, false if the device was unknown or description failed.

Example:

moveMap.unbindObj("keyboard", "numpad1", "rangeChange", %player);

ActionMap Class Reference [Input Management]

Public Member Functions

Detailed Description

Creating an ActionMap

Binding Functions

Switching ActionMaps

Member Function Documentation

ActionMap Class Reference
[Input Management]