CombustionEngine
The Combustion Engine (device name "combustionEngine") is our engine model which represents all types of internal combustion engines. It is a device with its own inertia, speed, friction, and torque. It transfers torque to the powertrain through a clutch-like device. When the clutch is open, the engine is operating independently, managing its rpm by balancing its torque against inertia and friction.
The basis for the engine is a table of "gross torque" vs. engine rpm. From this table, a base torque curve is created. When the engine is running, friction and inertia reduce the output torque depending on the state of the engine, while superchargers, turbochargers and nitrousOxideInjection can increase the output torque, leading to a real time "net torque". From some efficiency parameters, the fuel efficiency and thermal efficiency can be determined, which result in consumption of fuel from a energyStorage device and heat generated in the Engine_Thermal_Simulation.
As of 0.11 the combustionEngine has support for stalling, reverse rotation, Nitrous Oxide, and it contains an internal starter motor to recover from stalling.
Jbeam Properties
Name | Type | Optional | Default Value | Description | ||
---|---|---|---|---|---|---|
torque | table | false | na | This table defines the base torque curve of the engine, of the form ["rpm","torque"]. Absolutely essential! Make sure the table has entries from 0 rpm to (rpm >= maxRPM). This table is the same as the old "enginetorque" table from pre 0.7.2 | ||
torqueReactionNodes | array | false | na | Choose 3 orthogonal nodes on the engine for torque reactions, and for the game to know where the engine is located in space for sound and other misc uses. Ex: "torqueReactionNodes:":["e1l","e2l","e4r"] | ||
idleRPM | number | false | na | The natural idle rpm of the engine. When rpm drops below this value, the engine will apply some throttle to maintain itself. | ||
maxRPM | number | false | na | The maximum rpm of the engine. Beyond this rpm, throttle will be cut using the rev limiter if one is present. Keep in mind, if the engine does not have enough torque in this rpm range, it may never reach maxRPM on its own. | ||
idleRPMRoughness | number | 50 | The idle roughness of an engine, sets how much engine will randomly deviate from set idle RPM. | |||
maxIdleThrottle | number | 0.15 | Maximum throttle engine will use to maintain idle RPM. | |||
hasRevLimiter | bool | true | Determines whether the engine has a rev limiter to prevent overreving. | |||
revLimiterRPM | number | maxRPM | Determines the RPM at which the rev limiter activates, allowing it to be set separately from the engine maxRPM. | |||
revLimiterType | string | rpmDrop | Determines what type of rev limiter is used if one is present. Possible Values: "rpmDrop", "timeBased", "soft" | |||
revLimiterRPMDrop | number | maxRPM * 0.03 | If a rpmDrop type limiter is used, the rev limiter waits until the engine RPM has dropped by revLimiterRPMDrop before reapplying throttle. | |||
revLimiterCutTime | number | 0.15 | If a timeBased type limiter is used, the rev limiter waits until the specified time has elapsed before reapplying throttle. | |||
revLimiterMaxRPMDrop | number | 500 | If a timeBased limiter results in the engine dropping more the the specified RPMs, it will be overridden and the throttle reapplied. | |||
revLimiterSmoothOvershootRPM | number | 50 | If a soft type limiter is used, the rev limiter will allow the engine to overrev by the specified RPMs before dynamically limiting it. | |||
redlineTorqueDropOffRange | number | 500 | The amount an engine is allowed to overrev before it's torque is reduced for a natural redline. | |||
inertia | number | false | 0.1 | The inertia of the engine in kg*m^2. Includes the rotating components inside the engine, the flywheel, and clutch or torque converter. The lower the value, the faster the engine can rev. | ||
friction | number | false | na | The base friction torque on the engine in Nm. 1*friction is applied when throttle is max, but as throttle drops to 0, friction increases to 2*friction. | ||
dynamicFriction | number | false | na | The dynamic friction torque on the engine in Nm/s. This is a friction torque which increases proportional to engine AV (rad/s). dynamicFriction = brakingcoefRPS/2pi from pre 0.7.2. | ||
burnEfficiency | number | false | na | The energy efficiency of the engine. How many KJ of gross work is created from a KJ of fuel energy. Can also be a table of the form ["throttle","burnEfficiency"]. | ||
particulates | number | 0 | How much exhaust smoke is generated when the engine is under full load. | |||
idleParticulates | number | 0 | How muxh exhaust smoke is generated when the engine is under no load. | |||
instantAfterFireCoef | number | 0 | Chance of afterfire occurring when engine load suddenly drops at high RPM. | |||
sustainedAfterFireCoef | number | 0 | Chance of afterfire continuing to occur after engine load drops. | |||
sustainedAfterFireTime | number | 1.5 | How long afterfire may continue after engine load drops. | |||
maxOverRevDamage | number | 1500 | Arbitrary number which determines how long an engine may be overreved before damage occurs. | |||
maxTorqueRating | number | -1 | The maximum torque (in Nm) an engine can sustain before risking over torque damage. Set -1 to disable. | |||
maxOverTorqueDamage | number | 1000 | Arbitrary number which determines how long and how much an engine may be over-torqued before catastrophic failure occurs. | |||
energyStorage | string | na | Tells the engine to look for any fuel tanks with a name that matches the value, in order to draw fuel from them. If not defined, the engine has infinite fuel and will not reduce any fuel tanks on the vehicle. | |||
requiredEnergyType | string | gasoline | Ensures that the engine only uses a specific type of fuel. Possible values: "gasoline" or "diesel" or "kerosene". Custom fuel types may also be created, if defined in energyStorage. If the type of fuel in the fuel tank does not match, the engine will not run. | |||
thermalsEnabled | bool | false | Enables engine thermals. See Engine_Thermal_Simulation for thermals-specific engine properties. | |||
isAirCooledOnly | --- | false | true/false | If set to true, the engine will not use coolant, and instead depend on oil and air cooling. See Engine_Thermal_Simulation for thermals-specific engine properties. | ||
breakTriggerBeam | string | na | breakTriggerBeam tells the engine to look for any beams with a name that matches the value. When said beam breaks, the engine will be disabled. "breakTriggerBeam":"engineBeam" will disable the engine when a beam named "engineBeam" breaks. | |||
starterTorque | number | =friction*4 | Max torque of the starter motor (occurs at 0 rpm). The default is designed to work for most engines. | |||
starterMaxRPM | number | =idleRPM | Max rpm of the starter motor (where torque drops to 0). Default is designed to work for most engines. |
Examples
Here is an example of the required powertrain section, along with the additional section for the many properties.
"powertrain": [ ["type", "name", "inputName", "inputIndex"], ["combustionEngine", "mainEngine", "dummy", 0], ], "mainEngine": { "torque":[ ["rpm", "torque"] [0, 0], [500, 85], [1000, 102], [1500,109.5], [2000, 122], [3000, 145], [4000, 159], [5000,159.5], [6000, 152], [7000, 121], [7500, 74], [8000, 44], [9000, 34], ], "idleRPM":800, "maxRPM":6700, "inertia":0.08, "friction":12, "dynamicFriction":0.022, "burnEfficiency":[ [0, 0.12], [0.05, 0.26], [0.4, 0.42], [0.7, 0.47], [1, 0.35], ], "torqueReactionNodes:":["e1l","e2l","e4r"] "energyStorage": "mainTank", "requiredEnergyType":"gasoline", //node beam interface "waterDamage": {"[engineGroup]:":["engine_intake"]}, "radiator": {"[engineGroup]:":["radiator"]}, "engineBlock": {"[engineGroup]:":["engine_block"]}, "breakTriggerBeam":"engine", "uiName":"Engine", },
Tuning and Debugging
Torquecurve App
To check out the final torque of the engine (including effect of superchargers and turbos) You can use the UI app called "Torque Curve", which displays a very close result to the dynamic engine torque.
Engine Dynamometer App
To check out the torque of the engine in real time you can use the UI app called "Engine Dynamometer".