Input
API for handling user input in a way that's compatible with all supported input devices (keyboards, mice, gamepads, and more!).
Inputs are defined as a set of Actions, collectively called an Action Set. Each Action is bound to one or more physical buttons and/or analogue sensors, and carries a semantic meaning that should be adhered to. This ensures players are free to configure their inputs how they want, on a range of devices, while still having a consistent experience across games and addons.
Action Sets can be selected on the fly to change how input behaves for players. For example, switching to menu navigation when they open chat.
Functions
Input.switchToBasicActionSet
Switches the active action set to "Basic", which should support most 2D and 3D player characters.
If the player is using a mouse, their cursor is locked to the screen when switching to this action set.
Input.switchToBasicActionSet()
Input.switchToMenuActionSet
Switches the active action set to "Menu", enabling the navigation of UIs.
Pass the optional MenuType enum to control which input will trigger the dismissMenu action.
If the player is using a mouse, their cursor is unlocked from the screen when switching to this action set.
Input.switchToMenuActionSet(menu?: MenuType)
Parameters
| Name | Type | Description |
|---|---|---|
| menu | MenuType? | The (optional) menu type being switched to. |
Input.addEventListener
Adds an event listener. A list of events can be found here.
Input.addEventListener(eventType: string, callback: function): function
Parameters
| Name | Type | Description |
|---|---|---|
| eventType | string | The event to listen for. |
| callback | function | The callback to use. |
Returns
| Name | Type | Description |
|---|---|---|
| callback | function | The callback that was registered. |
Input.removeEventListener
Removes an event listener.
Input.removeEventListener(eventType: string, callback: function)
Parameters
| Name | Type | Description |
|---|---|---|
| eventType | string | The event to remove the listener from. |
| callback | function | The callback to remove. |
Types
DigitalAction
A digital action, i.e. a button press (but not necessarily bound to a physical button).
Note that none of these properties are mutually exclusive. It is valid for a button to be pressed and released during, and held at the end of, a given input sample.
type DigitalAction = { .wasPressedThisFrame: boolean, .wasReleasedThisFrame: boolean, .isHeld: boolean }
Properties
| Field | Type | Description |
|---|---|---|
| wasPressedThisFrame | boolean | True if the button transitioned from not pressed to pressed during this input sample |
| wasReleasedThisFrame | boolean | True if the button transitioned from pressed to not pressed during this input sample |
| isHeld | boolean | True if the button was held at the end of this input sample |
MenuActionSet
A collection of actions available when the "Menu" action set is active.
type MenuActionSet = { .cursor: number[], .scroll: number[], .up: DigitalAction, .down: DigitalAction, .left: DigitalAction, .right: DigitalAction, .previousTab: DigitalAction, .nextTab: DigitalAction, .activateCursor: DigitalAction, .affirm: DigitalAction, .cancel: DigitalAction, .openContextMenu: DigitalAction, .hotkey1: DigitalAction, .hotkey2: DigitalAction, .hotkey3: DigitalAction, .hotkey4: DigitalAction, .dismissMenu: DigitalAction }
Properties
| Field | Type | Description |
|---|---|---|
| cursor | number[] | The delta (in pixels) of the physical or virtual mouse cursor since the last time input was processed. |
| scroll | number[] | The delta of the scroll action since the last time input was processed. |
| up | DigitalAction | Selects a focusable UI element immediately above the currently focused element |
| down | DigitalAction | Selects a focusable UI element immediately below the currently focused element |
| left | DigitalAction | Selects a focusable UI element immediately left of the currently focused element |
| right | DigitalAction | Selects a focusable UI element immediately right of the currently focused element |
| previousTab | DigitalAction | Selects the previous tab or page in the currently active window or modal |
| nextTab | DigitalAction | Selects the next tab or page in the currently active window or modal |
| activateCursor | DigitalAction | Clicks/presses an interactive UI element underneath the current cursor position |
| affirm | DigitalAction | Affirms confirmation modals or clicks/presses the currently focused element |
| cancel | DigitalAction | Cancels/closes modals or returns to the previous screen |
| openContextMenu | DigitalAction | Opens a context menu or displays more information for the currently hovered/focused UI element |
| hotkey1 | DigitalAction | Generic action which can be used by developers for interactions not covered by the above actions |
| hotkey2 | DigitalAction | Generic action which can be used by developers for interactions not covered by the above actions |
| hotkey3 | DigitalAction | Generic action which can be used by developers for interactions not covered by the above actions |
| hotkey4 | DigitalAction | Generic action which can be used by developers for interactions not covered by the above actions |
| dismissMenu | DigitalAction | Dismisses the currently open menu. Bound dynamically depending on the active menu type |
BasicActionSet
A collection of actions available when the "Basic" action set is active.
Useful for generic 2D/3D player character controllers and simple/arcade land, sea and air vehicles.
type BasicActionSet = { .look: number[], .move: number[], .jump: DigitalAction, .crouch: DigitalAction, .sprint: DigitalAction, .primary: DigitalAction, .secondary: DigitalAction, .previousItem: DigitalAction, .nextItem: DigitalAction, .reload: DigitalAction, .interact: DigitalAction, .openInventory: DigitalAction, .openMainMenu: DigitalAction, .openSocialMenu: DigitalAction, .hotkey1: DigitalAction, .hotkey2: DigitalAction, .hotkey3: DigitalAction, .hotkey4: DigitalAction }
Properties
| Field | Type | Description |
|---|---|---|
| look | number[] | Adjusts the player's viewport on two axes |
| move | number[] | Moves the player on two axes. Length is clamped to one, but can be shorter |
| jump | DigitalAction | Causes the player to perform an action they would expect to be bound to their jump button |
| crouch | DigitalAction | Causes the player to perform an action they would expect to be bound to their crouch button |
| sprint | DigitalAction | Causes the player to perform an action they would expect to be bound to their sprint button |
| primary | DigitalAction | Causes the player to perform an action they would expect to be bound to the button usually used for shooting/attacking in FPS/TPS games |
| secondary | DigitalAction | Causes the player to perform an action they would expect to be bound to the button usually used for aiming in FPS/TPS games |
| previousItem | DigitalAction | Selects the previous item/weapon held by the player |
| nextItem | DigitalAction | Selects the next item/weapon held by the player |
| reload | DigitalAction | Causes the player to reload/recharge their item/weapon. |
| interact | DigitalAction | Causes the player to interact with the object they're looking at (e.g. entering a vehicle) |
| openInventory | DigitalAction | Opens the player's inventory (if relevant to the type of game or addon you're building) |
| openMainMenu | DigitalAction | Should always open the main in-game menu (usually a pause menu in singleplayer games) |
| openSocialMenu | DigitalAction | Opens a menu used for social features in multiplayer (e.g. chat) |
| hotkey1 | DigitalAction | Generic action which can be used by developers for interactions not covered by the above actions |
| hotkey2 | DigitalAction | Generic action which can be used by developers for interactions not covered by the above actions |
| hotkey3 | DigitalAction | Generic action which can be used by developers for interactions not covered by the above actions |
| hotkey4 | DigitalAction | Generic action which can be used by developers for interactions not covered by the above actions |
Enums
MenuType
Menu types which are opened by an action, and should be dismissed by the same action.
| Value |
|---|
| Main |
| Inventory |
| Social |
Events
"menuActionSet"
Fired every time input is processed while the "Menu" action set is active.
- In the menu, this is fired every frame
- In games on the client, this is fired once per server tick for the local player
- This action set does not exist on the server
Input.addEventListener("menuActionSet", fn(actions, deltaTime) end)
Parameters
| Name | Type | Description |
|---|---|---|
| actions | MenuActionSet | A snapshot of the menu actions this frame/tick. |
| deltaTime | number | Seconds passed since the last time input was processed (including for other action sets) |
"basicActionSetPredicted"
Fired in the menu and games on the client every time input is processed while the "Basic" action set is active.
- In the menu, this is fired every frame
- In games, this is fired once per server tick for each player and when performing local prediction
On the server, the "basicActionSet" event is fired instead.
Input.addEventListener("basicActionSetPredicted", fn(player, actions, isFirstTimePredicted, deltaTime) end)
Parameters
| Name | Type | Description |
|---|---|---|
| player | Player | The player these inputs are for. |
| actions | BasicActionSet | A snapshot of the basic actions this frame/tick. |
| isFirstTimePredicted | boolean | True if this is the first time we're processing this input |
| deltaTime | number | Seconds passed since the last time input was processed (including for other action sets) |
"basicActionSet"
Fired on the server every time input is processed while the "Basic" action set is active.
On the client, the "basicActionSetPredicted" event is fired instead.
Input.addEventListener("basicActionSet", fn(player, actions, deltaTime) end)
Parameters
| Name | Type | Description |
|---|---|---|
| player | Player | The player these inputs are for. |
| actions | BasicActionSet | A snapshot of the basic actions this frame/tick. |
| deltaTime | number | Seconds passed since the last time input was processed (including for other action sets) |