Games/ETS2/Modding guides/1.54

Introduction

The following page contains modding guidelines for the new update of the game.

To better understand changes in units it is recommended to check Units documentation page.

Recommendations

• When basing your model on the original ones, add to your mod also ALL original /automat/ files used by it. The names of the files are generated as CityHash64 hash of theirs content so whenever we change the parameters of the material in any way, a different file will be used to store them and the original file might cease to exist if there is no other model utilizing the original parameters.
• When modifying original models, always include ALL components of the model (pmg+pmd) instead of just those you changed. Otherwise you risk crash if we change the model.
• As always when adding new objects to files which support multi-file approach (e.g. road_look.sii) it is HIGHLY RECOMMENDED to use suffix or prefix in the name to avoid conflicts with new objects we are adding in patches. Otherwise you might have to use the batch renaming functionality (see Batch renaming) to fix the conflicts when new patch appears.

How to convert map

• Load map
• Do rebuild (F8)
• Save map

Changes & New Features

Cargo system

New cargo system aims to decouple trailer and it's cargo model to generic assembly. Where trailers with specific loading methods will be able to automatically load any cargo that uses it. The system is designed to independently define trailer data from cargo data.

Basically binding cargo to trailer remains the same via cargo model match. What changes is how this two are bound together. If for example you are working on a new trailer that should support existing cargoes in the game you just need to define body with proper cargo_loading_methods and rest of auxiliary data in the body. No need for cargo data extension.

Similarly if you want to add new cargo, in majority of cases you don't need to touch any trailer data. Everything should work once you define new cargo model match, except in the case of custom loading method where you need to define custom loads data per body per cargo. This loading method should be last resort in case you special cargo is not able to use any other loading method.

So in summary what you need to do, depends whether you are adding new trailer or new cargo to the game:

• For new trailer: setup trailer data via accessory_trailer_body_data_u and ensure your trailer is using body accessory and has linked trailer_def_u unit. In the case of owned trailer, it is linked inside trailer_body_set_u unit and in case of the freight market trailer it is linked inside master trailer_u defined inside /def/vehilce/trailer/<trailer>.sui
• For new cargo: define cargo_data_u as until now and newly put cargo model match and belonging cargo accessory in the folder: /def/vehicle/cargo/<cargo_name>/.

Trailer data

To support cargo loading and lashing on trailer, body accessory needs to be used, it's mandatory, since cargo system loads new attributes from it:

• cargo_loading_methods[] - array of tokens representing supported cargo [loading methods|#Loading-Methods] by this body
• cargo_regular_width - float representing at which width extension parts for the trailer are switched on
• cargo_warning_signs - bool value indicating whether body should have warning signs part switching supported or not
• cargo_areas - array of area sizes (X,Z) that are used for any of area based loading method
• cargo_areas_cylinder_data[] - array aligned with cargo areas, storing additional data for cylinder based loading (each item representing height, slope angle for given cargo area)
• cargo_custom_loads[] - array of cargo_custom_load_data_u unit pointers storing custom load offset per cargo
• cargo_lashing_mounts[] - array of cargo_lashing_mount_u unit pointers storing lashing mount definitions
• cargo_lashing_strap - unit pointer to cargo_lashing_gear_u storing configuration of lashing gear used when strap gear method is selected by the cargo model match
• cargo_lashing_chain - unit pointer to cargo_lashing_gear_u storing configuration of lashing gear used when chain gear methods is selected by the cargo model match.

If body has set cargo_warning_signs: true then game will try to switch particular parts on body, chassis and selected accessories models depending on the loaded cargo model bounding box as follows:

• wrn_sgn_off part will be switched on if loaded cargo width is under 2.5m
• wrn_sgn_29 part will be switched on if loaded cargo width is above 2.5m and under 2.9m
• wrn_sgn_32 part will be switched on if loaded cargo width is above 2.9m and under 3.2m
• wrn_sgn_max part will be switched on if loaded cargo width is above 3.2m

Additionally if loaded cargo is wider than set cargo_regular_width in the body data, then extension parts on the trailer body or chassis (if trailer body model is not present) will be switched on. Extension parts are collected differently depending on the loading method:

• For area based loading methods game searches for the parts larea_on_X and larea_off_X where X is the index of the area from cargo_areas[] attribute.
• For rest of the loading methods game will be searching for the parts cargo_on and cargo_off.

In both cases game will make sure to disable any part not belonging to the currently used loading method. When area loading is used both cargo_on and cargo_off will be disabled and vice versa, when non-area based loading method is used any larea_on_X and larea_off_X will be disabled.

Cargo Custom Load Data

New unit cargo_custom_load_data_u was introduced to store custom load placement for the cargo model match:

• cargo_token - cargo suffix token for which this custom load data are used
• offset - position offset from cargo locator
• rotation - rotation offset from cargo locator in degrees

Cargo Lashing Mount

New unit cargo_lashing_mount_u was introduced used on vehicle body to lash cargo on and define the open/closed ring models:

• spacing - float defining space between individual lashing mount points on the lashing mount
• hook_angle_constraints - float3 defining angle constraints on each axis for the hook used with this mount, ranging from 0 to 90° (zero meaning no rotation allowed, 90° meaning 90 degrees into either negative or positive direction)
• open_model - string as path to the model placed on lashing mount when lashing is done to it
• closed_model - string as path to the model placed on lashing mount when when spaced position is not used (this model will be placed only in case spacing is grater than 0)

For lashing mount to be correctly loaded, the body or chassis (if body model is not defined) has to have proper model locators pair: lashm_s_X and lashm_e_X where X is the index of the lashing mount inside the cargo_lashing_mounts array of the trailer body data. First locator is representing the start and second is representing the end of the lashing mount. Note that lashing mounts should be placed on forward vehicle axis from front to the rear of the vehicle.

Cargo Lashing Gear

New unit cargo_lashing_gear_u was introduced to store lashing gear data:

• material - string referencing material to represent generated geometry lash look
• size - float2 defining width and height of generated lashing geometry intersection
• texcoord_uratio - float defining U ratio of texture used within material of generated geometry: uratio = texture_width / texture_height
• start_hook - string as path to the model to be added on the start of the generated lashing path
• start_hook_length - float as length from model origin to the hook end it it's forward direction for which lashing will be offset
• end_hook - string as path to the model to be added on the end of the generated lashing path
• end_hook_length - float as length from model origin to the hook end it it's forward direction for which lashing will be offset
• binder - string as path to the binder model that is inserted on first part of lashing, model has to be placed along forward direction to be properly aligned with generated lashing
• binder_length - float as length from model origin to the end of the binder bottom in it's inverse forward direction

Cargo model match data

Cargo model match units were moved into vehicle definition space, since they are only to be used in conjunction with the vehicle and cargo loading logic. Additionally existing cargo model match unit was refactored and now supports following attributes:

• data_path[] - array of strings defining different models of same cargo model match (aka has same dimensions but different look)
• dimensions - float3 representing dimensions of the cargo model match in each axis (X,Y,Z). Y component is currently ignored however might be used in the future.
• unit_volume_factor - float as factor of the cargo unit volume defined in cargo data. This is usually used to distinguish different cargo model matches of the same cargo, that have completely different visual and thus different ratio to the cargo unit volume. Unless you are not defining new cargo model matches for existing cargo nor you have multiple cargo model matches you should not define it
• loading_method - token of the loading method cargo model match will be using, see #Cargo loading methods
• lashing_method - token of the lashing method cargo model match will be using, see #Cargo lashing methods
• lashing_gear_type - token of the lashing device cargo model match will be using, see #Cargo lashing gear types
• lashing_hook_angle_constraints - float3 defining angle constraint on each axis of the hook in range between 0 and 90° (this will work similarly as angle constriants on body lashing mounts except that his is applied only when direct lashing is used for the cargo model match)

Common structures

Common structures are either used directly or indirectly on both sides.

Cargo loading methods

As written above, cargo loading method will tell cargo and trailer how specific cargo model match will be loaded onto the trailer. The loading is done by the game differently for each loading method:

• area - cargo placed on area, game automatically calculates number of cargo model matches that can fit onto the trailer
• area_cont_20ft - variation of area for 20ft containers
• area_cont_40ft - variation of area for 40ft containers
• area_cont_45ft - variation of area for 45ft containers
• area_cont_53ft - variation of area for 53ft containers
• area_cylinder - cylindrical cargo placed into prism volume defined by bottom and top area
• area_logger - variation of area for loggers with side support
• auxiliary_only - no real cargo it has only auxiliary models placed on custom nodes (e.g. ADR, reefer lights)
• bulk - bulk cargo loaded with mesh generation
• custom - cargo placed on custom placement according to cargo locator and cargo_custom_load_data_u' defined inside body

All area based loading methods will be looking for the larea_s_X and larea_e_X model locators inside body or chassis (if body model is not present), where X is the index of loading area inside the trailer body data cargo_areas[] attribute. This locators define corners for each loading area plane.

Cargo lashing methods

Lashing method defines how cargo will be lashed to the trailer:

• direct - cargo is lashed directly from rigid point on cargo to the trailer lashing mounts utilizing
• top_over - cargo is lashed with top over technique, trying to find perpendicular lashing against the loading area
• none - cargo is not lashed, this can be used in combination with cargoes that are embedded on the trailer or lashed on itself

Each method (except none) requires different locators within the cargo model.

For direct lashing cargo model needs locators with naming: lash_d_X where X is incremental index from 0 to 99. As soon model locator for given index is not found rest will be ignored. Lashing will be done in the direction of model locator forward axis, game will pick closest possible lashing mount placement from the vehicle.

For top_over lashing cargo model requires lashing rail locators with naming: lash_s_Z_X and lash_e_Z_X where Z donates index of multiple rails along model forward axis and X donates index of multiple rails along model X axis. Multiple rails are usually used when there is some obstruction in the model and you need manual dividing into multiple railing (e.g. some separation elements). In all other cases one should use single Z rail indexing since the game will place multiple lashings on the distance of 1.25m from each other. X indexing should be done from left to the right (from -X to +X in model space)

Cargo lashing gear types

There are currently two different lashing gear types:

• chain - game creates diamond intersections segments to simulate chain mesh with a combination of alpha test material
• strap - game creates square intersection segments to simulate strap mesh
• none - game doesn't use any lashing, should be used in conjunction with none lashing method

Traffic trailer data

As for the traffic vehicles, they got reworked too. Similarly as player vehicles, they now need linked trailer_def_u and list of the cargoes they support via new attribute cargoes[] which is an array of cargo name tokens. So if you want to create new traffic trailer one would need to:

1. link permanent trailer definition from /def/vehicle/trailer_defs/
2. add body accessory to it
3. supply array of supported cargoes.

Example of traffic trailer definition:

traffic_trailer : traffic.trailer.scs_brick_r
{
	trailer_definition: trailer_def.scs.flatbed.single_3.brick
	
	accessories[]: .scs_brick_r.chassis
	accessories[]: .scs_brick_r.rwheel
	accessories[]: .scs_brick_r.rwheel2
	accessories[]: .scs_brick_r.rwheel3
	accessories[]: .scs_brick_r.body
	accessories[]: .scs_brick_r.paint_job

	cargo_mass: 20000

	tags[]: low
	tags[]: flatbed
	tags[]: brick
	tags[]: medium
	tags[]: cargo
	tags[]: construct

	cargoes[]: fertilizer
	cargoes[]: bricks
	cargoes[]: outdr_flr_tl
	cargoes[]: plant_substr
}

vehicle_accessory: .scs_brick_r.chassis
{
	data_path: "/def/vehicle/trailer/scs_brick/red.sii"
}

vehicle_wheel_accessory: .scs_brick_r.rwheel
{
	offset: 0
	data_path: "/def/vehicle/t_wheel/single_385_55_steel.sii"
}

vehicle_wheel_accessory: .scs_brick_r.rwheel2
{
	offset: 2
	data_path: "/def/vehicle/t_wheel/single_385_55_steel.sii"
}

vehicle_wheel_accessory: .scs_brick_r.rwheel3
{
	offset: 4
	data_path: "/def/vehicle/t_wheel/single_385_55_steel.sii"
}
vehicle_accessory: .scs_brick_r.body
{
	data_path: "/def/vehicle/trailer/scs_brick/accessory/body.sii"
}
vehicle_paint_job_accessory: .scs_brick_r.paint_job
{
	data_path: "/def/vehicle/trailer/scs_brick/custom_paint_job/red.sii"
}