Difference between revisions of "Documentation/Engine/Units"

From SCS Modding Wiki
Jump to navigation Jump to search
(Created page with "=What is unit?= Units are objects in Prism3d that have ability to be serialized or deserialized. Units has: * Name - units can be nameless or have some specified name names...")
 
Line 5: Line 5:
 
Units has:
 
Units has:
  
* Name - units can be nameless or have some specified name names are divided into<br />
+
* Name - units can be nameless or have some specified name names are divided into components which are 12-char tokens separated by dot - for example correct unit name will be <code>vehicle.dummy.truck however</code> in most cases you should not use them as in case engine detects two units with the same name it will fail so 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>
components which are 12-char tokens separated by dot - for example correct<br />
+
* Attributes - attributes is a set of the data unit can store, it can be number, text, other unit connection, set of them etc. Some units are failing in case they contain serialized some attribute that is no longer supported however some of them have special flag in the engine to allow loading not allowed attributes.
unit name will be <code>vehicle.dummy.truck however</code> in most cases you should not use<br />
 
them as in case engine detects two units with the same name it will fail so in<br />
 
case some mod is using name <code>vehicle.dummy.truck</code> and you will also use this your<br />
 
mod will fail to load. To create nameless unit simply use dot as the prefix for<br />
 
your unit name for example <code>.my_mod.nameless.units</code>
 
* Attributes - attributes is a set of the data unit can store, it can be number,<br />
 
text, other unit connection, set of them etc. Some units are failing in case they<br />
 
contain serialized some attribute that is no longer supported however some of<br />
 
them have special flag in the engine to allow loading not allowed attributes.
 
  
 
== SII files ==
 
== SII files ==
  
Units are stored in SII files. There are two versions of this file supported by<br />
+
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.
engine textual and binary however only textual form is used for definitions.
 
  
 
=== Struture ===
 
=== Struture ===
Line 55: Line 45:
 
=== Comments ===
 
=== Comments ===
  
You can comment some of your data using C-like multi-line comments syntax starting<br />
+
You can comment some of your data using C-like multi-line comments syntax starting from <code>/*</code> and ending with <code>*/</code>.
from <code>/*</code> and ending with <code>*/</code>.
 
  
 
'''Example:'''
 
'''Example:'''
Line 77: Line 66:
 
=== Includes ===
 
=== Includes ===
  
You can also include other files into another. To do this you need to use SII<br />
+
You can also include other files into another. To do this you need to use SII preprocessor directives <code>@include</code>.
preprocessor directives <code>@include</code>.
 
  
 
'''Example:'''
 
'''Example:'''
  
 
<pre>@include &quot;some_file_to_include.sui&quot;</pre>
 
<pre>@include &quot;some_file_to_include.sui&quot;</pre>
You may notice usage of the new extension - '''.sui'''. It's used for unit serialized<br />
+
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.
files without magic mark <code>SiiNUnit</code> that are included somewhere in different files.<br />
 
We recommend you also using this extension.
 
  
 
== Attribute types ==
 
== Attribute types ==
Line 199: Line 185:
 
| attribute: my.unit
 
| attribute: my.unit
 
|}
 
|}
 
Copyright © 2015 by SCS SOFTWARE
 

Revision as of 13:15, 14 January 2016

What is unit?

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

Units has:

  • Name - units can be nameless or have some specified name names are divided into components which are 12-char tokens separated by dot - for example correct unit name will be vehicle.dummy.truck however in most cases you should not use them as in case engine detects two units with the same name it will fail so 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 is a set of the data unit can store, it can be number, text, other unit connection, set of them etc. Some units are failing in case they contain serialized some attribute that is no longer supported however some of them have special flag in the engine to allow loading not allowed attributes.

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_vector3: (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 directives @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

TODO: arrays
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)
float4x4 ? ?
fixed x ?
fixed2 (x, y) ?
fixed3 (x, y, z) ?
fixed4 (x, y, z, w) ?
int2 (x, y) attribute: (20, 69)
quaternion (w, x, y, z) attribute: (1.0, 0.0, 0.0, 0.0)
placement ? ?
placement_scale ? ?
placement_nonuniform ? ?
plane ? ?
aabox ? ?
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