@quenty/inputkeymaputils 3.4.1-canary.8533eea.0 → 3.5.1

package/CHANGELOG.md

@@ -3,7 +3,15 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [3.4.1-canary.8533eea.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/inputkeymaputils@3.4.0...@quenty/inputkeymaputils@3.4.1-canary.8533eea.0) (2021-12-18)
+## [3.5.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/inputkeymaputils@3.5.0...@quenty/inputkeymaputils@3.5.1) (2021-12-30)
+
+**Note:** Version bump only for package @quenty/inputkeymaputils
+
+
+
+
+
+# [3.5.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/inputkeymaputils@3.4.0...@quenty/inputkeymaputils@3.5.0) (2021-12-18)
 
 **Note:** Version bump only for package @quenty/inputkeymaputils
 

package/README.md

@@ -1,10 +1,10 @@
 ## InputKeyMapUtils
 <div align="center">
-  <a href="http://quenty.github.io/api/">
-    <img src="https://img.shields.io/badge/docs-website-green.svg" alt="Documentation" />
+  <a href="http://quenty.github.io/NevermoreEngine/">
+    <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/docs.yml/badge.svg" alt="Documentation status" />
   </a>
   <a href="https://discord.gg/mhtGUS8">
-    <img src="https://img.shields.io/badge/discord-nevermore-blue.svg" alt="Discord" />
+    <img src="https://img.shields.io/discord/385151591524597761?color=5865F2&label=discord&logo=discord&logoColor=white" alt="Discord" />
   </a>
   <a href="https://github.com/Quenty/NevermoreEngine/actions">
     <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/build.yml/badge.svg" alt="Build and release status" />
@@ -13,28 +13,9 @@
 
 Utility methods for input map
 
+<div align="center"><a href="https://quenty.github.io/NevermoreEngine/api/InputKeyMapUtils">View docs →</a></div>
+
 ## Installation
 ```
 npm install @quenty/inputkeymaputils --save
-```
-
-## Usage
-Usage is designed to be simple.
-
-### `InputKeyMapUtils.createKeyMap(inputMode, inputTypes)`
-
-### `InputKeyMapUtils.getInputTypesSetForActionBinding(inputKeyMapList)`
-
-### `InputKeyMapUtils.getInputTypesForActionBinding(inputKeyMapList)`
-Converts keymap into ContextActionService friendly types
-
-### `InputKeyMapUtils.getInputTypeListForMode(inputKeyMapList, inputMode)`
-
-### `InputKeyMapUtils.getInputTypeSetForMode(inputKeyMapList, inputMode)`
-
-### `InputKeyMapUtils.getInputModes(inputKeyMapList)`
-
-### `InputKeyMapUtils.isRobloxTouchButton(inputKeyMapList)`
-
-### `InputKeyMapUtils.isTapInWorld(inputKeyMapList)`
-
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/inputkeymaputils",
-  "version": "3.4.1-canary.8533eea.0",
+  "version": "3.5.1",
   "description": "Utility methods for input map",
   "keywords": [
     "Roblox",
@@ -26,12 +26,12 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/inputmode": "3.4.1-canary.8533eea.0",
-    "@quenty/loader": "3.1.1",
-    "@quenty/table": "2.1.0"
+    "@quenty/inputmode": "^3.5.1",
+    "@quenty/loader": "^3.1.2",
+    "@quenty/table": "^2.1.1"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "8533eeade3bf6835c0295785c1c326b9abee3222"
+  "gitHead": "d146c77d0a8e452824de0ab0b4b03ba0370bcc1b"
 }

package/src/Client/InputKeyMapUtils.lua

@@ -1,6 +1,45 @@
---- Utility methods for input map
--- @module InputKeyMapUtils
--- @author Quenty
+--[=[
+	Utility methods for input. Centralizes input. In the future, this will allow
+	user configuration.
+
+	```lua
+	local inputMap = {
+		JUMP = {
+			InputKeyMapUtils.createKeyMap(INPUT_MODES.KeyboardAndMouse, { Enum.KeyCode.Space });
+			InputKeyMapUtils.createKeyMap(INPUT_MODES.Gamepads, { Enum.KeyCode.ButtonA });
+			InputKeyMapUtils.createKeyMap(INPUT_MODES.Touch, { InputKeyMapUtils.createSlottedTouchButton("primary3") });
+		};
+		HONK = {
+			InputKeyMapUtils.createKeyMap(INPUT_MODES.KeyboardAndMouse, { Enum.KeyCode.H });
+			InputKeyMapUtils.createKeyMap(INPUT_MODES.Gamepads, { Enum.KeyCode.DPadUp });
+			InputKeyMapUtils.createKeyMap(INPUT_MODES.Touch, { InputKeyMapUtils.createSlottedTouchButton("primary2") });
+		};
+		BOOST = {
+			InputKeyMapUtils.createKeyMap(INPUT_MODES.KeyboardAndMouse, { Enum.KeyCode.LeftControl });
+			InputKeyMapUtils.createKeyMap(INPUT_MODES.Gamepads, { Enum.KeyCode.ButtonX });
+			InputKeyMapUtils.createKeyMap(INPUT_MODES.Touch, { InputKeyMapUtils.createSlottedTouchButton("primary4") });
+		};
+	}
+	```
+
+	Then, we can use these input maps in a variety of services, including [ScoredActionService] or
+	just binding directly to [ContextActionService].
+
+	```lua
+	local inputKeyMapList = inputMap.JUMP
+
+	ContextActionService:BindActionAtPriority(
+		"MyAction",
+		function(_actionName, userInputState, inputObject)
+			print("Process input", inputObject)
+		end,
+		InputKeyMapUtils.isRobloxTouchButton(inputKeyMapList),
+		Enum.ContextActionPriority.High.Value,
+		unpack(InputKeyMapUtils.getInputTypesForActionBinding(inputKeyMapList)))
+	```
+
+	@class InputKeyMapUtils
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -9,7 +48,34 @@ local Table = require("Table")
 
 local InputKeyMapUtils = {}
 
--- Should be called "createInputKeyMapList"
+--[=[
+	A valid input type that can be represented here.
+	@type InputType KeyCode | UserInputType | SlottedTouchButton | "TouchButton" | "Tap" | any
+	@within InputKeyMapUtils
+]=]
+
+--[=[
+	A grouping of input types for a specific input mode to use.
+
+	@interface InputKeyMap
+	.inputMode InputMode
+	.inputTypes { InputType }
+	@within InputKeyMapUtils
+]=]
+
+--[=[
+	A mapping of input keys to maps
+	@type InputKeyMapList { InputKeyMap }
+	@within InputKeyMapUtils
+]=]
+
+--[=[
+	Should be called "createInputKeyMap". Creates a new InputKeyMap.
+
+	@param inputMode InputMode
+	@param inputTypes { InputType }
+	@return InputKeyMap
+]=]
 function InputKeyMapUtils.createKeyMap(inputMode, inputTypes)
 	assert(type(inputMode) == "table", "Bad inputMode")
 	assert(type(inputTypes) == "table", "Bad inputTypes")
@@ -20,11 +86,19 @@ function InputKeyMapUtils.createKeyMap(inputMode, inputTypes)
 	})
 end
 
+--[=[
+	@param inputKeyMapList InputKeyMapList
+	@return { KeyCode | UserInputType }
+]=]
 function InputKeyMapUtils.getInputTypesSetForActionBinding(inputKeyMapList)
 	return Set.fromList(InputKeyMapUtils.getInputTypesForActionBinding(inputKeyMapList))
 end
 
---- Converts keymap into ContextActionService friendly types
+--[=[
+	Converts keymap into ContextActionService friendly types
+	@param inputKeyMapList InputKeyMapList
+	@return { KeyCode | UserInputType }
+]=]
 function InputKeyMapUtils.getInputTypesForActionBinding(inputKeyMapList)
 	assert(type(inputKeyMapList) == "table", "inputKeyMapList must be a table")
 	local types = {}
@@ -43,6 +117,12 @@ function InputKeyMapUtils.getInputTypesForActionBinding(inputKeyMapList)
 	return types
 end
 
+--[=[
+	Given an inputMode, gets the relevant lists available
+	@param inputKeyMapList InputKeyMapList
+	@param inputMode InputMode
+	@return { InputKeyMap }
+]=]
 function InputKeyMapUtils.getInputTypeListForMode(inputKeyMapList, inputMode)
 	assert(type(inputKeyMapList) == "table", "inputKeyMapList must be a table")
 
@@ -63,6 +143,13 @@ function InputKeyMapUtils.getInputTypeListForMode(inputKeyMapList, inputMode)
 	return results
 end
 
+--[=[
+	Gets a set of input types for a given mode from the list.
+
+	@param inputKeyMapList InputKeyMapList
+	@param inputMode InputMode
+	@return { [InputType] = true }
+]=]
 function InputKeyMapUtils.getInputTypeSetForMode(inputKeyMapList, inputMode)
 	assert(type(inputKeyMapList) == "table", "inputKeyMapList must be a table")
 
@@ -79,7 +166,12 @@ function InputKeyMapUtils.getInputTypeSetForMode(inputKeyMapList, inputMode)
 	return results
 end
 
+--[=[
+	Retrieves the set of input modes for a given list.
 
+	@param inputKeyMapList InputKeyMapList
+	@return { InputMode }
+]=]
 function InputKeyMapUtils.getInputModes(inputKeyMapList)
 	assert(type(inputKeyMapList) == "table", "inputKeyMapList must be a table")
 
@@ -92,6 +184,20 @@ function InputKeyMapUtils.getInputModes(inputKeyMapList)
 	return modes
 end
 
+--[=[
+	Internal data representing a slotted touch button
+	@interface SlottedTouchButtonData
+	.slotId string
+	.inputMode InputMode
+	@within InputKeyMapUtils
+]=]
+
+--[=[
+	Gets slotted touch button data for an inputKeyMapList
+
+	@param inputKeyMapList InputKeyMapList
+	@return { SlottedTouchButtonData }
+]=]
 function InputKeyMapUtils.getSlottedTouchButtonData(inputKeyMapList)
 	local slottedTouchButtons = {}
 
@@ -112,12 +218,34 @@ function InputKeyMapUtils.getSlottedTouchButtonData(inputKeyMapList)
 	return slottedTouchButtons
 end
 
+--[=[
+	Returns whether an inputType is a SlottedTouchButton type
+
+	@param inputType any
+	@return boolean
+]=]
 function InputKeyMapUtils.isSlottedTouchButton(inputType)
 	return type(inputType) == "table" and inputType.type == "SlottedTouchButton"
 end
 
--- Touch buttons should always show up in the same position
--- We use the SlotId to determine which slot we should put these buttons in
+--[=[
+	A touch button that goes into a specific slot. This ensures
+	consistent slot positions.
+
+	@interface SlottedTouchButton
+	.type "SlottedTouchButton"
+	.slotId string
+	@within InputKeyMapUtils
+]=]
+
+--[=[
+	Touch buttons should always show up in the same position
+	We use the SlotId to determine which slot we should put
+	these buttons in.
+
+	@param slotId string
+	@return SlottedTouchButton
+]=]
 function InputKeyMapUtils.createSlottedTouchButton(slotId)
 	assert(slotId == "primary1" or slotId == "primary2" or slotId == "primary3" or slotId == "primary4", "Bad slotId")
 
@@ -127,6 +255,14 @@ function InputKeyMapUtils.createSlottedTouchButton(slotId)
 	}
 end
 
+--[=[
+	Computes a unique id for an inputType which can be used
+	in a set to deduplicate/compare the objects. Used to know
+	when to exclude different types from each other.
+
+	@param inputType InputType
+	@return any
+]=]
 function InputKeyMapUtils.getUniqueKeyForInputType(inputType)
 	if InputKeyMapUtils.isSlottedTouchButton(inputType) then
 		return inputType.slotId
@@ -135,7 +271,11 @@ function InputKeyMapUtils.getUniqueKeyForInputType(inputType)
 	end
 end
 
--- Only returns true if we're a Roblox touch button
+--[=[
+	Only returns true if we're a Roblox touch button
+	@param inputKeyMapList InputKeyMapList
+	@return boolean
+]=]
 function InputKeyMapUtils.isRobloxTouchButton(inputKeyMapList)
 	for _, inputKeyMap in pairs(inputKeyMapList) do
 		assert(inputKeyMap.inputMode, "Bad inputKeyMap.inputMode")
@@ -151,6 +291,11 @@ function InputKeyMapUtils.isRobloxTouchButton(inputKeyMapList)
 	return false
 end
 
+--[=[
+	Whether this input type is a tap in the world input (for touched events)
+	@param inputKeyMapList InputKeyMapList
+	@return boolean
+]=]
 function InputKeyMapUtils.isTapInWorld(inputKeyMapList)
 	assert(type(inputKeyMapList) == "table", "inputKeyMap must be a table")
 

package/src/Client/ProximityPromptInputUtils.lua

@@ -1,6 +1,8 @@
----
--- @module ProximityPromptInputUtils
--- @author Quenty
+--[=[
+	Utility functions to configure a proximity prompt based upon the
+	input key map given.
+	@class ProximityPromptInputUtils
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -9,6 +11,12 @@ local INPUT_MODES = require("INPUT_MODES")
 
 local ProximityPromptInputUtils = {}
 
+--[=[
+	Creates an InputKeyMapList from a proximity prompt.
+
+	@param prompt ProximityPrompt
+	@return InputKeyMapList
+]=]
 function ProximityPromptInputUtils.inputKeyMapFromPrompt(prompt)
 	assert(typeof(prompt) == "Instance", "Bad prompt")
 
@@ -18,6 +26,13 @@ function ProximityPromptInputUtils.inputKeyMapFromPrompt(prompt)
 	}
 end
 
+
+--[=[
+	Sets the key codes for a proximity prompt to match an inputKeyMapList
+
+	@param prompt ProximityPrompt
+	@param inputKeyMapList InputKeyMapList
+]=]
 function ProximityPromptInputUtils.configurePromptFromInputKeyMap(prompt, inputKeyMapList)
 	assert(typeof(prompt) == "Instance", "Bad prompt")
 	assert(type(inputKeyMapList) == "table", "Bad inputKeyMapList")
@@ -34,6 +49,13 @@ function ProximityPromptInputUtils.configurePromptFromInputKeyMap(prompt, inputK
 	end
 end
 
+--[=[
+	Picks the first keyCode that matches the inputMode.
+
+	@param inputKeyMapList InputKeyMapList
+	@param inputMode InputMode
+	@return KeyCode?
+]=]
 function ProximityPromptInputUtils.getFirstInputKeyCode(inputKeyMapList, inputMode)
 	assert(type(inputKeyMapList) == "table", "Bad inputKeyMapList")
 	assert(inputMode, "Bad inputMode")