SheepWizard / Roblox-ActionBinds

Roblox ActionBinds

Roblox ActionBinds is a module that will allow you to create actions that can be controlled by key presses

Installation

Copy the contents of ActionBinds.lua into a module in StarterPlayerScripts.

Basic usage

Below is a basic example of a local script creating two actions and controlling the actions events.

local ActionBinds = require(script.Parent:WaitForChild("ActionBinds"))

-- Create a action called 'sprint' whos events will be controlled by left or right shift.
ActionBinds.newAction("sprint", {Enum.KeyCode.LeftShift, Enum.KeyCode.RightShift}, false)
ActionBinds.newAction("reload", {Enum.KeyCode.R}, false)

-- When 'R' is pressed this event will run.
ActionBinds.onActionKeyPressed("reload", function(keycode)
	print("Reload button pressed with key " .. tostring(keycode))
end)
-- When left or right shift is pressed this event will run, disabling the reload event.
ActionBinds.onActionKeyPressed("sprint", function(keycode)
	print("Start sprinting.")
	ActionBinds.disable("reload") -- Disable reload action
end)	
-- When left or right shift is released this even will run, enabling the reload event
ActionBinds.onActionKeyReleased("sprint", function(keycode)
	print("Stop sprinting.")
	ActionBinds.enable("reload") -- Enable reload action
end)

You can also see a basic example of all functions being used here: https://github.com/SheepWizard/Roblox-ActionBinds/blob/master/Example.lua

API

ActionBinds.newAction

Creates a new action.

ActionBinds.newAction(name: string, keys: KeyList, gameProcessed: boolean?): Action

Parameter	Description
name	Name of the action
keys	List of key code enums which will trigger action events. There is no limit on how many keycodes you can use. You can also use string "MouseButton1", "MouseButton2", "MouseButton3", to detect mouse clicks
gameProcessed	If action events should trigger if gameProcessed is true or false (optional)

Example:

ActionBinds.newAction("sprint", {Enum.KeyCode.LeftShift, Enum.KeyCode.RightShift, "MouseButton1"}, false)

ActionBinds.onActionKeyPressed

Add a key pressed event to the action. When one of the actions keys is pressed this event will run.

ActionBinds.onActionKeyPressed(actionName: string, event: (Enum.KeyCode?) -> any?)

Parameter	Description
actionName	Name of the action
event	Function to run when one of actions keys is pressed. The key that is pressed is given as a parameter

Example:

ActionBinds.onActionKeyPressed("sprint", function(keycode)
	print("Start sprinting.")
end)

ActionBinds.onActionKeyReleased

Add a key released event to the action. When one of the actions keys is released this event will run.

ActionBinds.onActionKeyReleased(actionName: string, event: (Enum.KeyCode?) ->any?)

Parameter	Description
actionName	Name of the action
event	Function to run when one of actions keys is released. The key that is pressed is given as a parameter

Example:

ActionBinds.onActionKeyReleased("sprint", function(keycode)
	ActionBinds.enable("reload")
end)

ActionBinds.isActive

Returns true or false if the action is currently active. A action will be active if one of its keys is pressed.

ActionBinds.isActive(actionName: string): boolean

Parameter	Description
actionName	Name of the action
Example:

print(ActionBinds.isActive("sprint"))

ActionBinds.disable

Disable events from running on a action.

ActionBinds.disable(actionName: string)

Parameter	Description
actionName	Name of the action
Example:

ActionBinds.disable("reload") 

ActionBinds.enable

Enable events on a action.

ActionBinds.enable(actionName: string)

Parameter	Description
actionName	Name of the action

Example:

ActionBinds.enable("reload") 

ActionBinds.isDisabled

Check is a actions events have been disabled

ActionBinds.isDisabled(actionName: string): boolean

Parameter	Description
actionName	Name of the action

Example:

print(ActionBinds.isDisabled("sprint"))

ActionBinds.ignoreGameProcessed

If set to true action events will ignore all gameProcessed rules and the event will run when gameProcessed is both true or false.

ActionBinds.ignoreGameProcessed(actionName: string, bool: boolean)

Parameter	Description
actionName	Name of the action
bool	If gameProcessed should be ignored or not

Example:

ActionBinds.ignoreGameProcessed("menu", true)

ActionBinds.getKeys

Get a list of all keys bound to a action.

ActionBinds.getKeys(actionName: string): KeyList

Parameter	Description
actionName	Name of the action

Example:

local keyList1 = ActionBinds.getKeys("reload")

ActionBinds.changeKeys

Give a new list of keys that will run the actions events, replacing the old ones.

ActionBinds.changeKeys(actionName: string, keys: KeyList)

Parameter	Description
actionName	Name of the action
keys	New list of keycode enums

Example:

ActionBinds.changeKeys("sprint", {Enum.KeyCode.KeypadEnter})

ActionBinds.getActionObject

Get the Action object.

ActionBinds.getActionObject(actionName: string): Action

Parameter	Description
actionName	Name of the action

Example:

local action = ActionBinds.getActionObject("reload")

ActionBinds.GUIButton

When the GUI button is activated it will run the actions key pressed events then immediately run the key released events. The keycode given for events run by GUI buttons will be Enum.KeyCode.Unknown

ActionBinds.GUIButton(actionName: string, button: GuiButton)

Parameter	Description
actionName	Name of the action
button	The GUI button you want to use to run action events

Example:

local button = Instance.new("TextButton")
ActionBinds.GUIButton("reload", button)

ActionBinds.runActionEvents

Run events for a action manually. Best to run both event to simulate a key press and release. If eventType 1 is used the actions 'active' property will be set to true and stay that way until a key released event is pressed. The keycode given for event run by this function will be Enum.KeyCode.Unknown

ActionBinds.runActionEvents(actionName: string, eventType: number)

Parameter	Description
actionName	Name of the action
eventType	Either 0 or 1. 0 for key released events, 1 for key pressed events

Example:

ActionBinds.runActionEvents("sprint", 1)
wait(5)
ActionBinds.runActionEvents("sprint", 0)

ActionBinds.actionNames

A table of all action names. Example:

for k, v in pairs(ActionBinds.actionNames) do
	print(v)
end

Types

type KeyList = {Enum.KeyCode | "MouseButton1" | "MouseButton2" | "MouseButton3"}

type Action = {
	name: string,
	keys: KeyList,
	gameProcessed: boolean?,
	ingoreGameProcessed: boolean?,
	disabled: boolean,
	active: boolean,
	keyPressedEvents: {(Enum.KeyCode?) -> nil},
	keyReleasedEvents: {(Enum.KeyCode?) -> nil},
}