HSL Input System and Keybindings

Jump to: navigation, search


See also: Keybindings

Please Note: If you are simply looking for an easy way to reassign current key bindings in the HeroCloud, the GameKeyBindings.ini is provided in the root directory. It is in the GAME package and so may be freely edited to provide game-specific overrides.

The system described herein we will collectively call the "InputSystem", which is comprised of elements of C-level engine code, HSL client-side scripts and HSL server-side scripts. In general, this system is engaged only while HeroBlade or the client are in "game" mode. This means that the input that GUI elements receive and input that [HeroBlade interprets directly in edit mode are not handled by the "InputSystem" with the only exception being HeroicMouseEvents ( left/right click while in edit mode DOES result in a call to the Input_Mouse script's HeroicMouseDown and HeroicMouseUp functions ).

Command Layers

Commands are organized into logical groups called Command Layers, which in turn are pushed onto the Command Layer Stack. An incoming command sent to each Command Layer in the stack starting at the layer last pushed onto the stack until a layer indicates that it has processed the input by returning true or all layers have been given a chance to process the command. Command Layers that are currently on the stack may be selectively activated and deactivated.


Layers are pushed onto the stack during the login process as the result of a call to the client script CharacterSystem:OnSetControlledCharacter() using the external PushCmdLayer() function. Please note, because commands are passed through the stack of command layers the order of layers may be extremely important as one layer marking the command as "handled" will result in layers deeper in the stack never getting a chance to act on the command.


After Command Layers are pushed on the Command Layer Stack they must be activated using the external ActivateCmdLayer( layerName, true ). Deactivating a Command Layer uses the same function but sends the second parameter as false.


Popping the last command layer off the stack is a simple call to the external function PopCmdLayer(). However, in most cases popping the last command layer is probably never the right answer unless you know no other layer has been pushed onto the stack. More commonly you are likely to use the ActivateCmdLayer function to deactivate a command layer that is not currently being used.


Layers are defined first in the HeroEngineKeyBindings.ini file. They can also be defined in a second game-specific file, set as a client configuration parameter. A part of that definition is the script commands sent to that layer when the buttons are pressed. To use a new Layer, it must be first defined in the game-specific keybindings file before keybindings may be saved to the layer.

As of the HeroEngine 1.7.0, the following layers are defined:

LayerName Script Description
HE_Movement _Input_Movement Handles both mouse and keyboard movement commands
HE_Camera _Input_Camera Handles both mouse and keyboard control of the camera
HE_Command _Input_Command Handles keyboard commands for game controls such as activating abilities on a hotbar or opening GUIs such as inventory
HE_Mouse _Input_Mouse Maps the mouse buttons to input commands
GUIEditor _Input_GUIEditor Handles keyboard commands for manipulating elements in the GUIEditor mode


Inputs such as a keypress or mouse-click are routed to the functions OnCmdStart(), OnCmdStop(), and for mouse movement OnMouseMove() in the script specified by the layer's definition with the cmd set to the string that has been defined for the particular keycombination for that layer. Each of those functions returns a boolean, if the return value is true no further layers will be called for the current input event. Most layers return false for most commands as handling in the camera layer should not necessarily stop handling by the command layer.


CautionSign.gif This is a Clean Engine file, any changes you make to it will be overwritten during the publish process.

This file represents the default control scheme for the client, it is always active beneath the currently loaded keybinding profile (if any) and handles any input event keybinding profile does not override. The file is located in the root directory of your asset repository (HE/).

Displayed below is the representation of two of the Command Layers in the HeroEngineKeyBindings.ini.

Please Note: The Master Control is a HeroEngine Source Tool only and not needed when developing in the HeroCloud

Implementing your game specific keybindings file is as simple as setting a client configuration value in Master Control to provide the path to your game specific keybindings.ini file. As of June 5, 2010, GameKeyBindings.ini is provided also in the root directory. It is in the GAME package and so may be freely edited to provide game-specific overrides.

// DefaultKeyBindings.ini
// format:
// [LayerName] = ClientScriptName
//   Command = [CTRL+ | ALT+ | SHIFT+]Key
//   Command = UNASSIGNED
//   Command
//  If UNASSIGNED is specified, the command will appear in the list returned
//  by GetKeyBindings(), and players can assign keys to it via SetKeyBinding().
//  If there is no equals sign, it will not appear in GetKeyBindings(), but scripts 
//  can still call GetCmdState and SetCmdState on it.
//  Combinations of modifiers such as CTRL+SHIFT are not supported.
//  Commands are strings interpreted by the script.
// List of all key names:
// MOUSE.4
// MOUSE.5
// A-Z
// 0-9        (on main keyboard area)
// NUM0-NUM9  (on the numeric keypad if numlock is engaged)
// NUM/       (on the numeric keypad)
// NUM*
// NUM-
// NUM+
// NUM.
// CLEAR      (num5 if numlock is not engaged)
// F1-F12
// `          (accent/tilde)
// -
// =
// [
// ]
// \          (backslash)
// /
// '          (singlequote)
// ;
// ,
// .
// TAB
// UP
// END
// ESC

[HE_Movement] = _Input_Movement
  LeaveGameMode = CTRL+`
  Forward = ANY+W
  Forward = ANY+UP
  AutoForward = ANY+BACKSPACE
  Walk = CTRL
  Sprint = SHIFT
  Backward = ANY+S
  Backward = ANY+DOWN
  Left = ANY+A
  Left = ANY+LEFT
  Right = ANY+D
  Right = ANY+RIGHT
  RotateLeft = ANY+Q
  RotateRight = ANY+E
  ToggleToolTips = CTRL+T
  LeftButton = ANY+MOUSE.LEFT
  RightButton = ANY+MOUSE.RIGHT
  Jump = ANY+SPACE

[HE_Camera] = _Input_Camera
  DragRotate = ANY+MOUSE.RIGHT
  DragRotateCamera = ANY+MOUSE.4
  ClearRotateCamera = ANY+MOUSE.5
  ToggleFullscreen = F12
  Click = MOUSE.LEFT
  ToggleAspectRatio = SHIFT+F12
  RotateCameraUp = ANY+R
  RotateCameraDown = ANY+F
  ZoomIn = NUM+
  ZoomOut = NUM-

[HE_Command] = _Input_Command
  PlayMode = CTRL+G
  LeaveGameMode = SHIFT+`

[HE_Mouse] = _Input_Mouse
  LeftButton = MOUSE.LEFT
  RightButton = MOUSE.RIGHT
  MiddleButton = MOUSE.MIDDLE
  DragSelectButton = CTRL+MOUSE.LEFT

[GUIEditor] = _Input_GUIEditor
  DeleteControl = DELETE
  CopyControl = CTRL+C
  CutControl = CTRL+X
  PasteControl = CTRL+V
  MoveLeftGrid = LEFT
  MoveRightGrid = RIGHT
  MoveUpGrid = UP
  MoveDownGrid = DOWN
  MoveLeft = CTRL+LEFT
  MoveRight = CTRL+RIGHT
  MoveUp = CTRL+UP
  MoveDown = CTRL+DOWN
  ResizeLeft = SHIFT+LEFT
  ResizeRight = SHIFT+RIGHT
  ResizeUp = SHIFT+UP
  SelectParent = ESC
  ResizeDown = SHIFT+DOWN

Input Scripts

Input scripts are called in turn based on the order in which their command layers were pushed onto the stack ( FIFO ). If an input script returns true to the function call, any further calls to the scripts of layers higher up in the stack will be prevented. Consequently, returning false is the standard unless you really don't want other layers to have the opportunity to execute from a particular input.

When an input is caught by the C engine, if a layer has that input it is then translated into the corresponding command and send to the input script for that layer. This means each layer is able to define a command for a particular input independant of what any other layer may have defined that input to be. For example, ANY+MOUSE.RIGHT is defined as DragRotate in the camera layer and as RightButton in the Movement layer.

There are several functions that are called by the C engine:

function description
onCmdStart Called when an input starts, such as pressing the key down.
onCmdStop Called when an input stops, such as when a key is released.
onMouseMove Called when the mouse's pointer is changing position.
onMouseWheel Called when the mouse wheel is moved.
OnMouseEnter Called when the mouse pointer enters a node which is MouseTargetable and not MouseTransparent.
OnMouseLeave Called when the mouse pointer leaves a node which is MouseTargetable and not MouseTransparent.
OnMouseClick Called when a mouse clicks on a node that is MouseTargetable and not MouseTransparent.
OnMouseDoubleClick Called when a mouse double clicks on a node that is MouseTargetable and not MouseTransparent.

Personal tools