crystal.input

The classes and functions in this module allow you to:

• Manage which physical buttons correspond to which actions in your game.
• Manage which input devices are assigned to which player (in a multiplayer game).
• Route input events to specific game entities like player characters.
• Implement areas that react to mouse inputs.

A player can have bindings to both keyboard and gamepad buttons at the same time. This allows them to seemlessly switch between input methods. For singleplayer games, you do not have to do anything related to assigning or unassigning gamepads.

After configuring bindings, player inputs can be handled via Scene:action_pressed/Scene:action_released. More conveniently, you can use these callbacks to forward the inputs to an InputSystem and rely on InputListener components to implement actual responses.

Functions

Reading Inputs

Name	Description
crystal.input.axis_action_value	Returns the current value of a gamepad axis associated with a specific action.
crystal.input.current_mouse_target	Returns the mouse target the mouse pointer is currently on top of.
crystal.input.gamepad_id	Returns the gamepad assigned to the specified player, if any.
crystal.input.input_method	Returns the input method last used by the specified player.
crystal.input.is_action_down	Returns whether any input mapped to a specific action is currently being pressed.
crystal.input.mouse_player	Returns the player index of the player using the mouse.

Configuration

Name	Description
crystal.input.add_mouse_target	Registers a rectangular area that supports mouse interaction.
crystal.input.assign_gamepad	Assigns a gamepad to a player.
crystal.input.assign_mouse	Assigns the mouse to a player.
crystal.input.bindings	Returns a table describing which actions are bound to which inputs for the specified player.
crystal.input.configure_autorepeat	Defines which actions emit events while inputs are being held, and how frequently.
crystal.input.map_axis_to_actions	Map positions on gamepad analog axis to binary actions.
crystal.input.set_bindings	Sets which actions are bound to which inputs for the specified player.
crystal.input.set_unassigned_gamepad_handler	Defines a callback function which runs when a button is pressed on an unassigned gamepad.
crystal.input.unassign_gamepad	Unassigns a player’s current gamepad.

Classes

Name	Description
crystal.InputListener	A Component which allows an entity to receive input events.
crystal.InputSystem	A System which dispatches input events.
crystal.MouseArea	A Component which allows an entity to receive mouse hover and click-related events.

Enums

Name	Description
InputMethod	Device being used to play the game.