Friday, October 28, 2011

Key Binds and Exec Functions in UnrealScript

UnrealScript allows the definition of executable functions. These functions can be called from the in-game console and can also be bind with keys / buttons.

Example of an executable function:
exec function TestExec()
{    
 worldinfo.game.broadcast(self, "TESTING EXEC FUNCTION");
}

The exec functions can only be defined in some classes (and subclasses) such as: Controller, Pawn, Input, InventoryManager, Weapon, HUD, GameInfo, CheatManager.

There are several exec functions defined in UnrealScript that can be used for tests. For example, start a game as UTGame (UDK Menu: View -> WorldProperties -> Game Type). Open the in-game console by pressing the ~ key (or ' key). Type ThrowWeapon and press ENTER.


The key binds in UnrealScript are defined in a configuration file named DefaultInput.ini that is located in the folder "..\UDK-20??-??\UDKGame\Config\".

For example, to bind the H key with my function TestExec() use the following:

.Bindings=(Name="H",Command="TestExec")

In the file DefaultInput.ini we can see that the exec functions were organized as Game Bindable Actions (GBA). This helps when we need to assign an exec function to multiple keys.

Our example with Game Bindable Action:

.Bindings=(Name="GBA_Test",Command="TestExec")

.Bindings=(Name="H",Command="GBA_Test")

And if we want to bind the Y button of a XBox 360 controller to the same function:

.Bindings=(Name="XboxTypeS_Y",Command="GBA_Test")


To test the key bind, I created a subclass of UTPawn named TestPawn that is placeable and add a SkeletalMesh to it. I write an Exec Function in the TestPawn class and bind it to the H key. I put in the level an instance of TestPawn and started the game. Pressed the H key and then... nothing happened??? :(

I checked the Log (..\UDK-20??-??\UDKGame\Logs\Launch.log) and found the name of my function "TestExec". This means that the bind done in the DefaultInput.ini worked, the problem is that the Unreal Engine did not find my function definition in the TestPawn class.

After that I put my Exec Function inside the UTPlayerController class to test and it works.

Then, I created a subclass of UTGame named MyUTGame just to set my TestPawn class as the Default Pawn Class. I started the game as MyUTGame. Doing this, the key bind and the exec function work without problems.
class MyUTGame extends UTGame;
//UTGame is a subclass of GameInfo
defaultproperties
{
    DefaultPawnClass=class'RomeroScripts.TestPawn'
}

My conclusion is that probably the Unreal Engine looks for executable functions starting in the GameInfo class. So, the classes with Exec Functions must be being referenced directly or indirectly by a GameInfo class. The GameInfo class will be the subject of the next article.

For more information about Key Binds and Exec Functions:
http://udn.epicgames.com/Three/KeyBinds.html
http://udn.epicgames.com/Three/ExecFunctions.html