{"id":"illusionac/illusion-inputactionsystem","name":"illusion-inputactionsystem","scope":"illusionac","platform":"roblox","description":"Illusion's InputActionSystem - A modular input & keybind management library for Roblox","version":"1.0.0","latest":"1.0.0","versions":["1.0.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"6ffde74d8fe3f8e13cbb9af157bf735591c57bcdb8a67a342a7e7d8606f21359","likes":0,"downloads":0,"install":"forest install illusionac/illusion-inputactionsystem","url":"https://forest.dev/p/roblox/illusionac/illusion-inputactionsystem","files":"https://api.forest.dev/ai/package/roblox/illusionac/illusion-inputactionsystem/files","readme":"# Illusion's InputActionSystem
\r\n\r\n\r\n\r\n \r\n
\r\n\r\nHey developers! I'm excited to share the latest version of my **InputActionSystem** library - a complete rewrite of my [previous keybind system](https://devforum.roblox.com/t/illusions-inputactionsystem-an-easy-way-of-adding-keybinds-and-other/4061839) that's now fully modular and can be integrated anywhere in your LocalScripts.\r\n\r\nIf you're working with Roblox's new InputActionSystem or just need robust keybind management, this library will save you hours of development time.\r\n\r\n---\r\n\r\n## Key Features\r\n\r\n- **Flexible Input Types**: Define actions as Hold or Toggle buttons\r\n- **Multi-Key Support**: Assign multiple keys per action for full gamepad compatibility\r\n- **Key Combinations**: Create complex actions using modifier keys (e.g., Shift + F)\r\n- **UI Integration**: Connect keybinds to GuiButtons for seamless mobile support\r\n- **Cooldown System**: Prevent action spam with customizable cooldowns\r\n- **Input Buffering**: Capture inputs even during busy frames\r\n- **Tap Detection**: Trigger actions with double-tap or multi-tap sequences\r\n- **Priority & Sinking**: Fine control over input processing order\r\n- **Full Roblox IAS Synchronization**: Support for `PreferredBinding`, `InputActionLabel`, `InputBindingType`, and all 5 `InputActionType` modes (`Bool`, `Direction1D`, `Direction2D`, `Direction3D`, `ViewportPosition`)\r\n\r\n---\r\n\r\n## Installation\r\n### Non Server Authority version:\r\n\r\n**Option 1:** [Download from Creator Store](https://create.roblox.com/store/asset/92059655869452/Illusions-InputActionSystem-Module)\r\n\r\n**Option 2:** [Clone from GitHub](https://github.com/IllusionAC/Illusion-InputActionSystem)\r\n\r\n**Option 3:** Wally Package Manager\r\nAdd to your `wally.toml`:\r\n```toml\r\n[dependencies]\r\nIllusionIAS = \"illusionac/illusion-inputactionsystem@^1.0.0\"\r\n```\r\n\r\nPlace the module in `ReplicatedStorage` (or via Wally `Packages`) and require it in any LocalScript:\r\n\r\n```lua\r\nlocal IAS = require(game.ReplicatedStorage.IllusionIAS)\r\n-- Or if using Wally:\r\n-- local IAS = require(game.ReplicatedStorage.Packages.IllusionIAS)\r\n```\r\n\r\n### Server Authority version:\r\n\r\nDo the same steps as for normal version, but require the module from a Server Script.\r\n\r\n---\r\n\r\n## API Reference\r\n\r\n### Create, Manage and Give Contexts to Binds\r\n\r\n```lua\r\nIIAS.new(name: string, InputType: Enum.InputActionType?) -- Create a new keybind, set an InputActionType (default: Bool)\r\nIIAS.Get(name: string) -- Retrieve a specific bind (alias of .get)\r\nIIAS.GetAll() -- Get all registered binds (alias of .getAll)\r\nIIAS.enableControlHints(module: Instance | string, parent: Instance | PlayerGui?)\r\n -- Enable ControlHints - By ZurichBT\r\n\r\n-- IMPORTANT: Context here organizes your binds logically.\r\nIIAS.addContext(name: string, ...Object) -- Add Binds to a context group\r\nIIAS.getContext(name: string) -- Returns a context group table\r\nIIAS.newContext(name: string) -- Create a new context group\r\nIIAS.enableContext(name: string, enabled: boolean) -- Enable or disable all binds in the context group\r\nIIAS.isContextEnabled(name: string) -- Returns the context group enabled state\r\nIIAS.clearContexts() -- Clear all context groups\r\nIIAS.removeContext(name: string) -- Remove a context group\r\nIIAS.removeFromContext(name: string, bind: Object) -- Remove a bind from a context group\r\nIIAS.removeAllFromContext(name: string) -- Empty a context group without deleting it\r\n```\r\n\r\n### Configuration Methods\r\n\r\n```lua\r\n:SetHold(hold: boolean) -- true = hold to activate, false = toggle\r\n:SetUIButton(button: GuiButton?) -- Link a GUI button as alternate input\r\n:SetUIModifier(button: GuiButton?) -- Link a GUI button as modifier\r\n:GetUIModifier() -- Get linked modifier GUI button\r\n:SetCooldown(cooldown: number) -- Set cooldown in seconds (default: 0)\r\n:ResetCooldown() -- Manually reset cooldown\r\n:CooldownEnded() -- boolean: true when cooldown is not active\r\n:SetEnabled(enabled: boolean) -- Enable/disable the bind\r\n:IsEnabled() -- Check if bind is enabled (:IsEnable is an alias)\r\n:SetTapActivation(taps: number, window: number) -- Require N taps within time window\r\n```\r\n\r\n### Input Context Control\r\n\r\n```lua\r\n:SetPriority(priority: number) -- Set processing priority\r\n:GetPriority() -- Get current priority\r\n:SetSink(sink: boolean) -- Set if input should sink\r\n:GetSink() -- Get sink state\r\n```\r\n\r\n### Input Buffering\r\n\r\n```lua\r\n:SetInputBufferEnabled(enabled: boolean) -- Enable input buffering (default: false)\r\n:SetInputBufferTime(time: number) -- Buffer window in seconds (default: 0.15)\r\n```\r\n\r\n### Keybind Management\r\n\r\n```lua\r\n:AddBind(mainKey, primaryMod?, secondaryMod?, uiButton?, uiModifier?, displayName?, displayImage?, bindingType?)\r\n -- Add a keybind with optional modifiers and configuration\r\n:SetBind(mainKey, primaryMod?, secondaryMod?, uiButton?, uiModifier?, displayName?, displayImage?, bindingType?)\r\n -- Replace all binds with a single bind\r\n:GetBinds() -- Get all current keybinds table\r\n:RemoveBind(mainKey, primaryMod?, secondaryMod?) -- Remove a specific keybind\r\n:EditBind(oldMain, oldMods, newMain, newMods) -- Edit an existing keybind\r\n:ClearBinds() -- Remove all keybinds\r\n:Destroy() -- Delete the bind and its Roblox instances entirely\r\n:SetCompositeDirections(up, down, left, right, forward, backward) -- Sets composite directions for directional actions\r\n:GetCompositeDirections() -- Returns table with Up, Down, Left, Right, Forward, Backward\r\n:SetCompositeModifiers(primaryModifier, secondaryModifier) -- Sets composite modifiers\r\n:GetCompositeModifiers() -- Returns table with PrimaryModifier, SecondaryModifier\r\n```\r\n\r\n### Display & Label Helpers\r\n\r\n```lua\r\n:SetDisplayName(mainKey, displayName: string) -- Set custom display text on InputBinding\r\n:GetDisplayName(mainKey) -- Get display text of binding\r\n:SetDisplayImage(mainKey, displayImage: any) -- Set custom image content on InputBinding\r\n:GetDisplayImage(mainKey) -- Get image content of binding\r\n:SetBindingType(mainKey, bindingType: Enum.InputBindingType) -- Set Automatic or Scriptable\r\n:GetBindingType(mainKey) -- Get binding type\r\n:CreateActionLabel(parent?: Instance) -- Creates a native Roblox InputActionLabel bound to this action\r\n```\r\n\r\n### Engine Instance Access\r\n\r\n```lua\r\n:GetInputAction() -- Returns underlying Roblox InputAction instance\r\n:GetInputContext() -- Returns underlying Roblox InputContext instance\r\n:GetInputBinding(key?) -- Returns specific child InputBinding instance\r\n:GetPreferredBinding() -- Returns the active InputBinding currently driving the action\r\n```\r\n\r\n### InputActionType Management\r\n\r\n```lua\r\n:Fire(active, pressed) -- Fire the bind manually\r\n:GetState() -- Returns active state matching action type\r\n:SetScale(scale) -- Set Scale for Directions\r\n:GetScale() -- Get Scale for Directions\r\n:SetVectorScale(vector) -- Set VectorScale for Direction2D / Direction3D\r\n:GetVectorScale() -- Get VectorScale for Direction2D / Direction3D\r\n:SetResponseCurve(curve) -- Set ResponseCurve for Directions\r\n:GetResponseCurve() -- Get ResponseCurve for Directions\r\n:SetPressedThreshold(threshold) -- Set Pressed Threshold for Bool\r\n:GetPressedThreshold() -- Get Pressed Threshold for Bool\r\n:SetReleasedThreshold(threshold) -- Set Released Threshold for Bool\r\n:GetReleasedThreshold() -- Get Released Threshold for Bool\r\n:SetPointerIndex(index) -- Set PointerIndex\r\n:GetPointerIndex() -- Get PointerIndex\r\n:SetClampMagnitudeToOne(bool) -- Set ClampMagnitudeToOne\r\n:GetClampMagnitudeToOne() -- Get ClampMagnitudeToOne\r\n```\r\n\r\n---\r\n\r\n## Utilities / Introspection\r\n\r\n```lua\r\n:GetCooldownRemaining() -- number: seconds remaining on the current cooldown (0 if none)\r\n:CooldownEnded() -- boolean: true when cooldown is inactive, false while active\r\n:IsBuffered() -- boolean: whether an input is currently buffered\r\n:ResetBuffer() -- void: clears any buffered input\r\n:GetBufferedVariant() -- variant?: the buffered value, if present\r\n:GetBufferedKey() -- Enum.KeyCode?: the buffered key code, if present\r\n:GetActiveBindCount() -- number: how many binds are currently active\r\n:GetToggleState() -- boolean: current toggle state for toggle-mode binds\r\n:GetActiveMainKey() -- Enum.KeyCode?: which main key is currently active, if any\r\n```\r\n\r\n### Properties\r\n\r\n```lua\r\nKeybind.Name -- The bind's name\r\nKeybind.Active -- Current activation state\r\nKeybind.Enabled -- Whether bind is enabled\r\nKeybind.Priority -- InputContext priority\r\nKeybind.Sink -- InputContext sinkability\r\nKeybind.Hold -- Hold mode state\r\nKeybind.Cooldown -- Cooldown duration\r\nKeybind.Activated -- IAScriptSignal event (active, pressed)\r\nKeybind.Started -- IAScriptSignal event, fired on input start\r\nKeybind.Ended -- IAScriptSignal event, fired on input end\r\nKeybind.Scale -- InputBinding Scale\r\nKeybind.VectorScale -- InputBinding VectorScale\r\nKeybind.ResponseCurve -- InputBinding ResponseCurve\r\nKeybind.PressedThreshold -- InputBinding PressedThreshold\r\nKeybind.ReleasedThreshold -- InputBinding ReleasedThreshold\r\nKeybind.PointerIndex -- InputBinding PointerIndex\r\nKeybind.ClampMagnitudeToOne -- InputBinding ClampMagnitudeToOne\r\n```\r\n\r\nThe `Activated`, `Started`, and `Ended` events work like standard Roblox signals with `:Connect()`, `:Once()`, `:Wait()`, and `:Fire()` methods.\r\n\r\n---\r\n\r\n## Example: Sprint & Walk System\r\n\r\n```lua\r\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\r\nlocal Players = game:GetService(\"Players\")\r\nlocal IIAS = require(ReplicatedStorage.IllusionIAS)\r\n\r\nlocal player = Players.LocalPlayer\r\nlocal character = player.Character or player.CharacterAdded:Wait()\r\nlocal humanoid = character:WaitForChild(\"Humanoid\")\r\n\r\n-- Create binds\r\nlocal sprint = IIAS.new(\"Sprint\")\r\nlocal walk = IIAS.new(\"Walk\")\r\n\r\n-- Configure as hold buttons\r\nsprint:SetHold(true)\r\nwalk:SetHold(true)\r\n\r\n-- Set keybinds\r\nsprint:AddBind(Enum.KeyCode.LeftShift)\r\nwalk:AddBind(Enum.KeyCode.LeftControl)\r\n\r\n-- Connect to humanoid\r\nsprint.Activated:Connect(function(active, pressed)\r\n humanoid.WalkSpeed = active and 24 or 16\r\nend)\r\n\r\nwalk.Activated:Connect(function(active, pressed)\r\n humanoid.WalkSpeed = active and 8 or 16\r\nend)\r\n```\r\n\r\n---\r\n\r\n## Example: Advanced Keybind with Cooldown\r\n\r\n```lua\r\nlocal IIAS = require(game.ReplicatedStorage.IllusionIAS)\r\n\r\nlocal bind = IIAS.new(\"Bind\")\r\n\r\n-- Shift + F to activate\r\nbind:AddBind(Enum.KeyCode.F, Enum.KeyCode.LeftShift)\r\n\r\n-- Toggle mode\r\nbind:SetHold(false)\r\n\r\n-- 2 second cooldown\r\nbind:SetCooldown(2)\r\n\r\n-- Double-tap within 0.5s to activate\r\nbind:SetTapActivation(2, 0.5)\r\n\r\nbind.Activated:Connect(function(active, pressed)\r\n if not bind:CooldownEnded() then return end\r\n print(\"Bind state:\", active, \"| Key pressed:\", pressed)\r\nend)\r\n```\r\n\r\n---\r\n\r\n## Feedback & Support\r\n\r\nI'd love to hear your thoughts! Please share:\r\n- Feature requests\r\n- Bug reports\r\n- Use cases from your projects\r\n- Suggestions for improvements\r\n\r\nThanks for checking out IllusionIAS - happy scripting!\r\n\r\n*- Illusion* | discord: @illuusion\r\n","readmeTruncated":false}