Merge pull request #112 from moonbit5/docs-update-guides

Docs: Create CONTROLS.md and format documentation
2026-09-22 22:48:03 +03:00 · 2025-10-09 14:10:39 -03:00
parent 73d2131c73 96188c69f5
commit ab20dd9420
3 changed files with 164 additions and 30 deletions
@@ -4,6 +4,13 @@

 This project emulates the SEGA Lindbergh, allowing games to run on modern Linux computers to be used as replacement hardware for broken Lindbergh systems in physical arcade machines. It supports both Intel and AMD CPUs as well as Intel, NVIDIA and AMD GPUs, surround sound audio, networking and JVS pass through.

+## 📚 Documentation
+
+For detailed information on configuration and controls, please see the following guides:
+
+- [**🚀 General Guide**](docs/guide.md): Information on supported games, known issues, and general configuration.
+- [**🎮 Controls Guide**](docs/CONTROLS.md): A detailed guide on how to customize your controls using the `controls.ini` file.
+
 If you'd like to support the development work of this emulator, see early development builds or get support from the authors please consider [becoming a patreon here](https://www.patreon.com/LindberghLoader).

 If you need any help please ask the community in the [arcade community discord](https://arcade.community). Please only submit issues if they are bugs with the software, ask in the arcade community discord if you're not sure if it's a bug or you're not setting something up properly!
@@ -0,0 +1,129 @@
+# 🎮 Guide to Customizing controls.ini
+
+This document explains how to configure your input devices by editing the `controls.ini` file. This file gives you full control over how your keyboard, mouse, joysticks, and gamepads are mapped to in-game actions.
+
+## 📄 1. Generating the Default File
+
+Before you start, it's highly recommended to generate a fresh, default `controls.ini` file. This gives you a complete template with all possible actions and recommended starting points for your controls.
+
+To generate the file, run the application from your terminal with the `--create` flag, followed by the argument `controls`.
+
+**Basic Command:**
+This will create a file named `controls.ini` in the current directory.
+```bash
+./lindbergh --create controls
+```
+
+**Specifying a Path:**
+You can also specify a path to create the file in a different location. The folder must already exist.
+
+- **Create in a specific folder:**
+  ```bash
+  ./lindbergh --create controls ./my/folder/
+  ```
+- **Create with a custom name and location:**
+  ```bash
+  ./lindbergh --create controls ./my/path/to/mycontrols.ini
+  ```
+
+## 📂 2. Structure of the INI File
+
+The file is organized into sections, each marked with a name in square brackets (e.g., `[Config]`). Under each section are key-value pairs, separated by an equals sign (`=`).
+
+```ini
+[SectionName]
+Key = Value1, Value2, ...
+```
+
+- **Section:** A category of settings (e.g., `[Driving]`, `[Shooting]`). The game automatically loads the `[Common]` section plus one other section that matches the game's type.
+- **Key:** The name of the logical in-game action you want to map (e.g., `P1_Start`, `Steer`, `Trigger`).
+- **Value:** One or more physical input strings, separated by commas, that will trigger the action.
+
+## ⚙️ 3. Configuration Sections
+
+### [Config]
+
+This section contains global settings that affect all input devices.
+
+- **`<ActionName>_DeadZone`**: Sets a custom analog deadzone for a specific logical action. This gives you precise control over actions like steering and pedals. The value is from `0` (no deadzone) to `32767`. If not specified, a sensible default is used (a large deadzone for centering sticks, a small one for non-centering pedals/triggers).
+  - **Example:** `Steer_DeadZone = 7000`
+  - **Example for Player 2:** `P2_Gas_DeadZone = 500`
+- **`ShakeIncreaseRate` / `ShakeDecayRate`**: Controls the gun shaking effect in games like *House of the Dead 4*.
+
+### [ControllerGUIDs]
+
+This section is managed automatically by the application to ensure your controllers are always assigned to the correct player.
+
+- **`P<N>_GUID`**: Stores the unique hardware ID for the controller assigned to Player `<N>`. You should not need to edit this section manually.
+- **Swapping Players**: If you have multiple controllers and want to change which one is Player 1 vs. Player 2, you can do so by swapping the GUID strings between the `P1_GUID` and `P2_GUID` keys.
+- **Resetting Assignments**: If you want to reset all controller assignments, you can delete this entire section. The application will regenerate it on the next launch based on the order the controllers are detected.
+
+### Game Type Sections
+
+These sections contain the actual control mappings. The application will load `[Common]` and one other section based on the game being played.
+
+-   **`[Common]`**: For actions shared by all games (Test, Coin, Start, Service).
+-   **`[Digital]`**: For standard arcade games with an 8-way joystick and buttons.
+-   **`[Driving]`**: For racing games with analog steering, gas, and brake.
+-   **`[Shooting]`**: For lightgun games.
+-   **`[ABC]`**: For games with flight-stick style controls like *After Burner Climax*.
+-   **`[Mahjong]`**: For mahjong panel controls.
+
+## 🕹️ 4. Understanding Controller Mappings (gamecontrollerdb.txt)
+
+For the application to recognize your gamepad (like an Xbox or PlayStation controller) and allow you to use the simple `GC` bindings (e.g., `GC0_BUTTON_A`), it needs a database of controller mappings.
+
+-   **Built-in Mappings**: The application already includes a large, built-in database of mappings for hundreds of common controllers, so many devices will work out of the box.
+-   **Adding Custom Mappings**: If you have a rare controller or want to override the built-in behavior, you can provide an external mapping file. The file can have any name (though `gamecontrollerdb.txt` is standard) but must follow the SDL mapping format. You can load a custom file by running the application with the `--controllerdb` flag:
+    ```bash
+    ./lindbergh --controllerdb ./path/to/your_mappings.txt
+    ```
+    The mappings from your file will be added to the existing built-in database.
+-   **Where to get mapping files**: You can find the community-sourced `gamecontrollerdb.txt` file, which is a great starting point for custom mappings, at the [official SDL GameControllerDB GitHub repository](https://github.com/gabomdq/SDL_GameControllerDB).
+
+## ⌨️ 5. Binding String Syntax
+
+The value for each key is a comma-separated list of physical input strings. Here is the format for each device type:
+
+### Keyboard
+
+-   **Format**: `KEY_<ScanCodeName>`
+-   **Example**: `KEY_A, KEY_Space, KEY_ArrowUp`
+-   **Note**: The name is the SDL Scancode Name, not necessarily the character on the key.
+
+### Mouse
+
+-   **Buttons**: `MOUSE_LEFT_BUTTON`, `MOUSE_RIGHT_BUTTON`, `MOUSE_MIDDLE_BUTTON`
+-   **Axes**: `MOUSE_AXIS_X`, `MOUSE_AXIS_Y`
+
+### Generic Joysticks (JOY) and Standard Gamepads (GC)
+
+-   **Player Index `<N>`**: The number `<N>` after `JOY` or `GC` always refers to the player. The application uses the `[ControllerGUIDs]` section to determine which physical device is assigned to which player. `JOY0_` and `GC0_` will always be the controller assigned to Player 1, `JOY1_` and `GC1_` will be for Player 2, and so on.
+-   **Buttons**:
+    -   `JOY<N>_BUTTON_<ButtonNumber>` (e.g., `JOY0_BUTTON_0`)
+    -   `GC<N>_BUTTON_<ButtonName>` (e.g., `GC0_BUTTON_A`, `GC0_BUTTON_LEFTSHOULDER`)
+-   **Hats/D-Pads**: `JOY<N>_HAT<HatNumber>_<Direction>` (e.g., `JOY0_HAT0_UP`)
+-   **Axes**:
+    -   `JOY<N>_AXIS_<AxisNumber>` (e.g., `JOY0_AXIS_0`)
+    -   `GC<N>_AXIS_<AxisName>` (e.g., `GC0_AXIS_LEFTX`, `GC0_AXIS_TRIGGERRIGHT`)
+
+### Axis Suffixes (for JOY and GC axes)
+
+You can add suffixes to an axis string to change its behavior:
+
+-   **`_POSITIVE` / `_NEGATIVE`**: Treats one direction of an analog axis like a digital button press.
+    -   **Example**: `P1_Right = GC0_AXIS_LEFTX_POSITIVE`
+-   **`_POSITIVE_HALF` / `_NEGATIVE_HALF`**: Used to map two different triggers or pedals to a single combined analog action (like a throttle).
+    -   **Example**: `Throttle = JOY0_AXIS_5_POSITIVE_HALF, JOY0_AXIS_2_NEGATIVE_HALF`
+-   **`_INVERTED`**: Reverses the direction of an analog axis.
+    -   **Example**: `Throttle = GC0_AXIS_RIGHTY_INVERTED`
+
+### Example
+
+Here is a complex mapping for Player 1's "Start" button:
+
+```ini
+P1_Start = KEY_1, GC0_BUTTON_START, JOY0_BUTTON_9
+```
+
+This means the action will be triggered by pressing the `'1'` key on the keyboard, the `'Start'` button on Player 1's gamepad, OR button number `9` on Player 1's generic joystick.
@@ -1,6 +1,6 @@
-# Guide
+# 🚀 Guide

-## Supported Games
+## 🎮 Supported Games

 The follow list of games are supported. It is worth noting that there are multiple releases of these games, and some specific releases may not be supported.

@@ -68,19 +68,19 @@ The follow list of games are supported. It is worth noting that there are multip
 | Virtua Tennis 3 Rev B                            | SBKX    | DVP-0005B | ✓      | ✓            | ✓          | ✓                 |
 | Virtua Tennis 3 Rev C                            | SBKX    | DVP-0005C | ✓      | ✓            | ✓          | ✓                 |

-## Game Issues & Fixes
+## 🛠️ Game Issues & Fixes

 ### All Games: missing dependencies & libraries

 Additional libraries that you might need to install to get all games running are listed here:

-```
+```bash
 sudo apt install build-essential freeglut3:i386 freeglut3-dev:i386 libglew-dev xorg-dev libopenal1:i386 libopenal-dev:i386 libxmu6:i386 libstdc++5:i386 libsdl2-dev:i386 libfaudio0:i386 libfaudio-dev:i386 libncurses5:i386 libasound2-dev:i386 alsa-utils:i386 libasound2-plugins:i386
 ```

 On Debian, `libglut` might not be found. Adding a symbolic link will fix it.

-```
+```bash
 sudo ln -s /lib/i386-linux-gnu/libglut.so /lib/i386-linux-gnu/libglut.so.3
 ```

@@ -96,7 +96,7 @@ sudo ln -s /lib/i386-linux-gnu/libglut.so /lib/i386-linux-gnu/libglut.so.3

 The games will ask for libGLcore.so.1 and libnvidia-tls.so.1 you can copy for example libkswapapi.so as libGLcore.so.1 and libnvidia-tls.so.1 and the game will work fine.

-## Configuration File : lindbergh.ini
+## ⚙️ Configuration File : lindbergh.ini

 All configurable options are set and explained in the [`lindbergh.ini`](lindbergh.ini) file itself, and should be reasonably easy to understand. This chapter further explains some of those setup options.

@@ -120,26 +120,26 @@ In the second input mode, inputs are taken directly from the evdev library in li

 To list the available inputs you should type:

-```
+```bash
 ./lindbergh --list-controllers
 ```

 From there you will be able to see the controllers and all of the inputs support. Then in the config file you should map an arcade input to a controller input as follows.

-```
+```ini
 PLAYER_1_BUTTON_UP XBOX_CONTROLLER_BTN_UP
 ANALOGUE_1 XBOX_CONTROLLER_ABS_X
 ```

 You can map digital controls to analogue controls. The analogue value will be set to the digital value, such that if the button isn't pressed it will be set to 0, and if the button is pressed it will be set to MAX. This is useful if your controller doesn't have analogue accelerator or break buttons.

-```
+```ini
 ANALOGUE_0 XBOX_CONTROLLER_BUTTON_BR
 ```

 You can map analogue controls to digital controls too. For each analogue input, there are 2 more inputs created ending in _MAX and _MIN. These are digital controls that will be triggered when the analogue input is either at the minimum or maximum value. This can be useful if you'd like to use an analogue stick to control a fighting game for example.

-```
+```ini
 PLAYER_1_BUTTON_UP XBOX_CONTROLLER_ABS_Y_MAX
 PLAYER_1_BUTTON_DOWN XBOX_CONTROLLER_ABS_Y_MIN
 PLAYER_1_BUTTON_LEFT XBOX_CONTROLLER_ABS_X_MIN
@@ -148,7 +148,7 @@ PLAYER_1_BUTTON_RIGHT XBOX_CONTROLLER_ABS_X_MAX

 You can set a deadzone for analogue axis. Each anaolgue input has 3 potential deadzones: start, middle, and end. The deadzone is a percentage of the range from the start, middle, or end that should snap to its respective extreme. This is useful for input devices that don't perfectly center, or pedals that don't perfectly return to 0. For instance.

-```
+```ini
 ANALOGUE_DEADZONE_1 10 13 10
 ```

@@ -163,7 +163,7 @@ Will cause input on analogue input 1 to be clamped as follows:
 There are currently no audio options that you can set. If you have a stereo sound card installed then the audio will be downmixed to stereo. If you have a 5.1 sound card installed and the game supports surround sound, each surround channel should be passed through properly and should play sound as it was originally intended.


-## Installing and Running the Flatpak
+## 📦 Installing and Running the Flatpak

 ### Prerequisites

@@ -173,19 +173,19 @@ Before installing the main package, ensure that Flatpak is set up on your system

 Once downloaded, install Lindbergh Loader by running the following command in your terminal:

-```
+```bash
 flatpak install lindbergh-loader-dev.flatpak
 ```

 Additionally, install the required dependencies:

-```
+```bash
 flatpak install org.freedesktop.Platform.Compat.i386//24.08
 flatpak install org.freedesktop.Platform.GL32.default//24.08
 ```
 Intel GPU Users (VAAPI Support):

-```
+```bash
 flatpak install org.freedesktop.Platform.VAAPI.Intel.i386//24.08
 ```

@@ -194,12 +194,12 @@ NVIDIA GPU Users (Driver Support):
 If your system uses an NVIDIA GPU, you need to install the matching NVIDIA driver package for your system.
 To check your NVIDIA driver version, run:

-```
+```bash
 nvidia-smi
 ```
 Then, install the corresponding Flatpak package, replacing 570-86-16 with your actual driver version:

-```
+```bash
 flatpak install org.freedesktop.Platform.GL32.nvidia-570-86-16
 ```

@@ -207,7 +207,7 @@ flatpak install org.freedesktop.Platform.GL32.nvidia-570-86-16

 Once installed, launch the application with:

-```
+```bash
 flatpak run com.github.lindberghloader.dev
 ```

@@ -221,7 +221,7 @@ By default, games should be added to:

 If you need to add more locations, install Flatseal:

-```
+```bash
 flatpak install com.github.tchx84.Flatseal
 ```

@@ -235,29 +235,29 @@ so you can han the loader libs in any of those locations.

 Passing -c option you can specify the location of the .conf file like this:

-```
+```bash
 ./lindbergh -c /my/custom/folder/myconfig.conf
 ```

-## -g or --gamepath
+## 📂 -g or --gamepath
 With this new option, you can specify the location of the game, where the game's ELF resides.

-```
+```bash
 ./lindbergh -g /my/custom/folder/hod4/elf
 ```

 The loader will search for known elf files in that folder but you can also run it like this:

-```
+```bash
 ./lindbergh myCustom.elf -g /my/custom/folder/hod4/elf
 ```

 The loader will load `myCustom.elf` inside the passed folder.

-## Passing a folder containing an elf
+## 📁 Passing a folder containing an elf
 With this option, you pass a full path, including an ELF name like this:

-```
+```bash
 ./lindbergh /my/custom/folder/hod4/elf/myCustom.elf
 ```

@@ -271,12 +271,10 @@ The loader will try to find the files.
 If by mistake, you pass both, a full path including an ELF and a path with -g option, the path passed with -g option will be omitted.
 Remember that if the path containg spaces, which is not recommended, pass the path inside double quotes or `\` before the space.

-## Creating lindbergh.ini or controls.ini
+## 📝 Creating lindbergh.ini or controls.ini

-```
+```bash
 ./lindbergh --create --help
 ```

-Will give you instructions on how to use the new commands.
-
-
+Will give you instructions on how to use the new commands.