Documentation/Engine/Units/accessory engine data

From SCS Modding Wiki
< Documentation‎ | Engine‎ | Units
Revision as of 04:16, 18 September 2016 by Smarty (talk | contribs) (Added relevant wiki link back to player truck definitions, and typical file path)

Jump to navigation Jump to search

The accessory_engine_data unit type is used to define the engine characteristics for the player's vehicle, as well as some upshift and downshift characteristics for automatic transmission gameplay. Units of this type are usually defined in /def/vehicle/truck/<make.model>/engine/*.sii

Attributes

Many common attributes are inherited from accessory_data.

Name Type Required/Optional Description
info string array optional Three info members are usually defined for accessory_engine_data.
info[]: "197 @@hp@@ (147@@kw@@)"     // The first is the rated power
info[]: "550 @@lb_ft@@ (782 @@nm@@)" // The second is the peak torque
info[]: "1@@dg@@200 @@rpm@@"         // The third is the peak torque speed

Note: The info attribute has no effect on the engine simulation. Rather, it is used for UI display and for attaching to World of Trucks profile truck uploads.

torque float required This defines the maximum torque output of the engine in N·m.
torque_curve float2 array optional This defines the torque output of the engine at various engine speeds, relative to the maximum torque defined in torque. For example:
torque: 745.7 // 550 lb-ft
	
// Detroit Diesel Curve E4-1061-52-20
torque_curve[]: (300,  0)
torque_curve[]: (440,  0.5)  // Fiddling with the output around 440 rpm will influence how easily the engine stalls when clutching.
torque_curve[]: (800,  0.96) // 528 lb-ft at 800 rpm
torque_curve[]: (1200, 1)    // 550 lb-ft at 1200 rpm (peak torque)
torque_curve[]: (1400, 0.99)
torque_curve[]: (1600, 0.97)
torque_curve[]: (1800, 0.45)
torque_curve[]: (2000, 0.91)
torque_curve[]: (2100, 0.89) // 489.5 lb-ft at 2100 rpm (197 hp, rated power)
torque_curve[]: (2300, 0)    // High idle (0hp) at 2300 rpm

The torque output is linearly interpolated between data points. For engine speeds outside the domain of the data points, the output is clamped to the values at the highest/lowest rpm points. The valid range for torque output is 0-1.

rpm_idle float required This is the engine speed the virtual engine controller will attempt to maintain with no throttle input.
rpm_limit float required This is the maximum engine speed the virtual engine controller will allow (except if the engine is being driven by the wheels).
rpm_limit_neutral float optional This is the maximum engine speed the virtual engine controller will allow if the transmission is in neutral. If unset, this defaults to rpm_limit.
rpm_range_low_gear float2 required Defines the downshift and upshift engine speeds in low-range gears.
rpm_range_high_gear float2 required Defines the downshift and upshift engine speeds in high-range gears.
rpm_range_engine_brake float2 optional Defines the downshift and upshift engine speeds while the engine brake is operating.
rpm_range_power_boost float2 optional Defines the change to rpm_range_low_gear and rpm_range_high_gear at full throttle when adaptive automatic transmission is enabled.
engine_brake float optional Peak engine braking torque relative to torque, at the maximum engine brake strength.
engine_brake_downshift bool optional When true, automatic transmissions will downshift upon beginning engine brake behavior as long as rpm_limit is not exceeded. Defaults to false.
engine_brake_positions uint optional Defines the number of strength levels for the engine brake. The braking torque at each position is based linearly on the number of positions. So for engine_brake_positions: 3 the first position will have 13 × engine_brake × torque, the second position will have 23 × engine_brake × torque, and the highest position will have engine_brake × torque.
volume float required The (four-stroke) volumetric displacement of the engine in liters. It is used in fuel consumption calculations.

Note: For two-stroke diesel engines, this should be roughly twice the swept volume.

consumption_coef float optional This is used to scale the fuel consumption of the engine relative to the game's calculated value.
adblue_consumption float optional This is used to scale the engine's consumption of AdBlue (Diesel Exhaust Fluid) relative to the game's default.
no_adblue_power_limit float optional When the AdBlue tank is empty, the engine's power is scaled by this factor.

Relevant Unit Conversions and Formulas

Cubic Inches to Liters

1 cu·in = 0.0164 L

Pound-Feet to Newton-Meters

1 lbf·ft = 1.3558 N·m

Horsepower to Kilowatts

1 hp = 0.7457 kW

Torque from Power and Speed (Metric Units)

T [N·m] = ( P [kW] × 9549 ) ÷ N [RPM]

Torque from Power and Speed (English Units)

T [lbf·ft] = ( P [hp] × 5252 ) ÷ N [RPM]

Raw Unit Definition

  "accessory_engine_data":{
   "superclass":"accessory_data",
   "attrs":{
    "name":{
     "type": "string"
    },
    "short_name":{
     "type": "string"
    },
    "icon":{
     "type": "string"
    },
    "info":{
     "type": "string_array"
    },
    "price":{
     "type": "s64"
    },
    "unlock":{
     "type": "uint"
    },
    "suitable_for":{
     "type": "string_array"
    },
    "conflict_with":{
     "type": "string_array"
    },
    "defaults":{
     "type": "string_array"
    },
    "require":{
     "type": "token_array"
    },
    "torque":{
     "type": "float"
    },
    "torque_curve":{
     "type": "float2_array"
    },
    "rpm_idle":{
     "type": "float"
    },
    "rpm_limit":{
     "type": "float"
    },
    "rpm_limit_neutral":{
     "type": "float"
    },
    "rpm_range_low_gear":{
     "type": "float2"
    },
    "rpm_range_high_gear":{
     "type": "float2"
    },
    "rpm_range_engine_brake":{
     "type": "float2"
    },
    "rpm_range_power_boost":{
     "type": "float2"
    },
    "engine_brake":{
     "type": "float"
    },
    "engine_brake_downshift":{
     "type": "bool"
    },
    "engine_brake_positions":{
     "type": "uint"
    },
    "volume":{
     "type": "float"
    },
    "consumption_coef":{
     "type": "float"
    },
    "adblue_consumption":{
     "type": "float"
    },
    "no_adblue_power_limit":{
     "type": "float"
    }
   }
  },