comment TSDOC for configHandler.ts

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,

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_");
     });
 }

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,

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,

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,

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,

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<string>;
+    alt: Array<string>;
 }
 
 const repeatInputDelayMillis = 250;

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,

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;