VehicleController overhaul

Hey everyone,

today I'd like to introduce you to some deep changes inside a core part of the game. For the average user this is not really of much interest, modders however (especially those with more advanced vehicle lua mods) will appreciate the insight.

TLDR: If you are the author of a vehicle mod that uses the stock vehicleController but a custom shiftLogic, keep on reading. If not, the changes do not really affect you.

Up till now it was very difficult to support anything else than vehicles with a single combustion engine. Hybrids or electric powertrains weren't really supported out of the box. Of course you could always create your own logic from scratch and have everything working the way you like. However, that requires quite some knowledge about the game and how stuff works.
To make things easier for the future I decided to revamp large parts of how the vehicleController works and make it more future proof by removing the dependency of having a combustion engine with a gearbox.
In the end this means that it's much easier to keep using the vehicleController logic for custom powertrains while only supplying some supplementary logic.

The downside of this improved compatibility is that I had to do some breaking changes that will break some mods. Please note: this issue only applies to mods that use the stock vehicleController.lua file with an additional custom "shiftLogic" module. Fortunately there are two easy options to fix that:

1. Update your code according to what I'll describe below (preferred)
2. Ship a copy of the current vehicleController.lua with your mod

Option 1

There are a bunch of small changes required to make things less focused on combustion engines. Here's what needs to be changed:

Every shiftLogic module now has some more exposed data, giving it greater control over how certain aspects of the vehicleController work:

Code:

M.smoothedAvgAVInput = 0
M.rpm = 0
M.idleRPM = 0
M.maxRPM = 0

M.engineThrottle = 0
M.engineLoad = 0
M.engineTorque = 0
M.gearboxTorque = 0

M.ignition = true
M.isEngineRunning = 0

M.oilTemp = 0
M.waterTemp = 0
M.checkEngine = false

M.energyStorages = {}

Most of these new properties need to be updated every frame, the stock shiftLogic modules have now a dedicated method for that:

Code:

local function updateExposedData()
  M.rpm = engine and (engine.outputAV1 * constants.avToRPM) or 0
  M.smoothedAvgAVInput = sharedFunctions.updateAvgAVSingleDevice("gearbox")
  M.waterTemp = (engine and engine.thermals) and (engine.thermals.coolantTemperature and engine.thermals.coolantTemperature or engine.thermals.oilTemperature) or 0
  M.oilTemp = (engine and engine.thermals) and engine.thermals.oilTemperature or 0
  M.checkEngine = engine and engine.isDisabled or false
  M.ignition = engine and not engine.isDisabled or false
  M.engineThrottle = (engine and engine.isDisabled) and 0 or M.throttle
  M.engineLoad = engine and (engine.isDisabled and 0 or engine.instantEngineLoad) or 0
  M.running = engine and not engine.isDisabled or false
  M.engineTorque = engine and engine.combustionTorque or 0
  M.gearboxTorque = gearbox and gearbox.outputTorque or 0
  M.isEngineRunning = engine and ((engine.isStalled or engine.ignitionCoef <= 0) and 0 or 1) or 1
end

This method is then being called every frame from the various updateXYZ() methods throughout the file.

There is also a new exposed method for every shiftLogic module:

Code:

local function sendTorqueData()
  if engine then
    engine:sendTorqueData()
  end
end

M.sendTorqueData = sendTorqueData

Last but not least the init method got overhauled too. The parameters changed and it needs to do a bit of additional work:

Code:

local function init(jbeamData, sharedFunctionTable)
  sharedFunctions = sharedFunctionTable
  engine = powertrain.getDevice("mainEngine")
  gearbox = powertrain.getDevice("gearbox")
  torqueConverter = powertrain.getDevice("torqueConverter")
  [..]

Code:

M.maxRPM = engine.maxRPM
  M.idleRPM = engine.idleRPM
  M.maxGearIndex = automaticHandling.maxGearIndex
  M.minGearIndex = abs(automaticHandling.minGearIndex)
  M.energyStorages = sharedFunctions.getEnergyStorages({engine})

I know this probably looks quite scary but I'm happy to help anyone that asks, just send me a message

I've also attached a current copy of the auto shiftLogic so you can take a look at the overall file.

Attention: the changed code obviously won't work for the current public version, this guide is just so that you can update your mods once the next update is out!

Option 2

The much easier, but definitely not preferred method is to include a copy of your current vehicleController.lua file in your mod. Upon loading the mod this will overwrite the new file with your old copy, keeping everything working as is. Please note: This should only be a last resort, if you do this, you miss out on future improvements of the vehicleController. (Also: this is only allowed for controllers/powertrain/energyStorage as they were designed with this in mind, never do this with any other stock lua files!)


Feel free to ask questions or post suggestions about this here.

 

Does this new change allow for multiple engines?(For example 2 separate combustion engines)?

I feel like more flexibility with the powertrain system would be welcome. Right now (as far as I know) we anly have the MainEngine, how about adding an ability to name each engine separately using some sort of a template, the same could go for transmissions, transfercases and such.
This would allow modders to create interesting contraptions along the lines of the twinstar eldorado.
You could for example have a powertrain layed out like that:
CombEngine1-torqueConverter1-differentialF-wheelaxleFL/FR
And:
CombEngine2-torqueConverter2-differentialR-wheelaxleRL/RR.



Even if multiple separate powertrain systems wouldn't be possible, I'm still sure the hybrid stuff you've mentioned could come usefull if not exactly for me then for sure for others.

 

Yes that is possible too now. Please note: possible does not mean it works out of the box, but rather that the are no hurdles in making it happen. You could make a 6x6 with 6 electric motors no problem as long as you create your own shiftLogic module that controls all 6 of these in some way.

I obviously can't include logic for all sorts of weird and wonderful things, so that stuff needs to be implemented by modders.

 

Hm I don't quite understand, you are either using an existing shiftLogic file (in which case the mod will continue to use the existing file and nothing happens) or you have your own file in the mod in which case that file is then outdated and needs to be updated. Oh, do you mean you just copied the stock cvt logic file to your mod without modifying it? If so, why?

 

He, you can indeed point it to some random file, in the vehicleController jbeam section, set the "shiftLogicName" attribute to "cvtGearbox". Ie:

Code:

"vehicleController": {
  [..]
  "shiftLogicName": "cvtGearbox",
  [..]
}

 

Nope that's been there ever since these shiftLogic modules existed

 

Just tested, when I do what I proposed above, the hybrid ETK works fine on my current version. (wouldn't work before the fix ofc)

BTW, really nice job on that one!

 

No, I'm not going to include stuff anymore that is not used by our own content, in the past doing this has fired back at me a few times already...

 

I literally said that weird stuff won't be included and why and you guys conclude that exactly that will be part of an update...?