{"id":"vocksel/context-controls","name":"context-controls","scope":"vocksel","platform":"roblox","description":"Wrapper for ContextActionService with an easy to use API ","version":"1.0.0","latest":"1.0.0","versions":["1.0.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"a9b274b477ca15fdefac57409b2a9045db86a6456e605ec01f51c7017d7f785e","likes":0,"downloads":0,"install":"forest install vocksel/context-controls","url":"https://forest.dev/p/roblox/vocksel/context-controls","files":"https://api.forest.dev/ai/package/roblox/vocksel/context-controls/files","readme":"# ContextControls\n\nWrapper around ContextActionService that provides a clean API for creating and\nbinding actions, along with flexible mobile button support.\n\n## Installation\n\n### Wally\n\nAdd the following to your `wally.toml`:\n\n```\n[dependencies]\nContextControls = \"vocksel/context-controls@v1.0.0\n```\n\n### Model File\n\n* Download a copy of the rbxm from the [releases page](https://github.com/vocksel/context-controls/releases/latest) under the Assets section. \n* Drag and drop the file into Roblox Studio to add it to your experience.\n\n## Usage\n\n```lua\nlocal ContextControls = require(game.ReplicatedStorage.ContextControls)\n\nlocal action = ContextControls.createAction({\n    name = \"foo\",\n    inputTypes = {\n        Enum.KeyCode.E,\n        Enum.KeyCode.ButtonX,\n    },\n    callback = function(input: InputObject)\n        print(\"Hello world!\")\n    end,\n})\n\naction:bind()\n```\n\n## API\n\n**ContextControls.createAction(actionObject): Action**\n\nConstructs an Action from a table of properties. This allows you to setup\neverything, such as the name, callback, and input types, without having to call\nany methods.\n\nMost if not all properties of the Action class listed below can be used here.\n\n```lua\nlocal action = Action.fromObject({\n\tname = \"foo\",\n\tinputTypes = {\n\t\tEnum.KeyCode.E,\n\t\tEnum.UserInputType.MouseButton1,\n\t},\n\tcallback = function(input: InputObject)\n\t\tprint(\"Hello, world!\")\n\tend\n})\n```\n\n**ContextControls.getTouchGui(): GuiObject | nil**\n\nReturns the LocalPlayer's TouchGui if they are on a touch enabled device, nil otherwise.\n\n```lua\nlocal touchGui = ContextControls.getTouchGui()\nprint(touchGui:GetFullName()) -- Players.Player1.PlayerGui.TouchGui\n```\n\n**ContextControls.getJumpButton(): GuiObject | nil**\n\nReturns the LocalPlayer's JumpButton if they are on a touch enabled device, nil otherwise.\n\n```lua\nlocal jumpButton = ContextControls.getJumpButton()\nprint(jumpButton:GetFullName()) -- ...TouchGui.TouchControlFrame.JumpButton\n```\n\n## Action\n\nThis is the class that wraps around ContextActionService to provide a better API\nto work with. Use one of the constructors to create one,\n\n### Constructors\n\n**new(name: string): Action**\n\nConstructs an Action instance from a name. You then need to use the various\nmethods of this class to setup the callback, input types, and anything else\nbefore binding.\n\n```lua\nlocal action = Action.new(\"foo\")\n\naction:setInputTypes({\n\tEnum.KeyCode.E,\n\tEnum.UserInputType.MouseButton1,\n})\n\naction:setCallback(function(input: InputObject)\n\tprint(\"Hello, world!\")\nend)\n```\n\n**fromObject(actionObject): Action**\n\nConstructs an Action from a table of properties. This allows you to setup\neverything, such as the name, callback, and input types, without having to call\nany methods.\n\nAll properties listed below can be used here.\n\n```lua\nlocal action = Action.fromObject({\n\tname = \"foo\",\n\tinputTypes = {\n\t\tEnum.KeyCode.E,\n\t\tEnum.UserInputType.MouseButton1,\n\t},\n\tcallback = function(input: InputObject)\n\t\tprint(\"Hello, world!\")\n\tend\n})\n```\n\n### Properties\n\n**name: string**\n\nThe name of the action.\n\n**callback: function**\n\nThe function that gets run when the action is triggered.\n\n**inputTypes: Array<KeyCode|UserInputType|PlayerActions|string>**\n\nThe various input types that the action responds to.\n\n**inputState: UserInputState (optional)**\n\nA specific UserInputState that the callback responds to.\n\nBy default, the callback is called twice: once when the user starts interacting,\nand again when they stop. This is because ContextActionService does not use\n`InputBegan` or `InputEnd` events like UserInputService. It triggers the\ncallback for both, and leaves it up to the user to filter out the one they want.\n\nInstead of having a to check `if input.UserInputState == Enum.UserInputState.Foo`\nin your callback, you can simply set this property.\n\n**priority: integer (optional)**\n\nSets the priority that ContextActionService will use for the action. By default\nthis is `Enum.ContextActionPriority.Default.Value`\n\n**isBound: boolean (readonly)**\n\nWhether or not the action is currently bound.\n\nThis is managed internally and should not be set from outside the class.\n\n### Methods\n\n**setCallback(callback: function): void**\n\nSets the callback for the action. This is what gets called when one of the input\ntypes is activated by the user.\n\n```lua\nlocal action = Action.new(\"foo\")\n\naction:setCallback(function(input: InputObject)\n\tprint(\"Hello world!\")\nend)\n```\n\n**setInputTypes(inputTypes: Array<KeyCode|UserInputType|PlayerActions|string>): void**\n\nSets the input types that the action will be triggered for.\n\n```lua\nlocal action = Action.new(\"foo\")\n\naction:setInputTypes({\n\tEnum.KeyCode.E,\n\tEnum.KeyCode.ButtonX,\n})\n```\n\n**bindAtPriority(priority: integer): void**\n\nBinds the action at the given priority level. From here, any of the input types\nbeing triggered will cause the callback to be run.\n\nIf the callback or input types are not set, this function will error.\n\nIf the function is already bound, it will error.\n\n```lua\nlocal action = Action.new(\"foo\")\naction:setCallback(...)\naction:setInputTypes(...)\n\naction:bindAtPriority(Enum.ContextActionPriority.High.Value)\n```\n\n**bind(): void**\n\n**Binds the action using the default priority level\n(`Enum.ContextActionPriority.Default.Value`). From here, any of the input types\nbeing triggered will cause the callback to be run.\n\nIf the callback or input types are not set, this function will error.\n\nIf the function is already bound, it will error.\n\n```lua\nlocal action = Action.new(\"foo\")\naction:setCallback(...)\naction:setInputTypes(...)\n\naction:bind()\n```\n\n**unbind(): void**\n\nUnbinds the action so that the callback will not be run when one of the input\ntypes is triggered.\n\n```lua\nlocal action = Action.new(\"foo\")\naction:setCallback(...)\naction:setInputTypes(...)\n\naction:bind()\n\n-- later\naction:unbind()\n```\n\n**addTrigger(trigger: ProximityPrompt, callback: function): void**\n\nAutomatically binds and unbinds the action when in range of the ProximityPrompt\nacting as a trigger.\n\nWith this method, you do not need to call `bind()`, `unbind()`, or\n`setCallback()`. These methods are all handled automatically based on\n[PromptShown](https://developer.roblox.com/en-us/api-reference/event/ProximityPrompt/PromptShown)\nand [PromptHidden](https://developer.roblox.com/en-us/api-reference/event/ProximityPrompt/PromptHidden)\nfiring.\n\n```lua\nlocal action = Action.new(\"foo\")\naction:setInputTypes(...)\n\naction:addTrigger(trigger, function(input: InputObject)\n\tprint(\"Hello world!\")\nend)\n```\n\nYou can add as many triggers as you want for the same action, and they will all\ntake control of binding and unbinding it.\n\nIf you use this method, it is recommended that you do not manually bind and\nunbind the action, as this could lead to unexpected results.\n\n## License\n\n[MIT License](LICENSE)","readmeTruncated":false}