From 13e47e82aec1577fb736a60f0a3e1f4ea329343c Mon Sep 17 00:00:00 2001 From: Greenlamp Date: Thu, 16 May 2024 01:35:19 +0200 Subject: [PATCH] comment TSDOC for configHandler.ts --- src/configs/cfg_keyboard_azerty.ts | 2 +- src/configs/configHandler.ts | 175 ++++++++++++++++++++++------- src/configs/pad_dualshock.ts | 2 +- src/configs/pad_generic.ts | 2 +- src/configs/pad_unlicensedSNES.ts | 2 +- src/configs/pad_xbox360.ts | 2 +- src/inputs-controller.ts | 7 +- src/test/cfg_keyboard.example.ts | 2 +- src/test/helpers/menuManip.ts | 4 +- 9 files changed, 148 insertions(+), 50 deletions(-) diff --git a/src/configs/cfg_keyboard_azerty.ts b/src/configs/cfg_keyboard_azerty.ts index 3dc71103cc2..c1f94f4ef28 100644 --- a/src/configs/cfg_keyboard_azerty.ts +++ b/src/configs/cfg_keyboard_azerty.ts @@ -4,7 +4,7 @@ import {SettingKeyboard} from "#app/system/settings-keyboard"; const cfg_keyboard_azerty = { padID: 'keyboard', padType: 'default', - gamepadMapping: { + deviceMapping: { KEY_A: Phaser.Input.Keyboard.KeyCodes.A, KEY_B: Phaser.Input.Keyboard.KeyCodes.B, KEY_C: Phaser.Input.Keyboard.KeyCodes.C, diff --git a/src/configs/configHandler.ts b/src/configs/configHandler.ts index 3b31338fa5e..8a94bf47c78 100644 --- a/src/configs/configHandler.ts +++ b/src/configs/configHandler.ts @@ -1,64 +1,132 @@ +/** + * Retrieves the key associated with the specified keycode from the mapping. + * + * @param config - The configuration object containing the mapping. + * @param keycode - The keycode to search for. + * @returns The key associated with the specified keycode. + */ export function getKeyWithKeycode(config, keycode) { - return Object.keys(config.gamepadMapping).find(key => config.gamepadMapping[key] === keycode); + return Object.keys(config.deviceMapping).find(key => config.deviceMapping[key] === keycode); } +/** + * Retrieves the setting name associated with the specified keycode. + * + * @param config - The configuration object containing custom settings. + * @param keycode - The keycode to search for. + * @returns The setting name associated with the specified keycode. + */ export function getSettingNameWithKeycode(config, keycode) { const key = getKeyWithKeycode(config, keycode); return config.custom[key]; } +/** + * Retrieves the icon associated with the specified keycode. + * + * @param config - The configuration object containing icons. + * @param keycode - The keycode to search for. + * @returns The icon associated with the specified keycode. + */ export function getIconWithKeycode(config, keycode) { const key = getKeyWithKeycode(config, keycode); return config.icons[key]; } +/** + * Retrieves the button associated with the specified keycode. + * + * @param config - The configuration object containing settings. + * @param keycode - The keycode to search for. + * @returns The button associated with the specified keycode. + */ export function getButtonWithKeycode(config, keycode) { const settingName = getSettingNameWithKeycode(config, keycode); return config.settings[settingName]; } -export function getKeycodeWithKey(config, key) { - return config.gamepadMapping[key] -} - +/** + * Retrieves the key associated with the specified setting name. + * + * @param config - The configuration object containing custom settings. + * @param settingName - The setting name to search for. + * @returns The key associated with the specified setting name. + */ export function getKeyWithSettingName(config, settingName) { return Object.keys(config.custom).find(key => config.custom[key] === settingName); } +/** + * Retrieves the setting name associated with the specified key. + * + * @param config - The configuration object containing custom settings. + * @param key - The key to search for. + * @returns The setting name associated with the specified key. + */ export function getSettingNameWithKey(config, key) { - return config.custom[key] + return config.custom[key]; } +/** + * Retrieves the icon associated with the specified key. + * + * @param config - The configuration object containing icons. + * @param key - The key to search for. + * @returns The icon associated with the specified key. + */ export function getIconWithKey(config, key) { - return config.icons[key] + return config.icons[key]; } +/** + * Retrieves the icon for a special case where a key is bound to a different type of binding. + * This special case occurs when attempting to bind a key from either a main or alternate binding + * to a different type of binding, resulting in two main or two alternate bindings having the same action. + * In such cases, the two bindings are swapped to maintain uniqueness. + * + * @param config - The configuration object containing icons. + * @param keycode - The keycode to search for. + * @param settingName - The setting name to search for. + * @returns The icon associated with the special case or null if not found. + */ export function getIconSpecialCase(config, keycode, settingName) { - const potentialKey = isAlreadyBinded(config, keycode, settingName); + const potentialKey = getKeySolvingConflict(config, keycode, settingName); if (potentialKey) return getIconWithKey(config, potentialKey); return null; } +/** + * Retrieves the button associated with the specified setting name. + * + * @param config - The configuration object containing settings. + * @param settingName - The setting name to search for. + * @returns The button associated with the specified setting name. + */ export function getButtonWithSettingName(config, settingName) { return config.settings[settingName]; } -export function getButtonWithKey(config, key) { - const settingName = config.custom[key]; - return getButtonWithSettingName(config, settingName); -} - +/** + * Retrieves the icon associated with the specified setting name. + * + * @param config - The configuration object containing icons. + * @param settingName - The setting name to search for. + * @returns The icon associated with the specified setting name. + */ export function getIconWithSettingName(config, settingName) { const key = getKeyWithSettingName(config, settingName); return getIconWithKey(config, key); } -export function getKeycodeWithSettingName(config, settingName) { - const key = getKeyWithSettingName(config, settingName); - return getKeycodeWithKey(config, key); -} - -export function getSettingNameWithButton(config, button, alt= false) { +/** + * Retrieves the setting name associated with the specified button. + * + * @param config - The configuration object containing settings. + * @param button - The button to search for. + * @param alt - A flag indicating if the search is for an alternate setting. + * @returns The setting name associated with the specified button. + */ +export function getSettingNameWithButton(config, button, alt = false) { return Object.keys(config.settings).find(k => { const a = !alt && !k.includes("ALT_"); const b = alt && k.includes("ALT_"); @@ -67,22 +135,30 @@ export function getSettingNameWithButton(config, button, alt= false) { }); } -export function getKeyWithButton(config, button, alt= false) { +/** + * Retrieves the key associated with the specified button. + * + * @param config - The configuration object containing custom settings. + * @param button - The button to search for. + * @param alt - A flag indicating if the search is for an alternate setting. + * @returns The key associated with the specified button. + */ +export function getKeyWithButton(config, button, alt = false) { const settingName = getSettingNameWithButton(config, button, alt); return getKeyWithSettingName(config, settingName); } -export function getKeycodeWithButton(config, button, alt= false) { - const key = getKeyWithButton(config, button, alt); - return getKeycodeWithKey(config, key); -} - -export function getIconWithButton(config, button, alt= false) { - const key = getKeyWithButton(config, button, alt); - return getIconWithKey(config, key); -} - -export function isAlreadyBinded(config, keycode, settingNameTarget) { +/** + * Identifies a key that resolves a binding conflict when attempting to bind a keycode to a specified setting name target. + * This function checks if the keycode is already bound to a different type of binding (main or alternate) and returns + * the conflicting key if found. + * + * @param config - The configuration object containing custom settings. + * @param keycode - The keycode to check. + * @param settingNameTarget - The setting name target to bind. + * @returns The conflicting key if found, or null if no conflict is found. + */ +export function getKeySolvingConflict(config, keycode, settingNameTarget) { const key = getKeyWithKeycode(config, keycode); const isMain = config.main.includes(key); @@ -94,18 +170,26 @@ export function isAlreadyBinded(config, keycode, settingNameTarget) { return null; } +/** + * Swaps the binding of a keycode with the specified setting name target. + * If the target setting is deleted, it directly binds the keycode to the target setting. + * Otherwise, it handles any potential conflicts by swapping the bindings. + * + * @param config - The configuration object containing custom settings. + * @param settingNameTarget - The setting name target to swap. + * @param keycode - The keycode to swap. + */ export function swap(config, settingNameTarget, keycode) { - // 2 alt can't do the same thing - // 2 main can't do the same thing - // can't swap an alt if another alt is already doing the same - // can't swap a main if another main is already doing the same + // Check if the setting name target is already deleted (i.e., not bound to any key). const isDeleted = !getKeyWithSettingName(config, settingNameTarget); + // If the setting name target is deleted, bind the new key to the setting name target and return. if (isDeleted) { const new_key = getKeyWithKeycode(config, keycode); config.custom[new_key] = settingNameTarget; return; } - const potentialExistingKey = isAlreadyBinded(config, keycode, settingNameTarget); + // Check for any potential conflict with existing bindings. + const potentialExistingKey = getKeySolvingConflict(config, keycode, settingNameTarget); const prev_key = potentialExistingKey || getKeyWithSettingName(config, settingNameTarget); const prev_settingName = getSettingNameWithKey(config, prev_key); @@ -118,19 +202,32 @@ export function swap(config, settingNameTarget, keycode) { regenerateIdentifiers(config); } +/** + * Deletes the binding of the specified setting name. + * + * @param config - The configuration object containing custom settings. + * @param settingName - The setting name to delete. + */ export function deleteBind(config, settingName) { const key = getKeyWithSettingName(config, settingName); config.custom[key] = -1; regenerateIdentifiers(config); } +/** + * Regenerates the identifiers for main and alternate settings. + * This allows distinguishing between main and alternate bindings. + * + * @param config - The configuration object containing custom settings. + */ export function regenerateIdentifiers(config) { config.main = Object.keys(config.custom).filter(key => { - const value = config.custom[key] + const value = config.custom[key]; return value !== -1 && !value.includes("ALT_"); }); + config.alt = Object.keys(config.custom).filter(key => { - const value = config.custom[key] + const value = config.custom[key]; return value !== -1 && value.includes("ALT_"); }); -} \ No newline at end of file +} diff --git a/src/configs/pad_dualshock.ts b/src/configs/pad_dualshock.ts index 845e7d61004..c866b494420 100644 --- a/src/configs/pad_dualshock.ts +++ b/src/configs/pad_dualshock.ts @@ -7,7 +7,7 @@ import {Button} from "../enums/buttons"; const pad_dualshock = { padID: 'Dualshock', padType: 'dualshock', - gamepadMapping: { + deviceMapping: { RC_S: 0, RC_E: 1, RC_W: 2, diff --git a/src/configs/pad_generic.ts b/src/configs/pad_generic.ts index ce2edd421e6..f5a1b10ebf2 100644 --- a/src/configs/pad_generic.ts +++ b/src/configs/pad_generic.ts @@ -7,7 +7,7 @@ import {Button} from "../enums/buttons"; const pad_generic = { padID: 'Generic', padType: 'xbox', - gamepadMapping: { + deviceMapping: { RC_S: 0, RC_E: 1, RC_W: 2, diff --git a/src/configs/pad_unlicensedSNES.ts b/src/configs/pad_unlicensedSNES.ts index c60ccbe74d8..119864b2a89 100644 --- a/src/configs/pad_unlicensedSNES.ts +++ b/src/configs/pad_unlicensedSNES.ts @@ -7,7 +7,7 @@ import {Button} from "../enums/buttons"; const pad_unlicensedSNES = { padID: '081f-e401', padType: 'snes', - gamepadMapping : { + deviceMapping : { RC_S: 2, RC_E: 1, RC_W: 3, diff --git a/src/configs/pad_xbox360.ts b/src/configs/pad_xbox360.ts index 3f820e59dc0..bd9d12dd974 100644 --- a/src/configs/pad_xbox360.ts +++ b/src/configs/pad_xbox360.ts @@ -7,7 +7,7 @@ import {Button} from "#app/enums/buttons"; const pad_xbox360 = { padID: 'Xbox 360 controller (XInput STANDARD GAMEPAD)', padType: 'xbox', - gamepadMapping: { + deviceMapping: { RC_S: 0, RC_E: 1, RC_W: 2, diff --git a/src/inputs-controller.ts b/src/inputs-controller.ts index 389ccabc676..fe4158161a3 100644 --- a/src/inputs-controller.ts +++ b/src/inputs-controller.ts @@ -13,7 +13,7 @@ import cfg_keyboard_azerty from "./configs/cfg_keyboard_azerty"; import {Device} from "#app/enums/devices"; import {getButtonWithKeycode, regenerateIdentifiers, swap} from "#app/configs/configHandler"; -export interface GamepadMapping { +export interface DeviceMapping { [key: string]: number; } @@ -32,12 +32,13 @@ export interface MappingLayout { export interface InterfaceConfig { padID: string; padType: string; - gamepadMapping: GamepadMapping; - ogIcons: IconsMapping; + deviceMapping: DeviceMapping; icons: IconsMapping; setting: SettingMapping; default: MappingLayout; custom: MappingLayout; + main: Array; + alt: Array; } const repeatInputDelayMillis = 250; diff --git a/src/test/cfg_keyboard.example.ts b/src/test/cfg_keyboard.example.ts index cc18e83f6eb..44c2f3905d6 100644 --- a/src/test/cfg_keyboard.example.ts +++ b/src/test/cfg_keyboard.example.ts @@ -41,7 +41,7 @@ export enum SettingInterface { const cfg_keyboard_azerty = { padID: 'keyboard', padType: 'default', - gamepadMapping: { + deviceMapping: { KEY_A: Phaser.Input.Keyboard.KeyCodes.A, KEY_B: Phaser.Input.Keyboard.KeyCodes.B, KEY_C: Phaser.Input.Keyboard.KeyCodes.C, diff --git a/src/test/helpers/menuManip.ts b/src/test/helpers/menuManip.ts index f26e0667dd6..055c4a5b6c9 100644 --- a/src/test/helpers/menuManip.ts +++ b/src/test/helpers/menuManip.ts @@ -6,7 +6,7 @@ import { getIconWithKey, getIconWithKeycode, getIconWithSettingName, - getKeyWithKeycode, getKeyWithSettingName, isAlreadyBinded, swap + getKeyWithKeycode, getKeyWithSettingName, getKeySolvingConflict, swap } from "#app/configs/configHandler"; export class MenuManip { @@ -76,7 +76,7 @@ export class MenuManip { OopsSpecialCaseIcon(icon) { this.specialCaseIcon = this.config.icons[icon]; - const potentialExistingKey = isAlreadyBinded(this.config, this.keycode, this.settingName); + const potentialExistingKey = getKeySolvingConflict(this.config, this.keycode, this.settingName); const prev_key = potentialExistingKey || getKeyWithSettingName(this.config, this.settingName); expect(getIconWithKey(this.config, prev_key)).toEqual(this.specialCaseIcon); return this;