Package openmw.input
openmw.input
can be used only in menu scripts and scripts attached to a player.
Most mods should prefer to use the actions/triggers API over the direct input device methods.
Actions have one value on each frame (resolved just before the onFrame
engine handler),
while Triggers don't have a value, but can occur multiple times on each frame.
Prefer to use built-in methods of binding actions, such as the inputBinding setting renderer
Usage:
local input = require('openmw.input')
-- Example of Action usage
input.registerAction {
key = 'MyAction',
type = input.ACTION_TYPE.Boolean,
l10n = 'MyLocalizationContext',
name = 'MyAction_name',
description = 'MyAction_full_description',
defaultValue = false,
}
return {
onFrame = function()
local myAction = input.getBooleanActionValue('MyAction')
if (myAction) then print('My action is active!') end
end,
}
-- Example of Trigger usage
input.registerTrigger {
key = 'MyTrigger',
l10n = 'MyLocalizationContext',
name = 'MyTrigger_name',
description = 'MyTrigger_full_description',
}
input.registerTriggerHandler('MyTrigger', async:callback(function() print('MyTrigger') end))
Type input
input.ACTION |
(DEPRECATED, use getBooleanActionValue) Values that can be used with isActionPressed. |
input.ACTION_TYPE |
Values that can be used in registerAction |
input.CONTROLLER_AXIS |
Values that can be used with getAxisValue. |
input.CONTROLLER_BUTTON |
Values that can be passed to onControllerButtonPress/onControllerButtonRelease engine handlers. |
input.CONTROL_SWITCH |
[Deprecated, moved to types.Player] Values that can be used with getControlSwitch/setControlSwitch. |
input.KEY |
Key codes. |
input.actions |
Map of all currently registered actions |
input.activateTrigger(key) |
Activates the trigger with the given key |
input.bindAction(key, callback, dependencies) |
Provides a function computing the value of given input action. |
input.getAxisValue(axisId) |
Get value of an axis of a game controller. |
input.getBooleanActionValue(key) |
Returns the value of a Boolean action |
input.getControlSwitch(key) |
[Deprecated, moved to types.Player] Get state of a control switch. |
input.getKeyName(code) |
Returns a human readable name for the given key code |
input.getMouseMoveX() |
Horizontal mouse movement during the last frame. |
input.getMouseMoveY() |
Vertical mouse movement during the last frame. |
input.getNumberActionValue(key) |
Returns the value of a Number action |
input.getRangeActionValue(key) |
Returns the value of a Range action |
input.isActionPressed(actionId) |
(DEPRECATED, use getBooleanActionValue) Input bindings can be changed ingame using Options/Controls menu. |
input.isAltPressed() |
Is |
input.isControllerButtonPressed(buttonId) |
Is a controller button currently pressed. |
input.isCtrlPressed() |
Is |
input.isIdle() |
Is player idle. |
input.isKeyPressed(keyCode) |
Is a keyboard button currently pressed. |
input.isMouseButtonPressed(buttonId) |
Is a mouse button currently pressed. |
input.isShiftPressed() |
Is |
input.isSuperPressed() |
Is |
input.registerAction(info) |
Registers a new input action. |
input.registerActionHandler(key, callback) |
Registers a function to be called whenever the action's value changes |
input.registerTrigger(info) |
Registers a new input trigger. |
input.registerTriggerHandler(key, callback) |
Registers a function to be called whenever the trigger activates |
input.setControlSwitch(key, value) |
[Deprecated, moved to types.Player] Set state of a control switch. |
input.triggers |
Map of all currently registered triggers |
Type ACTION
Type ACTION_TYPE
ACTION_TYPE.Boolean |
Input action with value of true or false |
ACTION_TYPE.Number |
Input action with a numeric value |
ACTION_TYPE.Range |
Input action with a numeric value between 0 and 1 (inclusive) |
Type ActionInfo
ActionInfo.defaultValue |
initial value of the action |
ActionInfo.description |
Localization key of the action's description |
ActionInfo.key | |
ActionInfo.l10n |
Localization context containing the name and description keys |
ActionInfo.name |
Localization key of the action's name |
ActionInfo.type |
Type CONTROLLER_AXIS
CONTROLLER_AXIS.LeftX |
Left stick horizontal axis (from -1 to 1) |
CONTROLLER_AXIS.LeftY |
Left stick vertical axis (from -1 to 1) |
CONTROLLER_AXIS.LookLeftRight |
(DEPRECATED, use the LookLeftRight action) View direction horizontal axis (RightX by default, can be mapped to another axis in Options/Controls menu) |
CONTROLLER_AXIS.LookUpDown |
(DEPRECATED, use the LookUpDown action) View direction vertical axis (RightY by default, can be mapped to another axis in Options/Controls menu) |
CONTROLLER_AXIS.MoveForwardBackward |
(DEPRECATED, use the MoveForwardBackward action) Movement forward/backward (LeftY by default, can be mapped to another axis in Options/Controls menu) |
CONTROLLER_AXIS.MoveLeftRight |
(DEPRECATED, use the MoveLeftRight action) Side movement (LeftX by default, can be mapped to another axis in Options/Controls menu) |
CONTROLLER_AXIS.RightX |
Right stick horizontal axis (from -1 to 1) |
CONTROLLER_AXIS.RightY |
Right stick vertical axis (from -1 to 1) |
CONTROLLER_AXIS.TriggerLeft |
Left trigger (from 0 to 1) |
CONTROLLER_AXIS.TriggerRight |
Right trigger (from 0 to 1) |
Type CONTROLLER_BUTTON
Type CONTROL_SWITCH
CONTROL_SWITCH.Controls |
Ability to move |
CONTROL_SWITCH.Fighting |
Ability to attack |
CONTROL_SWITCH.Jumping |
Ability to jump |
CONTROL_SWITCH.Looking |
Ability to change view direction |
CONTROL_SWITCH.Magic |
Ability to use magic |
CONTROL_SWITCH.VanityMode |
Vanity view if player doesn't touch controls for a long time |
CONTROL_SWITCH.ViewMode |
Ability to toggle 1st/3rd person view |
Type KEY
Type KeyboardEvent
KeyboardEvent.code |
Key code. |
KeyboardEvent.symbol |
The pressed symbol (1-symbol string if can be represented or an empty string otherwise). |
KeyboardEvent.withAlt |
Is |
KeyboardEvent.withCtrl |
Is |
KeyboardEvent.withShift |
Is |
KeyboardEvent.withSuper |
Is |
Type TouchEvent
TouchEvent.device |
Device id (there might be multiple touch devices connected). Note: the specific device ids are not guaranteed. Always use previous user input (onTouch... handlers) to get a valid device id (e. g. in your script's settings page). |
TouchEvent.finger |
Finger id (the device might support multitouch). |
TouchEvent.position |
Relative position on the touch device (0 to 1 from top left corner), |
TouchEvent.pressure |
Pressure of the finger. |
Type TriggerInfo
TriggerInfo.description |
Localization key of the trigger's description |
TriggerInfo.key | |
TriggerInfo.l10n |
Localization context containing the name and description keys |
TriggerInfo.name |
Localization key of the trigger's name |
Type input
Field(s)
- #ACTION input.ACTION
-
(DEPRECATED, use getBooleanActionValue) Values that can be used with isActionPressed.
- #ACTION_TYPE input.ACTION_TYPE
-
Values that can be used in registerAction
- #CONTROLLER_AXIS input.CONTROLLER_AXIS
-
Values that can be used with getAxisValue.
- #CONTROLLER_BUTTON input.CONTROLLER_BUTTON
-
Values that can be passed to onControllerButtonPress/onControllerButtonRelease engine handlers.
- #CONTROL_SWITCH input.CONTROL_SWITCH
-
[Deprecated, moved to types.Player] Values that can be used with getControlSwitch/setControlSwitch.
- #map<#string,#ActionInfo> input.actions
-
Map of all currently registered actions
- input.activateTrigger(key)
-
Activates the trigger with the given key
Parameter
-
#string key
:
-
- input.bindAction(key, callback, dependencies)
-
Provides a function computing the value of given input action.
The callback is called once a frame, after the values of dependency actions are resolved. Throws an error if a cyclic action dependency is detected.
Parameters
-
#string key
: -
openmw.async#Callback callback
: returning the new value of the action, and taking as arguments: frame time in seconds, value of the function, value of the first dependency action, ... -
#list<#string> dependencies
:
Usage:
input.bindAction('Activate', async:callback(function(dt, use, sneak, run) -- while sneaking, only activate things while holding the run binding return use and (run or not sneak) end), { 'Sneak', 'Run' })
-
- input.getAxisValue(axisId)
-
Get value of an axis of a game controller.
Parameter
-
#number axisId
: Index of a controller axis, one of openmw.input#CONTROLLER_AXIS.
Return value
#number: Value in range [-1, 1].
-
- input.getBooleanActionValue(key)
-
Returns the value of a Boolean action
Parameter
-
#string key
:
Return value
#boolean:
-
- input.getControlSwitch(key)
-
[Deprecated, moved to types.Player] Get state of a control switch.
I.e. is player able to move/fight/jump/etc.
Parameter
-
#ControlSwitch key
: Control type (see openmw.input#CONTROL_SWITCH)
Return value
#boolean:
-
- input.getKeyName(code)
-
Returns a human readable name for the given key code
Parameter
-
#KeyCode code
: A key code (see openmw.input#KEY)
Return value
#string:
-
- input.getMouseMoveX()
-
Horizontal mouse movement during the last frame.
Return value
#number:
- input.getMouseMoveY()
-
Vertical mouse movement during the last frame.
Return value
#number:
- input.getNumberActionValue(key)
-
Returns the value of a Number action
Parameter
-
#string key
:
Return value
#number:
-
- input.getRangeActionValue(key)
-
Returns the value of a Range action
Parameter
-
#string key
:
Return value
#number:
-
- input.isActionPressed(actionId)
-
(DEPRECATED, use getBooleanActionValue) Input bindings can be changed ingame using Options/Controls menu.
Parameter
-
#number actionId
: One of openmw.input#ACTION
Return value
#boolean:
-
- input.isAltPressed()
-
Is
Alt
key pressed.Return value
#boolean:
- input.isControllerButtonPressed(buttonId)
-
Is a controller button currently pressed.
Parameter
-
#number buttonId
: Button index (see openmw.input#CONTROLLER_BUTTON)
Return value
#boolean:
-
- input.isCtrlPressed()
-
Is
Ctrl
key pressed.Return value
#boolean:
- input.isIdle()
-
Is player idle.
Return value
#boolean:
- input.isKeyPressed(keyCode)
-
Is a keyboard button currently pressed.
Parameter
-
#KeyCode keyCode
: Key code (see openmw.input#KEY)
Return value
#boolean:
-
- input.isMouseButtonPressed(buttonId)
-
Is a mouse button currently pressed.
Parameter
-
#number buttonId
: Button index (1 - left, 2 - middle, 3 - right, 4 - X1, 5 - X2)
Return value
#boolean:
-
- input.isShiftPressed()
-
Is
Shift
key pressed.Return value
#boolean:
- input.isSuperPressed()
-
Is
Super
/Win
key pressed.Return value
#boolean:
- input.registerAction(info)
-
Registers a new input action.
The key must be unique
Parameter
-
#ActionInfo info
:
-
- input.registerActionHandler(key, callback)
-
Registers a function to be called whenever the action's value changes
Parameters
-
#string key
: -
openmw.async#Callback callback
: takes the new action value as the only argument
-
- input.registerTrigger(info)
-
Registers a new input trigger.
The key must be unique
Parameter
-
#TriggerInfo info
:
-
- input.registerTriggerHandler(key, callback)
-
Registers a function to be called whenever the trigger activates
Parameters
-
#string key
: -
openmw.async#Callback callback
: takes the new action value as the only argument
-
- input.setControlSwitch(key, value)
-
[Deprecated, moved to types.Player] Set state of a control switch.
I.e. forbid or allow player to move/fight/jump/etc.
Parameters
-
#ControlSwitch key
: Control type (see openmw.input#CONTROL_SWITCH) -
#boolean value
:
-
- #map<#string,#TriggerInfo> input.triggers
-
Map of all currently registered triggers
Type ACTION
(DEPRECATED, use actions with matching keys)
Field(s)
- #number ACTION.Activate
- #number ACTION.AlwaysRun
- #number ACTION.AutoMove
- #number ACTION.Console
- #number ACTION.CycleSpellLeft
- #number ACTION.CycleSpellRight
- #number ACTION.CycleWeaponLeft
- #number ACTION.CycleWeaponRight
- #number ACTION.GameMenu
- #number ACTION.Inventory
- #number ACTION.Journal
- #number ACTION.Jump
- #number ACTION.MoveBackward
- #number ACTION.MoveForward
- #number ACTION.MoveLeft
- #number ACTION.MoveRight
- #number ACTION.QuickKey1
- #number ACTION.QuickKey10
- #number ACTION.QuickKey2
- #number ACTION.QuickKey3
- #number ACTION.QuickKey4
- #number ACTION.QuickKey5
- #number ACTION.QuickKey6
- #number ACTION.QuickKey7
- #number ACTION.QuickKey8
- #number ACTION.QuickKey9
- #number ACTION.QuickKeysMenu
- #number ACTION.QuickLoad
- #number ACTION.QuickMenu
- #number ACTION.QuickSave
- #number ACTION.Run
- #number ACTION.Screenshot
- #number ACTION.Sneak
- #number ACTION.ToggleDebug
- #number ACTION.ToggleHUD
- #number ACTION.TogglePOV
- #number ACTION.TogglePostProcessorHUD
- #number ACTION.ToggleSpell
- #number ACTION.ToggleWeapon
- #number ACTION.Use
- #number ACTION.ZoomIn
- #number ACTION.ZoomOut
Type ACTION_TYPE
Field(s)
- #ActionType ACTION_TYPE.Boolean
-
Input action with value of true or false
- #ActionType ACTION_TYPE.Number
-
Input action with a numeric value
- #ActionType ACTION_TYPE.Range
-
Input action with a numeric value between 0 and 1 (inclusive)
Type ActionInfo
Field(s)
- ActionInfo.defaultValue
-
initial value of the action
- #string ActionInfo.description
-
Localization key of the action's description
- #string ActionInfo.key
- #string ActionInfo.l10n
-
Localization context containing the name and description keys
- #string ActionInfo.name
-
Localization key of the action's name
Type ActionType
Type CONTROLLER_AXIS
Ids of game controller axises.
Used as an argument in getAxisValue.
Field(s)
- #number CONTROLLER_AXIS.LeftX
-
Left stick horizontal axis (from -1 to 1)
- #number CONTROLLER_AXIS.LeftY
-
Left stick vertical axis (from -1 to 1)
- #number CONTROLLER_AXIS.LookLeftRight
-
(DEPRECATED, use the LookLeftRight action) View direction horizontal axis (RightX by default, can be mapped to another axis in Options/Controls menu)
- #number CONTROLLER_AXIS.LookUpDown
-
(DEPRECATED, use the LookUpDown action) View direction vertical axis (RightY by default, can be mapped to another axis in Options/Controls menu)
- #number CONTROLLER_AXIS.MoveForwardBackward
-
(DEPRECATED, use the MoveForwardBackward action) Movement forward/backward (LeftY by default, can be mapped to another axis in Options/Controls menu)
- #number CONTROLLER_AXIS.MoveLeftRight
-
(DEPRECATED, use the MoveLeftRight action) Side movement (LeftX by default, can be mapped to another axis in Options/Controls menu)
- #number CONTROLLER_AXIS.RightX
-
Right stick horizontal axis (from -1 to 1)
- #number CONTROLLER_AXIS.RightY
-
Right stick vertical axis (from -1 to 1)
- #number CONTROLLER_AXIS.TriggerLeft
-
Left trigger (from 0 to 1)
- #number CONTROLLER_AXIS.TriggerRight
-
Right trigger (from 0 to 1)
Type CONTROLLER_BUTTON
Field(s)
- #number CONTROLLER_BUTTON.A
- #number CONTROLLER_BUTTON.B
- #number CONTROLLER_BUTTON.Back
- #number CONTROLLER_BUTTON.DPadDown
- #number CONTROLLER_BUTTON.DPadLeft
- #number CONTROLLER_BUTTON.DPadRight
- #number CONTROLLER_BUTTON.DPadUp
- #number CONTROLLER_BUTTON.Guide
- #number CONTROLLER_BUTTON.LeftShoulder
- #number CONTROLLER_BUTTON.LeftStick
- #number CONTROLLER_BUTTON.RightShoulder
- #number CONTROLLER_BUTTON.RightStick
- #number CONTROLLER_BUTTON.Start
- #number CONTROLLER_BUTTON.X
- #number CONTROLLER_BUTTON.Y
Type CONTROL_SWITCH
Field(s)
- #ControlSwitch CONTROL_SWITCH.Controls
-
Ability to move
- #ControlSwitch CONTROL_SWITCH.Fighting
-
Ability to attack
- #ControlSwitch CONTROL_SWITCH.Jumping
-
Ability to jump
- #ControlSwitch CONTROL_SWITCH.Looking
-
Ability to change view direction
- #ControlSwitch CONTROL_SWITCH.Magic
-
Ability to use magic
- #ControlSwitch CONTROL_SWITCH.VanityMode
-
Vanity view if player doesn't touch controls for a long time
- #ControlSwitch CONTROL_SWITCH.ViewMode
-
Ability to toggle 1st/3rd person view
Type ControlSwitch
String id of a #CONTROL_SWITCH
Type KEY
Field(s)
Type KeyCode
Numeric id of a #KEY
Type KeyboardEvent
The argument of onKeyPress
/onKeyRelease
engine handlers.
Field(s)
- #KeyCode KeyboardEvent.code
-
Key code.
- #string KeyboardEvent.symbol
-
The pressed symbol (1-symbol string if can be represented or an empty string otherwise).
- #boolean KeyboardEvent.withAlt
-
Is
Alt
key pressed.
- #boolean KeyboardEvent.withCtrl
-
Is
Control
key pressed.
- #boolean KeyboardEvent.withShift
-
Is
Shift
key pressed.
- #boolean KeyboardEvent.withSuper
-
Is
Super
/Win
key pressed.
Type TouchEvent
The argument of onTouchPress/onTouchRelease/onTouchMove engine handlers.
Field(s)
- #number TouchEvent.device
-
Device id (there might be multiple touch devices connected). Note: the specific device ids are not guaranteed. Always use previous user input (onTouch... handlers) to get a valid device id (e. g. in your script's settings page).
- #number TouchEvent.finger
-
Finger id (the device might support multitouch).
- openmw.util#Vector2 TouchEvent.position
-
Relative position on the touch device (0 to 1 from top left corner),
- #number TouchEvent.pressure
-
Pressure of the finger.
Type TriggerInfo
Field(s)
- #string TriggerInfo.description
-
Localization key of the trigger's description
- #string TriggerInfo.key
- #string TriggerInfo.l10n
-
Localization context containing the name and description keys
- #string TriggerInfo.name
-
Localization key of the trigger's name