Modding guides for 1.9.0


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.

Some new models utilizing the "sc" suffix or prefix are still work in progress and it is likely that they might change significantly in some next patch. For this reason it is recommended that you avoid using them in your mods at this time.

How to convert map

  • If you have any objects which use prefix not matching the type (e.g. it is not "sign." for signs), fix them. The game assumes that the prefix is fixed (see Unit name checks).
  • If you modified the signs, set the distance_type attribute and drop the obsolete ones (see Changes in signs)
  • If you modified the road looks, update the ai_speed_type and lane_count_* attributes and drop the obsolete ones (see Changes in road looks)
  • If you modified the road materials, convert them to the new format (see Changes in road materials)
  • If you modified the terrain materials, convert them to the new format (see Changes in terrain materials)
  • If you added any custom fonts, you need to update the format (see Changes in fonts)
  • Load the map in the editor. If the load fails, examine the log and fix the errors. The -unlimitedlog command line parameter might be useful during that if you have many old prefabs.
  • Use the find tool in editor to locate road items reported as "Bad road item (X)". Most likely you are connecting a UK roads with non-UK ones here.
  • Use the find tool in editor to locate prefabs which were reported in the log as " Incorrect origin node detected, but not corrected!" when the editor converts the map to the new format and recreate them if necessary.
  • Ensure that the log does not contain ANY errors related to missing signs. (see Unit name checks)
  • If you added new road material or terrain material for use in a new sectors, you might want to rename them to add prefix or suffix to the name to avoid conflicts with the materials we added (see Batch renaming).
  • Use the replacement dialog (F3, "Prefab node correction") to add to map nodes which we added to the prefabs (see Changes in prefabs).
  • Save and reload the map or do rebuild (F8)


Changes in paintjobs

The trucks now have a additional third uv coordinates with improved layout and some paintjobs were updated to take advantage of that. The paintjobs can opt in to using this uv coordinate using a new alternate_uvset parameter in the paintjob definition. Please note that it is error when paintjob requires coordinate which the model does not have and the resulting behavior is undefined. This might happen if you modded a standard truck and the player I using one from the paintjobs which we updated. In that case you might want to include a older version of the paintjob definitions and textures in your mod.

Changes in fonts

The font files now contain information about the sizes of underlying textures. You need to update all image definition lines to include the size.

For example


If the texture associated with /font/big_0.mat would have dimensions of 256x512 the new line should be.

image:/font/big_0.mat, 256, 512

Unit name checks

Many from the world definition files (e.g. /world/sign.sii) expect that the full unit names are starting with fixed prefix component (e.g. "sign.") which is followed by a single component with the name (There are few exceptions. When in doubt, see the naming used in the original file which is part of the game). Depending on the situation, the game might sometimes locate the units only using the name component or it might construct the full name from the fixed prefix and the name and locate the unit using this full name. To ensure that the game will find the unit using both methods, the units must use the expected naming convention.

For example the names of sign units are expected to start with "sign." so "fkmm070" or "add.navsg001" are not valid names and will be not found during map conversion.

The game will now check names in selected unit definition files and print error if name does not conform to the expected convention.

Changes in ferries

The ferry definition format was enhanced to support addition of new connections to existing ferries without need to override the base .sii file.

In addition to the standard definition in the /def/ferry/<name>.sii files, the game will also load all files from /def/ferry/connection. Each from those files should contain a single ferry_connection unit (see example bellow) which defines connection between two ferries and must be named conn.<from>.<to> where from and to are names of respective ferries. The game will add specified connection to the base ferry definition or it will override its parameters if the connection already exists. Currently there is no way to remove existing connection using this mechanism.

If more than one file defines the same connection, it is undefined which one from them wins. For this reason the files should be named as <from>_<to>.sii (e.g. europoort_harwich.sii) even if the game currently does not enforce this.

Example of defining connection from eurpoort to harwich using a connection unit stored in /def/ferry/connection/europoort_harwich.sii

ferry_connection: conn.europoort.harwich
   price: 960
   time: 480
   distance: 207

Changes in city definitions

Added traffic related attributes:

  • traffic_density_coef
    • modifies the traffic spawn density around player (default value is 2.0)
    • if more cities are close enough, their density coefs are added
  • traffic_density_range
    • default value is 2000.0
    • sets the maximum range beyond city border at which the traffic_density_coef is still applied
    • the value of traffic_density_coef applied is decreasing with distance: maximum value is at the border and 0.0 at the traffic_density_range

Changes in road looks

The roads now support specifying different number of lanes in left and right part. They are defined using new lane_count_left and lane_count_right attributes. The ai_lane_count and one_way attributes are now obsolete. To keep backward compatibility with existing definitions, the game will override the value of the new attributes if ai_lane_count or one_way attributes are set in the definition. Please note that this fallback might be disabled in some future patch so it is highly recommended to update the looks to use the new mechanism. The feature only controls the AI behavior on the road and has no effect on the visualization of the roads. Support for more custom definition of road visualization including more lanes is planed for some future patch.

The ai_road_offset and actor_lane_count attributes are obsolete and ignored.

The ai_speed_type attribute is now enum with following values: none (-1), city (0), regular (1), highway (2). Direct numeric values still work at this time and are compatible with the previous state however using the name is preferred.

Changes in road materials

To allow independent addition of road and sidewalk materials we extracted them to separate files ( road_material.sii and road_sidewalk.sii) which support the .<idofyourmod>.sii convention and suffixed/prefixed unit names. The values of the corresponding arrays inside road.sii are ignored.

When converting the map from old format, the material indices are converted to units which are suffixed by the same value (i.e. index 5 is mapped to unit road_mat.5). If you added materials which conflicts with the materials we added in this patch, you might want to use the renaming functionality to move your new material to new suffixed representation.

Changes in terrain materials

As with road materials, the terrain_material.sii was changed to allow independent addition The .<idofyourmod>.sii convention and suffixed/preffixed unit names are supported.

When converting the map from old format, the material indices are converted to units which are suffixed by the same value (i.e. index 5 is mapped to unit terrain_mat.5). If you added materials which conflicts with the materials we added in this patch, you might want to use the renaming functionality to move your new material to new suffixed representation.

Changes in semaphores

The game now supports semaphore profiles referenced from prefabs.

The characteristics of the semaphores are defined in semaphore_profile.sii. When locating the profile to use, the game locates unit named tr_sem_prof.<profile_name>.<country_code> and if that fails, it attempts to find tr_sem_prof.<profile_name>

Semaphore visualization models are defined in semaphore_model.sii. When locating the model to use, the game locates unit named tr_sem_mdl.<profile_name>.<country_code> and if that fails, it attempts to find tr_sem_mdl.<profile_name>

Semaphore Profiles

Most profile attributes are arrays. When applying a profile, semaphore IDs are used as indexes. Prefab semaphores must have their 'type' set to '(use profile)'.

If there is no value for some ID, the last value from the corresponding array attribute is used

  • model - array of tokens (suffixes of semaphore model names from semaphore_model.sii without country suffixes)
  • type - array of enum values:
    • barrier_distance - a barrier activated by proximity of an object (road crossings)
    • barrier_manual - a barrier, which is closed until a condition is met (tollgates, gas stations)
    • model_only - if set, the current instance will be only a visual representation of a real traffic semaphore
    • traffic_light - standard traffic light
    • traffic_light_blockable - traffic light which is blocked by passing vehicles (controlling of one-way road segments, e.g. roadworks)
    • traffic_light_major - standard traffic light with a 'major road' sign
    • traffic_light_minor - standard traffic light with a 'minor road' sign
  • interval - array of float4 values (Green, Orange, Red, Orange)
  • cycle - array of float values (semaphore cycle shift)
  • id_map - array of indexes
    • in some cases (e.g. model_only types used for road crossings), multiple semaphores need to be linked to some other semaphore to ensure their synchronization
  • inherited - full name of the fallback profile (attributes not set in the current profile are taken from the inherited one)

Changes in building models

New attributes min_scale and max_scale of the building_model unit can be used to randomize scale of the model. The model_size_override attribute is now obsolete and should be not used for new definitions.

New attribute rand_rot specifies maximal range in degrees by which can be the model randomly rotated along the vertical axis. The model will be rotated by random value in in <-rand_rot/2;rand_rot/2> from its default orientation (i.e. specifying 360 degress will give fully random rotation). To avoid visual errors on existing maps, do not set the attribute to non-zero value for models which are already used in the map.

Changes in AI

The AI is now utilizing additional information defined in signs (see bellow) to control its behavior (e.g. speeds) so use of proper signs is important.

The sign_models defined in /dev/world/sign.sii now have a new optional attribute traffic_rule which references a rule defined in traffic_rules.sii specifying additional traffic-related semantics for that sign (e.g. speed limit).

Additional configuration file (/def/traffic_data.sii) was added which controls behavior of the AI. There are many attributes, which control the behavior of AI vehicles. However, since some of them can change or be removed in the near future, only attributes already in the configuration file are officially supported. More attributes will appear there in the near future.

Currently supported traffic attributes:

  • max_vehicle_count - maximum count of all active vehicles. Increasing it can lower the performance
  • max_truck_count - maximum count of all active trucks. Increasing it can lower the performance
  • ai_safety_modifier - modifies the general safety of AI behavior. Interval of possible values: <-1.0; 1.0>, where -1.0 means 'minimum safety', 1.0 means 'maximum safety' and 0.0 means 'no change'

The maximal speed of AI vehicles is now specified in new attribute max_speed of traffic_vehicle unit which is specified in km/h. The attribute speed is now obsolete and ignored.

The type of vehicle is now specified as enum-based attribute type which might have one from following values: car, truck, bus. The speed_class and use_truck_path attributes is now obsolete and ignored.

The vehicle shifting behavior is now described using a gearbox attribute. It allows defining different accelerations for different vehicle speeds: (speed [km/h], acceleration [m/s/s]) .

Default values:

# car default gearbox
gearbox[]: (0, 4.5)
gearbox[]: (20, 3.5)
gearbox[]: (45, 2.5)
gearbox[]: (70, 1.8)
gearbox[]: (100, 1.2)

# truck default gearbox
gearbox[]: (0, 1.26)
gearbox[]: (10, 1.06)
gearbox[]: (20, 0.89)
gearbox[]: (32, 0.74)
gearbox[]: (45, 0.61)
gearbox[]: (57, 0.49)
gearbox[]: (70, 0.40)
gearbox[]: (80, 0.33)

# bus default gearbox
gearbox[]: (0, 2.5)
gearbox[]: (15, 1.8)
gearbox[]: (25, 1.5)
gearbox[]: (50, 1.2)
gearbox[]: (70, 0.9)

Changes in prefabs

The new AI uses a modified format of the prefab with additional precomputed information. The game will automatically try to convert a previous format to the new one during load.

Basic Structures - Memory Layout

WARNING: any information in this section can change without notice!

Navigation Curves

struct ppd_curve_t
    token_t name;
    u32 flags;
    u32 leads_to_nodes;
    float3_t pos0;
    float3_t pos1;
    float3_t dir0;
    float roll0;
    float3_t dir1;
    float roll1;
    float length;
    u32 next_curves[4];
    u32 prev_curves[4];
    u32 next_count;
    u32 previous_count;
    u32 tr_light_id;
    float speed_limit; // obsolete, not used

curve flags:

const unsigned PNCF_STOPPER = 0x00000001;
const unsigned PNCF_FORCE_NO_BLINKER = 0x00000004;
const unsigned PNCF_RIGHT_BLINKER = 0x00000008;
const unsigned PNCF_LEFT_BLINKER = 0x00000010;
const unsigned PNCF_SMALL_VEHICLES = 0x00000020;
const unsigned PNCF_LARGE_VEHICLES = 0x00000040;
const unsigned PNCF_PRIORITY_MASK = 0x000F0000;
const unsigned PNCF_PRIORITY_SHIFT = 16;
const unsigned PNCF_LOW_PROBABILITY = 0x00002000;
const unsigned PNCF_ADDITIVE_PRIORITY = 0x00008000;

(other flags known from the previous version are obsolete)


const unsigned PNLF_END_NODE_MASK = 0x000000FF;
const unsigned PNLF_END_NODE_SHIFT = 0;
const unsigned PNLF_END_LANE_MASK = 0x0000FF00;
const unsigned PNLF_END_LANE_SHIFT = 8;
const unsigned PNLF_START_NODE_MASK = 0x00FF0000;
const unsigned PNLF_START_NODE_SHIFT = 16;
const unsigned PNLF_START_LANE_MASK = 0xFF000000;
const unsigned PNLF_START_LANE_SHIFT = 24;

Traffic Semaphores

NOTE: using semaphore profiles instead of setting per-instance attributes is strongly advised

struct ppd_tr_light_t
    float3_t pos;
    quat_t qrot;
    u32 type;
    u32 id;
    float4_t intervals;
    float cycle;
    token_t profile;
    u32 flags;

semaphore types:

const unsigned TST_PROFILE = 0; // using values from semaphore_profile.sii instead of prefab
const unsigned TST_MODEL_ONLY = 1;
const unsigned TST_TRAFFIC_LIGHT = 2;
const unsigned TST_TRAFFIC_LIGHT_MINOR = 3;
const unsigned TST_TRAFFIC_LIGHT_MAJOR = 4;
const unsigned TST_BARRIER_MANUAL_TIMED = 5;
const unsigned TST_BARRIER_DISTANCE = 6;



    • start intersection - the point where two or more curves are leading from one locator
      • automatically generated - no priority management
    • cross intersection - the point where two or more curves intersect
      • non-zero priority modifiers have to be set for each intersecting curve
    • end intersection - the point where two or more curves are leading to one locator
      • non-zero priority modifiers have to be set for each intersecting curve
      • a special case is lane merging:
        • all curves have the same priority
        • vehicles will use 'zip merging' in this case
struct ppd_intersection_t
    u32 curve_id;
    float position;
    float radius;
    u32 flags;

intersection flags:

const unsigned PIF_SIBLING_COUNT_MASK = 0x000000F0;
const unsigned PIF_SIBLING_COUNT_SHIFT = 4;
const unsigned PIF_TYPE_START = 0x00010000;
const unsigned PIF_TYPE_END = 0x00020000;

Important Notes:
  • intersection structures must be generated for EVERY curve involved in an intersection
  • structures have to be stored in such way that the first structure contains the number of siblings (curves involved)
    • all remaining siblings must immediately follow the first one and MUST HAVE THE NUMER OF SIBLINGS SET TO ZERO
  • AI vehicles now use prefab curves also for player movement prediction, which means
    • make sure valid curves lead from/to all directions where player can drive (even if AI vehicles won't ever go there)
    • use correct blinker flags - the vehicles 'see' which blinker has the player turned on and predict its path accordingly
    • make sure there are prefab nodes in all directions where player can drive (e.g. dock entrances...)
      • After modifying the prefab you can use "Prefab node correction" command in the replacement dialog (F3) to let the game to add the missing nodes.

Changes in editor

Batch renaming

The editor now supports a batch renaming of some types of objects based on config file. First you need to prepare configuration file describing the changes which should be applied (see bellow). Afterwards you need to load the map in the editor, press F3 to open the replacement dialog, press the Batch replace button and confirm the change. Afterwards you should save and reload the map.

The operation requires that units for both the old and the new names exist during the operation so you will need to do the operation in separate steps by first adding units under the new names to the definitions, then doing the rename and afterwards removing the units with the old names from the definitions.

The configuration file must be stored as Documents\Euro Truck Simulator 2\replace.sii. The file must contain a single unit of type editor_search_replace. The unit contains string array attribute sectors which must contain names of all sectors in which to apply the changes. The sector name corresponds to base name of the files used to store that sector (e.g. sec+0001-0001). The unit also contains additional string array attributes which define the replacements. The format of the replacement string is "old_name|new_name". Following arrays are supported:

  • ter_material - terrain materials
  • road_material - road materials
  • sidewalk_material - sidewalk materials
  • bld_scheme - building schemes
  • model - models
  • vegetation - vegetations
  • road_look - road looks
  • ter_profile - terrain profiles
  • railing - railings on roads
  • sign - lamps/bollars along the road

Example of replacement file

editor_search_replace : .edit_replace 
   # List of sectors where the search replace should be performed

   sectors[]: "sec-0002-0007"
   sectors[]: "sec-0002-0008"

   # Terrain material replacement  old terrain material unit suffix | new terrain material unit suffix

   ter_material[]: "24|121"
   ter_material[]: "103|129"

   # Building scheme replacement  old scheme unit suffix | new scheme unit suffix

   bld_scheme[]: "22|2sc"

   # Model replacement  old model unit suffix | new model unit suffix

   model[]: "122|1sc"
   model[]: "757|2sc"
   model[]: "56a|3sc"


New attribute category of model_def, sign_model, prefab_model and building_scheme units specifies a string with category to which the unit belongs. This can be used in respective editor dialogs to filter the set of the items to only items belonging to selected category.

Changes in Signs

The signs now appear as a standalone items in the editor. If you have modified editor_data.sii, you need to update the sub_mode_types array to make the corresponding entry visible in the ui.

A new distance_type attribute was added to the sign definition (0 - short, 1 - close, 2 - middle, 3 - far). The short_distance attribute is now obsolete and ignored.

A new Follow road dir checkbox was added to the Sign properties. It aligns the sign orientation according to the near road and to keep relative position when the road moves.