Grinding Tranny Mod 2

Dear mod developer or enthusiastic rFactor tweaker,

I’ve made Grinding Tranny Mod 2 with you in mind.  This plugin still provides an alternative gearbox model for rFactor, but its now much more customisable and user friendly.  My aim for version 2 has been to make the plugin as transperant as possible to the end user so that it can be installed as part of a mod without any (much) additional effort being required by the user.  The point of this letter then is to inform you about what kind of integration is possible with your mod, and how to get the behaviour you want from the plugin.

Cheers,

Richard

richardjackett | gmail | com (hardjack79 at nogrip)

What the end-user should see

Installation

As far as installation is concerned, the plugin files can be placed in the Plugins folder by the mod installer, the only real issue being whether the GrindingTranny.ini file is overwritten or not if it already exists (more on this later).  For the plugin to work, a key must be mapped to the Neutral function in rFactor, and Upshift and Downshift must be unmapped.  I have left these tasks up to the end user, although it would be possible for an installer to do this by force... that is your decision.  In contrast to version 1, the plugin can now determine the player name and Neutral key mapping automatically.

Usage

Version 2 is able to turn itself on only when it is explicitly supported by the current mod, making it possible to install it as part of your mod without worrying that it will affect the other mods that the user has installed.  Within a supported mod, the plugin allows for the end user to turn the Grinding Tranny functionality on or off within rFactor’s GUI by changing the setting of the “Gearbox” upgrade for the current car.  The 1st and 2nd levels of upgrade turn the plugin off, the 3rd and 4th turn it on.  There can be distinct behaviours of the Gearbox for settings 3 and 4, controlled by parameters contained within the car’s upgrades.ini and/or .veh files.  For example, setting 3 could behave like a synchromesh gearbox, and setting 4 could behave like a dog-engagement gearbox; or perhaps 3 could use the plugin’s own sound engine while setting 4 could use rFactor’s horn function to produce the grinding sound.  Finally, gearbox parameters can vary car by car.

How the plugin works

Each time you hit the track (the EnterRealtime event) the plugin first loads the current settings from the GrindingTranny.ini file.  It then does a scan of the UserData folder to find which driver is active and does its best to read which key has been assigned to Neutral in the Controller.ini.  After a pause of 1 second it locates the .veh file for the current car and reads in the state of the “Gearbox” upgrade and any overloaded parameters for the current upgrade state.  Finally, it attempts to determine the current gear ratios from tempGarage.svm.  Now the plugin watches the game telemetry and triggers a missed shift event as necessary.  First the gearbox is forced into neutral by faking a continuous stream of Neutral keypresses, and the grinding sound is played.  This continues until the missed shift event is terminated, either by a successful reshift or after 5 seconds, whichever occurs first.

Essential settings for using the plugin

Format of the gear ratios

The ratios are pulled from the comments at the end of the GearNSetting strings in the tempGarage.svm and the text formatting of the gear ratios is crucial if they are going to be read correctly.  RatioDetectionMethod in the ini file defines what method the plugin uses to read the ratios.  Method 2 is slightly less precise, but far more reliable, so it is recommended.  Any double slash at the start of the line is ignored by the plugin.

RatioDetectionMethod=1 works for the native rFactor format by reading in the first 4 characters following the // after the equals sign, but will fail when this number is not a decimal or is greater than 9.99.

RatioDetectionMethod=2 reads the contents of the brackets at the end of the line (which is the gear ratio multiplied by the final ratio) and therefore is far more robust even when the gear ratio is commented as a fraction, as long as the brackets contain a decimal.

The final ratio is determined by finding the number that lies between the final / and the first : in the row.  Using Method 2, if it can be determined, the individual gear ratios are divided by it.  If it can’t be determined the individual gear ratios are left as is, and a final ratio of 1.0 is used.  In either case the plugin will work fine, but for Method 1 it is essential that the final ratio can be read.

Example 1:

Gear1Setting=0//3.60 (10.80)

//Gear2Setting=3//2.40 (7.20)

Gear3Setting=5//13/7 (5.57)

//FinalDriveSetting=1//3.00:1

Method 1 could handle gears 1, 2, and final, but not 3rd, because it is stored as a fraction.  Method 2 would read all of them (the bracketed portion), and would back-calculate the individual ratios by division by the final ratio.

Example 2:  As above, except,

//FinalDriveSetting=3// 8/37 (bevel 1/1)

Neither method can read this format directly.  Method 1 will now determine the final ratio by dividing the bracketed quantity in Gear1Setting by the decimal ratio.  Method 2 will just set the final ratio to 1.00, given that the other ratios already include the final.

Any other format is likely to fail.  In my opinion Method 2 is preferred even when decimals are used because of its ability to handle numbers larger than 9.99.  FYI The lack of a explicit final ratio is no problem as far as the operation of the plugin is concerned, it just doesn’t look as nice in the telemetry.

Car_Upgrades.ini

Due to how the plugin forces the gearbox into neutral after a missed shift (rapidly repeating simulated presses of the neutral key) it is essential that there is a slight delay between rFactor receiving a message to shift and it actually engaging the gear.  The NeutralKeyRepeatRate in the GrindingTranny.ini will be set to 0.01 seconds by default, and a system running at 60 fps will get through a cycle of key up down up in a maximum of 0.05 seconds, so the delay between message and engagement should therefore be greater than or equal to 0.05 seconds.  Clearly a 30 fps system would require a maximum of 0.10 seconds to be sure that the ‘Force Neutral’ message would always win out against rFactor’s ‘Engage now!’ messages.  Unfortunately this latter value is getting towards the point where it starts to interfere with the driver’s ability to time the clutch for quick shifts, so I recommend something from 0.05 to 0.10 seconds for the parameters UpshiftDelay and DownshiftDelay.

These parameters can be set in the .hdv file, but as you will probably want to change these depending on which Gearbox upgrade has been selected, probably the Car_Upgrades.ini is a better place to do it.

Customising plugin behaviour to suit your mod

GrindingTranny.ini

The most obvious place to change settings is the GrindingTranny.ini file, and this is certainly the easiest way to test all the options out, as many parameters are reloaded every time you hit the track.  Unfortunately there is only one ini file to be shared by all mods in a given install, so overwriting existing settings is a potential issue.  Fortunately there is little in this file that can’t be overloaded by the .veh files, so I encourage you to leave the GrindingTranny.ini as close to default settings as possible for your application, thus minimising the likelihood that any subsequent ini change will mess things up for you.

The GrindingTranny.ini file is quite well documented, and rather than describe each of the parameters again here, I encourage you to have a quick read of the ini to familiarise yourself with the customisation that is possible for the plugin’s operation.

The first thing to do is to set PluginActive=1, as this will make sure that the plugin is inactive unless it is specifically supported by a mod (at the very least, yours).

Telemetry should be set to 0 or 1, as 2 will create big files and eventually cause stutters in rFactor when it reads/writes.  Console definitely set to 0 once you have debugged everything.

The [Sound] and [Tuning] sections can be overloaded in the .veh file.

State of the “Gearbox” upgrade

In the car_Uprades.ini file you should create an upgrade called “Gearbox” (apologies to non-English speakers, but it must be exactly as written).  As well as the usual upgrades.ini functionality, this has several additional effects:

1)  It tells the plugin that it is supported by the current mod.

2)  It determines whether the plugin should be switched on or off (ON for the 3rd and 4th upgrade levels, OFF for the 1st and 2nd).

3)  It can be used to choose how the plugin’s parameters are overloaded (see below).

This gives the user the ability to turn the plugin on or off depending on what method of gearshifting they use, and whether they want to be able to miss gears or not.  It gives you the ability to get creative with the 3rd and 4th Gearbox upgrade settings, as discussed below.

Upgrade.ini settings

The car_Upgrades.ini is the best place to define the UpshiftDelay and DownshiftDelay parameters, as they will probably change depending on which “Gearbox” upgrade is used.  The “Gearbox” upgrade functionality is described in the section above, so I will use this space to show an example of how GrindingTranny could be implemented in a hypothetical mod.  Disclaimer:  I haven’t experiemented very thoroughly with the other Upgrades.ini parameters so you will want to do your own testing instead of relying on my (guessed) values.

UpgradeType="Gearbox"

{

UpgradeLevel="Sequential"

{

Description="Sequential shifting with automatic clutching and throttle lift/blip"

HDV=[DRIVELINE]

HDV=SemiAutomatic=1

HDV=UpshiftDelay=0.15

HDV=UpshiftLiftThrottle=1

HDV=DownshiftDelay=0.20

HDV=DownshiftBlipThrottle=1

}

UpgradeLevel="Gated Shifter (No Missed Shifts)"

{

Description="Manual H-pattern gearbox with no electronic aids.  Missed shifts are not punished."

}

UpgradeLevel="Synchromesh Gated Shifter"

{

Description="Manual H-pattern synchromesh gearbox with possibility to miss shifts (powered by the Grinding Tranny Mod). Please ensure that NEUTRAL is mapped to a key and UPSHIFT and DOWNSHIFT are unmapped."

HDV=[DRIVELINE]

HDV=UpshiftDelay=0.3

HDV=DownshiftDelay=0.3

}

UpgradeLevel="Dog-engagement Gated Shifter"

{

Description="Manual H-pattern dog-engagement gearbox with possibility to miss shifts (powered by the Grinding Tranny Mod). Please ensure that NEUTRAL is mapped to a key and UPSHIFT and DOWNSHIFT are unmapped."

Price=1000

HDV=[DRIVELINE]

HDV=UpshiftDelay=0.06

HDV=DownshiftDelay=0.06

}

}

So in the preceding example the first two gearbox upgrade settings are suitable for the default rFactor sequential and gated shifting options respectively, and the next two upgrade settings turn on the Grinding Tranny Mod and make shifts behave like a synchromesh or a dog-box transmission respectively (at least when combined with some overloading in the .veh file).  You don’t need to include an upgrade for level 4 if you don’t need it.

Overloading vehicle (.veh) files

If a “Gearbox” upgrade level of 3 or 4 is detected the plugin will look in the current vehicle’s .veh file for Grinding Tranny Mod parameters, and if found will use these in preference to those recorded in the GrindingTranny.ini.  There are two levels of overloading possible, general and specific.  General overloading is definined by including the parameter name as it appears in the GrindingTranny.ini and will apply to both levels of upgrade.  Specific overloading is defined by including a parameter name with either “3” or “4” appendend to the end, and will only apply to the corresponding upgrade level.  Specific overloading has a higher priority than general overloading.  

To illustrate this, here is an extract from a hypothetical ThisCar.veh (this code could be placed anywhere within the file):

/// Below are some Grinding Tranny parameters for ThisCar

ReshiftMethod=2

SoundVolume=100

SoundFile3=.\Plugins\Grind1.wav

SoundFile4=.\Plugins\Grind2.mp3

SoundVolume4=70

/// This is the end of the parameter overloading example.

“ReshiftMethod=2” will require the user to make a full clutched reshift for ThisCar, regardless of what is set in the GrindingTranny.ini (but only if the Gearbox setting is 3 or 4).  You can also see that for setting 3 we will use a wav file for the sound, and for setting 4 we’ll use an mp3 as the grinding sound.  The wav will be played at 100% volume and the mp3 will be played at 70% volume, because a specific (numbered) parameter takes precedence over a general one.  All unlisted parameters will take their values from the GrindingTranny.ini.

Examples:

I will complete the example I started in the section on “Upgrade.ini Settings”, where Gearbox=3 is a synchromesh box and Gearbox=4 is a (better) dog-engagement gearbox.

ThisCar.veh:

/// Grinding Tranny parameters for ThisCar

// Synchro box (Gearbox=3)

SoundFile3=.\Plugins\Grind_Synchro.wav

SoundDuration3=0.7

RevMatchTolerance3=0.15

ClutchThreshold3=0.85

// Dogbox (Gearbox=4)

SoundFile4=.\Plugins\Grind_Dogbox.mp3

SoundDuration4=-2.0

RevMatchTolerance4=0.25

I don’t know if these values are realistic, but you should see that in this example the synchro box is much more difficult to clutchless shift with (c.f. RevMatchTolerance), and also slightly more demanding on the amount of clutch needed if clutching the shift (c.f. ClutchThreshold).  From the Car_Upgrades.ini you might recall that the synchro box also involves a 0.3 s delay before the gear is engaged, to simulate the transition through the synchro, whereas the dog engagement is very fast.  Finally, there is a different grinding sound for each box, the synchro grind playing once for a maximum of 0.7 seconds, while the dog box grind file will be repeated over and over for a maximum of 2 seconds in total.

You may be able to conjure up much better values after some experimentation, and I would love to hear about your findings.  Of course ‘better’ for your mod may mean more realistic, or it may mean more worthy of paying a steep upgrade price, or it may mean having two very different but finely balanced settings to decide between.  For the latter, I would be tempted to include the following lines:

ReshiftMethod3=2

ReshiftMethod4=3

This would require a full clutched reshift to recover with the dog-box, while the synchro would require only a quick dip of the clutch to unload the layshaft and let the gear engage.

To illustrate another example given at the start of this document, the final two settings could determine whether the plugin’s sound engine or rFactor’s sound engine handles the grinding sound (only the last 2 upgrade levels shown!):

ThisModel_Upgrades.ini:

UpgradeLevel="Gated Shifter (external sound engine)"

{

Description="Manual H-pattern gearbox with possibility to miss shifts (powered by the Grinding Tranny Mod).  Uses an external sound engine for grinding sounds."

HDV=[DRIVELINE]

HDV=UpshiftDelay=0.06

HDV=DownshiftDelay=0.06

}

UpgradeLevel="Gated Shifter (internal sound engine)"

{

Description="Manual H-pattern gearbox with possibility to miss shifts (powered by the Grinding Tranny Mod).  Uses an external sound engine for grinding sounds."

HDV=[DRIVELINE]

HDV=UpshiftDelay=0.06

HDV=DownshiftDelay=0.06

SFX=VS_INSIDE_HORN=\Secondary\Grind_Default_In.wav

SFX=VS_OUTSIDE_HORN=\Secondary\Grind_Default_Out.wav

}

ThisCar.veh:

/// Below are some Grinding Tranny parameters for ThisCar

SoundFile=.\Plugins\Grind_Experimental.wav

SoundVolume3=70

SoundVolume4=-1

For setting 3 the plugin’s own sound engine is used with the file Grind_Experimental.wav being played at 70% volume.  For setting 4 the plugin is instructed to activate rFactor’s horn every time a shift is missed (by SoundVolume4=-1) and the upgrades.ini has pointed the internal and external horn sounds to grinding sound files that you placed in the \GameData\Sounds\Secondary folder.

There are countless other possibilities, and if you come up with any good ones please let me know.

Disclaimer, Legal, and Acknowledgements

You may include this plugin and supporting files in any freely distributed mod provided that they are not modified in any way.  The only exception to this is the GrindingTranny.ini file, in which you may change parameter values (you may also add some text if necessary).  Somewhere visible in your mod you should mention that it employs the Grinding Tranny Mod, not least because some people may want to delete it as the first thing they do.  I also encourage you to include a mention of “Grinding Tranny Mod” somewhere in the description for Gearbox upgrades 3 and 4 if that makes sense in the context of your mod.  The disclaimer bit is very simple: I am sure that there is nothing in this plugin or accompanying files that could cause any harm to your system, security, or privacy, but you use and distribute this work completely at your own risk and I take no responsibility for any repurcussions of doing so.  If you accept all that then you are free to distribute the Grinding Tranny Mod as part of your mod without my explicit permission (but please drop me an email so that I know!).

To conclude this document, I’d like to pay special thanks to the HistorX mod team, especially Rantam, Yoshi, Gonzas, and Hugh, for all the encouragement, suggestions, testing, and bandwidth I received from them while trying to make this plugin play nice with an AAA mod like theirs.  Also a big thanks to the developers of the BASS sound library for making it simple enough even for me to use.  Finally, thank you for considering using Grinding Tranny Mod as part of your project and for bothering to read this far through the guidance document.