UnigineScript
The Language
Core Library
Engine Library
Node-Related Classes
GUI-Related Classes
Plugins Library
High-Level Systems
Samples
Usage Examples
C++ API
API Reference
Integration Samples
Usage Examples
C++ Plugins
Migration
Migrating to UNIGINE 2.0
C++ API Migration
Migrating from UNIGINE 2.0 to UNIGINE 2.1

engine.controls Functions

This set of functions is used to handle input from the user (keyboard, mouse, joystick or gamepad) and set application controls.

Notice
Besides using these default controls, it is also possible to create custom controls (see Controls and ControlsDummy classes). By default, all created players automatically use the default engine controls.

The following functions are used to register actions (i.e. controls states) that will be executed on the provided input and bind them to specified input events. The actual meaning of all controls registered with CONTROLS_STATE_* variables (for example, CONTROLS_STATE_JUMP or CONTROLS_STATE_FIRE) is defined manually in script by the programmer who uses them.

The example below shows how to implement controls handling in your code. It toggles showing the item inventory when 'i' key is pressed on the keyboard. For that, auxiliary state CONTROLS_STATE_AUX_0 is used.

Source code (UnigineScript)
int inventory_toggled = false; // show item inventory toggle

void init_controls() { 
// Check if the key is pressed and update the state of the specified control.
// You can use both 'i' or ASCII code (105).
engine.controls.setStateKey(CONTROLS_STATE_AUX_0,'i');
}

// Implement your game logic for showing or hiding item inventory.
void update_game_logic() {	
// If the control state is positive (the key has been pressed), toggle item
// inventory on and off.
if(engine.controls.getState(CONTROLS_STATE_AUX_0)) {
inventory_toggled = !inventory_toggled;
}
}

/*
*/
int init() {
init_controls();
}

// Update controls each frame according to the user input.
int update() {
update_game_logic();
}

int engine.controls.clearState (int control)

Returns a control state and clears it to 0 (not pressed). This function allows to handle control only once even if it is kept pressed over several frames.

Arguments

Return value

1 if the control is pressed, and this function was not called previously in the current frame; otherwise, 0.

int engine.controls.getAlwaysRun ()

Returns a value indicating if the player is running by default. If the player is in this mode, the Run control will switch them to walking.

Return value

1 if the player is running by default; otherwise, 0.

variable engine.controls.getButtonPressCallback ()

Returns the name of the callback function, which is invoked when a mouse button is pressed. To set the callback, use the engine.controls.setButtonPressCallback() function.

Return value

Name of the callback function.

Examples

Source code (UnigineScript)
// A callback function that takes button as an argument.
int button_pressed_callback_func(int button) {
	log.message("Mouse button has pressed\n");
	return 0;
}

// Get the name of the callback function, which is called on pressing the mouse button.
log.message("Callback function name: %s",engine.controls.getButtonPressCallback());

variable engine.controls.getButtonReleaseCallback ()

Returns the name of the callback function, which is invoked when a mouse button is released. To set the callback, use the engine.controls.setButtonReleaseCallback() function.

Return value

Name of the callback function.

Examples

Source code (UnigineScript)
// A callback function that takes button as an argument.
int button_released_callback_func(int button) {
	log.message("Mouse button has released\n");
	return 0;
}

// Get the name of the callback function, which is called on releasing the mouse button.
log.message("Callback function name: %s",engine.controls.getButtonReleaseCallback());

variable engine.controls.getKeyPressCallback ()

Returns the name of the callback function, which is invoked when a key (standard QWERTY one: non-localized, lower-case) is pressed.

Return value

Name of the callback function.

variable engine.controls.getKeyReleaseCallback ()

Returns the name of the callback function, which is invoked when a key (standard QWERTY one: non-localized, lower-case) is released.

Return value

Name of the callback function.

float engine.controls.getMouseDX ()

Returns a screen position change of the mouse pointer along the X-axis during the last frame (i.e. the delta of mouse movement).

Return value

Change of the X-coordinate.

float engine.controls.getMouseDY ()

Returns a screen position change of the mouse pointer along the Y-axis during the last frame (i.e. the delta of mouse movement).

Return value

Change of the Y-coordinate.

int engine.controls.getMouseInverse ()

Returns a value indicating if back-and-forth movements of the mouse (by Y-axis) are inverted: when the mouse is moved upward, the camera looks downwards, and when the mouse is moved downwards, the camera looks upwards. This mode is available only to control the camera.

Return value

1 if the mouse is inverted; otherwise, 0.

float engine.controls.getMouseSensitivity ()

Returns the current mouse sensitivity used to increase or decrease the speed of mouse movement.

Return value

Mouse sensitivity.

int engine.controls.getStateButton (int state)

Returns a mouse button that switches a given state on and off.

Arguments

Return value

Button that toggles the state (one of APP_BUTTON_* variables):
  1. APP_BUTTON_LEFT = 1 << 0
  2. APP_BUTTON_MIDDLE
  3. APP_BUTTON_RIGHT
  4. APP_BUTTON_DCLICK
  5. APP_BUTTON_AUX_0
  6. APP_BUTTON_AUX_1
  7. APP_BUTTON_AUX_2
  8. APP_BUTTON_AUX_3

void engine.controls.getStateEvent (int state)

Lets the user assign a key or a mouse button to a given state.

Arguments

  • int state - State (one of CONTROLS_STATE_* variables), to which a key or a mouse button is going to be assigned.

int engine.controls.getStateKey (int state)

Returns a key that toggles a given state on and off.

Arguments

Return value

Key that switches the state. It is a standard ASCII key code or one of the APP_KEY_* variables:
  1. APP_KEY_ESC = 256
  2. APP_KEY_TAB
  3. APP_KEY_BACKSPACE
  4. APP_KEY_RETURN
  5. APP_KEY_DELETE
  6. APP_KEY_INSERT
  7. APP_KEY_HOME
  8. APP_KEY_END
  9. APP_KEY_PGUP
  10. APP_KEY_PGDOWN
  11. APP_KEY_LEFT
  12. APP_KEY_RIGHT
  13. APP_KEY_UP
  14. APP_KEY_DOWN
  15. APP_KEY_SHIFT
  16. APP_KEY_CTRL
  17. APP_KEY_ALT
  18. APP_KEY_SCROLL
  19. APP_KEY_CAPS
  20. APP_KEY_NUM
  21. APP_KEY_F1
  22. APP_KEY_F2
  23. APP_KEY_F3
  24. APP_KEY_F4
  25. APP_KEY_F5
  26. APP_KEY_F6
  27. APP_KEY_F7
  28. APP_KEY_F8
  29. APP_KEY_F9
  30. APP_KEY_F10
  31. APP_KEY_F11
  32. APP_KEY_F12

string engine.controls.getStateName (int state)

Returns the name of a given state, that was assigned to one of controls.

Arguments

Return value

State name ("key KEY_NAME" or "button BUTTON_NAME").

int engine.controls.getState (int control)

Checks the state of the given control (pressed or unpressed).

Arguments

Return value

1 if the control is pressed; otherwise, 0.

int engine.controls.isMouseEnabled ()

Returns a value indicating if the mouse is enabled.

Return value

1 if the mouse is enabled; otherwise, 0.

int engine.controls.isStateButton (int button)

Checks if a given mouse button already acts as an application control. This is useful to avoid collisions between application controls.

Arguments

Return value

1 if the button is a control; otherwise, 0.

int engine.controls.isStateEvent ()

Returns a value indicating if a key or a mouse button is successfully assigned to a control.

Return value

1 if a key or a mouse button is already assigned; otherwise, 0.

int engine.controls.isStateKey (int keycode)

Checks if a given key already acts as an application control. This is useful to avoid collisions between application controls and hot keys.

Arguments

  • int keycode - Key in one of the following formats:
    • Character format (for example, 'a')
    • Standard ASCII key code (for example, 97)
    • One of APP_KEY_* variables

Return value

1 if the key is a control; otherwise, 0.

void engine.controls.setAlwaysRun (int mode)

Sets a value indicating if the player is running by default. If the player is in this mode, the Run control will switch them to walking.

Arguments

  • int mode - Positive integer to make the player run by default; otherwise, 0.

void engine.controls.setButtonPressCallback (variable function)

Sets a callback function, which is invoked each time a mouse button is pressed. The function should have one argument of the int type; the pressed button will be passed as that argument (see APP_BUTTON_* variables).
  • The callback function should return 0 for control to be handled further (automatically update control state, etc.) In this case, the callback does not interfere with controls handling.
  • If the function returns 1, the control stops to be handled once the callback function is executed.

Arguments

  • variable function - Name of the callback function.

Examples

Source code (UnigineScript)
// Implement a callback function that takes button as an argument.
int button_pressed_callback_func(int button) {
// Your callback code
return 0;
}

// Set the callback on pressing the mouse button.
engine.controls.setButtonPressCallback("button_pressed_callback_func");

void engine.controls.setButtonReleaseCallback (variable function)

Sets a callback function, which is invoked each time a mouse button is released. The function should have one argument of the int type; the released button will be passed as that argument (see APP_BUTTON_* variables).
  • The callback function should return 0 for control to be handled further (automatically update control state, etc.) In this case, the callback does not interfere with controls handling.
  • If the function returns 1, the control stops to be handled once the callback function is executed.

Arguments

  • variable function - Name of the callback function.

Examples

Source code (UnigineScript)
// Implement a callback function that takes button as an argument.
int button_released_callback_func(int button) {
// Your callback code	
return 0;
}

// Set the callback on releasing the mouse button.
engine.controls.setButtonReleaseCallback("button_released_callback_func");

void engine.controls.setKeyPressCallback (variable function)

Sets a callback function, which is invoked each time a key (standard QWERTY one: non-localized, lower-case) is pressed. The function should have one argument of the int type; the pressed key will be passed as that argument (either a standard ASCII key code or one of APP_KEY_* variables).
  • The callback function should return 0 for control to be handled further (automatically update control state, etc.) In this case, the callback does not interfere with controls handling.
  • If the function returns 1, the control stops to be handled once the callback function is executed.
Notice
engine.controls functions only detect standard QWERTY keys (non-localized and lower-case). To detect pressing localized keys and combination of keys (for example, SHIFT + key for upper-case letters or SHIFT + number for special symbols), use engine.gui.setKeyPressCallback().
You can use both functions to detect the whole range of input keys. engine.gui.setKeyPressCallback() will be called prior to the engine.controls.setKeyPressCallback().

Arguments

  • variable function - Name of the callback function.

Examples

Source code (UnigineScript)
// Implement a callback function that takes key as an argument.
int key_pressed_callback_func(int key) {
// Your callback code	
return 0;
}

// Set the callback on pressing the key.
engine.controls.setKeyPressCallback("key_pressed_callback_func");

void engine.controls.setKeyReleaseCallback (variable function)

Sets a callback function, which is invoked each time a key is released. The function should have one argument of the int type; the released key will be passed as that argument (either a standard ASCII key code or one of APP_KEY_* variables).
  • The callback function should return 0 for control to be handled further (automatically update control state, etc.) In this case, the callback does not interfere with controls handling.
  • If the function returns 1, the control stops to be handled once the callback function is executed.

Arguments

  • variable function - Name of the callback function.

Examples

Source code (UnigineScript)
// Implement a callback function that takes key as an argument.
int key_released_callback_func(int key) {
// Your callback code
return 0;
}

// Set the callback on releasing the key.
engine.controls.setKeyReleaseCallback("key_released_callback_func");

void engine.controls.setMouseDX (float delta)

Sets a screen position change of the mouse pointer along the X-axis since the last frame (i.e. updates the delta of mouse movement).

Arguments

  • float delta - Change of the X-coordinate.

void engine.controls.setMouseDY (float delta)

Sets a screen position change of the mouse pointer along Y-axis since the last frame (i.e. updates the delta of mouse movement).

Arguments

  • float delta - Change of the Y-coordinate.

void engine.controls.setMouseEnabled (int mode)

Enables or disables the mouse input.

Arguments

  • int mode - Positive integer to enable the mouse; otherwise, 0.

void engine.controls.setMouseInverse (int mode)

Sets how back-and-forth movements of the mouse (by Y-axis) to be interpreted as inverted: when the mouse is moved upward, the camera looks downwards, and when the mouse is moved downwards, the camera looks upwards. This mode is available only to control the camera.

Arguments

  • int mode - Positive integer to inverse the mouse; otherwise, 0.

void engine.controls.setMouseSensitivity (float sensitivity)

Sets mouse sensitivity used to increase or decrease the speed of mouse movement.

Arguments

  • float sensitivity - Mouse sensitivity. Higher values increase the mouse speed; lower values decrease it.

void engine.controls.setStateButton (int state, int button)

Sets a mouse button that will toggle a given state on and off.

Arguments

void engine.controls.setStateKey (int state, int key)

Sets a key that will toggle a given state on and off.

Arguments

  • int state - State (one of CONTROLS_STATE_* variables).
  • int key - Key that will switch the state; it can be of any of the following formats:
    • Character format (for example, 'a')
    • Standard ASCII key code (for example, 97)
    • One of APP_KEY_* variables

void engine.controls.setState (int state, int value)

Toggles the state of the given control on or off.

Arguments

  • int state - State to update (one of CONTROLS_STATE_* variables).
  • int value - Positive value to "press" the corresponding control; 0 to release it.
Last update: 2017-07-03