Difference between revisions of "Documentation/Engine/Units"
Line 179: | Line 179: | ||
attribute_name[2]: 9 | attribute_name[2]: 9 | ||
</pre> | </pre> | ||
+ | |||
+ | [[Category:Engine]] | ||
+ | [[Category:Documentation]] |
Revision as of 16:31, 9 February 2016
Contents
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 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 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