From SCS Modding Wiki
< Documentation‎ | Engine
Revision as of 01:40, 19 December 2018 by ErykDwornicki (Talk | contribs) (What is unit?)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

What is unit?

Units are objects inside SCS game engine. One of their core abilities is so they can be serialized or deserialized making it a perfect tool to give content creators a way to define various parts of the games.

Unit has:

  • Name - units can be nameless or have some specified name. Unit names are divided into components which are 12-char tokens separated by dot - for example correct unit name will be vehicle.dummy.truck incorrect will be vehicledummytruck however in most cases you should not use them, in case some mod is using name vehicle.dummy.truck and you will also use this your mod will fail to load. To create nameless unit simply use dot as the prefix for your unit name for example .my_mod.nameless.units
  • Attributes - attributes are set of the data that unit can store, it can be number, text, other unit connection, set of them etc.

SII files

Units are stored in SII files. There are two versions of this file supported by the game engine: plain-text and binary. However, only the plain-text format is used for definitions.


The magic mark – used to check if the file is a real SII file or not.


The opening bracket used to explicitly show the global file scope start


Here you put your unit definitions

some_unit : .my_mod.unit
    attribute_number: 40
    attribute_string: "TEST STRING"
    attribute_unit: test.unit
    attribute_float3: (1.0, 1.0, 1.0)
    attribute_float_number_ieee754: &40490f5a

The closing bracket for the SiiNunit


It's always good to add one blank line at the end of the file.

Unit definition entry

Unit definition entry format is:

class name : unit name


You can comment some of your data using C-like multi-line comments syntax starting from /* and ending with */.


/* Definition of some unit.
 * Author: You */
some_unit : .my_mod.unit

Also you can use one-line comments those are starting from # or //.


some_unit : .my_mod.unit // Some unit
    # This value should be tweaked after users feedback
    some_value: 45.875


You can also include the contents of other files using the SII preprocessor directive - @include. The contents of the included file will be read as if they were in the file itself.


example: doing.includes
    foo: "bar"
    over: 9000
@include "some_file_to_include.sui"


    ninjas: true

How the game “sees” some_file_using_include.sii:

example: doing.includes
    foo: "bar"
    over: 9000
    ninjas: true

You may notice usage of the new extension - .sui. It's used for unit serialized files without magic mark SiiNunit that are included somewhere in different files. We recommend you also use this extension.

Note: The @include directive must appear at the beginning of a new line with no whitespace (space, tab, etc) before it. The following examples will not work:

bad_examples: just.the.worst {
    foo: "bar"
    @include "dont_get_too_attached_to_indents.sui"

    foo: @include "you_definitely_cannot_use_it_inline.sui"

Attribute types

Type Value Example Notes
string "x" attribute: "String value"
float x attribute: 1.0 // Using normal float-notation
attribute: &3f800000 // using ieee754 hexa notation
float2 (x, y) attribute: (1.0, 2.0)
float3 (x, y, z) attribute: (1.0, 5.0, 3.0)
float4 (x, y, z, w) attribute: (1.0, 5.0, 3.0, 9.0)
placement (x, y, z) (w; x, y, z) attribute: (0, 0, 0) (1; 0, 0, 0)
fixed x attribute: 10
fixed2 (x, y) attribute: (10, 22)
fixed3 (x, y, z) attribute: (10, 22, 33)
fixed4 (x, y, z, w) attribute: (10, 22, 33, 44)
int2 (x, y) attribute: (20, 69)
quaternion (w, x, y, z) attribute: (1.0, 0.0, 0.0, 0.0)
s16 x attribute: -15
s32 x attribute: -15
s64 x attribute: -15
u16 x attribute: 15
u32 x attribute: 15
u64 x attribute: 15
bool (boolean) x attribute: true

attribute: false

token x attribute: value Token is a string of maximum length of 12 characters, only lowercase alphanumeric characters and underscore can be used [a-z0-9_]
owner pointer (owner_ptr) x attribute: .some.nameless.unit owner_ptr refers to unit defined within the same SiiNunit (eg. .trailer.tchassis)
link pointer (link_ptr) x attribute: some.named.unit link_ptr refers to a named unit that is defined elsewhere (eg. cabin_a.brand.model.cabin)
resource_tie "x" attribute: "path/to/some/resource.pma" resource_tie is typically used to bind animations to animated models. The syntax is the same as for 'string' type attributes.


You can also use arrays of the values. The array syntax is:

attribute_name[]: value
attribute_name[]: value2
attribute_name[]: value3

In some cases you may notice fixed-arrays written in this format:

attribute_name: 3           <-- Size of the array.
attribute_name[0]: 1        <-- 1st element
attribute_name[1]: 5        <-- 2nd element
attribute_name[2]: 9        <-- 3rd element

Documented Unit Types

accessory addon dataaccessory addon trailer cables dataaccessory cabin data
accessory cargo dataaccessory chassis dataaccessory data
accessory engine dataaccessory interior dataaccessory paint job data
accessory rim dataaccessory sound dataaccessory transmission data
accessory truck dataaccessory wheel datacargo data
cargo defcompany defcompany permanent
glass pane datajourney events cutscenejourney events road event
package version infosound datasound engine data
sound noise datatrailertrailer cable data
trailer deftransmission namesvehicle accessory
vehicle addon accessoryvehicle paint job accessoryvehicle wheel accessory
wiper data