Module input

Input management facilities.

The module returns a single function, input.

Requires ubiquitousse.signal.

Usage:

    TODO

Functions

input () Make a new input object.

Input objects

Input.config Input configuration table.
Input.children List and map of children inputs.
Input.name Name of the input.
Input.grabbed False if the input is currently not grabbed, a subinput otherwise.
Input.grabbing False if the input is not a subinput, the input it grabbed otherwise.
Input.event Input event registry.
Input:update () Update the input and its children.
Input:clone () Create a new input object based on this input config data.
Input:reload () Relond the input config, and do the same for its children.
Input:disable () Disable the input and its children, preventing further updates and events.
Input:onNextActiveSource (fn[, filter]) Will call fn(source) on the next activated source (including sources not currently used by this input).
Input:grab () Grab the input and its children input and returns the new subinput.
Input:release () Release a subinput and its children.
Input:neutralize () Set the state of this input to a neutral position (i.e.
Input:setJoystick (joystick) Set the joystick associated with this input.
Input:getJoystick () Returns the currently selected joystick.
Input:down () Returns true if the input is currently down.
Input:pressed () Returns true if the input has just been pressed.
Input:released () Returns true if the input has just been released.
Input:value () Returns the current value of the input.
Input:delta () Returns the delta value of the input since the last call to update.
Input:pointer () If there is a horizontal and vertical children inputs, this returns the horizontal value and the vertical value.
Input:clamped () Same as pointer, but normalize the returned vector, i.e.


Functions

input ()
Make a new input object. t: input configuration table (optional)

Input objects

Input methods.
Input.config
Input configuration table. It can be used to recreate this input object later (by passing the table as an argument for the input constructor). This table does not contain any userdata and should be easily serializable (e.g. to save custom input binding config). This doesn’t include input state, grab state, the event registry and the selected joystick since they may change often during runtime. Can be changed anytime, but you may need to call reload to apply changes.

Usage:

    player.config = {
  "key.a", "key.d - key.a", {"key.left + x", x=0.5}, -- list of input sources expressions
  jump = {...}, -- children input
  deadzone = 0.05, -- The deadzone for analog inputs (e.g. joystick axes): if the input absolute value is strictly below this, it will be considered as 0.
  threshold = 0.05 -- The pressed threshold: an input is considered down if above or equal to this value.
}
Input.children
List and map of children inputs. {[child1.name]=child1, [child2.name]=child2, child1, child2…}
Input.name
Name of the input. Defined on children inputs only.
Input.grabbed
False if the input is currently not grabbed, a subinput otherwise. This may be different between each subinput.
Input.grabbing
False if the input is not a subinput, the input it grabbed otherwise. This may be different between each subinput.
Input.event
Input event registry. The following events are available:

  • "moved": called when the input value change, with arguments (new value, delta since last event)
  • "pressed": called when the input is pressed
  • "released": called when the input is released

For pointer inputs (have a “horizontal” and “vertical” children inputs) is also avaible:

  • "pointer moved": called when the pointer position change, with arguments (new pointer x, new pointer y, delta x since last event, delta y since last event)

Each subinput has a different event registry.

Input:update ()
Update the input and its children. Should be called every frame, typically after you've done all your input handling (otherwise pressed and released may never return true and delta might be wrong). (Note: this should not be called on subinputs)
Input:clone ()
Create a new input object based on this input config data.
Input:reload ()
Relond the input config, and do the same for its children. This will reenable the input if it was disabled using disable.
Input:disable ()
Disable the input and its children, preventing further updates and events. The input can be reenabled using reload.
Input:onNextActiveSource (fn[, filter])
Will call fn(source) on the next activated source (including sources not currently used by this input). Typically used to detect an input in your game input binding settings.

Parameters:

  • fn function that will be called on the next activated source matching the filter
  • filter list of string patterns that sources must start with (example {"button", "key"} to only get buttons and key sources) (optional)
Input:grab ()
Grab the input and its children input and returns the new subinput.

A grabbed input will no longer update and instead pass all new update to the subinput. This is typically used for contextual action or pause menus: by grabbing the player input, all the direct use of this input in the game will stop (can’t move caracter, …) and instead you can use the subinput to handle input in the pause menu. To stop grabbing an input, you will need to :release the subinput.

This will also reset the input to a neutral state. The subinput will share everything with this input, except grabbed, grabbing, event (a new event registry is created), and of course its current state.

Input:release ()
Release a subinput and its children. The parent grabbed input will be updated again. This subinput will be reset to a neutral position and won’t be updated further.
Input:neutralize ()
Set the state of this input to a neutral position (i.e. value = 0).
Input:setJoystick (joystick)
Set the joystick associated with this input. The input will ignore every other joystick. Set joystick to nil to disable and get input from every connected joystick.

Parameters:

  • joystick LÖVE jostick object to associate
Input:getJoystick ()
Returns the currently selected joystick.
Input:down ()
Returns true if the input is currently down.
Input:pressed ()
Returns true if the input has just been pressed.
Input:released ()
Returns true if the input has just been released.
Input:value ()
Returns the current value of the input.
Input:delta ()
Returns the delta value of the input since the last call to update.
Input:pointer ()
If there is a horizontal and vertical children inputs, this returns the horizontal value and the vertical value. Typically used for movement/axes pairs (e.g. to get x,y of a stick or directional pad).
Input:clamped ()
Same as pointer, but normalize the returned vector, i.e. “clamp” the returned x,y coordinates into a circle of radius 1. Typically used to avoid faster movement on diagonals (as if both horizontal and vertical values are 1, the pointer vector has √2 magnitude, higher than the 1 magnitude of a purely vertical or horizontal movement).
generated by LDoc 1.4.6 Last updated 2022-09-16 20:07:07