@hexium-softworks/inputservice 1.0.1

package/src/Shared/InputServiceConfigUtils.luau

@@ -0,0 +1,168 @@
+--!strict
+--[=[
+	Validation helpers for InputService configs.
+
+	@class InputServiceConfigUtils
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local Table = require("Table")
+
+local InputServiceConfigUtils = {}
+
+type FieldMap = { [string]: string }
+
+local CONTEXT_FIELDS: FieldMap = Table.readonly({
+	Name = "string",
+	Enabled = "boolean",
+	Priority = "number",
+	Sink = "boolean",
+	Actions = "table",
+})
+
+local ACTION_FIELDS: FieldMap = Table.readonly({
+	Name = "string",
+	DisplayName = "string",
+	Enabled = "boolean",
+	Type = "InputActionType",
+	Bindings = "table",
+})
+
+local BINDING_FIELDS: FieldMap = Table.readonly({
+	Name = "string",
+	Type = "InputBindingType",
+	KeyCode = "KeyCode",
+	UIButton = "GuiButton",
+	UIModifier = "GuiButton",
+	PrimaryModifier = "KeyCode",
+	SecondaryModifier = "KeyCode",
+	DisplayName = "string",
+	DisplayImage = "Content",
+	PressedThreshold = "number",
+	ReleasedThreshold = "number",
+	ResponseCurve = "number",
+	Scale = "number",
+	Vector2Scale = "Vector2",
+	Vector3Scale = "Vector3",
+	PointerIndex = "number",
+	ClampMagnitudeToOne = "boolean",
+	Up = "KeyCode",
+	Down = "KeyCode",
+	Left = "KeyCode",
+	Right = "KeyCode",
+	Forward = "KeyCode",
+	Backward = "KeyCode",
+})
+
+local function validateName(value: any, path: string): ()
+	assert(typeof(value) == "string", string.format("%s.Name must be a string", path))
+	assert(#value > 0, string.format("%s.Name must not be empty", path))
+	assert(#value <= 100, string.format("%s.Name must be 100 characters or fewer", path))
+	assert(not string.find(value, "[%c/]"), string.format("%s.Name contains unsupported characters", path))
+end
+
+local function validateEnumItem(value: any, enumType: any, fieldName: string): ()
+	assert(typeof(value) == "EnumItem", string.format("%s must be an EnumItem", fieldName))
+	assert(value.EnumType == enumType, string.format("%s must be a member of %s", fieldName, tostring(enumType)))
+end
+
+local function validateGuiButton(value: any, fieldName: string): ()
+	assert(typeof(value) == "Instance", string.format("%s must be a GuiButton", fieldName))
+	assert(value:IsA("GuiButton"), string.format("%s must be a GuiButton", fieldName))
+end
+
+local function validateField(value: any, expectedType: string, fieldName: string): ()
+	if expectedType == "KeyCode" then
+		validateEnumItem(value, Enum.KeyCode, fieldName)
+	elseif expectedType == "InputActionType" then
+		validateEnumItem(value, Enum.InputActionType, fieldName)
+	elseif expectedType == "InputBindingType" then
+		validateEnumItem(value, Enum.InputBindingType, fieldName)
+	elseif expectedType == "GuiButton" then
+		validateGuiButton(value, fieldName)
+	elseif expectedType == "Content" then
+		assert(typeof(value) == "string" or typeof(value) == "Content", string.format("%s must be Content", fieldName))
+	else
+		assert(typeof(value) == expectedType, string.format("%s must be %s", fieldName, expectedType))
+	end
+end
+
+local function validateKnownFields(config: { [any]: any }, allowedFields: FieldMap, path: string): ()
+	for key, value in config do
+		assert(typeof(key) == "string", string.format("%s contains a non-string key", path))
+
+		local expectedType = allowedFields[key]
+		assert(expectedType ~= nil, string.format("%s.%s is not a supported config field", path, key))
+
+		if value ~= nil then
+			validateField(value, expectedType, string.format("%s.%s", path, key))
+		end
+	end
+end
+
+function InputServiceConfigUtils.validateBindingConfig(config: any, path: string?): ()
+	local bindingPath = path or "Binding"
+	assert(typeof(config) == "table", string.format("%s must be a table", bindingPath))
+	validateKnownFields(config, BINDING_FIELDS, bindingPath)
+	validateName(config.Name, bindingPath)
+
+	if config.PressedThreshold ~= nil and config.ReleasedThreshold ~= nil then
+		assert(
+			config.PressedThreshold >= config.ReleasedThreshold,
+			string.format("%s.PressedThreshold must be greater than or equal to ReleasedThreshold", bindingPath)
+		)
+	end
+end
+
+function InputServiceConfigUtils.validateActionConfig(config: any, path: string?): ()
+	local actionPath = path or "Action"
+	assert(typeof(config) == "table", string.format("%s must be a table", actionPath))
+	validateKnownFields(config, ACTION_FIELDS, actionPath)
+	validateName(config.Name, actionPath)
+
+	if config.Bindings ~= nil then
+		for index, bindingConfig in config.Bindings do
+			assert(typeof(index) == "number", string.format("%s.Bindings must be an array", actionPath))
+			InputServiceConfigUtils.validateBindingConfig(
+				bindingConfig,
+				string.format("%s.Bindings[%d]", actionPath, index)
+			)
+		end
+	end
+end
+
+function InputServiceConfigUtils.validateContextConfig(config: any, path: string?): ()
+	local contextPath = path or "Context"
+	assert(typeof(config) == "table", string.format("%s must be a table", contextPath))
+	validateKnownFields(config, CONTEXT_FIELDS, contextPath)
+	validateName(config.Name, contextPath)
+
+	if config.Actions ~= nil then
+		for index, actionConfig in config.Actions do
+			assert(typeof(index) == "number", string.format("%s.Actions must be an array", contextPath))
+			InputServiceConfigUtils.validateActionConfig(
+				actionConfig,
+				string.format("%s.Actions[%d]", contextPath, index)
+			)
+		end
+	end
+end
+
+function InputServiceConfigUtils.assertCanCreateInputClass(className: string): ()
+	local ok, instance = pcall(Instance.new, className, nil)
+	if ok and typeof(instance) == "Instance" then
+		instance:Destroy()
+		return
+	end
+
+	error(
+		string.format(
+			"%s is not available in this Roblox runtime. Enable the Input Action System beta or run in a newer engine.",
+			className
+		),
+		2
+	)
+end
+
+return InputServiceConfigUtils

package/src/Shared/InputServiceConfigUtils.spec.luau

@@ -0,0 +1,86 @@
+--!strict
+--[=[
+	@class InputServiceConfigUtils.spec
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local InputServiceConfigUtils = require("InputServiceConfigUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function getBoolInputActionType(): any
+	local ok, value = pcall(function()
+		return Enum.InputActionType.Bool
+	end)
+
+	if ok then
+		return value
+	end
+
+	return nil
+end
+
+describe("InputServiceConfigUtils", function()
+	it("accepts a valid context config", function()
+		expect(function()
+			InputServiceConfigUtils.validateContextConfig({
+				Name = "PlayContext",
+				Enabled = true,
+				Priority = 2000,
+				Sink = true,
+				Actions = {
+					{
+						Name = "Sprint",
+						Bindings = {
+							{
+								Name = "Keyboard",
+								KeyCode = Enum.KeyCode.LeftShift,
+							},
+						},
+					},
+				},
+			})
+		end).never.toThrow()
+	end)
+
+	if getBoolInputActionType() ~= nil then
+		it("accepts InputActionType enum values", function()
+			expect(function()
+				InputServiceConfigUtils.validateActionConfig({
+					Name = "Sprint",
+					Type = getBoolInputActionType(),
+				})
+			end).never.toThrow()
+		end)
+	end
+
+	it("rejects unknown fields", function()
+		expect(function()
+			InputServiceConfigUtils.validateContextConfig({
+				Name = "PlayContext",
+				RemoteEventName = "Nope",
+			})
+		end).toThrow()
+	end)
+
+	it("rejects unsafe names", function()
+		expect(function()
+			InputServiceConfigUtils.validateActionConfig({
+				Name = "Bad/Action",
+			})
+		end).toThrow()
+	end)
+
+	it("rejects mismatched enum types", function()
+		expect(function()
+			InputServiceConfigUtils.validateActionConfig({
+				Name = "Sprint",
+				Type = Enum.KeyCode.E,
+			})
+		end).toThrow()
+	end)
+end)

package/src/Shared/InputServiceConstants.luau

@@ -0,0 +1,28 @@
+--!strict
+--[=[
+	Constants for the input action system wrapper.
+
+	@class InputServiceConstants
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local Table = require("Table")
+
+export type InputServiceConstants = {
+	ROOT_FOLDER_NAME: string,
+	ROOT_FOLDER_CLASS_NAME: string,
+	CONTEXT_CLASS_NAME: string,
+	ACTION_CLASS_NAME: string,
+	BINDING_CLASS_NAME: string,
+	DEFAULT_CONTEXT_PRIORITY: number,
+}
+
+return Table.readonly({
+	ROOT_FOLDER_NAME = "Inputs",
+	ROOT_FOLDER_CLASS_NAME = "Folder",
+	CONTEXT_CLASS_NAME = "InputContext",
+	ACTION_CLASS_NAME = "InputAction",
+	BINDING_CLASS_NAME = "InputBinding",
+	DEFAULT_CONTEXT_PRIORITY = 0,
+} :: InputServiceConstants)

package/src/Shared/InputServiceInstanceUtils.luau

@@ -0,0 +1,194 @@
+--!strict
+--[=[
+	Instance creation and upsert utilities for InputService.
+
+	@class InputServiceInstanceUtils
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local InputServiceConfigUtils = require("InputServiceConfigUtils")
+local InputServiceConstants = require("InputServiceConstants")
+local InputServiceTypes = require("InputServiceTypes")
+
+type InputContextConfig = InputServiceTypes.InputContextConfig
+type InputActionConfig = InputServiceTypes.InputActionConfig
+type InputBindingConfig = InputServiceTypes.InputBindingConfig
+
+local InputServiceInstanceUtils = {}
+
+local CONTEXT_PROPERTIES = { "Enabled", "Priority", "Sink" }
+local ACTION_PROPERTIES = { "DisplayName", "Enabled", "Type" }
+local BINDING_PROPERTIES = {
+	"Type",
+	"KeyCode",
+	"UIButton",
+	"UIModifier",
+	"PrimaryModifier",
+	"SecondaryModifier",
+	"DisplayName",
+	"DisplayImage",
+	"PressedThreshold",
+	"ReleasedThreshold",
+	"ResponseCurve",
+	"Scale",
+	"Vector2Scale",
+	"Vector3Scale",
+	"PointerIndex",
+	"ClampMagnitudeToOne",
+	"Up",
+	"Down",
+	"Left",
+	"Right",
+	"Forward",
+	"Backward",
+}
+
+local function findTypedChild(parent: Instance, name: string, className: string): Instance?
+	local child = parent:FindFirstChild(name)
+	if child == nil then
+		return nil
+	end
+
+	assert(
+		child:IsA(className),
+		string.format("%s exists but is a %s, not %s", child:GetFullName(), child.ClassName, className)
+	)
+	return child
+end
+
+local function upsertChild(parent: Instance, name: string, className: string): Instance
+	local child = findTypedChild(parent, name, className)
+	if child then
+		return child
+	end
+
+	InputServiceConfigUtils.assertCanCreateInputClass(className)
+
+	local instance = Instance.new(className)
+	instance.Name = name
+	instance.Parent = parent
+	return instance
+end
+
+local function applyProperties(instance: Instance, config: { [string]: any }, propertyNames: { string }): ()
+	local writableInstance = instance :: any
+	for _, propertyName in propertyNames do
+		local value = config[propertyName]
+		if value ~= nil then
+			writableInstance[propertyName] = value
+		end
+	end
+end
+
+function InputServiceInstanceUtils.getOrCreateRootFolder(parent: Instance): Folder
+	local child = parent:FindFirstChild(InputServiceConstants.ROOT_FOLDER_NAME)
+	if child then
+		assert(
+			child:IsA(InputServiceConstants.ROOT_FOLDER_CLASS_NAME),
+			string.format(
+				"%s must be a %s",
+				child:GetFullName(),
+				InputServiceConstants.ROOT_FOLDER_CLASS_NAME
+			)
+		)
+		return child :: Folder
+	end
+
+	local folder = Instance.new(InputServiceConstants.ROOT_FOLDER_CLASS_NAME)
+	folder.Name = InputServiceConstants.ROOT_FOLDER_NAME
+	folder.Parent = parent
+	return folder :: Folder
+end
+
+function InputServiceInstanceUtils.getContext(rootFolder: Instance, contextName: string): InputContext?
+	local context = findTypedChild(rootFolder, contextName, InputServiceConstants.CONTEXT_CLASS_NAME)
+	return context :: InputContext?
+end
+
+function InputServiceInstanceUtils.getAction(context: Instance, actionName: string): InputAction?
+	assert(context:IsA(InputServiceConstants.CONTEXT_CLASS_NAME), "Context must be an InputContext")
+
+	local action = findTypedChild(context, actionName, InputServiceConstants.ACTION_CLASS_NAME)
+	return action :: InputAction?
+end
+
+function InputServiceInstanceUtils.getBinding(action: Instance, bindingName: string): InputBinding?
+	assert(action:IsA(InputServiceConstants.ACTION_CLASS_NAME), "Action must be an InputAction")
+
+	local binding = findTypedChild(action, bindingName, InputServiceConstants.BINDING_CLASS_NAME)
+	return binding :: InputBinding?
+end
+
+function InputServiceInstanceUtils.upsertBinding(action: Instance, config: InputBindingConfig): InputBinding
+	assert(action:IsA(InputServiceConstants.ACTION_CLASS_NAME), "Binding parent must be an InputAction")
+	InputServiceConfigUtils.validateBindingConfig(config)
+
+	local binding = upsertChild(action, config.Name, InputServiceConstants.BINDING_CLASS_NAME) :: InputBinding
+	applyProperties(binding, config :: any, BINDING_PROPERTIES)
+	return binding
+end
+
+function InputServiceInstanceUtils.upsertAction(context: Instance, config: InputActionConfig): InputAction
+	assert(context:IsA(InputServiceConstants.CONTEXT_CLASS_NAME), "Action parent must be an InputContext")
+	InputServiceConfigUtils.validateActionConfig(config)
+
+	local action = upsertChild(context, config.Name, InputServiceConstants.ACTION_CLASS_NAME) :: InputAction
+	applyProperties(action, config :: any, ACTION_PROPERTIES)
+
+	if config.Bindings then
+		for _, bindingConfig in config.Bindings do
+			InputServiceInstanceUtils.upsertBinding(action, bindingConfig)
+		end
+	end
+
+	return action
+end
+
+function InputServiceInstanceUtils.upsertContext(rootFolder: Instance, config: InputContextConfig): InputContext
+	assert(rootFolder:IsA(InputServiceConstants.ROOT_FOLDER_CLASS_NAME), "Context parent must be the input root Folder")
+	InputServiceConfigUtils.validateContextConfig(config)
+
+	local context = upsertChild(rootFolder, config.Name, InputServiceConstants.CONTEXT_CLASS_NAME) :: InputContext
+	applyProperties(context, config :: any, CONTEXT_PROPERTIES)
+
+	if config.Actions then
+		for _, actionConfig in config.Actions do
+			InputServiceInstanceUtils.upsertAction(context, actionConfig)
+		end
+	end
+
+	return context
+end
+
+function InputServiceInstanceUtils.removeContext(rootFolder: Instance, contextName: string): boolean
+	local context = InputServiceInstanceUtils.getContext(rootFolder, contextName)
+	if not context then
+		return false
+	end
+
+	context:Destroy()
+	return true
+end
+
+function InputServiceInstanceUtils.removeAction(context: Instance, actionName: string): boolean
+	local action = InputServiceInstanceUtils.getAction(context, actionName)
+	if not action then
+		return false
+	end
+
+	action:Destroy()
+	return true
+end
+
+function InputServiceInstanceUtils.removeBinding(action: Instance, bindingName: string): boolean
+	local binding = InputServiceInstanceUtils.getBinding(action, bindingName)
+	if not binding then
+		return false
+	end
+
+	binding:Destroy()
+	return true
+end
+
+return InputServiceInstanceUtils

package/src/Shared/InputServiceInstanceUtils.spec.luau

@@ -0,0 +1,100 @@
+--!strict
+--[=[
+	@class InputServiceInstanceUtils.spec
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local InputServiceConstants = require("InputServiceConstants")
+local InputServiceInstanceUtils = require("InputServiceInstanceUtils")
+local Jest = require("Jest")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function canCreateInputActionInstances(): boolean
+	local ok, instance = pcall(Instance.new, InputServiceConstants.CONTEXT_CLASS_NAME, nil)
+	if ok and typeof(instance) == "Instance" then
+		instance:Destroy()
+		return true
+	end
+
+	return false
+end
+
+describe("InputServiceInstanceUtils", function()
+	it("guards unsupported runtimes", function()
+		expect(typeof(canCreateInputActionInstances())).toEqual("boolean")
+	end)
+
+	if canCreateInputActionInstances() then
+		it("upserts contexts without duplicating actions or bindings", function()
+			local root = Instance.new("Folder")
+			root.Name = InputServiceConstants.ROOT_FOLDER_NAME
+
+			local context = InputServiceInstanceUtils.upsertContext(root, {
+				Name = "PlayContext",
+				Enabled = true,
+				Priority = 10,
+				Sink = false,
+				Actions = {
+					{
+						Name = "Sprint",
+						Type = Enum.InputActionType.Bool,
+						Bindings = {
+							{
+								Name = "Keyboard",
+								KeyCode = Enum.KeyCode.LeftShift,
+							},
+						},
+					},
+				},
+			})
+
+			InputServiceInstanceUtils.upsertContext(root, {
+				Name = "PlayContext",
+				Priority = 25,
+				Actions = {
+					{
+						Name = "Sprint",
+						DisplayName = "Run",
+						Bindings = {
+							{
+								Name = "Keyboard",
+								KeyCode = Enum.KeyCode.E,
+							},
+						},
+					},
+				},
+			})
+
+			local sprint = context:FindFirstChild("Sprint")
+			expect(context.Priority).toEqual(25)
+			expect(#root:GetChildren()).toEqual(1)
+			expect(sprint ~= nil).toEqual(true)
+			expect(#(sprint :: Instance):GetChildren()).toEqual(1)
+
+			root:Destroy()
+		end)
+
+		it("removes only targeted objects", function()
+			local root = Instance.new("Folder")
+			root.Name = InputServiceConstants.ROOT_FOLDER_NAME
+
+			local context = InputServiceInstanceUtils.upsertContext(root, {
+				Name = "PlayContext",
+				Actions = {
+					{ Name = "Sprint" },
+					{ Name = "Jump" },
+				},
+			})
+
+			expect(InputServiceInstanceUtils.removeAction(context, "Sprint")).toEqual(true)
+			expect(context:FindFirstChild("Sprint")).toEqual(nil)
+			expect(context:FindFirstChild("Jump") ~= nil).toEqual(true)
+
+			root:Destroy()
+		end)
+	end
+end)

package/src/Shared/InputServiceTypes.luau

@@ -0,0 +1,63 @@
+--!strict
+--[=[
+	Shared public types for InputService.
+
+	@class InputServiceTypes
+]=]
+
+local InputServiceTypes = {}
+
+export type InputActionState = boolean | number | Vector2 | Vector3
+
+export type InputBindingConfig = {
+	Name: string,
+	Type: Enum.InputBindingType?,
+	KeyCode: Enum.KeyCode?,
+	UIButton: GuiButton?,
+	UIModifier: GuiButton?,
+	PrimaryModifier: Enum.KeyCode?,
+	SecondaryModifier: Enum.KeyCode?,
+	DisplayName: string?,
+	DisplayImage: any?,
+	PressedThreshold: number?,
+	ReleasedThreshold: number?,
+	ResponseCurve: number?,
+	Scale: number?,
+	Vector2Scale: Vector2?,
+	Vector3Scale: Vector3?,
+	PointerIndex: number?,
+	ClampMagnitudeToOne: boolean?,
+	Up: Enum.KeyCode?,
+	Down: Enum.KeyCode?,
+	Left: Enum.KeyCode?,
+	Right: Enum.KeyCode?,
+	Forward: Enum.KeyCode?,
+	Backward: Enum.KeyCode?,
+}
+
+export type InputActionConfig = {
+	Name: string,
+	DisplayName: string?,
+	Enabled: boolean?,
+	Type: Enum.InputActionType?,
+	Bindings: { InputBindingConfig }?,
+}
+
+export type InputContextConfig = {
+	Name: string,
+	Enabled: boolean?,
+	Priority: number?,
+	Sink: boolean?,
+	Actions: { InputActionConfig }?,
+}
+
+export type ActionSignalBundle = {
+	Pressed: any,
+	Released: any,
+	StateChanged: any,
+	EnabledChanged: any,
+	PreferredBindingChanged: any,
+	Destroy: (ActionSignalBundle) -> (),
+}
+
+return InputServiceTypes

package/src/jest.config.lua

@@ -0,0 +1,3 @@
+return {
+	testMatch = { "**/*.spec" },
+}

package/src/node_modules.project.json

@@ -0,0 +1,7 @@
+{
+  "name": "node_modules",
+  "globIgnorePaths": [ "**/.package-lock.json" ],
+  "tree": {
+    "$path": { "optional": "../node_modules" }
+  }
+}