Sunday, December 18, 2011

PlayerInput Class (UnrealScript)

The PlayerInput class was created to help manage the player input. This class is an inner class of PlayerController class. This means that an object of PlayerInput class can not exist without an object of PlayerController class.

The PlayerInput class is declared this way:
class PlayerInput extends Input within PlayerController

An inner class has direct access to variables and functions of the outer class. But if in the inner class there are variables / functions with the same name, you must use the keyword "Outer" to reference the outer class. It is always recommended to use the keyword "Outer" to avoid confusion in the code. As an example, the PlayerController class has a variable named "bDemoOwner". To access it in the PlayerInput class, use:
Outer.bDemoOwner

The instance of the PlayerInput class is created in the function "InitInputSystem()" of PlayerController class as follows:
PlayerInput = new(Self) InputClass;

The "InputClass" is defined in the PlayerController's DefaultProperties and "Self" is the reference of PlayerController class that will be stored in the Outer object of PlayerInput class.

-----

As seen in the article on Key Binds and Exec Functions, the configuration file "DefaultInput.ini" is used to define the commands that can be executed by the player.

In the PlayerInput class are defined variables that will store some information related to Axes. These variables have a modifier called input making them accessible to the Unreal input system.

Below are some examples of variables in the PlayerInput class:
var input    float    aBaseX;
var input    float    aBaseY;
var input    float    aBaseZ;
var input    float    aMouseX;
var input    float    aMouseY;
var input    float    aForward;
var input    float    aTurn;
var input    float    aStrafe;
var input    float    aUp;
var input    float    aLookUp;

var input    float    aRightAnalogTrigger;
var input    float    aLeftAnalogTrigger;

Example of a binding to one of these variables:
.Bindings=(Name="GBA_MoveForward",Command="Axis aBaseY Speed=1.0")

The action GBA_MoveForward assign the position of the axis of the input device directly to the variable aBaseY. The "Speed" attribute is used to multiplier the value of the axis.

-----

When a function is bind to a key/button, it will only be called once when the key is pressed. The function will only be called again when you release and press the key/button. This way we can not implement actions that are performed while the key is being pressed.

To solve this problem we can use an exec function that receives a boolean value as parameter. When the key is pressed the function is called with the value "true" and when the key is released (Onrelease) the function is called with the value "false".

As an example, in the Unreal Tournament the Score Table is displayed while the F1 key is being pressed. When you release the F1 key the Score Table is no longer displayed.

The code below shows the binding and the function that stores the boolean value.
//In DefaultInput.ini:

.Bindings=(Name="GBA_ShowScores",Command="SetShowScores true | Onrelease SetShowScores false")


//In HUD class (Engine package):

/** sets bShowScores to a specific value (not toggle) */
exec function SetShowScores(bool bNewValue)
{ 
    bShowScores = bNewValue; 
}