Controller configs

README.md

@@ -383,6 +383,133 @@ python main.py --token-cache /path/to/your/cache.json
 !token
 ```
 
+## Game Control Configuration (`data/config/game_controls.json`)
+
+The `data/config/game_controls.json` file allows you to define custom game control schemes for different games. This enables the bot to adapt its input commands (keyboard or controller) based on the game currently being played.
+
+### Structure
+
+The JSON file has the following main structure:
+
+```json
+{
+  "default_game": "YourDefaultGameName",
+  "games": {
+    "YourDefaultGameName": {
+      // Configuration for YourDefaultGameName
+    },
+    "AnotherGameName": {
+      // Configuration for AnotherGameName
+    }
+    // ... more game configurations
+  }
+}
+```
+
+-   `"default_game"`: (String) Specifies the name of the game configuration that will be loaded by default when the bot starts. The command names from this game's configuration will be registered at startup.
+-   `"games"`: (Object) A dictionary where each key is a unique game name (e.g., "Apex Legends", "Minecraft", "MyCustomGame"). Each game name maps to an object containing its specific control configuration.
+
+### Game Configuration Structure
+
+Each game entry within the `"games"` object has the following structure:
+
+```json
+"GameName": {
+  "description": "A brief description of this game or control scheme.",
+  "keyboard": {
+    // Keyboard control mappings for GameName
+  },
+  "controller": {
+    // Controller control mappings for GameName
+  }
+}
+```
+
+-   `"description"`: (String) A human-readable description for this game configuration (e.g., "Apex Legends - Standard Controls", "Dark Souls - Fat Roll Setup"). This description is shown in `!gamehelp`.
+-   `"keyboard"`: (Object) Contains mappings for keyboard-based commands.
+-   `"controller"`: (Object) Contains mappings for virtual gamepad-based commands.
+
+### Control Mapping Structure (Keyboard & Controller)
+
+Inside both the `"keyboard"` and `"controller"` objects, you define individual control commands. The **keys** in these objects are the **actual command strings** users will type in Twitch chat (without the `!` prefix). For example, if you define `"w": {...}`, users will type `!w`.
+
+Each command mapping has the following structure:
+
+```json
+"command_user_types": {
+  "action_type": "type_of_action_to_perform",
+  "params": {
+    // Parameters specific to the action_type
+  },
+  "description": "What this command does in this specific game (e.g., 'Move Forward', 'Jump', 'Primary Attack')."
+}
+```
+
+-   `"command_user_types"`: (String) The command string the user types (e.g., `"w"`, `"space"`, `"mouse_left"`, `"a_button"`, `"ls_up"`).
+-   `"action_type"`: (String) Defines the kind of input to simulate. This corresponds to methods available in `KeyboardController` or `VirtualController`.
+    -   **Common Keyboard `action_type` values:**
+        -   `"press_key"`: Simulates pressing a keyboard key.
+            -   `params`: `{ "key": "key_name" }` (e.g., `"w"`, `"space"`, `"shift"`, `"ctrl"`, `"1"`)
+        -   `"press_mouse_button"`: Simulates a mouse button press.
+            -   `params`: `{ "button": "button_name" }` (e.g., `"left"`, `"right"`, `"middle"`)
+    -   **Common Controller `action_type` values:**
+        -   `"press_button"`: Simulates pressing a gamepad button.
+            -   `params`: `{ "button_name": "name_of_button" }` (e.g., `"a"`, `"b"`, `"x"`, `"y"`, `"left_shoulder"`, `"right_shoulder"`, `"left_thumb"`, `"right_thumb"`, `"start"`, `"back"`)
+        -   `"press_trigger"`: Simulates pressing a gamepad trigger.
+            -   `params`: `{ "trigger_name": "left_or_right" }` (e.g., `"left"`, `"right"`)
+        -   `"move_left_stick"` / `"move_right_stick"`: Simulates moving an analog stick.
+            -   `params`: `{ "direction": "up/down/left/right" }` (e.g., `"up"`)
+            -   *Note: For more precise stick control, the `VirtualController` might support direct x/y values in the future, which would require different params.*
+        -   `"press_dpad"`: Simulates pressing a D-Pad direction.
+            -   `params`: `{ "direction": "up/down/left/right" }`
+-   `"params"`: (Object) A dictionary of parameters required by the specified `action_type`. The keys and values within `params` depend directly on what the underlying controller methods (`KeyboardController` or `VirtualController` methods) expect.
+    -   An optional `"duration"` (float, in seconds) can often be included in `params` to specify how long a key/button should be held. If omitted, a short default (e.g., 0.1 seconds) is typically used.
+-   `"description"`: (String) This is crucial. It explains what the command does in the context of *this specific game*. This description is shown to users via the `!gamehelp` command.
+
+### Example Snippet
+
+```json
+{
+  "default_game": "ExampleFPS",
+  "games": {
+    "ExampleFPS": {
+      "description": "Standard FPS Controls",
+      "keyboard": {
+        "w": {"action_type": "press_key", "params": {"key": "w"}, "description": "Move Forward"},
+        "s": {"action_type": "press_key", "params": {"key": "s"}, "description": "Move Backward"},
+        "mouse_left": {"action_type": "press_mouse_button", "params": {"button": "left"}, "description": "Fire Weapon"}
+      },
+      "controller": {
+        "ls_up": {"action_type": "move_left_stick", "params": {"direction": "up"}, "description": "Move Forward (L-Stick)"},
+        "rt": {"action_type": "press_trigger", "params": {"trigger_name": "right"}, "description": "Fire Weapon (RT)"},
+        "a": {"action_type": "press_button", "params": {"button_name": "a"}, "description": "Jump (A Button)"}
+      }
+    },
+    "RacingSim": {
+      "description": "Basic Racing Controls",
+      "keyboard": {
+        "w": {"action_type": "press_key", "params": {"key": "w", "duration": 0.5}, "description": "Accelerate"},
+        "s": {"action_type": "press_key", "params": {"key": "s", "duration": 0.3}, "description": "Brake/Reverse"}
+      },
+      "controller": {
+        "rt": {"action_type": "press_trigger", "params": {"trigger_name": "right"}, "description": "Accelerate (RT)"},
+        "lt": {"action_type": "press_trigger", "params": {"trigger_name": "left"}, "description": "Brake/Reverse (LT)"}
+      }
+    }
+  }
+}
+```
+
+### Activating a Game Configuration
+
+-   At startup, the commands defined in the `keyboard` and `controller` sections of the `default_game` are registered. Their descriptions (from the JSON) are used.
+-   An admin can change the active game configuration at any time using the `!setgame <GameName>` command (e.g., `!setgame RacingSim`).
+-   Once the game is switched:
+    -   The `!gamehelp` command will display the controls for the newly activated game.
+    -   When users type a command (e.g., `!w`), the bot will execute the action defined for `"w"` in the *currently active game's* configuration. If `"w"` is not defined for the active game, it will be treated as an unknown command for that game.
+
+This system allows for a highly flexible and game-adaptive control scheme managed entirely through the `game_controls.json` file.
+
 ## License
 
 This project is open source and available under the MIT License.