Difference between revisions of "Documentation/Engine/Units/accessory engine data"

From SCS Modding Wiki
Jump to navigation Jump to search
(New documentation for the accessory_engine_data unit. SCS guys please double-check adblue_consumption. ;))
 
m (→‎Attributes)
 
(38 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
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.
+
The '''accessory_engine_data''' unit class is used to define the engine characteristics for the [[Documentation/Engine/Game_data/Player_trucks_definitions|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/<brand.model>/engine/*.sii'''
  
 
== Attributes ==
 
== Attributes ==
Line 6: Line 6:
 
!Name
 
!Name
 
![[Documentation/Engine/Units#Attribute_types|Type]]
 
![[Documentation/Engine/Units#Attribute_types|Type]]
−
!Required/Optional
+
!Default Value
 
!Description
 
!Description
 
|-
 
|-
 
|info
 
|info
−
|string array
+
|array&lt;string&gt;
−
|optional
+
|
−
|Three '''info''' members are usually defined for '''accessory_engine_data'''.
+
|This member is attribute of accessory data, however three '''info''' members are usually defined for '''accessory_engine_data'''.
 
<syntaxhighlight lang="cpp">
 
<syntaxhighlight lang="cpp">
 
info[]: "197 @@hp@@ (147@@kw@@)"    // The first is the rated power
 
info[]: "197 @@hp@@ (147@@kw@@)"    // The first is the rated power
Line 19: Line 19:
 
</syntaxhighlight>
 
</syntaxhighlight>
 
{{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.}}
 
{{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.}}
 +
{{Tip|The strings surrounded by ''@'' are for localization &mdash; <code>@@hp@@</code> displays the localized shorthand for horsepower, <code>@@dg@@</code> displays the localized thousands separator, etc.}}
 +
|-
 +
|type
 +
|token
 +
|diesel
 +
|This defines type and behavior of engine, powertrain, and few other aspects of the vehicle. Acceptable values are '''diesel''' or '''electric'''. ''(Added in 1.50)''
 
|-
 
|-
 
|torque
 
|torque
 
|float
 
|float
−
|required
+
|0.0
 
|This defines the maximum torque output of the engine in N&middot;m.
 
|This defines the maximum torque output of the engine in N&middot;m.
 +
|-
 +
|secondary_torque
 +
|float
 +
|0.0
 +
|If positive and greater than zero, this defines the secondary maximum torque output of the engine in N&middot;m for multi-torque engines. ''(Added in 1.30)''
 +
|-
 +
|secondary_torque_gear_ratio
 +
|float
 +
|1.0
 +
|This defines the transmission gear ratio below which '''secondary_torque''' is used on multi-torque engines. ''(Added in 1.30)''
 
|-
 
|-
 
|torque_curve
 
|torque_curve
−
|float2 array
+
|array&lt;float2&gt;
−
|optional
+
|''See description''
−
|This defines the torque output of the engine at various engine speeds, relative to the maximum torque defined in '''torque'''. For example:
+
|This defines the torque output of the engine at various engine speeds, relative to the maximum torque defined in '''torque'''. If unset, the default curve is used:
 
<syntaxhighlight lang="cpp">
 
<syntaxhighlight lang="cpp">
−
torque: 745.7 // 550 lb-ft
+
  torque_curve[]: (300, 0)
−
+
  torque_curve[]: (440, 0.5)
−
// Detroit Diesel Curve E4-1061-52-20
+
  torque_curve[]: (1000, 1)
−
torque_curve[]: (300, 0)
+
  torque_curve[]: (1300, 1)
−
torque_curve[]: (440, 0.5) // Fiddling with the output around 440 rpm will influence how easily the engine stalls when clutching.
+
  torque_curve[]: (1900, 0.77)
−
torque_curve[]: (800, 0.96) // 528 lb-ft at 800 rpm
+
  torque_curve[]: (2400, 0.4)
−
torque_curve[]: (1200, 1)    // 550 lb-ft at 1200 rpm (peak torque)
+
  torque_curve[]: (2600, 0)
−
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
 
 
</syntaxhighlight>
 
</syntaxhighlight>
−
 
 
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.
 
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.
 +
|-
 +
|secondary_torque_curve
 +
|array&lt;float2&gt;
 +
|''See description''
 +
|This defines the secondary torque output of a multi-torque engine at various engine speeds, relative to the maximum torque defined in '''secondary_torque'''. If unset, '''torque_curve''' is used instead. The syntax is the same as '''torque_curve'''. ''(Added in 1.30)''
 +
|-
 +
|resistance_torque
 +
|float
 +
| -1
 +
|This is the resistive torque in N&middot;m at 2000rpm, used for passive engine braking and consumption. ''(New as of ETS 1.27/ATS 1.6)''
 +
{{Note|When unset, or when set to any negative value, resistance_torque is calculated as (''volume'' &times; 20.0).}}
 
|-
 
|-
 
|rpm_idle
 
|rpm_idle
 
|float
 
|float
−
|required
+
|550
−
|This is the engine speed the virtual engine controller will attempt to maintain with no throttle input.
+
|This is the engine speed the virtual engine controller will attempt to maintain with no throttle input. Valid range is 500-850 rpm.
 
|-
 
|-
 
|rpm_limit
 
|rpm_limit
 
|float
 
|float
−
|required
+
|2500
−
|This is the maximum engine speed the virtual engine controller will allow (except if the engine is being driven by the wheels).
+
|This is the maximum engine speed the virtual engine controller will allow except if the engine is being driven by the wheels (e.g. if the vehicle is running away downhill or the player makes an ill-advised downshift).
 
|-
 
|-
 
|rpm_limit_neutral
 
|rpm_limit_neutral
 
|float
 
|float
−
|optional
+
|2500
−
|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'''.
+
|This is the maximum engine speed the virtual engine controller will allow if the transmission is in neutral &ndash; unless '''rpm_limit''' is lower, in which case it is clamped.
 
|-
 
|-
 
|rpm_range_low_gear
 
|rpm_range_low_gear
 
|float2
 
|float2
−
|required
+
|(700, 1500)
−
|Defines the downshift and upshift engine speeds in low-range gears.
+
|Defines the downshift and upshift engine speeds in low-range gears (automatic transmission).
 
|-
 
|-
 
|rpm_range_high_gear
 
|rpm_range_high_gear
 
|float2
 
|float2
−
|required
+
|(1000, 1350)
−
|Defines the downshift and upshift engine speeds in high-range gears.
+
|Defines the downshift and upshift engine speeds in high-range gears - typically peek torque range (automatic transmission). ''(Tweaked in 1.38)''
 
|-
 
|-
−
|rpm_range_engine_brake
+
|rpm_range_power
 
|float2
 
|float2
−
|optional
+
|(1400, 1900)
−
|Defines the downshift and upshift engine speeds while the engine brake is operating.
+
|Defines the rough rpm range if more power is requested - used either in hills or for adaptive shifting, especially power mode (automatic transmission). ''(Added in 1.37, tweaked in 1.38)''
 
|-
 
|-
−
|rpm_range_power_boost
+
|''rpm_range_power_boost''
 
|float2
 
|float2
−
|optional
+
|(550, 450)
−
|Defines the ''change'' to '''rpm_range_low_gear''' and '''rpm_range_high_gear''' at full throttle when adaptive automatic transmission is enabled.
+
|''(Obsolete in 1.37)''
 +
Defines the rough rpm range ''change'' to '''rpm_range_low_gear''' and '''rpm_range_high_gear''' if more power is requested - used either in hills or for adaptive shifting, especially power mode. (Automatic transmission).
 +
{{Tip|Be careful that the resulting values when '''rpm_range_power_boost''' is added to '''rpm_range_*_gear''' don't exceed '''rpm_limit'''. Otherwise, the transmission may fail to shift correctly in adaptive automatic mode.}}
 +
|-
 +
|rpm_range_engine_brake
 +
|float2
 +
|(1500, 2500)
 +
|Defines the downshift and upshift engine speeds while the engine brake is operating. (Automatic transmission)
 
|-
 
|-
 
|engine_brake
 
|engine_brake
 
|float
 
|float
−
|optional
+
|1.0
−
|Peak engine braking torque relative to '''torque''', at the maximum engine brake strength.
+
|Engine braking torque relative to a typical exhaust brake on an engine of the same '''volume'''.
 
|-
 
|-
 
|engine_brake_downshift
 
|engine_brake_downshift
 
|bool
 
|bool
−
|optional
+
|true
−
|When true, automatic transmissions will downshift upon beginning engine brake behavior as long as '''rpm_limit''' is not exceeded. Defaults to false.
+
|When true, automatic transmissions will downshift upon beginning engine brake behavior, to keep rpm within '''rpm_range_engine_brake'''. When false, the regular rpm are kept.
 
|-
 
|-
 
|engine_brake_positions
 
|engine_brake_positions
 
|uint
 
|uint
−
|optional
+
|3
−
|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 <code>engine_brake_positions: 3</code> the first position will have <sup>1</sup>&frasl;<sub>3</sub> &times; '''engine_brake''' &times; '''torque''', the second position will have <sup>2</sup>&frasl;<sub>3</sub> &times; '''engine_brake''' &times; '''torque''', and the highest position will have '''engine_brake''' &times; '''torque'''.
+
|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 <code>engine_brake_positions: 3</code> the first position will have <sup>1</sup>&frasl;<sub>3</sub> of the full strength, the second position will have <sup>2</sup>&frasl;<sub>3</sub> of the full strength, and the highest position will have the full strength.
 +
|-
 +
|auxiliary_brakes
 +
|array&lt;float3&gt;
 +
|
 +
|When set, this overrides the engine brake control so that it controls both the engine brake and retarder (if present). The components are (engine brake strength, forced downshift, retarder strength). The value of '''engine_brake_positions''' must match the number of members in auxiliary_brakes. (''Added in 1.40'') For example:
 +
<pre> engine_brake_positions: 5
 +
auxiliary_brakes[]: (0.3, 0, 0) // 30% engine brake only
 +
auxiliary_brakes[]: (0.6, 0, 0) // 60% engine brake only
 +
auxiliary_brakes[]: (1.0, 0, 0) // 100% engine brake only
 +
auxiliary_brakes[]: (1.0, 1, 0) // 100% engine brake and downshift
 +
auxiliary_brakes[]: (1.0, 1, 1) // 100% engine brake, downshift and 100% retarder</pre>
 
|-
 
|-
 
|volume
 
|volume
 
|float
 
|float
−
|required
+
|0.0
−
|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.}}
+
|The volumetric displacement of the engine in liters. It is used in base fuel consumption calculation, engine mass & inertia calculations, and also default '''resistance_torque''' calculations. Minimum acceptable engine volume is 6.
 
|-
 
|-
 
|consumption_coef
 
|consumption_coef
 
|float
 
|float
−
|optional
+
|1.0
 
|This is used to scale the fuel consumption of the engine relative to the game's calculated value.
 
|This is used to scale the fuel consumption of the engine relative to the game's calculated value.
 
|-
 
|-
 
|adblue_consumption
 
|adblue_consumption
 
|float
 
|float
−
|optional
+
|0.05
−
|This is used to scale the engine's consumption of AdBlue (Diesel Exhaust Fluid) relative to the game's default.
+
|This is how many liters of AdBlue (Diesel Exhaust Fluid) are consumed per liter of fuel.
 +
{{Tip|For older engines which do not use AdBlue, this attribute should be set to 0.}}
 
|-
 
|-
 
|no_adblue_power_limit
 
|no_adblue_power_limit
 
|float
 
|float
−
|optional
+
|1.0
 
|When the AdBlue tank is empty, the engine's power is scaled by this factor.
 
|When the AdBlue tank is empty, the engine's power is scaled by this factor.
 +
|-
 +
|sound
 +
|string
 +
|
 +
|Path to the truck [[Documentation/Engine/Sound/TruckEngine|engine sound bank.]] (format like "/sound/truck/engine.bank")
 +
{{Note|The default engine bank has been removed (1.38+). You must explicitly specify a bank from one of the base game vehicles, or specify your own bank.}}
 +
|-
 +
|sounds
 +
|array&lt;string&gt;
 +
|
 +
|Each item assigns an FMOD event to an engine function, using the "''<nowiki>sound_name|sound_path</nowiki>''" [[Games/ETS2/Modding_guides/1.39#Accessories|format]]. ''Added in 1.39''
 +
 +
Expected sound event names are: engine, exhaust, start_bad, and turbo.
 
|}
 
|}
  
Line 129: Line 181:
 
=== Torque from Power and Speed (English Units) ===
 
=== Torque from Power and Speed (English Units) ===
 
T [lb<sub>f</sub>&middot;ft] = ( P [hp] &times; 5252 ) &divide; N [RPM]
 
T [lb<sub>f</sub>&middot;ft] = ( P [hp] &times; 5252 ) &divide; N [RPM]
−
 
−
== Raw Unit Definition ==
 
−
<pre style="max-height:300px;overflow:auto">  "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"
 
−
    }
 
−
  }
 
−
  },</pre>
 

Latest revision as of 04:50, 10 June 2024

The accessory_engine_data unit class 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/<brand.model>/engine/*.sii

Attributes

Many common attributes are inherited from accessory_data.

Name Type Default Value Description
info array<string> This member is attribute of accessory data, however 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.

TIP: The strings surrounded by @ are for localization — @@hp@@ displays the localized shorthand for horsepower, @@dg@@ displays the localized thousands separator, etc.

type token diesel This defines type and behavior of engine, powertrain, and few other aspects of the vehicle. Acceptable values are diesel or electric. (Added in 1.50)
torque float 0.0 This defines the maximum torque output of the engine in N·m.
secondary_torque float 0.0 If positive and greater than zero, this defines the secondary maximum torque output of the engine in N·m for multi-torque engines. (Added in 1.30)
secondary_torque_gear_ratio float 1.0 This defines the transmission gear ratio below which secondary_torque is used on multi-torque engines. (Added in 1.30)
torque_curve array<float2> See description This defines the torque output of the engine at various engine speeds, relative to the maximum torque defined in torque. If unset, the default curve is used: 
  torque_curve[]: (300, 0)
  torque_curve[]: (440, 0.5)
  torque_curve[]: (1000, 1)
  torque_curve[]: (1300, 1)
  torque_curve[]: (1900, 0.77)
  torque_curve[]: (2400, 0.4)
  torque_curve[]: (2600, 0)

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.

secondary_torque_curve array<float2> See description This defines the secondary torque output of a multi-torque engine at various engine speeds, relative to the maximum torque defined in secondary_torque. If unset, torque_curve is used instead. The syntax is the same as torque_curve. (Added in 1.30)
resistance_torque float -1 This is the resistive torque in N·m at 2000rpm, used for passive engine braking and consumption. (New as of ETS 1.27/ATS 1.6)

Note: When unset, or when set to any negative value, resistance_torque is calculated as (volume × 20.0).

rpm_idle float 550 This is the engine speed the virtual engine controller will attempt to maintain with no throttle input. Valid range is 500-850 rpm.
rpm_limit float 2500 This is the maximum engine speed the virtual engine controller will allow except if the engine is being driven by the wheels (e.g. if the vehicle is running away downhill or the player makes an ill-advised downshift).
rpm_limit_neutral float 2500 This is the maximum engine speed the virtual engine controller will allow if the transmission is in neutral – unless rpm_limit is lower, in which case it is clamped.
rpm_range_low_gear float2 (700, 1500) Defines the downshift and upshift engine speeds in low-range gears (automatic transmission).
rpm_range_high_gear float2 (1000, 1350) Defines the downshift and upshift engine speeds in high-range gears - typically peek torque range (automatic transmission). (Tweaked in 1.38)
rpm_range_power float2 (1400, 1900) Defines the rough rpm range if more power is requested - used either in hills or for adaptive shifting, especially power mode (automatic transmission). (Added in 1.37, tweaked in 1.38)
rpm_range_power_boost float2 (550, 450) (Obsolete in 1.37)

Defines the rough rpm range change to rpm_range_low_gear and rpm_range_high_gear if more power is requested - used either in hills or for adaptive shifting, especially power mode. (Automatic transmission).

TIP: Be careful that the resulting values when rpm_range_power_boost is added to rpm_range_*_gear don't exceed rpm_limit. Otherwise, the transmission may fail to shift correctly in adaptive automatic mode.

rpm_range_engine_brake float2 (1500, 2500) Defines the downshift and upshift engine speeds while the engine brake is operating. (Automatic transmission)
engine_brake float 1.0 Engine braking torque relative to a typical exhaust brake on an engine of the same volume.
engine_brake_downshift bool true When true, automatic transmissions will downshift upon beginning engine brake behavior, to keep rpm within rpm_range_engine_brake. When false, the regular rpm are kept.
engine_brake_positions uint 3 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 1⁄3 of the full strength, the second position will have 2⁄3 of the full strength, and the highest position will have the full strength.
auxiliary_brakes array<float3> When set, this overrides the engine brake control so that it controls both the engine brake and retarder (if present). The components are (engine brake strength, forced downshift, retarder strength). The value of engine_brake_positions must match the number of members in auxiliary_brakes. (Added in 1.40) For example: 
	engine_brake_positions: 5
	auxiliary_brakes[]: (0.3, 0, 0)	// 30% engine brake only
	auxiliary_brakes[]: (0.6, 0, 0)	// 60% engine brake only
	auxiliary_brakes[]: (1.0, 0, 0)	// 100% engine brake only
	auxiliary_brakes[]: (1.0, 1, 0)	// 100% engine brake and downshift
	auxiliary_brakes[]: (1.0, 1, 1) // 100% engine brake, downshift and 100% retarder
volume float 0.0 The volumetric displacement of the engine in liters. It is used in base fuel consumption calculation, engine mass & inertia calculations, and also default resistance_torque calculations. Minimum acceptable engine volume is 6.
consumption_coef float 1.0 This is used to scale the fuel consumption of the engine relative to the game's calculated value.
adblue_consumption float 0.05 This is how many liters of AdBlue (Diesel Exhaust Fluid) are consumed per liter of fuel.

TIP: For older engines which do not use AdBlue, this attribute should be set to 0.

no_adblue_power_limit float 1.0 When the AdBlue tank is empty, the engine's power is scaled by this factor.
sound string Path to the truck engine sound bank. (format like "/sound/truck/engine.bank")

Note: The default engine bank has been removed (1.38+). You must explicitly specify a bank from one of the base game vehicles, or specify your own bank.

sounds array<string> Each item assigns an FMOD event to an engine function, using the "sound_name|sound_path" format. Added in 1.39

Expected sound event names are: engine, exhaust, start_bad, and turbo.

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]

Retrieved from "https://modding.scssoft.com/index.php?title=Documentation/Engine/Units/accessory_engine_data&oldid=5562"