Difference between revisions of "Games/ATS/Modding guides/1.6"

From SCS Modding Wiki
Jump to navigation Jump to search
(Changes)
 
(4 intermediate revisions by 2 users not shown)
Line 17: Line 17:
 
= Changes =
 
= Changes =
  
Note that this page contains only changes which are specific to ATS, for other changes see ETS2 1.27 modding guide [http://modding.scssoft.com/wiki/Games/ETS2/Modding_guides/1.27 link]
+
== Vehicles data ==
 +
 
 +
=== Truck cameras ===
 +
 
 +
Please ensure that all cameras are set in the accessory_truck_data. A missing camera data can cause crash of ATS 1.6.0.6 open beta.
 +
 
 +
=== Truck accessory data ===
 +
 
 +
There is new rule '''overrides[]''' added. Its values are file names and it is non-lazy version of '''defaults[]'''. This means whenever this rule is used adding accessory also adds all override accessories regardless of presence of same type accessory (old ones are discarded). Typical use case is engine that takes engine badge or sound with itself. Forcing the change simplifies other rules as now engine badges or sounds do not need suitable rule on their sides which removes unwanted cross links between accessories. Use carefully as any forced change can loop easily with incorrect data.
 +
 
 +
=== Engine data ===
 +
 
 +
Part of engine simulation improvement is specifying inner engine resistance. It is defined by '''resistance_torque''' attributes that defines resistance in Nm that is measured at 2000 rpm (arbitrary value). It is mainly linked with size of engine so if you set it to negative value it is defaulted from engine volume (volume * 20.0).
 +
 
 +
Default value for '''engine_brake_positions''' was changed to 3. Hold button logic works same as before, but now players could use partial engine brake usage as is present in most current trucks.
 +
 
 +
=== Chassis data ===
 +
 
 +
New attribute '''air_tank_pressure''' now defines nominal pressure truck wants to keep in air tanks. Default value is 10 bars.
 +
 
 +
=== Interior data ===
 +
 
 +
With more exact simulation of air pressure we unified animation API. All animation now expect values in bars. To prevent misunderstanding they were also renamed (with their '''_max''' and '''_min''' values): '''oil_psi_anim''' to '''oil_pressure_anim''', '''air_psi_anim''' to '''air_pressure_anim''', '''button_low_air_psi''' to '''indicator_low_air_pressure''', '''button_low_oil_psi''' to '''indicator_low_oil_pressure'''.
 +
 
 +
In addition, animation '''brake_psi_anim''' was renamed to '''brake_pressure_anim''', and is not in range 0-1 of brake limit anymore, it uses bars like all other pressure animations instead.
 +
 
 +
There was also added many new animations: '''differential_lock_stick_anim''' and '''indicator_differential_lock''' for new differential lock feature, '''indicator_weigh_green''' and '''indicator_weigh_red''' for weight pass model LEDs, and '''indicator_trailer_axle_lift''' for liftable axles on trailer.
 +
 
 +
Default value for '''clock_small_anim_max''' was changed to 24 as it is logic the code worked with always.
 +
 
 +
== Materials ==
 +
 
 +
The method of generating names of material files in the /automat directory was changed from SHA1 to CityHash64.
 +
 
 +
== Model format ==
 +
 
 +
Animated models are now skinned on the GPU and the PMG format was changed to allow its data to be directly used for rendering. Note that the new version only supports four bones affecting single vertex while the previous version did not have any limit.
 +
 
 +
* The game will automatically convert the previous format during load so older mods will continue to work. If the more than four bones are affecting a single vertex, only the four strongest influences will be used.
 +
* A updated conversion tools generating this new format will be released soon.
 +
* If necessary, existing PMG resources can be converted to the new format using the '''-conversion_dump_path''' command line option.
 +
 
 +
=== Low level format changes ===
 +
 
 +
==== Low level format changes ====
 +
 
 +
This is description of changes between the 0x506d6713 and 0x506d6714 version of the PMG format. It is intended to be used by people who are already familiar with the previous version of the format and need to access it directly.
 +
 
 +
* Changes to file header.
 +
** A u32 field containing number of per vertex weights was added directly behind the field containing number of bones. The only allowed values are either 0 for rigid model or 4 for skinned model.
 +
** Instead of tree separate blocks containing static, dynamic and skinning data respectively, there is only one block containing interleaved vertex data (see bellow). Offset and size fields for the separate blocks were removed and replaced by single offset and size for this combined block.
 +
 
 +
* Changes to piece header.
 +
** A u32 field containing number of per vertex weights was removed.
 +
** A u32 field containing size of a single interleaved vertex in bytes was added to the piece header between the AABB and positions offset.
 +
** A u32 field containing offset of array with vertex influences was removed.
 +
** A u32 field containing offset of array with indices was moved to the end of the piece header.
 +
** The bone dependencies and weights offsets should be set to 0xffffffff if skinning data are not present (i.e. for rigid model)
 +
 
 +
* Interleaved vertex
 +
** float3 position
 +
** float3 normal
 +
** (optional) float4 tangent
 +
** u32 vertex color
 +
** (optional) u32 secondary vertex color
 +
** (optional) float2[texcoord_width] texture coordinate
 +
** (bone_count > 0) u8[4] with 8bit bone indexes
 +
** (bone_count > 0) u8[4] with 8bit bone weights
 +
 
 +
If the vertex is affected by less than four bones, those bones should be stored in the leading entries. The remaining entries should replicate bone index from the last valid entry and use a zero weight. There must be at least one bone affecting each vertex and sum of weights over all bones affecting a vertex should be 255.
  
 
== Prefab ==
 
== Prefab ==

Latest revision as of 07:58, 27 April 2018

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 compoments 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

If your map is using some prefabs or road edges which were removed in this update, you need to convert it using a steps mentioned bellow. Otherwise no conversion is necessary.

  • Download the compatibility mod link and put it into mods folder.
  • Download a batch replace config link and put it into "Documents\American Truck Simulator" folder.
  • Load map in the editor
  • Open the replacement tool using F3 key and press the "Batch replace" button.
  • Save map
  • Correct prefabs according to the Prefab changes section bellow.
  • Save map

Changes

Vehicles data

Truck cameras

Please ensure that all cameras are set in the accessory_truck_data. A missing camera data can cause crash of ATS 1.6.0.6 open beta.

Truck accessory data

There is new rule overrides[] added. Its values are file names and it is non-lazy version of defaults[]. This means whenever this rule is used adding accessory also adds all override accessories regardless of presence of same type accessory (old ones are discarded). Typical use case is engine that takes engine badge or sound with itself. Forcing the change simplifies other rules as now engine badges or sounds do not need suitable rule on their sides which removes unwanted cross links between accessories. Use carefully as any forced change can loop easily with incorrect data.

Engine data

Part of engine simulation improvement is specifying inner engine resistance. It is defined by resistance_torque attributes that defines resistance in Nm that is measured at 2000 rpm (arbitrary value). It is mainly linked with size of engine so if you set it to negative value it is defaulted from engine volume (volume * 20.0).

Default value for engine_brake_positions was changed to 3. Hold button logic works same as before, but now players could use partial engine brake usage as is present in most current trucks.

Chassis data

New attribute air_tank_pressure now defines nominal pressure truck wants to keep in air tanks. Default value is 10 bars.

Interior data

With more exact simulation of air pressure we unified animation API. All animation now expect values in bars. To prevent misunderstanding they were also renamed (with their _max and _min values): oil_psi_anim to oil_pressure_anim, air_psi_anim to air_pressure_anim, button_low_air_psi to indicator_low_air_pressure, button_low_oil_psi to indicator_low_oil_pressure.

In addition, animation brake_psi_anim was renamed to brake_pressure_anim, and is not in range 0-1 of brake limit anymore, it uses bars like all other pressure animations instead.

There was also added many new animations: differential_lock_stick_anim and indicator_differential_lock for new differential lock feature, indicator_weigh_green and indicator_weigh_red for weight pass model LEDs, and indicator_trailer_axle_lift for liftable axles on trailer.

Default value for clock_small_anim_max was changed to 24 as it is logic the code worked with always.

Materials

The method of generating names of material files in the /automat directory was changed from SHA1 to CityHash64.

Model format

Animated models are now skinned on the GPU and the PMG format was changed to allow its data to be directly used for rendering. Note that the new version only supports four bones affecting single vertex while the previous version did not have any limit.

  • The game will automatically convert the previous format during load so older mods will continue to work. If the more than four bones are affecting a single vertex, only the four strongest influences will be used.
  • A updated conversion tools generating this new format will be released soon.
  • If necessary, existing PMG resources can be converted to the new format using the -conversion_dump_path command line option.

Low level format changes

Low level format changes

This is description of changes between the 0x506d6713 and 0x506d6714 version of the PMG format. It is intended to be used by people who are already familiar with the previous version of the format and need to access it directly.

  • Changes to file header.
    • A u32 field containing number of per vertex weights was added directly behind the field containing number of bones. The only allowed values are either 0 for rigid model or 4 for skinned model.
    • Instead of tree separate blocks containing static, dynamic and skinning data respectively, there is only one block containing interleaved vertex data (see bellow). Offset and size fields for the separate blocks were removed and replaced by single offset and size for this combined block.
  • Changes to piece header.
    • A u32 field containing number of per vertex weights was removed.
    • A u32 field containing size of a single interleaved vertex in bytes was added to the piece header between the AABB and positions offset.
    • A u32 field containing offset of array with vertex influences was removed.
    • A u32 field containing offset of array with indices was moved to the end of the piece header.
    • The bone dependencies and weights offsets should be set to 0xffffffff if skinning data are not present (i.e. for rigid model)
  • Interleaved vertex
    • float3 position
    • float3 normal
    • (optional) float4 tangent
    • u32 vertex color
    • (optional) u32 secondary vertex color
    • (optional) float2[texcoord_width] texture coordinate
    • (bone_count > 0) u8[4] with 8bit bone indexes
    • (bone_count > 0) u8[4] with 8bit bone weights

If the vertex is affected by less than four bones, those bones should be stored in the leading entries. The remaining entries should replicate bone index from the last valid entry and use a zero weight. There must be at least one bone affecting each vertex and sum of weights over all bones affecting a vertex should be 255.

Prefab

Prefab removals and renames

We removed some unused prefabs. Most of them were already marked as "DO NOT USE" in previous updates. If you used such prefab, then there are few cases:

  • Prefab was removed however compatible data are still there under a different name. In that case you can find updated definition in the prefab.scs16_data.sii which is part of the compatibility mod.
us09
us39
az39
az_oil_gst1
az_oul_gst
  • Prefab was removed completely. You will need to find a suitable replacement and edit that part of the map.
us_gas_13
us_gas_14
  • Prefab was replaced with a new version under a different name. The batch replacement step in "How to convert map" will rename it to the new name.
61
az44
az63
az64
az65
az75
us_23
us_28
us_29
us_30
us_32
us_41
us_42
us_43
us_44
us_44a
us_45
us_46
us_47
us_50
us_52
us_55
us_58
us_59
us_61
us_62
us_63
us_65
us_66
us_74
us_75
us03_r
us25
us41
us42
us43

Variant removals

Some variants were removed from prefabs so you will need to find a suitable replacement.

Separate corners

In case where the prefab was replaced with a new version (see above), it is very likely that the new version has its corners configurable in the prefab item in map editor instead of being part of the variant. After the batch replacement all such prefabs will be left with no corners set so there will be gaps in the map where the corners were. You need to visit those prefabs and select a suitable types of corners.

Road edges

Some road edges were replaced with a new ones. The batch replacement step should convert them to the new versions.