inputcontexthandler

Install

[dependencies]
InputContextHandler = "hooskyfivem/inputcontexthandler@0.1.0"

Declarative

Describe a context as a table. Actions and bindings are created for you.

local ICH = require(ReplicatedStorage.Packages.InputContextHandler)

local Build = ICH.new("Build", {
	Priority = 2000,
	Sink = true,
	Actions = {
		Place = { Enum.KeyCode.MouseButton1, Enum.KeyCode.ButtonR2 },
		Rotate = { Enum.KeyCode.R, Enum.KeyCode.ButtonY },
		Cancel = { Enum.KeyCode.Q, Enum.KeyCode.ButtonB },
		ToggleView = { Enum.KeyCode.V, Enum.KeyCode.ButtonL3 },

		Pan = { Type = "Direction2D", Bindings = { "WASD", "Thumbstick1" } },
		Zoom = { Type = "Direction1D", Bindings = { { Positive = Enum.KeyCode.E, Negative = Enum.KeyCode.Q } } },
	},
})

Build:On("Place", function()
	print("place")
end)

Build:On("Rotate", function()
	print("rotate")
end)

An action written as a bare array (Place = { ... }) is a Bool action bound to each entry. Use the long form when you need a type or per-binding options.

Fluent

local Gameplay = ICH.new("Gameplay")

Gameplay:Action("Jump")
	:Bind(Enum.KeyCode.Space)
	:Bind(Enum.KeyCode.ButtonA)
	:OnPressed(function()
		print("jump")
	end)

The context stack

The reason this exists: entering a mode should suspend the mode underneath it, and leaving should restore it — without every system tracking who else is listening.

ICH.Push(Build)   --// Gameplay is disabled, Build takes priority
ICH.Pop()         --// Build is disabled, Gameplay is restored

Push raises the context's Priority above whatever it covers, so Sink = true reliably swallows input from the layer below. Remove(context) pulls a context out from the middle of the stack without disturbing the rest.

Devices

ICH.Device.Current        --// "Keyboard" | "Gamepad" | "Touch"
ICH.Device.IsGamepad()
ICH.Device.Changed:Connect(function(current, previous)
	--// swap button prompts
end)

Touch bindings take a GuiButton — pass the instance and the action fires from that button:

Build:Get("Place"):Bind(PlaceButton)

Reading state

Build:Value("Pan")       --// Vector2 for a Direction2D action
Build:IsPressed("Place")
Build:Get("Zoom"):GetValue()

Rebinding

Build:Get("Rotate"):Bind(Enum.KeyCode.R, "Primary")
Build:Get("Rotate"):Rebind("Primary", Enum.KeyCode.T)

API

Module — new(name, schema?), Get(name), Destroy(name), Push(context), Pop(), Remove(context), Current(), Clear(), Device, Presets, ContextPushed, ContextPopped.

Context — Action(name, kind?), Get, Expect, Remove, Apply(schema), On, OnReleased, OnChanged, Value, IsPressed, Enable, Disable, SetEnabled, IsEnabled, Destroy. Unknown fields pass through to the underlying InputContext.

Action — Bind(schema, name?), BindMany, GetBinding, Rebind, ClearBindings, OnPressed, OnReleased, OnChanged, GetValue, IsPressed, Fire, SetEnabled, Destroy.

Binding — SetKeyCode, SetUIButton, SetScale, SetVector2Scale, SetThresholds, SetPreset, Apply, Destroy.

Presets — WASD, ArrowKeys, DPad, Thumbstick1, Thumbstick2, MouseWheel.

Action kinds are "Bool", "Direction1D", "Direction2D", "Direction3D".