Difference between revisions of "Documentation/Engine/Units"
(→What is unit?) |
|||
Line 1: | Line 1: | ||
=What is unit?= | =What is unit?= | ||
− | Units are objects inside SCS game engine. One of their core abilities is so | + | 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 to define various parts of the games. |
Unit has: | Unit has: |
Revision as of 01:40, 19 December 2018
Contents
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 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 bevehicledummytruck
however in most cases you should not use them, in case some mod is using namevehicle.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.
Structure
The magic mark – used to check if the file is a 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_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 { 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 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:
some_file_using_include.sii
SiiNunit { example: doing.includes { foo: "bar" over: 9000 @include "some_file_to_include.sui" } }
some_file_to_include.sui:
ninjas: true
How the game “sees” some_file_using_include.sii:
SiiNunit { 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:
SiiNunit { 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. |
Arrays
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 data
- accessory addon int data
- accessory addon int ui data
- accessory addon tank data
- accessory addon trailer cables data
- accessory cabin data
- accessory cargo data
- accessory chassis data
- accessory data
- accessory engine data
- accessory horn addon data
- accessory interior data
- accessory paint job data
- accessory rim data
- accessory sound data
- accessory trailer body data
- accessory transmission data
- accessory truck data
- accessory wheel data
- cargo data
- cargo def
- cargo model match
- company def
- company permanent
- dynamic cargo data
- glass pane data
- journey events cutscene
- journey events road event
- package version info
- sound data
- sound data voice navigation
- sound engine data
- sound noise data
- trailer
- trailer cable data
- trailer configuration
- trailer def
- transmission names
- vehicle accessory
- vehicle addon accessory
- vehicle paint job accessory
- vehicle wheel accessory
- wiper data