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.

The Torquecurve App

Engine Dynamometer App

To check out the torque of the engine in real time you can use the UI app called "Engine Dynamometer".

The Engine Dynamometer App