Binder

New Experimental Interface Utility

Binder is an input wrapper powered by the the newly released Input Action System that provides a more compact, up-to-date, and efficient implementation of the now deprecated ContextActionService functionality.

On top of this, binder offers automatic touch button positioning using predefined slots, support for multiple actions per binding, rebinding, customization, etc.

Code Snippets

The following examples demonstrate some common ways to use ‘Binder’.

PrintState

local Binder = require(Shared.CmeSuite.Binder)

--Bind
local Bind = Binder:Bind("PrintState" {KeyCodes = {Enum.KeyCode.E}}, function(Input)
  if Input.InputState == "Began" then
      print("Pressed.")
  elseif Input.InputState == "OnHold" then
      print("On hold.")
  elseif Input.InputState == "Ended" then
      print("Released.")
  end
)

--Unbind
task.delay(5, function()
  Bind:Unbind() --Alternatively, 'Binder:Find("PrintState")' can be used to obtain 'Bind'.
end)

Note: For compatibility with projects using maid/trove libraries, a hidden Destroy method mimicking Unbind is also provided for bind objects.

API

Constants

AdditiveBindings

ADDITIVE_BINDINGS: boolean Constant

By default a warning will be thrown when you attempt to bind an already existing binder, expecting you to use find and rebind to work with already existing binders to avoid undesired side effects.

This makes it so bind stacks by reconciling already existing binders with the passed arguments.

CreateTouchButton

CREATE_TOUCH_BUTTON: boolean Constant

By default, binder will generate a touch button for all your actions, assigning them the lowest slot available with an order of 0. For cases on which this isn’t desired, you can set the slot of your action to ‘-1’.

Setting this to false will make it so touch buttons are only generated when specified at the time of binding an action (‘Binder.TouchButton’ is exposed in case using the default touch button in such context is desired).

LockJumpButton

LOCK_JUMP_BUTTON: boolean Constant

By default roblox hides the jump action’s touch button when they ‘believe’ the player can’t jump. This is usually desired (thus why this is false by default), but can be an issue if you are handling the player’s jump manually (eg. double jump abilities).

Setting this to true forces the button to stay enabled regardless of the player’s ability to perform a jump.

ReturnGamepadWhenUnplugged

RETURN_GAMEPAD_WHEN_UNPLUGGED: boolean Constant

By default, binder returns an ‘unknown’ GamepadType when no gamepads are plugged, as it may be confusing for users to get one when no gamepads are plugged.

Setting this to ‘true’ returns the current GamepadType regardless of if the controller is plugged or not.

UseLastInputType

USE_LAST_INPUT_TYPE: boolean Constant

By default binder listens to LastInputType for changes instead of the recommended PreferredInput when detecting device changes. This is due to the behaviour of the later having potentially unintended side effects when listening to the DeviceChanged signal.

Setting this to ‘false’ will use PreferredInput instead.

Types

Binder Object Type Read Only

Object in charge of handling an in-game interaction’s input, actions, and state.

Enabled

Name

Description

Image

PressedImage

Slot

Order

TouchButton

Property	Description
Enabled: boolean	Whether input is processed and the touch button is visible.
Name: string	Name of the binder.
Description: string	Text displayed in the touch button (defaults to Name).
Image: ( string \| number )?	Image displayed in the touch button.
PressedImage: ( string \| number )?	Image displayed while the touch button is pressed (defaults to Image).
Slot: number	Position index for the touch button (uses lowest available if not provided).
Order: number	Priority when multiple buttons share the same slot (nearest available slot used if full).
TouchButton: GuiButton ?	Touch button monitored for input.

InternalBinder Object Type Read Only Internal

extends Binder

Internal properties of the Binder object.

KeyCodes

Actions

CloneTouchButton

InputContext

InputActions

InputBinding

Trove

StateTrove

InactiveButtons

Property	Description
KeyCodes: { KeyCode }	KeyCodes the binder listens to.
Actions: { Action }	Actions queued to be called.
CloneTouchButton: boolean ?	Whether the TouchButton is cloned (defaults to true).
InputContext: InputContext	The binder’s InputContext instance.
InputActions: { InputAction }	InputAction objects mapped per KeyCode (InputBinding is a child of each).
Trove: Trove	Main cleanup manager.
StateTrove: Trove	State-specific cleanup manager.
InactiveButtons: Folder	Folder storing inactive touch buttons.

BinderInfo

type BinderInfo = {
  Enabled: boolean?,
  Description: string?,
  Image: (string | number)?,
  PressedImage: (string | number)?,
  Slot: number?,
  Order: number?,
  KeyCodes: {Enum.KeyCode}?,
  TouchButton: GuiButton?,
  CloneTouchButton: boolean?
}

Properties to be changed when rebinding an bind object.

Input

type Input = {
  KeyCode: Enum.KeyCode,
  State: State,
  Device: Device,
  Gamepad: Gamepad
}

Describes a particular user input, similar to how InputObject did.

Action

type Action = (Input: Input) -> ()

Callback to be called when an action is performed.

State

type State = "Began" | "OnHold" | "Ended" | "Changed" | "Unknown"

Describes the input’s state.

Device

type Device = "KeyboardAndMouse" | "Gamepad" | "Touch" | "Unknown"

Describes the input’s device.

Gamepad

type Gamepad = "Xbox" | "Playstation" | "Unknown"

Describes the device’s type.

Properties

TouchButton Instance

Touch button used as the base for the autogenerated ones.

Binded Signal Read Only

Signal<Name: string>

Fires when a binder is created.

Rebinded Signal Read Only

Signal.Signal<Name: string, Property: string, NewValue: any, OldValue: any>

Fires when the property of a binder changes (which happens when it’s rebinded).

Unbinded Signal Read Only

Signal<Name: string>

Fires when a binder is destroyed.

KeyCodeAdded Signal Read Only

Signal<Name: string, KeyCode: Enum.KeyCode>

Fires when a keycode is added to a binder.

KeyCodeRemoved Signal Read Only

Signal<Name: string, KeyCode: Enum.KeyCode>

Fires when a keycode is removed from a binder.

ActionAdded Signal Read Only

Signal<Name: string, Action: Action>

Fires when an action is added to a binder.

ActionRemoved Signal Read Only

Signal<Name: string, Action: Action>

Fires when an action is removed from a binder.

DeviceChanged Signal Read Only

Signal<NewDevice: Device, OldDevice: Device>

Fires when the user’s device changes.

GamepadChanged Signal Read Only

Signal<NewGamepad: Gamepad, OldGamepad: Gamepad>

Fires when the user’s gamepad changes.

Methods

Class

Bind

Bind(Name: string, Info: BindInfo , …: Action ): Object Class Method

Creates a binder object.

Rebind

Rebind(Name: string, Info: BindInfo ): () Class Method

Updates an already existing binder using the given binderInfo.

Find

Find(Name: string): Object ? Class Method

Looks for an existing binder object with the given name.

Unbind

Unbind(Name: string): () Class Method

Destroys the specified binder object.

GetJumpButton

GetJumpButton(): GuiButton? Class Method

Returns the default mobile jump button, if it exists.

Object

AddAction

AddAction(self: Object , Action: Action ): () Object Method

Adds a new action.

RemoveAction

RemoveAction(self: Object , Action: Action ): () Object Method

Removes an already existing action, if found.

ClearActions

ClearActions(self: Object ): () Object Method

Removes all existing actions.

AddKeyCode

AddKeyCode(self: Object , Binding: Enum.KeyCode): () Object Method

Adds a new keycode.

RemoveKeyCode

RemoveKeyCode(self: Object , Binding: Enum.KeyCode): () Object Method

Removes an already existing keycode, if found.

ClearKeyCodes

ClearKeyCodes(self: Object ): () Object Method

Removes all existing keycodes.

Destroy

Destroy(self: Object ): () Object Method Internal

Destroys the binder.

Attribution

This resource was made possible thanks to the following authors.

PseudoPerson: ContextActionUtility, on which ‘Binder’ is based.
Sleitnick: RbxUtil.

Dependancies

Binder relies on the following third-party dependancies.

RbxUtil

Signal
Trove

Refer to the Getting Started section for help installing third-party dependancies.