engine.input Functions
Warning
The scope of applications for UnigineScript is limited to implementing materials-related logic (material expressions, scriptable materials, brush materials). Do not use UnigineScript as a language for application logic, please consider C#/C++ instead, as these APIs are the preferred ones. Availability of new Engine features in UnigineScript (beyond its scope of applications) is not guaranteed, as the current level of support assumes only fixing critical issues.
The Input class contains functions for simple manual handling of user inputs using a keyboard, a mouse or a gamepad.
This class represents a singleton of the Engine class and can be accessed via the following way:
Source code (UnigineScript)
engine.inputSee Also#
- Input sample in C# Component Samples suite
Usage Examples#
The following example shows a way to move and rotate a node by using the Input class:
Source code (UnigineScript)
int update() {
float move_speed = 1.0f;
float turn_speed = 5.0f;
if (engine.console.isActive())
return;
vec3 direction = node.getWorldDirection(AXIS_Y);
if (engine.input.isKeyPressed(INPUT_KEY_UP) || engine.input.isKeyPressed(INPUT_KEY_W))
{
node.setWorldPosition(node.getWorldPosition() + direction * move_speed * engine.game.getIFps());
}
if (engine.input.isKeyPressed(INPUT_KEY_DOWN) || engine.input.isKeyPressed(INPUT_KEY_S))
{
node.setWorldPosition(node.getWorldPosition() - direction * move_speed * engine.game.getIFps());
}
if (engine.input.isKeyPressed(INPUT_KEY_LEFT) || engine.input.isKeyPressed(INPUT_KEY_A))
{
node.rotate(0.0f, 0.0f, turn_speed * engine.game.getIFps());
}
if (engine.input.isKeyPressed(INPUT_KEY_RIGHT) || engine.input.isKeyPressed(INPUT_KEY_D))
{
node.rotate(0.0f, 0.0f, -turn_speed * engine.game.getIFps());
}
return 1;
}Input Class
Members
ivec2 engine.input.getMousePosition ( ) #
Returns a vector containing the global coordinates of the mouse cursor. In case of a mouse button event, the cursor position at the moment of the processed event is returned. In case of no such event, the mouse position at the beginning of the frame is returned. To get the cursor position during another type of event, get this event (for example getKeyEvent()) and get the cursor position stored inside it.Return value
Global coordinates of the cursor.ivec2 engine.input.getMouseDeltaPosition ( ) #
Returns a vector containing screen position change of the mouse pointer along the X and Y axes — the difference between the values in the previous and the current frames.Return value
Float mouse pointer position delta.int engine.input.getMouseWheel ( ) #
Returns the current mouse scroll value. Negative values correspond to scrolling downwards; positive values correspond to scrolling upwards; the value is zero when the mouse wheel is not scrolled.Return value
Mouse scroll value in the [-1;1] range.int engine.input.getMouseWheelHorizontal ( ) #
Returns the current horizontal mouse scroll value.Return value
Horizontal mouse scroll value in the [-1;1] range.void engine.input.setMouseGrab ( int grab ) #
Sets the value indicating if the mouse pointer is bound to the application window.Arguments
- int grab - 1 if the mouse cannot leave the application window; otherwise, 0.
int engine.input.isMouseGrab ( ) #
Returns the value indicating if the mouse pointer is bound to the application window.Return value
1 if the mouse cannot leave the application window; otherwise, 0.int engine.input.getNumGamePads ( ) #
Returns the total number of all gamepads.Return value
Number of all gamepads.InputGamePad engine.input.getGamePad ( int num ) #
Returns a gamepad of the given index.Arguments
- int num - Gamepad index.
Return value
InputGamepad object.int engine.input.getNumJoysticks ( ) #
Returns the total number of all joysticks.Return value
Number of all joysticks.InputJoystick engine.input.getJoystick ( int num ) #
Returns a joystick with the given index.Arguments
- int num - Joystick index.
Return value
InputJoystick object.int engine.input.isKeyPressed ( int key ) #
Returns a value indicating if the given key is pressed. Check this value to perform continuous actions.Source code (UnigineScript)
if (engine.input.isKeyPressed(INPUT_KEY_ENTER)) {
log.message("enter key is held down\n");
}Arguments
- int key - One of the INPUT_KEY_ codes.
Return value
1 if the key is pressed; otherwise, 0.int engine.input.isKeyDown ( int key ) #
Returns a value indicating if the given key was pressed during the current frame. Check this value to perform one-time actions on pressing a key.Source code (UnigineScript)
if (engine.input.isKeyDown(INPUT_KEY_KEY_SPACE)) {
log.message("space key was pressed\n");
}Arguments
- int key - One of the INPUT_KEY_ codes.
Return value
1 during the first frame when the key was pressed, 0 for the following ones until it is released and pressed again.int engine.input.isKeyUp ( int key ) #
Returns a value indicating if the given key was released during the current frame. Check this value to perform one-time actions on releasing a key.Source code (UnigineScript)
if (engine.input.isKeyUp(INPUT_KEY_F)) {
log.message("f key was released\n");
}Arguments
- int key - One of the INPUT_KEY_ codes.
Return value
1 during the first frame when the key was released; otherwise, 0.int engine.input.isMouseButtonPressed ( int button ) #
Returns a value indicating if the given mouse button is pressed. Check this value to perform continuous actions.Source code (UnigineScript)
if (engine.input.isMouseButtonPressed(INPUT_MOUSE_BUTTON_LEFT)) {
log.message("left mouse button is held down\n");
}Arguments
- int button - One of the INPUT_MOUSE_BUTTON_ codes.
Return value
1 if the mouse button is pressed; otherwise, 0.int engine.input.isMouseButtonDown ( int button ) #
Returns a value indicating if the given mouse button was pressed during the current frame. Check this value to perform one-time actions on pressing a mouse button.Source code (UnigineScript)
if (engine.input.isMouseButtonDown(INPUT_MOUSE_BUTTON_LEFT)) {
log.message("left mouse button was pressed\n");
}Arguments
- int button - One of the INPUT_MOUSE_BUTTON_ codes.
Return value
1 during the first frame when the mouse button was released; otherwise, 0.int engine.input.isMouseButtonUp ( int button ) #
Returns a value indicating if the given mouse button was released during the current frame. Check this value to perform one-time actions on releasing a mouse button.Source code (UnigineScript)
if (engine.input.isMouseButtonUp(INPUT_MOUSE_BUTTON_LEFT)) {
log.message("left mouse button was released\n");
}Arguments
- int button - One of the INPUT_MOUSE_BUTTON_ codes.
Return value
1 during the first frame when the mouse button was released; otherwise, 0.void engine.input.setMouseHandle ( int handle ) #
Sets the mouse behavior mode.Arguments
- int handle - Mouse behavior mode, one of the MOUSE_HANDLE_* values.
int engine.input.getMouseHandle ( ) #
Returns the mouse behavior mode.Return value
Mouse behavior mode, one of the MOUSE_HANDLE_* values.int engine.input.isTouchPressed ( int index ) #
Returns a value indicating if the touchscreen is pressed by the finger.Arguments
- int index - Touch input index.
Return value
1 if the touchscreen is pressed; otherwise, 0.int engine.input.isTouchDown ( int index ) #
Returns a value indicating if the given touch was pressed during the current frame.Arguments
- int index - Touch input index.
Return value
1 if the touchscreen is pressed during the current frame; otherwise, 0.int engine.input.isTouchUp ( int index ) #
Returns a value indicating if the given touch was released.Arguments
- int index - Touch input index.
Return value
1 during the first frame when the touch was released; otherwise, 0.ivec2 engine.input.getTouchPosition ( int index ) #
Returns a vector containing integer values of touch position.Arguments
- int index - Touch input index.
Return value
The touch position.ivec2 engine.input.getTouchDelta ( int index ) #
Returns a vector containing screen position change of the touch along the X and Y axes — the difference between the values in the previous and the current frames.Arguments
- int index - Touch input index.
Return value
The touch position delta.InputEventTouch engine.input.getTouchEvent ( int index ) #
Returns the action cast to the touch event.Arguments
- int index - Touch input index.
Return value
Touch input event.InputEventKeyboard engine.input.getKeyEvent ( int key ) #
Returns the currently processed keyboard input event.Arguments
- int key - One of the INPUT_KEY_ codes.
Return value
Keyboard input event, or null if there are no events for the specified key in the current frame.string engine.input.getKeyName ( int key ) #
Returns the specified key name.Arguments
- int key - One of the INPUT_KEY_ codes.
Return value
Key name.int engine.input.getKeyByName ( string name ) #
Returns the key by its name.Arguments
- string name - Key name.
Return value
One of the INPUT_KEY_ codes.InputEventMouseButton engine.input.getMouseButtonEvent ( int button ) #
Returns the mouse motion input event for the specified button.Arguments
- int button - One of the INPUT_MOUSE_BUTTON_ codes.
Return value
Mouse motion input event.string engine.input.getMouseButtonName ( int button ) #
Returns the mouse button name.Arguments
- int button - One of the INPUT_MOUSE_BUTTON_ codes.
Return value
Mouse button name.int engine.input.getMouseButtonByName ( string name ) #
Returns the mouse button by its name.Arguments
- string name - Mouse button name.
Return value
One of the INPUT_MOUSE_BUTTON_ codes.void engine.input.sendEvent ( InputEvent e ) #
Creates a user event and dispatches it to the Engine.Arguments
- InputEvent e - Input event.
void engine.input.setEventsFilter ( IntPtr func ) #
Sets a callback function to be executed on receiving input events. This input event filter enables you to reject certain input events for the Engine and get necessary information on all input events.Arguments
- IntPtr func - Input event callback.
int engine.input.isModifierEnabled ( int modifier ) #
Returns the value indicating if the specified modifier is enabled.Arguments
- int modifier - One of the INPUT_MODIFIER_ codes.
Return value
1 if the modifier is enabled; otherwise, 0.unsigned int engine.input.keyToUnicode ( int key ) #
Returns the specified key transformed to unicode.Arguments
- int key - One of the INPUT_KEY_ codes.
Return value
Unicode symbol.int engine.input.unicodeToKey ( unsigned int unicode ) #
Returns the specified key transformed to unicode.Arguments
- unsigned int unicode - Unicode symbol.
Return value
One of the INPUT_KEY_ codes.ivec2 engine.input.getMouseDeltaRaw ( ) #
Returns the physical change in the absolute mouse position (not the screen cursor).Return value
The change in the absolute mouse position, dots per inch.int engine.input.isEmptyClipboard ( ) #
Returns a value indicating if the clipboard is empty.Return value
1 if the clipboard is empty; otherwise, 0.void engine.input.setClipboard ( string clipboard ) #
Updates the contents of the system clipboard.Arguments
- string clipboard - Contents to set.
string engine.input.getClipboard ( ) #
Retrieves the contents of the system clipboard.Return value
Contents of the system clipboard.void engine.input.setMouseCursorHide ( int hide ) #
Sets a value indicating if the mouse cursor should be hidden. Can be used, for example, to hide mouse cursor for a certain element.Notice
This method hides the cursor only for one frame. So, you should call it each frame if a longer period is required.
Arguments
- int hide - 1 to hide the mouse cursor for a single frame, 0 - to show it.
int engine.input.isMouseCursorHide ( ) #
Returns a value indicating if the mouse cursor is hidden in the current frame.Return value
1 if mouse cursor is hidden in the current frame, 0 - to show it.void engine.input.setMouseCursorSystem ( int system ) #
Sets a value indicating if the OS mouse pointer should be displayed.Arguments
- int system - 1 to display the OS mouse pointer; otherwise, 0.
int engine.input.isMouseCursorSystem ( ) #
Returns a value indicating if the OS mouse pointer is displayed.Return value
1 if the OS mouse pointer is displayed; otherwise, 0.void engine.input.setMouseCursorNeedUpdate ( int update ) #
Sets a value indicating that some changes were made to the cursor (e.g., it was shown, hidden, changed to system, etc.) and it has to be updated. Suppose the cursor was modified, for example, by the Interface plugin. After closing the plugin's window the cursor shall not return to its previous state because SDL doesn't even know about the changes. You can use this flag to signalize, that mouse cursor must be updated.Arguments
- int update - 1 to signalize that the mouse cursor has to be updated; otherwise, 0.
int engine.input.isMouseCursorNeedUpdate ( ) #
Returns a value indicating that changes were made to the cursor (e.g., it was shown, hidden, changed to system, etc.) and it has to be updated. Suppose the cursor was modified, for example, by the Interface plugin. After closing the plugin's window the cursor shall not return to its previous state because SDL doesn't even know about the changes. You can use this flag to signalize, that mouse cursor must be updated.Return value
1 if the mouse cursor has to be updated; otherwise, 0.void engine.input.setMouseCursorSkinCustom ( Image image ) #
Sets a custom image to be used for the mouse cursor.Arguments
- Image image - Image containing pointer shapes to be set for the mouse cursor (e.g., select, move, resize, etc.).
void engine.input.setMouseCursorSkinSystem ( ) #
Sets the current OS cursor skin (pointer shapes like select, move, resize, etc.).void engine.input.setMouseCursorSkinDefault ( ) #
Sets the default Engine cursor skin (pointer shapes like select, move, resize, etc.).void engine.input.setMouseCursorCustom ( Image image, int x = 0, int y = 0 ) #
Sets a custom image for the OS mouse cursor. The image must be of the square size and RGBA8 format.Source code (UnigineScript)
engine.app.setMouseCursorCustom(new Image("textures/my_cursor.png"));
// show the OS mouse pointer
engine.input.setMouseCursorSystem(1);Arguments
- Image image - Cursor image to be set.
- int x - X coordinate of the cursor's hot spot.
- int y - Y coordinate of the cursor's hot spot.
void engine.input.clearMouseCursorCustom ( ) #
Clears the custom mouse cursor set via the setMouseCursorCustom() method.void engine.input.updateMouseCursor ( ) #
Updates the mouse cursor. This method should be called after making changes to the mouse cursor to apply them all together. After calling this method the cursor shall be updated in the next frame.string engine.input.getKeyLocalName ( int key ) #
Returns the name for the specified key taken from the currently selected keyboard layout.Notice
The returned value is affected by the modifier such as Shift.
Arguments
- int key - One of the INPUT_KEY_ codes.
Return value
Localized name for the specified key.ivec2 engine.input.getForceMousePosition ( ) #
Returns the absolute mouse position obtained from the OS.Return value
The absolute mouse position.int engine.input.isKeyText ( int key ) #
Returns a value indicating if the given key has a corresponding printable symbol (current Num Lock state is taken into account). For example, pressing 2 on the numpad with Num Lock enabled produces "2", while with disabled Num Lock the same key acts as a down arrow. Keys like Esc, PrintScreen, BackSpace do not produce any printable symbol at all.Arguments
- int key - One of the INPUT_KEY_ codes.
Return value
1 if the key value is a symbol; otherwise, 0.string engine.input.getModifierName ( int modifier ) #
Returns the name of the key modifier by its scancode.Arguments
- int modifier - Scancode of the modifier.
Return value
Key name of the modifier.int engine.input.getModifierByName ( string name ) #
Returns the scancode of the key modifier by its name.Arguments
- string name - Key name of the modifier.
Return value
Scancode of the modifier.Last update:
2023-04-13
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)