====== Enumerations ======

An enumeration (or enum) is a data type containing a set of constant values.

See the [[api:#Enumerations|list of all available enumerations]].

----

Previously, you could only refer to enum elements as strings. For example, to define the [[api:building#BuildingType|building type of a building]], you used ''BuildingType = "GENERAL"''.

Now, all enum values are stored in their enum type's table. This allows for a more clear syntax: ''BuildingType = BUILDING_TYPE.GENERAL''.

The conversion to string is still available with the function ''toString''. You can also convert the enum value to an integer and vice versa with the functions ''toNumber'' and ''fromNumber''. These functions are available in the ''enum'' table, and directly on the enum tables and enum values.

<file lua enum.lua>
local stringValue = BUILDING_TYPE.MONUMENT:toString()
-- same as enum.toString(BUILDING_TYPE.MONUMENT)
print(stringValue) -- prints "MONUMENT"

local intValue = BUILDING_TYPE.DECORATION:toNumber()
-- same as enum.toNumber(BUILDING_TYPE.DECORATION)
print(intValue) -- prints "2"

local enumValue = BUILDING_TYPE:fromNumber(intValue)
-- same as enum.fromNumber(BUILDING_TYPE, intValue)
print (enumValue == BUILDING_TYPE.DECORATION) -- prints ("true")
</file>

These functions are useful, for example, to use enum values for bitwise operations. When you want to use [[api:level#rayCast|the raycast method]], the ''//flag//'' argument is used as a bit field containing the different [[api:object_flag|object flags]] you want your ray cast to collide with. This means you have to create your flag using bitwise operations. To do this, you can use the [[http://bitop.luajit.org/api.html|BitOp module]], the functions of which are available in the ''bit'' table.

<file lua raycast.lua>
local raycastResult = {}

-- C equivalent: (1 << OBJECT_FLAG.TERRAIN) | (1 << OBJECT_FLAG.WATER) | (1 << OBJECT_FLAG.PLATFORM)
local flag = bit.bor(
	bit.lshift(1, OBJECT_FLAG.TERRAIN:toNumber()),
	bit.lshift(1, OBJECT_FLAG.WATER:toNumber()),
	bit.lshift(1, OBJECT_FLAG.PLATFORM:toNumber())
)

-- Raycast from the screen position [400; 300], forward
-- for a distance of 1000, only on objects with a TERRAIN,
-- WATER or PLATFORM flag
level:rayCast({ 400, 300 }, 1000, raycastResult, flag)
</file>

===== Dynamic enumerations =====

For enumerations tagged as dynamic, you can add new values with the function ''registerEnumValue''. Multiple mods can register the same new enum value, which is then shared.

You can find more information on the ''registerEnumValue'' on the [[:mod-management-functions#registerEnumValue|mod management function page]].