Add and link Configuration.md and gamepad configs

it documents dhewm3-specific configuration, esp. for gamepads
(but also listing other CVars added in dhewm3)

Changelog.md

@@ -23,6 +23,8 @@ Note: Numbers starting with a "#" like #330 refer to the bugreport with that num
   (0 = TGA, still the default, 1 = BMP, 2 = PNG, 3 = JPG). `r_screenshotJpgQuality` and
   `r_screenshotPngCompression` allow configuring how JPG/PNG are compressed.
   Thanks *eezstreet (Nick Whitlock)*!
+* Support for gamepads (based on code from [Quadrilateral Cowboy](https://github.com/blendogames/quadrilateralcowboy),
+  but heavily expanded). See [Configuration.md](./Configuration.md#using-gamepads) for more information.
 
 1.5.2 (2022-06-13)
 ------------------------------------------------------------------------

Configuration.md

@@ -0,0 +1,143 @@
+# Configuration
+
+This document explains some dhewm3-specific configuration options.
+
+For general Doom3 configuration see for example [this list of CVars](https://modwiki.dhewm3.org/CVars_%28Doom_3%29)
+and [this list of Console Commands](https://modwiki.dhewm3.org/Commands_%28Doom_3%29).
+
+**CVars** are set by entering `cvarName value` in the console, for example `com_showFPS 1`.  
+They can also be set as commandline arguments when starting dhewm3, for example `./dhewm3 +set r_fullscreen 0`.
+
+Just entering a CVar's name (without a value) will show its current value, its default value
+and a short description of what it does.
+
+Starting dhewm3 with the commandline argument `-h` (for example `dhewm3.exe -h`) will show some
+useful commandline arguments, for example how to tell dhewm3 where the game data can be found on your system.
+
+## The Console
+
+Like most id Software games from Quake 1 on, Doom3 has a console that allows entering commands 
+and setting Console Variables ("CVars"), often for advanced configuration or to aid development,
+see also https://modwiki.dhewm3.org/Console.  
+
+Unlike in original Doom3, in dhewm3 the console is always available (no need to set `com_allowconsole 1`
+or similar), and **can be opened with the key combination `Shift + Esc`**.  
+The classic "console key" (the one between `Esc`, `Tab` and `1`) should also still work with
+most keyboard layouts. However you can disable that, so you can bind that key like any other key
+(for example to select the chainsaw), by setting `in_ignoreConsoleKey 1`.
+
+## Using Gamepads
+
+Starting with 1.5.3 (or the git commits preceding the one adding this document), dhewm3 supports
+using gamepads, as long as they're supported by SDL2.  
+This includes XBox Controllers (and compatible ones), Playstation 3-5 controllers,
+Nintendo Switch Pro Controllers, many thirdparty controllers for those consoles, and lots of other
+gamepads for PC.
+
+Some notes:
+* By default, no bindings for the gamepad exist, so you need to configure them once in the
+  Settings -> Controls menu.
+    - You need to bind *Turn Left*, *Turn Right*, *Look Up* and *Look Down* to the corresponding
+      directions of one stick to use it to look around or aim.
+    - Similarly, you need to bind *Forward*, *Backpedal*, *Move Left* and *Move Right* to the
+      corresponding directions of a stick to use it for player movement.
+* The "Start" button ("+" on Nintendo gamepads, "Options" on Playstation 4/5 controllers) acts
+  like the Escape key, so it will **open/close the menu** and can not be bound.  
+  The other buttons, axes and triggers can be bound to arbitrary actions in the Controls menu,
+  except for the Home button, which can't be used by dhewm3 at all (because it opens Steam when that is running).
+* In **menus**, either stick will move the cursor, and the button you assign to *attack* (fire) acts
+  like the left mouse button, and so does the lower face button (A on XBox controllers, B on Nintendo
+  controllers, Cross on PS controllers) and the upper face button (Y on XBox, X on Nintendo, Triangle on PS).
+* The layout of the controller (XBox-like, Nintendo-like, Playstation-like) should be automatically
+  detected and is used to display the button names according to the layout. If yours isn't detected
+  correctly, you can overwrite it with the `joy_gamepadLayout` CVar.
+* Requires SDL2, layout detection requires SDL 2.0.12 or newer.
+* Only one gamepad is supported or, more specifically, if multiple are connected, they all behave the same
+  and you can't bind their buttons/axes to different actions, and the auto-layout detection will use the
+  last gamepad it found to determine the layout.
+* You can disable gamepads by setting the `in_useGamepad` CVar to `0`.
+* There are several CVars to tweak the behavior:
+    - `joy_deadZone` Deadzone of the sticks, where `1.0` would be "stick moved fully in one direction".
+       This means that values below this register as 0. If you move or look around ingame even though
+       you're not moving a stick, try increasing the `joy_deadZone` value (default is `0.25`).
+    - `joy_triggerThreshold` Basically the deadzone for triggers. If your trigger triggers without
+       being touched, try increasing this value (default is `0.05`).
+    - `joy_gamepadLayout` overwrite automatically detected layout (XBox, Nintendo, PS), see above.
+    - `joy_pitchSpeed` How fast you look up/down (when the stick is at a maximum position)
+    - `joy_yawSpeed` Same for turning left/right
+    - `joy_invertLook` Inverts the controls for looking up/down (like in a flight simulator)
+    - `joy_gammaLook` If set to `1`, use a log curve instead of a power curve for looking around,
+       affects how fast you turn (or look up/down) when the stick is between center and maximum.
+    - `joy_powerScale` If `joy_gammaLook` is `0`, this is the exponent used for the power curve.
+    - `joy_dampenLook` if enabled (`1`), somehow reduced the speed of looking around, depending on
+      `joy_deltaPerMSLook`.
+
+I created gamepad configs for the base game and d3xp (Resurrection of Evil), based on the standard bindings
+of Doom3 BFG, see gamepad.cfg and gamepad-d3xp.cfg in the [base/ directory](./base/).  
+Put them in your base/ folder, open the console and enter `exec gamepad.cfg` for the base game,
+or `exec gamepad-d3xp.cfg` for Resurrection of Evil (probably also works for Doom3: Lost Mission).
+
+**_Note_** that in *configs* (or `bind` commands in the console), the following names are used for
+gamepad buttons, sticks and triggers:
+
+<details><summary>Click to see the list of gamepad button/stick/trigger names</summary>
+
+* "JOY_BTN_SOUTH" - `A` button on XBox-style gamepads, `B` on Nintendo-style gamepads or `Cross` on Playstation-style gamepads 
+* "JOY_BTN_EAST" - `B` (XBox), `A` (Nintendo), `Circle` (Playstation)
+* "JOY_BTN_WEST" - `X` (XBox), `Y` (Nintendo), `Square` (Playstation)
+* "JOY_BTN_NORTH" - `Y` (XBox), `X` (Nintendo), `Triangle` (Playstation)
+* "JOY_BTN_BACK" - The `Back` button, aka `-` (Nintendo) or `Select`/`Share` (Playstation)
+* "JOY_BTN_LSTICK" - Pressing the Left Stick down
+* "JOY_BTN_RSTICK" - Pressing the Right Stick down
+* "JOY_BTN_LSHOULDER" - Left Shoulder Button
+* "JOY_BTN_RSHOULDER" - Right Shoulder button
+* "JOY_DPAD_UP" - DPad Up
+* "JOY_DPAD_DOWN" - DPad Down
+* "JOY_DPAD_LEFT" - DPad Left
+* "JOY_DPAD_RIGHT" - DPad Right
+* "JOY_BTN_MISC1" - misc. additional button, like Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button
+* "JOY_BTN_RPADDLE1" - Upper or primary paddle, under your right hand (e.g. Xbox Elite paddle P1)
+* "JOY_BTN_LPADDLE1" - Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3)
+* "JOY_BTN_RPADDLE2" - Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2)
+* "JOY_BTN_LPADDLE2" - Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4
+* "JOY_STICK1_UP" - Moving Left Stick up
+* "JOY_STICK1_DOWN" - Moving Left Stick down
+* "JOY_STICK1_LEFT" - Moving Left Stick to the left
+* "JOY_STICK1_RIGHT" - Moving Left Stick to the right
+* "JOY_STICK2_UP" - Moving Right Stick up
+* "JOY_STICK2_DOWN" - Moving Right Stick down
+* "JOY_STICK2_LEFT" - Moving Right Stick to the left
+* "JOY_STICK2_RIGHT" - Moving Right Stick to the right
+* "JOY_TRIGGER1" - Pressing the Left Trigger
+* "JOY_TRIGGER2" - Pressing the Right Trigger
+
+</details>
+
+## Screenshot configuration
+
+Doom3 always supported taking screenshots, but dhewm3 (from 1.5.3 on) supports using different
+formats than TGA.  
+This can be configured with the following CVars:
+
+- `r_screenshotFormat` What format screenshots should be in:
+  `0` = TGA (default), `1` = BMP, `2` = PNG, `3` = JPG
+- `r_screenshotJpgQuality` Quality when using JPG screenshots (`0` - `100`)
+- `r_screenshotPngCompression` Compression level when using PNG screenshots (`0` - `9`)
+
+## CVars added in dhewm3 that I'm currently too lazy to document more thoroughly
+
+- g_hitEffect
+
+- in_nograb
+- in_grabKeyboard
+
+- in_tty
+- in_kbd
+
+- r_fullscreenDesktop
+- r_fillWindowAlphaChan
+
+- r_useCarmacksReverse
+- r_useStencilOpSeparate
+
+- s_alReverbGain

README.md

@@ -31,6 +31,7 @@ Compared to the original _DOOM 3_, the changes of _dhewm 3_ worth mentioning are
 - SDL for low-level OS support, OpenGL and input handling
 - OpenAL for audio output, all OS-specific audio backends are gone
 - OpenAL EFX for EAX reverb effects (read: EAX-like sound effects on all platforms/hardware)
+- Gamepad support
 - Better support for widescreen (and arbitrary display resolutions)
 - A portable build system based on CMake
 - (Cross-)compilation with MinGW-w64
@@ -55,6 +56,11 @@ https://store.steampowered.com/app/208200/DOOM_3/
 
 See https://dhewm3.org/#how-to-install for game data installation instructions.
 
+## Configuration
+
+See [Configuration.md](./Configuration.md) for dhewm3-specific configuration, especially for 
+using gamepads.
+
 ## Compiling
 
 The build system is based on CMake: http://cmake.org/

base/gamepad-d3xp.cfg

@@ -0,0 +1,21 @@
+bind "JOY_BTN_SOUTH" "_moveUp"
+bind "JOY_BTN_WEST" "_impulse13"
+bind "JOY_BTN_BACK" "_impulse19"
+bind "JOY_BTN_LSTICK" "_speed"
+bind "JOY_BTN_RSTICK" "_moveDown"
+bind "JOY_BTN_LSHOULDER" "_impulse15"
+bind "JOY_BTN_RSHOULDER" "_impulse14"
+bind "JOY_DPAD_UP" "_impulse8"
+bind "JOY_DPAD_DOWN" "_impulse11"
+bind "JOY_DPAD_LEFT" "_impulse12"
+bind "JOY_DPAD_RIGHT" "_impulse1"
+bind "JOY_STICK1_UP" "_forward"
+bind "JOY_STICK1_DOWN" "_back"
+bind "JOY_STICK1_LEFT" "_moveLeft"
+bind "JOY_STICK1_RIGHT" "_moveRight"
+bind "JOY_STICK2_UP" "_lookUp"
+bind "JOY_STICK2_DOWN" "_lookDown"
+bind "JOY_STICK2_LEFT" "_left"
+bind "JOY_STICK2_RIGHT" "_right"
+bind "JOY_TRIGGER1" "_impulse0"
+bind "JOY_TRIGGER2" "_attack"

base/gamepad.cfg

@@ -0,0 +1,21 @@
+bind "JOY_BTN_SOUTH" "_moveUp"
+bind "JOY_BTN_WEST" "_impulse13"
+bind "JOY_BTN_BACK" "_impulse19"
+bind "JOY_BTN_LSTICK" "_speed"
+bind "JOY_BTN_RSTICK" "_moveDown"
+bind "JOY_BTN_LSHOULDER" "_impulse15"
+bind "JOY_BTN_RSHOULDER" "_impulse14"
+bind "JOY_DPAD_UP" "_impulse5"
+bind "JOY_DPAD_DOWN" "_impulse8"
+bind "JOY_DPAD_LEFT" "_impulse9"
+bind "JOY_DPAD_RIGHT" "_impulse0"
+bind "JOY_STICK1_UP" "_forward"
+bind "JOY_STICK1_DOWN" "_back"
+bind "JOY_STICK1_LEFT" "_moveLeft"
+bind "JOY_STICK1_RIGHT" "_moveRight"
+bind "JOY_STICK2_UP" "_lookUp"
+bind "JOY_STICK2_DOWN" "_lookDown"
+bind "JOY_STICK2_LEFT" "_left"
+bind "JOY_STICK2_RIGHT" "_right"
+bind "JOY_TRIGGER1" "_impulse11"
+bind "JOY_TRIGGER2" "_attack"