RBRControls - JoyKey and HShifter plugin for Richard Burns Rally

A plugin to support control key remappings (JoyKey for RBR) directly within RBR and without external applications.
You can, for example, map steering wheel buttons to RBR menu navigation keys.

Includes also an improved version of H-Shifter features built-in into RBRControls plugin (H-pattern vs sequential shifter).

Please see the in-game Options/Plugins/RBRControls plugin menu for more details about supported controls and key bindings.

ATTENTION! DO NOT use the legacy HShifter plugin at the same time with this RBRControls plugins.
           You should use RSFLauncher.Plugins app page to disable HShifter plugin or remove Plugins\HShifter.dll file.

-----------------------------------------------------------------------------------------------
HOW TO USE?

- Options/Plugins/RBRControls in-game menu has three pages. Use Left/Right arrow keys in "Pages" menu line to cycle through those pages.
- Use ENTER key to bind a steering wheel/joystick/gamepad buttons to various RBRControls controls (Page 1-3).
- Press DELETE key to remove a bind.
- Save changes by pressing ENTER key in "Save Settings" menu line.

Page [1/4 JoyKey]:
  - Up/Down/Left/Right = RBR menu navigation keys (arrow keyboard keys)
  - Esc = Previous menu navigation or pause race while a car is on stage
  - Backspace = Previous menu navigation (does nothing when a car is on stage)
  - Enter = Selection
  - Space = Toggle favorites stages and cars in RallySimFans
  - Left Shift / Left Control = Left shift and control keys. Use to do Shift+arrowKeys or Shift+Control+arrowKeys events to move digidash and GaugerPlugin position on screen
  - Control+S = Save setup changes in Setup Editor (tune car)
  - PageUp/PageDown/Home/End = RBR menu navigation keys
  - Delete = Removes a menu option in various RBR and plugin menus

Page [2/4 JoyKey]:
  - Ignition      = Starts a stalled engine (race time only)
  - Restart Stage = Restarts a stage (effective only in Practice and Hotlap races, not in Online races)
  - Call for Help = Call for help after crashing and a car is stuck on stage
  - Retire Stage  = Retire race or replay
  - Exit RBR      = Exit and Close RBR
  - F1  = Shows a tyre data while racing in RallySimFans (bottom left corner)
  - F9  = Toggle freeCam/externalCam mode while a camera is showing ExternalCam
  - F11 = Takes a screeenshot (screenshot files saved in Screenshots game folder)
  - VR Reset = Resets a VR camera view (supports RBRVR and OpenRBRVR plugins)
  - Numpad 4/6/8/2/0/+/-/* = Numpad keys used by RBRVR plugin (moves a seat and re-centers the VR view)
  - Custom1/Custom2/Custom3 = User specified key code or virtual key code (see below for more info about RBRControls.ini options)

Page [3/4 HShifter]:
  - Gear Volume = Sound volume of gear/shifting error in hpattern moden when a clutch is required (0=Muted)
  - Type Change Volume = Sound volume of the HPattern mode/Sequential mode/autoType shifter type notification message (0=Muted)
  - Type = H-Pattern / Sequential / AutoDetect = Shifter type h-pattern, sequential or automatically detected by a chosen car
  - Toggle Type = Toggles between hpattern/sequential/autoDetect shifter types

  H-Pattern shifter specific options
  - Auto Neutral     = Enabled/Disabled. When a shifter no longer keep a specific Gear1-6-R selected then neutral N gear is automatically selected (in most cases this should be enabled)
  - Clutch Required  = Clutch pedal press required to choose a new h-pattern gear
  - Clutch Threshold = 0-100% (0.0-1.0) threshold to activate the clutch (makes it possible to make the clutch effective even when not fully pressed down)
  - Gear 1-6-R       = H-pattern gears

  Sequential shifter specific options
  - Sequential N    = Sequential neutral N gear
  - Sequential Up   = Upshift a sequential gear
  - Sequential Down = Downshift a sequential gear

Page [4/4 Virtual OpenRBRVR]:
  - VR seat movement and VR view reset


ATTENTION! 
If you use RBRControls-hshifter plugin to bind gear controls then DO NOT bind original RBR HPATTERN gear bindings
Reverse/First/Second/Third/Fourth/Fifth/SixthGear in rbr Options/Controls/ControlSetup menu screen (clear those with DELETE key).

You can bind original RBR SEQUENTIAL gear bindings GearUp/GearDown/GearUpSecondary/GearDownSecondary/Neutral even when using 
the new RBRControls-hshifter plugin, but be careful not to bind the same button twice to avoid "double shift up/down" issues.
This makse it possible to use total of three different set of sequential buttons at the same time:
- Two sets in the original RBR bindings (GearUp/GearDown and GearUpSecondary/GearDownSecondary)
- One set in RBRControls-hshifter SequentialUp/SequentialDown

If your sequential shifter hardware has a problem and it sends out double events from a single shifting up or down event
then you can use RSFLauncher.Controls.PreventRepeatedShiftEvents option to workaround double sequential upshifts or downshifts

-----------------------------------------------------------------------------------------------
Plugins/RBRControls/RBRControls.ini configuration file:

[Main]
VerboseLogEnabled = false   ; true to enable more detailed log messages in plugins/RBRControls/RBRControls.log logfile. Set this to true value only when diagnosing issues. Do NOT keep it enabled all the time.
DelayedInitEnabled = true   ; true to delay controller initializations until RBR has completely initialized itself. If you experience delays until RBRControls binding start to work once you are in RBR game menus then try to set this to false value to initialize joysticks earlier in RBR bootup process.

[JoyKey]
Enabled = true            ; true or false

[HShifter]
Enabled = false           ; true or false
SoundVolume = 1           ; Sound volume of shifting and clutch errors while driving (0-Muted, 1=100%)
SoundVolumeShiftType = 1  ; Sound volume of the shifting type notification voiceout ("h-pattern vs sequential mode") (0-Muted, 1=100%)
AutoNeutral = true        ; H-pattern only: When shifter no longer hold the Gear-1-6-R selected then Gear-N is automatically selected
ClutchRequired = 1        ; H-pattern only: Shifting requires a clutch? 0-NotRequired, 1-Required, 2-Auto detected per car as set in plugins/RBRControls/carinfo.ini file. Shifting error sound effect played out when trying to shift without a clutch.
ClutchThreshold = 1       ; H-pattern only: 0=0%...1=100% clutch pressing required to activate the clutch
Type = 2                  ; Shifter type (h-pattern vs seq). 0-Sequential, 1-HPattern, 2-Auto detected per car).
                          ; If you use "auto-detect" option then please see carinfo.ini file also to see the default shifter type per car.

[KeyBind]
JOYKEY_UP = #3 Steering wheel A     ; Arrow key UP binding
JOYKEY_UP_GAMEMODE = 2              ; Valid game mode context for this binding (0-all game modes, 1-racing mode only, 2-RBR is showing a menu)
JOYKEY_UP_TRIGGERTYPE = 0           ; Type of the binding triggering (0-Instant, 1-Short delay, 2-Long delay)
JOYKEY_DOWN = #2 Steering wheel A
JOYKEY_DOWN_GAMEMODE = 2
JOYKEY_DOWN_TRIGGERTYPE = 0
JOYKEY_RESTART_STAGE = #4 Joy XYZ
JOYKEY_RESTART_STAGE_GAMEMODE = 1
JOYKEY_RESTART_STAGE_TRIGGERTYPE = 2

JOYKEY_CUSTOM1_KEYCODE=P            ; Custom1 Keycode to press key P
JOYKEY_CUSTOM2_KEYCODE=0xAE         ; Custom2 Virtual key code 0xAE = VK_VOLUME_DOWN = VolumeDown
JOYKEY_CUSTOM3_KEYCODE=0xAF         ; Custom3 Virtual key code 0xAF = VK_VOLUME_UP = VolumeUp. See this web page for more infno, https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes

...etc...


-----------------------------------------------------------------------------------------------
Copyright (c) 2023-2024 RBRControls (JoyKey for RBR) by Steven Lee. Contributions by mika-n.
Copyright (c) 2023-2024 Re-written and improved HShifter version and integration into RBRControls by mika-n, Towerbrah (better integration with RBR and sound effects).
Copyright (c) 2022 HShifter contributions by DrinkSlurm (clutch threshold).
Copyright (C) 2010 The original idea of HShifter plugin and concept by Racer_S.

See LICENSE file for more details.

This application uses FMOD (www.fmod.com) audio library services. Please see FMOD_Readme.txt file for more details.
This application uses SDL (www.libsdl.org) DirectMedia library services. Please see SDL_Readme.txt file for more details.

-----------------------------------------------------------------------------------------------
Version history:

5.2.26.0
- A bug fix for button bindings in a "MENU" game mode context (ie. button is effective only when RBR is showing a menu and not in racing state) in RallySchool and RallySeason gaming modes.

5.2.25.0
- "Clutch Required" option is no longer a simple TRUE/FALSE option. The option has now three states:
   - NotRequired   = In h-pattern mode a clutch pedal is not required while shifting (all cars).
   - Required      = In h-pattern mode a clutch pedal is required while shifting (all cars).
   - Autodetected  = In h-pattern mode the "clutch required" is set per car in plugins/RBRControls/carinfo.ini file (ie. some cars may require a clutch while others not).

   For now there is no plugin interface to modify the content of the plugins/RBRControls/carinfo.ini file, so those who want to use
   the "Clutch Required = AutoDetected" option need to modify the carinfo.ini file in Notepad. See the carinfo.ini or carinfo.ini.sample files for more details.
   The file supports a new clutch_required INI option:
      [Car17]
      car_name = "Fiat 126 Grp2"
      h_pattern = 1
      clutch_required = 1

5.2.24.2
- RBRControls.ini file has a new SoundFilePath option to set a custom folder source for WAV audio files.
  A codriver mod or a language mod can set SoundFilePath option in RBRControls.ini file and this way
  RBRControls plugin re-installation or an update won't overwrite those custom WAV audio files.

  If the SoundFilePath is not an absolute path reference then the path is assumed to be relative to RBR game folder.
  The following example would use c:\games\rbr\plugins\pacenote\sounds\MyCoolCoDriverMod folder to look for
  Shifter_AutoDetect.wav, Shifter_Error.wav, Shifter_HPattern.wav and Shiter_Sequential.wav audio files.

    SoundFilePath=plugins\pacenote\sounds\MyCoolCoDriverMod

5.2.24
- Added two new configuration options to plugins/RBRControls/RBRControls.ini file. These two options are meant to diagnose controller connection issues.
  You can use Notepad to add the [MAIN] section and these two new options in RBRControls.ini file if those options are missing at the moment (see example below).

  VerboseLogEnabled
    true  = Plugins/RBRControls/RBRControls.log logfile shows more detailed messages. Do NOT keep this enabled all the time because this slows down the plugin performance.
    false = (default) No extra logfiles messages. Shows only error messages.

  DelayedInitEnabled
    true  = (default) Delays controller connections until RBR is fully up and running after bootup.
    false = Controllers are connected early on during RBR bootup to make controllers respond to key bindings without delays. Set this to false value only if you experience significant delay until key bindings start to work after RBR bootup.

  Example options (three text lines) you can copy-paste to the beginning or at the end of RBRControls.ini file. If you use these with default values
  then no need to add anything to RBRControls.ini file.

    [Main]
    VerboseLogEnabled = false
    DelayedInitEnabled = true

5.2.23
- A keyboard binding shows both the key code and the key name.

5.2.22
- New button bindings to move a seat (driver's cam view) position in OpenRBRVR. See the new "OpenRBRVR 4/4" page. Thanks to Detegr.
- Minor bug fixes here and there.

5.2.21
- Faster connection to joysticks at RBR bootup time. Thanks to Detegr for diagnosing the delay issue with some joysticks.
- Fixed the handling of MadCatz ButtonPad controls (didn't recognize all buttons). Thanks to Durandom for helping to diagnose and fix the issue.
- New binding option:
     IGNITION = Starts a stalled engine. Alternative button binding for the rbr IGNITION control.

5.2.20
- Small bug fix release (OpenRBRVR integrations)

5.2.19
- Small bug fix release

5.2.18
- New binding options: 
     VR RESET VIEW   = VR camera view reset (RBRVR and OpenRBRVR)
     VR TOGGLE DEBUG = Toggles VR debug HUD on/off (RBRVR and OpenRBRVR)

5.2.16
- Support for keyboard bindings.
- Support for custom key codes JOYKEY_CUSTOM1_KEYCODE...JOYKEY_CUSTOM3_KEYCODE in RBRControls.ini file.
  The keycode value can be 0-9/A-Z key name or any other Windows virtual key code (VK_xxxx virtual key codes) as integer value.
  See https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes for more info about virtual key codes.
    JOYKEY_CUSTOM1_KEYCODE=P    -> Custom1 bind would press key P
    JOYKEY_CUSTOM2_KEYCODE=8    -> Custom2 bind would press key 8
    JOYKEY_CUSTOM3_KEYCODE=0xAF -> Custom3 bind would press "Volume Up" virtual key code (0xAF hex value is the same as 175 decimal value)

5.2.15
- HShifter disables itself if the original RBR options/Controls/ControlSetup hpattern gears have been set.
  GearFirst..GearSixth and Reverse controls in the original RBR binding screen should be empty if you 
  use this RBRControls-hshifter hpattern plugin. You can set GearUp/GearDown bindings in the original RBR
  bindings screen if necessary, but hpattern bindings should be empty there.

- Optimized handling of controller inputs.

5.2.13
- Support for "Prevent repeated shift events" RSFLauncher.Controls option in RBRControls-hshifter to workaround faulty shifter hardware sending duplicated events.

- A separate volume option for both "shifting/clutch error" and "shifter type notification voice-out" sounds (0=mutes the sound effect).

- Support for user selectable "Instant / [=] Short / [==] Long" trigger delay (a keybind action is processed instantly when a button was pressed or after certain delay while holding down the button).
  Use left/right arrow keys to cycle through these delay options in JoyKey bindings.

- Improved the handling of multiple bindings in the same JOY button (for example one with short delay and other binding with long delay). 
  It is now possible to choose if the processed action will be from the short or long binding option (ie. holding down a button and NOT releasing the button on "short delay marker" will skip the short action and will take the long action).
  
- Support for a game mode context "all / [race] / [menu]" (a keybind action is processed in all game modes or only while the game is in racing or RBR is showing a menu).
  This makes it easier to share a single button in several bindings (doing something in RBR menus and other things while racing).
  NOTE! The in-game plugin doesn't let you to change this option yet, but you can edit JOYKEY_XXX_GAMEMODE default context options in plugins/RBRControls/RBRControls.ini file using Notepad.

- Support for xinput and devices with haptic controls. Now these controls are properly detected.
   
- New binding options: 
    DELETE key
    BACKSPACE key
    CONTROL+S key to save changes in Setup Editor
    EXIT RBR action
    RETIRE STAGE OR REPLAY action

5.2.8
- The first public release.

5.2.0
- JoyKey feature improvements.
- HShifter plugin re-written from scratch and improved and added new features.
- New binding options: 
     CALL FOR HELP
     RESTART STAGE

5.1.0
- The first internal test release of RBRControls (JoyKey for RBR control mappings only)
