View source for Documentation/Engine/Units

=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 <code>vehicle.dummy.truck</code> incorrect will be <code>vehicledummytruck</code> however in most cases you should not use them, in case some mod is using name <code>vehicle.dummy.truck</code> 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 <code>.my_mod.nameless.units</code>
* 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.

=== Structure ===

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

<pre>SiiNunit</pre>
The opening bracket used to explicitly show the global file scope start

<pre>{</pre>
Here you put your unit definitions

<pre>some_unit : .my_mod.unit
{
    attribute_number: 40
    attribute_string: &quot;TEST STRING&quot;
    attribute_unit: test.unit
    attribute_float3: (1.0, 1.0, 1.0)
    attribute_float_number_ieee754: &amp;40490f5a
}</pre>
The closing bracket for the SiiNunit

<pre>}</pre>

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

=== Unit definition entry ===

Unit definition entry format is:

<pre>class name : unit name
{
    attributes
}</pre>
=== Comments ===

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

'''Example:'''

<pre>/* Definition of some unit.
 *
 * Author: You */
some_unit : .my_mod.unit
{
}</pre>
Also you can use one-line comments those are starting from <code>#</code> or <code>//</code>.

'''Example:'''

<pre>some_unit : .my_mod.unit // Some unit
{
    # This value should be tweaked after users feedback
    some_value: 45.875
}</pre>
=== Includes ===

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

'''Example:'''<br />
''some_file_using_include.sii''
<pre>SiiNunit
{
example: doing.includes
{
    foo: &quot;bar&quot;
    over: 9000
@include &quot;some_file_to_include.sui&quot;
}
}
</pre>
''some_file_to_include.sui:''
<pre>    ninjas: true</pre>
''How the game &ldquo;sees&rdquo; some_file_using_include.sii:''
<pre>SiiNunit
{
example: doing.includes
{
    foo: &quot;bar&quot;
    over: 9000
    ninjas: true
}
}
</pre>
You may notice usage of the new extension - '''.sui'''. It's used for unit serialized files without magic mark <code>SiiNunit</code> that are included somewhere in different files. We recommend you also use this extension.

{{Note|The <code>@include</code> directive must appear at the beginning of a new line with no whitespace (space, tab, etc) before it. The following examples will '''not''' work:
<pre>SiiNunit
{
bad_examples: just.the.worst {
    foo: &quot;bar&quot;
    @include &quot;dont_get_too_attached_to_indents.sui&quot;

    foo: @include &quot;you_definitely_cannot_use_it_inline.sui&quot;
}
}
</pre>}}

== Attribute types ==
{| class="wikitable"  width="100%"
! Type
! Value
! Example
! Notes
|-
| string
| &quot;x&quot;
| attribute: &quot;String value&quot;
|
|-
| float
| x
| attribute: 1.0 // Using normal float-notation<br>attribute: &amp;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
|
|-
| <span id="attribute_type_token">token</span>
| x
| attribute: value
| Token is a string of maximum length of 12 characters, only lowercase alphanumeric characters and underscore can be used [<code>a-z0-9_</code>]
|-
| owner pointer (owner_ptr)
| x
| attribute: .some.nameless.unit
| '''owner_ptr''' refers to unit defined within the same SiiNunit (eg. <code>.trailer.tchassis</code>)
|-
| link pointer (link_ptr)
| x
| attribute: some.named.unit
| '''link_ptr''' refers to a named unit that is defined elsewhere (eg. <code>cabin_a.brand.model.cabin</code>)
|-
| 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.
|}

===Arrays===

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

<pre>
attribute_name[]: value
attribute_name[]: value2
attribute_name[]: value3
</pre>

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

<pre>
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
</pre>

=Documented Unit Types=
{{Special:PrefixIndex/Documentation/Engine/Units/|hideredirects=1|stripprefix=1}}