Foundation - Modding Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Data types ======

----

==== boolean ====

<file lua>
local value = true
</file>

----

==== integer and unsigned integer ====

Integer number. Cannot be negative for unsigned integers.

<file lua>
local value = 42
</file>

----

==== float ====

Floating-point number with single precision

<file lua>
local value = 17.44
</file>

----

==== double ====

Floating-point number with double precision

<file lua>
local value = -61.7267023355
</file>

----

==== string ====

<file lua>
local value = "String value"
</file>

----

==== guid ====

GUID are unique identifiers used to reference Assets or Game Objects. It can be interpreted from a string.

<file lua>
local value = "645318b0-021a-4e02-9f91-bd18300e491a"
</file>

----

==== vec2i ====

2D integer vector

To initialize a ''vec2i'' with ''x = 54'' and ''y = 97'':
<file lua>
local value = { 54, 97 }
</file>

[[api:vec2i|Full vec2i api]].

----

==== vec2f ====

2D float vector

To initialize a ''vec2f'' with ''x = 73'' and ''y = 15.66'':
<file lua>
local value = { 73.0, 15.66 }
</file>

[[api:vec2f|Full vec2f api]].

----

==== vec3i ====

3D integer vector

To initialize a ''vec3i'' with ''x = 19'', ''y = 86'' and ''z = 45'':
<file lua>
local value = { 19, 86, 45 }
</file>

[[api:vec3i|Full vec3i api]].

----

==== vec3f ====

3D float vector.

To initialize a ''vec3f'' with ''x = -15.71'', ''y = -71'' and ''z = 93.03'':
<file lua>
local value = { -15.71, -71.0, 93.03 }
</file>

[[api:vec3f|Full vec3f api]].

----

==== quaternion ====

4D float vector representing a rotation

To initialize a ''quaternion'' with ''x = 0.302268'', ''y = 0.075567'', ''z = 0.6347627'' and ''w = 0.7071068'':
<file lua>
local value = { 0.302268, 0.075567, 0.6347627, 0.7071068 }
</file>

Quaternion properties can also be set with a ''vec3f'' containing the euler angles in degrees.

----

==== matrix ====

4x4 matrix representing a spatial transformation

Matrices can be initialized with an array of 16 float numbers.
<file lua>
local value = {
    1, 0, 0, 0,
    0, 1, 0, 0,
    0, 0, 1, 0,
    0, 0, 0, 1
}
</file>

Matrices can also be initialized with a dictionary containing three fields: ''Position'' (''vec3f''), ''Rotation'' (''quaternion'') and ''Scale'' (''vec3f''). All those fields are optional.

<file lua>
local value = {
    Position = { 0, 0, 0 },
    Rotation = { 0, 0, 0 },
    Scale = { 1, 1, 1 } 
}
</file>

----

==== color ====

A color is stored as four float numbers, representing the four channels. Each channel can have a value superior to 1, in case of HDR use.

To initialize a ''color'' with ''R = 1'', ''G = 0.549'', ''B = 0'' and ''A = 0.9'' (dark orange with 90% opacity; hex ''FF8C00E6''):
<file lua>
local value = { 1, 0.549, 0, 0.9 }
</file>

----

==== polygon ====

A 2D polygon is a list of 2D points (''vec2f'') defining a shape.

To initialize a square polygon with a side length of ''4.5'' and centered around the point ''[1; 1]'':
<file lua>
local value = {
    { 5.5, 5.5 },
    { 5.5, -3.5 },
    { -3.5, -3.5 },
    { -3.5, 5.5 }
}
</file>

You can also create simple polygons with the following functions:

  * ''polygon.**createRectangle**(//_size// [, //_offset//])''

^ Name ^ Type ^ Description ^
| //''_size''// | ''vec2f'' | Size of the rectangle |
| //''_offset''// | ''vec2f'' | Offset of the center of the rectange from [0; 0] |

  * ''polygon.**createCircle**(//_radius// [, //_offset// [, //_step//]])''

^ Name ^ Type ^ Description ^
| //''_radius''// | ''float'' | Radius of the circle |
| //''_offset''// | ''vec2f'' | Offset of the center of the circle from [0; 0] |
| //''_step''// | ''integer'' | Amount of sides of the circle |

----

==== bitfield ====

A bitfield is a dictionary with enumeration values of a specific type as keys, and boolean values as value.

When defining a new object, a enumeration value missing from a bitfield table will be considered as false. When [[:asset-override|overriding existing data]], a missing enumeration value means the existing value will not be overriden.

To initialize a bitfield of [[api:building_zone_type|BUILDING_ZONE_TYPE]] with the ''DEFAULT'' and ''GRASS_CLEAR'' values:
<file lua>
local bitfield = {
    DEFAULT = true,
    NAVIGABLE = false,
    GRASS_CLEAR = true
}
</file>

==== component type ====

Type of a component, represented as a string

<file lua>
local componentType = "COMP_BUILDING_PART"
</file>

==== list ====

A list is a collection of values of a specific type. This type can be used to create new properties for [[custom-classes|custom classes]]. The following example shows how to declare a ''[[data-types#float|float]]'' list property:

<file lua>
Properties = {
    ...
    {
        Name = "MyFloatListProperty", -- property name
        Type = "list<float>", -- type: list of float numbers
        Default = { 1.0, -4.0, 5.0 }, -- default value: list with three float numbers
    },
    ...
}

...

mod:log(tostring(#myClassInstance.MyFloatListProperty)) -- logs the size of the list
mod:log(tostring(myClassInstance.MyFloatListProperty[3])) -- logs the 3rd element of the list
</file>

==== fixed_sized_array ====

A fixed sized array is a list containing a fixed number of values of a specific type. This type of property is specified with it's size (e.g. ''float[5]''), and each value is accessible with the element's index (indexing is 1-based, like everything in lua). The following example shows how to declare and use a [[custom-classes|custom class]] array property containing 4 ''[[data-types#string|strings]]'':

<file lua>
Properties = {
    ...
    {
        Name = "MyStringArrayProperty", -- property name
        Type = "string[4]", -- type: array of 4 strings
        Default = { "my", "custom", "default", "values" }, -- default value
    },
    ...
}

...

mod:log(myClassInstance.MyStringArrayProperty[2]) -- logs the 2nd element of the list
</file>

An example of use can be found in the [[example-mods|Example 02 mod]], in the script file ''scripts/component/COMP_ANTENNA.lua''

==== fixed_sized_map ====

A fixed sized map is very similar to a fixed sized array, except it can only take enumeration values as keys. For some properties, a maximum key value can be specified.

With a fixed sized map of [[data-types#float|float]] with [[api:building_type|BUILDING_TYPE]] keys, to set the value corresponding to the key ''GENERAL'':

<file lua>
someType.MyMapProperty[BUILDING_TYPE.GENERAL] = 4.2
someType.MyMapProperty["GENERAL"] = 3.4 -- works only with the string version of the enum value
</file>