Difference between revisions of "Documentation/Engine/Units"

From SCS Modding Wiki
Jump to navigation Jump to search
(→‎What is unit?)
(26 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
=What is unit?=
 
=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.
+
Units are objects in Prism3d that have ability to be serialized or deserialized.
  
 
Unit has:
 
Unit has:
Line 10: Line 10:
 
== SII files ==
 
== 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.
+
Units are stored in SII files. There are two versions of this file supported by engine textual and binary however only textual form is used for definitions.
  
−
=== Structure ===
+
=== Struture ===
  
−
The magic mark – used to check if the file is a real SII file or not.
+
The magic mark - used to check if file is real SII file or not.
  
−
<pre>SiiNunit</pre>
+
<pre>SiiNUnit</pre>
 
The opening bracket used to explicitly show the global file scope start
 
The opening bracket used to explicitly show the global file scope start
  
Line 26: Line 26:
 
     attribute_number: 40
 
     attribute_number: 40
 
     attribute_string: &quot;TEST STRING&quot;
 
     attribute_string: &quot;TEST STRING&quot;
−
     attribute_unit: test.unit
+
     attribute_token: TEST
 
     attribute_float3: (1.0, 1.0, 1.0)
 
     attribute_float3: (1.0, 1.0, 1.0)
 
     attribute_float_number_ieee754: &amp;40490f5a
 
     attribute_float_number_ieee754: &amp;40490f5a
 
}</pre>
 
}</pre>
−
The closing bracket for the SiiNunit
+
The closing bracked for the SiiNUnit
  
 
<pre>}</pre>
 
<pre>}</pre>
Line 67: Line 67:
 
=== Includes ===
 
=== 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.
+
You can also include other files into another. To do this you need to use SII preprocessor directive - <code>@include</code>.
  
−
'''Example:'''<br />
+
'''Example:'''
−
''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>@include &quot;some_file_to_include.sui&quot;</pre>
−
<pre>SiiNunit
+
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 using this extension.
−
{
 
−
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 ==
 
== Attribute types ==
 
{| class="wikitable"  width="100%"
 
{| class="wikitable"  width="100%"
−
! Type
+
!width="19%"| Type
−
! Value
+
!width="25%"| Value
−
! Example
+
!width="55%"| Example
−
! Notes
 
 
|-
 
|-
 
| string
 
| string
 
| &quot;x&quot;
 
| &quot;x&quot;
 
| attribute: &quot;String value&quot;
 
| attribute: &quot;String value&quot;
−
|
 
 
|-
 
|-
 
| float
 
| float
 
| x
 
| x
 
| attribute: 1.0 // Using normal float-notation<br>attribute: &amp;3f800000 // using ieee754 hexa notation
 
| attribute: 1.0 // Using normal float-notation<br>attribute: &amp;3f800000 // using ieee754 hexa notation
−
|
 
 
|-
 
|-
 
| float2
 
| float2
 
| (x, y)
 
| (x, y)
 
| attribute: (1.0, 2.0)
 
| attribute: (1.0, 2.0)
−
|
 
 
|-
 
|-
 
| float3
 
| float3
 
| (x, y, z)
 
| (x, y, z)
 
| attribute: (1.0, 5.0, 3.0)
 
| attribute: (1.0, 5.0, 3.0)
−
|
 
 
|-
 
|-
 
| float4
 
| float4
 
| (x, y, z, w)
 
| (x, y, z, w)
 
| attribute: (1.0, 5.0, 3.0, 9.0)
 
| 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
 
| fixed
 
| x
 
| x
−
| attribute: 10
+
| 10
−
|
 
 
|-
 
|-
 
| fixed2
 
| fixed2
 
| (x, y)
 
| (x, y)
−
| attribute: (10, 22)
+
| (10, 22)
−
|
 
 
|-
 
|-
 
| fixed3
 
| fixed3
 
| (x, y, z)
 
| (x, y, z)
−
| attribute: (10, 22, 33)
+
| (10, 22, 33)
−
|
 
 
|-
 
|-
 
| fixed4
 
| fixed4
 
| (x, y, z, w)
 
| (x, y, z, w)
−
| attribute: (10, 22, 33, 44)
+
| (10, 22, 33, 44)
−
|
 
 
|-
 
|-
 
| int2
 
| int2
 
| (x, y)
 
| (x, y)
 
| attribute: (20, 69)
 
| attribute: (20, 69)
−
|
 
 
|-
 
|-
 
| quaternion
 
| quaternion
 
| (w, x, y, z)
 
| (w, x, y, z)
 
| attribute: (1.0, 0.0, 0.0, 0.0)
 
| attribute: (1.0, 0.0, 0.0, 0.0)
−
|
+
|-
 +
| token
 +
| x
 +
| attribute: value
 
|-
 
|-
 
| s16
 
| s16
 
| x
 
| x
 
| attribute: -15
 
| attribute: -15
−
|
 
 
|-
 
|-
 
| s32
 
| s32
 
| x
 
| x
 
| attribute: -15
 
| attribute: -15
−
|
 
 
|-
 
|-
 
| s64
 
| s64
 
| x
 
| x
 
| attribute: -15
 
| attribute: -15
−
|
 
 
|-
 
|-
 
| u16
 
| u16
 
| x
 
| x
 
| attribute: 15
 
| attribute: 15
−
|
 
 
|-
 
|-
 
| u32
 
| u32
 
| x
 
| x
 
| attribute: 15
 
| attribute: 15
−
|
 
 
|-
 
|-
 
| u64
 
| u64
 
| x
 
| x
 
| attribute: 15
 
| attribute: 15
−
|
 
 
|-
 
|-
−
| bool (boolean)
+
| bool
 
| x
 
| x
 
| attribute: true
 
| attribute: true
  
 
attribute: false
 
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)
+
| unit
 
| x
 
| x
−
| attribute: .some.nameless.unit
+
| attribute: my.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.
 
 
|}
 
|}
  
Line 239: Line 169:
 
<pre>
 
<pre>
 
attribute_name[]: value
 
attribute_name[]: value
−
attribute_name[]: value2
 
−
attribute_name[]: value3
 
 
</pre>
 
</pre>
  
Line 246: Line 174:
  
 
<pre>
 
<pre>
−
attribute_name: 3           <-- Size of the array.
+
attribute_name: 3
−
attribute_name[0]: 1       <-- 1st element
+
attribute_name[0]: 1
−
attribute_name[1]: 5       <-- 2nd element
+
attribute_name[1]: 5
−
attribute_name[2]: 9       <-- 3rd element
+
attribute_name[2]: 9
 
</pre>
 
</pre>
−
 
−
=Documented Unit Types=
 
−
{{Special:PrefixIndex/Documentation/Engine/Units/|hideredirects=1|stripprefix=1}}
 

Revision as of 09:28, 16 February 2016

What is unit?

Units are objects in Prism3d that have ability to be serialized or deserialized.

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 engine textual and binary however only textual form is used for definitions.

Struture

The magic mark - used to check if file is real SII file or not. 

SiiNUnit

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_token: TEST
    attribute_float3: (1.0, 1.0, 1.0)
    attribute_float_number_ieee754: &40490f5a
}

The closing bracked 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
{
    attributes
}

Comments

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

Example: 

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

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

Example: 

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

Includes

You can also include other files into another. To do this you need to use SII preprocessor directive - @include.

Example: 

@include "some_file_to_include.sui"

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 using this extension.

Attribute types

Type Value Example
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)
fixed x 10
fixed2 (x, y) (10, 22)
fixed3 (x, y, z) (10, 22, 33)
fixed4 (x, y, z, w) (10, 22, 33, 44)
int2 (x, y) attribute: (20, 69)
quaternion (w, x, y, z) attribute: (1.0, 0.0, 0.0, 0.0)
token x attribute: value
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 x attribute: true

attribute: false

unit x attribute: my.unit

Arrays

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

attribute_name[]: value

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

attribute_name: 3
attribute_name[0]: 1
attribute_name[1]: 5
attribute_name[2]: 9
Retrieved from "https://modding.scssoft.com/index.php?title=Documentation/Engine/Units&oldid=1688"