Powertrain
Need help Getting your mod working with the new Powertrain? See 0.8 Mod Conversion Guide
Introduction
The powertrain is a new system in 0.8 used to simulate a vehicle's engines, clutches, gearboxes, shafts, differentials, and other devices. It is completely modular, allowing nearly any combination of components, and it is also moddable, meaning creators can invent their own devices, layouts, and control systems.
Powertrain completely replaces the old "drivetrain" system, but is able to convert older vehicles on-the-fly to a basic form of the new system (compatibility mode). To take full advantage of the new features, creators can convert their vehicles by following the documentation and adding the necessary components of the powertrain system.
Technical Overview
The powertrain system works by creating a "tree" of devices, leading from an engine to a clutch-like device, then to all sorts of shafts or differential-like devices, ending down at the wheels. In this tree, the torque flows down from the engine at the top of the tree, down to the wheels. Speeds feed up from the wheels to the engine, creating a closed feedback loop. Because the device tree operates in the physics rate of 2000hz, very high drivetrain stiffness and stability is achieved.
To control the tree of devices, a "controller" system operates at a higher level, connecting the devices to the user input, user interface, and other systems, while controlling things such as clutching and shifting behavior. This system runs in the graphics rate, giving allowance for more complex logic and math.
Controller list with Links
| Name | Description |
|---|---|
| vehicleController | The main controller used to control official vehicles or mod vehicles with typical powertrain layouts |
| 4wd | A controller to control the transfer case and differential locks for off road trucks like the D-Series and Hopper. |
| beamNavigator | A controller to operate the vehicle navigation screens. |
| postCrashBrake | A controller that applies the brakes after a crash is detected; used on the ETK800 and ETK-K. |
| dummyController | A default controller used for props or when no controller is defined in jbeam. |
Device List with Links
| Name | Device Category | #Inputs | #Outputs | Description |
|---|---|---|---|---|
| combustionEngine | engine | 0 | 1 | The combustionEngine is mainly a port of the old engine model, with the added feature of stalling/starting and ability to run backwards. Most engine properties that applied to the old engine apply to the new one too. |
| frictionClutch | clutchlike | 1 | 1 | The frictionClutch is a model of the typical clutch used on a car with a manual transmission, having some dry friction elements and a sprung hub. frictionClutch can create a direct connection from engine to powertrain. |
| viscousClutch | clutchlike, viscouscoupling | 1 | 1 | The viscousClutch is a model of a fluid coupling, based on the clutch used in the original drivetrain code. It transmits a torque proportional to difference in rotation speed, always allowing some slip. The viscousClutch is used for compatibility mode, but may come in handy for some designs. |
| torqueConverter | clutchlike, viscouscoupling | 1 | 1 | The torqueConverter is a model of a typical 3-element torque converter used in automatic transmissions. It performs torque multiplication at low output speeds, raising the efficiency and power off the line when compared to a slipping viscousClutch or frictionClutch. |
| manualGearbox | gearbox | 1 | 1 | The manualGearbox is a model of a manual gear change box. Other than a set of gear ratios, it also includes gear damage/wear for shifting when there is still torque being transmitted. |
| automaticGearbox | gearbox | 1 | 1 | The automaticGearbox is a model of an automatic transmission. Unlike the manualGearbox, it can make smooth continuous shifts between gears. It also contains a parking lock. |
| dctGearbox | gearbox, clutchlike | 1 | 1 | dctGearbox contains two torque paths, each with their own clutch, allowing for ultra fast shifts. No clutch device is necessary, this gearbox connects directly to the engine. |
| cvtGearbox | gearbox | 1 | 1 | CVT gearboxes have an infinitely varying gear ratio, between a specified minimum and maximum. The controller logic determines what ratio to choose based on inputs such as throttle and engine speed. The cvtGearBox is designed to work behind a torqueConverter device. |
| rangeBox | gearbox | 1 | 1 | The rangeBox is like a manual gearbox, but with a simple toggle between 2 ranges, allowing high/low range control for 4 wheel drives or as a splitter for a truck gearbox. |
| shaft | shaft | 1 | 1 | The shaft is a simple direct connection between devices, or between devices and wheels. It has the ability to engage, disengage, or break, to change the flow of power in the powertrain. |
| differential | differential | 1 | 2 | The differential is used to split power between 2 outputs. It is modeled after the differentials available in cars. There are several subtypes available: Open, Locked, LSD, Viscous. |
| splitShaft | differential | 1 | 2 | The splitShaft is a composite of a clutch and a shaft. It has one input, and two outputs. The primary output is a direct connection like the shaft, but the secondary output is a viscousClutch or frictionClutch. This allows splitting of the power in a strongly biased way, replicating a power take-off (PTO) output. |
| multiShaft | differential | 1 | n | The multiShaft works like a differential, with the difference is that it contains any number of outputs, splitting the torque between them based on relative velocity (like a viscous clutch). This device is used for compatibility mode with older unconventional vehicles (odd number of wheels, more than 1 differential per wheel pair, or greater than 4 wheels). It can be used for a quick way to build a powertrain when accuracy is not too important. |
Adding a Controller
The first thing you need to start using the new powertrain is a controller. The standard controller available for the powertrain is called vehicleController, which is designed mainly to control wheeled vehicles with a single engine or multiple "parallel" engines that use the same inputs. vehicleController can handle typical gearBox and clutch combinations, as well as any "physically valid" combinations of shafts and differentials. The vehicleController handles user input, shifts the gears, and operates the clutch in different ways depending on whether it is in "Arcade", "Realistic", or "Realistic (clutch-assist)" mode.
To add the vehicleController you can simply add this section to your vehicle main jbeam:
"controller": [
["fileName"],
["vehicleController", {}],
],
If you do not add a controller, the game will load a dummy controller to perform some basic functions, but it will not control powertrain devices. In the future, more controllers may become available, and modders can write their own controllers for specialized vehicles.
Adding a Device Tree
In the vehicle jbeam, the device tree is defined by adding devices to a section called "powertrain". Each device has a name, a type, and a specified number of inputs and outputs. By matching names and inputIndexes, you control how the devices are connected to each other.
It's best to lead by example here:
"powertrain": [
["type", "name", "inputName", "inputIndex"]
["combustionEngine", "myEngine", "dummy", 0 ]
["torqueConverter", "myTorqueConverter", "myEngine", 1 ]
["automaticGearbox", "myGearbox", "myTorqueConverter", 1 ]
["shaft", "myDriveshaft", "myGearbox", 1 ]
["differential", "myRearDiff", "myDriveshaft", 1 ]
["shaft", "myAxleShaft1", "myRearDiff", 1, {"connectedWheel":"RL"}]
["shaft", "myAxleShaft2", "myRearDiff", 2, {"connectedWheel":"RR"}]
],
Above is the full tree of a typical rwd car defined from engine to rear wheels. By following the connections of "inputName" to "name" you can see the path from "MyAxleShaft" (with connected wheels) into "myRearDiff" outputs 1 and 2. From there, "myRearDiff" connects to "myDriveshaft" output 1. From "myDriveShaft" to "myGearbox" output 1, and so on.
By following this system, you can create any shape tree as long as it follows the rules of the device outputs, you can create all sorts of layouts of differentials and things.
It is not necessary to have all your devices in one single section. There can be a powertrain section in each relevant part of your vehicle. For example, the driveshaft in the above sample can be placed in a separate driveshaft part. When the part is removed in the part selector, the vehicle will behave just as if somebody has removed the driveshaft from a real car (the wheels and engine may rotate freely from each other).
Device Tree Golden Rules
Some rules have to be followed to create a valid device tree, they are as follows:
- Only one engine per tree. The engine forms the "top" of the tree, with "dummy" as the inputName and 0 as the inputIndex. Multiple engines require multiple trees.
- Do not connect a device input to one of its own outputs.
- Devices have a specific number of inputs and outputs and this must be obeyed in the design of the tree.
- Do not connect multiple trees to the same wheel.
- An engine device must be connected to a clutch device (friction clutch, viscous clutch, torque converter, or DCT gearbox). Similarly, a clutch device can only hook to the output of an engine device.
- An automaticGearbox must hook to the output of a torqueConverter or viscousClutch. However, a torqueConverter, or any clutch, can be used without a gearbox on the end.
- A dctGearbox must hook to the output of an engine device.
Configuring Devices
Once you have created an appropriate controller and a valid device tree, you will want to start adding properties to your devices to tailor them to your vehicle design. The quickest way to do this is to add the property inline with the device, inside {}, as follows:
"powertrain": [
["type", "name", "inputName", "inputIndex"]
["differential", "myRearDiff", "myDriveshaft", 1 {"diffType":"lsd", "gearRatio":3.55}]
],
While this method is the easiest to do, it gets cumbersome to use when there are a lot of properties to add. When there are a huge number of properties, you can create a special section in your jbeam part using the "name" of the device, as follows:
"myRearDiff": {
"diffType":"lsd",
"gearRatio":3.55,
"lsdPreload":150,
"lsdLockCoef":0.3,
"lsdRevLockCoef":0.15,
"diffTorqueSplit":0.5,
"friction":5
},
When the vehicle is loaded it will find these sections and apply them to the device with the matching name.
Configuring Controllers
While the main controlle (ex vehicleController) should be added to the main jbeam slot (ex. the part "pickup" in pickup.jbeam), additional properties can be added or changed in any part of the vehicle. Like the devices, you can create a special section sharing the name of the controller, as follows:
"vehicleController": {
"clutchLaunchCoef":2000,
"lowShiftDownRPM":1500,
"lowShiftUpRPM":2900,
"highShiftDownRPM":3000,
"highShiftUpRPM":5300,
},
The benefit of this is that you can place these sections in the other parts of your vehicle to allow yourself multiple options of gearbox modes, shift points, and so on.
You can also add more controllers for special functions. A special controller may only be relevant to a particular part. In this case the controller can be added into the specific part, so it only loads when needed.
| Vehicle Creation | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Get started: Introduction to Vehicle Creation | ||||||||||||||||
| ||||||||||||||||
| See also: JBeam Examples • JBeam Physics Theory |