Shift Logic - Automatic Gearbox

Summary

The automatic gearbox shift logic controller handles the automatic shifting logic of the transmission, the different drivemodes and torque converter lockup.

It is an extension of the vehicle controller and automatically gets called if a vehicle is equiped with an automatic transmission .


File Info

Filename shiftLogic-automaticGearbox.lua
Path /lua/vehicle/controller/shiftLogic-automaticGearbox.lua
Usage type Specific to vehicleController

JBeam Properties

string
type
PRNDS21M
default
The available shifting modes.

A transmission with only manual modes will not shift automatically while in realistic shifting mode.

This can be used to simulate automatic transmissions with manual valving, as found on some racing vehicles.

number
type
0
default
Minimum RPM at which the torque converter locks up.
This is based on the RPM of the converter output, so it will occur at the same speed even if the converter is heavily slipping.
number
type
RPM range over which the lockup clutch activates.
number
type
0
default
Smallest gear at which the torque converter will try to lock up.
number
type
5
default
Sets how fast the lockup clutch can activate/deactivate.
number
type
torqueConverterLockupRate * 2
default
Sets how fast the lockup clutch can activate.
number
type
torqueConverterLockupRate
default
Sets how fast the lockup clutch can deactivate.
string
type
N
default
Initial transmission gear when the car spawns.
string
type
D
default
The gear that will be used when going forward in arcade mode.
number
type
0
default
Sets minimum time (s) automatic gearbox will spend changing gears.
Sets minimum time (s) automatic gearbox will spend changing gears.
number
type
0
default
Sets minimum time (s) automatic gearbox will spend changing gears.
Sets minimum time (s) automatic gearbox will spend changing gears.
number
type
0
default
Sets time (s) automatic gearbox will spend changing gears when in sport or manual mode.
Set 0 to automatically calculate.
boolean
type
true
default
Enables automatic downshifting when the engine RPM reaches 1.2 times idle RPM.
number
type
1
default
Cuts throttle by set percent while shifting to increase smoothness.
Will not occur in sport/manual mode. Set 1 to disable for older style mechanical gearboxes


Electrics

Name
Units/Values
Description
Name
lockupClutchRatio
Units/Values
0 to 1
Description
Indicates the position of the torque converter lockup clutch. 0 means it’s disengaged, while 1 means it’s fully locked.

Public Functions

Function name
Parameters
Description
Function name
gearboxBehaviorChanged
Parameters
behavior
Description
Switches between arcade and realistic gearbox modes.
Function name
shiftUp
Parameters
Description
Switches to the next position on the gear lever.
Function name
shiftDown
Parameters
Description
Switches to the previous position on the gear lever.
Function name
shiftToGearIndex
Parameters
index
Description
Shifts the gear lever to the selected position.
Function name
getGearName
Parameters
Description
Current gear the transmission is in.
Function name
getGearPosition
Parameters
Description
Current position of the automatic shifter.
Function name
setDefaultForwardMode
Parameters
mode
Description
Changes the gearbox’s default forward mode.
Function name
sendTorqueData
Parameters
Description
Sends torque and power related data to the UI.

Public Properties

Name
Description
Name
brake
Description
Brake input
Name
checkEngine
Description
Indicates if the engine is disabled.
Name
clutchRatio
Description
Indicates clutch input. 1 is fully engaged, 0 is fully disengaged.
Name
currentGearIndex
Description
Current gear index of the gearbox.
Name
energyStorages
Description
Energy storage(s) associated to the engine
Name
engineLoad
Description
Engine load
Name
engineThrottle
Description
Throttle input.
Name
engineTorque
Description
Engine combustion torque, before friction losses.
Name
flywheelTorque
Description
Engine output torque.
Name
gearboxHandling
Description
List containing many of the parameters which influence gearbox shifting behavior.
Name
gearboxTorque
Description
Gearbox output torque.
Name
idleRPM
Description
Engine idle RPM
Name
ignition
Description
Indicates that the ignition is on.
Name
inputValues
Description
List containing the brake, throttle and clutch values.
Name
isArcadeSwitched
Description
Indicates if the gearbox is in arcade mode.
Name
isEngineRunning
Description
Indicates the engine is running
Name
isSportModeActive
Description
Indicates if sport mode is active.
Name
maxRPM
Description
Engine maximum RPM
Name
oilTemp
Description
Oil temperature of the engine.
Name
rpm
Description
Current engine RPM
Name
shiftPreventionData
Description
List containing the slip threshholds to prevent shifting.
Name
shiftBehavior
Description
List containing the current optimal shiftpoints defined by the vehicle controller.
Name
smoothedValues
Description
List containing a smoothed version of some properties.
Name
smoothedAvgAVInput
Description
Smoothed angular velocity of the gearbox input (rad/s)
Name
throttle
Description
Throttle input
Name
timer
Description
List containing current time values
Name
timerConstants
Description
List containing target values for the different timers, as set in the jbeam
Name
waterTemp
Description
Coolant temperature of the engine.

Example Usage

A vehicle controller section with parameters specific to this sub controller, defined within a transmission’s jbeam.

"vehicleController": {
    "automaticModes":"PRND21",
    "useSmartAggressionCalculation":false,
    "calculateOptimalLoadShiftPoints": true,
    "transmissionGearChangeDelay":2,
    "gearboxDecisionSmoothingUp":0.5,
    "gearboxDecisionSmoothingDown":0.5,
    "lowShiftDownRPM":1100,
    "lowShiftUpRPM":1900,
    //"highShiftDownRPM":3100,
},

Vehicle controller section associated to a locking torque converter.

"vehicleController": {
    "torqueConverterLockupRPM":1100,
    "torqueConverterLockupMinGear":3,
},
Last modified: August 7, 2023

Any further questions?

Join our discord
Our documentation is currently incomplete and undergoing active development. If you have any questions or feedback, please visit this forum thread.