Properties

In many cases, your scripts will require external input to fine-tune their behavior according to specific requirements. For example, a script might need a reference to another scene object or a numeric constant to configure a particular behavior. Our engine facilitates this through properties that are exposed to the editor, which can then be set by the user.

Defining Properties

Properties can be defined directly in the Lua script using the addProperty method. These properties are then visible and editable within the engine's editor, allowing users to configure script behavior dynamically without modifying the script's code. Properties may be defined with or without default values.

local MyBehaviour = Class.new(Behaviour)

MyBehaviour:addProperty("x", Property.Number, 0, "This is an optional string that describes the property")
MyBehaviour:addProperty("y", Property.Number, 0)

function MyBehaviour:init()
    print("The sum of x and y is:", self.x + self.y)
end

return MyBehaviour

Supported Property Types

The engine supports several types of properties that can be used according to the needs of the script. Each type serves different purposes, from simple numbers and strings to references to objects within the scene graph.

Property.EditorAction is documented in detail on the Editor Tools page. Use it only on EditorTool scripts, not on behaviours.

Array types

Each scalar type also has an array variant. Array properties are edited as a dynamic list in the inspector and are stored as Lua tables at runtime (1-based indexing).

Number array — useful for weights, timings, or any list of numeric parameters:

MyBehaviour:addProperty("weights", Property.NumberArray, { 0.25, 0.5, 0.75 }, {
    minValue = 0,
    maxValue = 1,
    info = "Blend weights applied in order",
})

function MyBehaviour:init()
    local total = 0
    for i, weight in ipairs(self.weights) do
        total = total + weight
        print("Weight", i, "=", weight)
    end
    print("Total weight:", total)
end

String array — useful for tags, layer names, or lookup keys:

MyBehaviour:addProperty("tags", Property.StringArray, { "enemy", "boss" })

function MyBehaviour:init()
    for _, tag in ipairs(self.tags) do
        print("Tag:", tag)
    end
end

Boolean array — useful for per-slot feature toggles:

MyBehaviour:addProperty("enabledSlots", Property.BoolArray, { true, false, true })

function MyBehaviour:init()
    for i, enabled in ipairs(self.enabledSlots) do
        if enabled then
            print("Slot", i, "is enabled")
        end
    end
end

Node array — useful when a script needs references to several scene objects:

MyBehaviour:addProperty("targets", Property.NodeArray, {})

function MyBehaviour:init()
    for i, target in ipairs(self.targets) do
        if target then
            print("Target", i, ":", target:getDisplayName())
        end
    end
end

Link array — useful for lists of project items (meshes, images, materials, etc.):

MyBehaviour:addProperty("meshes", Property.LinkArray, {}, {
    allowedTypes = { "Mesh", "Image" },
})

function MyBehaviour:init()
    for i, mesh in ipairs(self.meshes) do
        if mesh then
            print("Mesh", i, ":", mesh:getName())
        end
    end
end

allowedTypes works the same way on Property.LinkArray as on Property.Link.

Property Options

The fourth argument to addProperty can be a string (used as an info tooltip) or an options table:

MyBehaviour:addProperty("speed", Property.Number, 1.0, {
    info = "Movement speed in units per second",
    minValue = 0,
    maxValue = 100,
})

MyBehaviour:addProperty("advancedSection", Property.Separator, "Advanced", {
    collapsed = true,
})

MyBehaviour:addProperty("useCustomSpeed", Property.Bool, false)
MyBehaviour:addProperty("customSpeed", Property.Number, 5, {
    conditions = { useCustomSpeed = true },
})

MyBehaviour:addProperty("material", Property.Link, nil, {
    allowedTypes = { "Material" },
})

MyBehaviour:addProperty("texture", Property.Link, nil, {
    allowedTypes = { "Image", "Composition" },
})

Separators

Separator properties group following properties into a collapsible section in the inspector. The default value is used as the section title. Properties declared after a separator appear inside that section until the next separator.

Conditions

The conditions option controls whether a property is visible in the inspector. The format matches datatype field conditions elsewhere in the engine:

-- Show only when another property equals a value
conditions = { mode = "advanced" }

-- Show when any condition matches
conditions = { ["$or"] = {
    { mode = "advanced" },
    { enabled = true },
}}

-- Invert a condition
conditions = { ["$not"] = { mode = "simple" } }

-- Optional dependency (no error if the field does not exist)
conditions = { ["otherField?"] = true }

Conditions are evaluated in the editor when you change other script properties on the same script instance.

Link Properties

Link properties reference items from the project explorer. Drag and drop an item onto the field in the inspector, or use the picker dialog. At runtime the linked item is loaded and injected as a Lua Item handle (for example Mesh, Image, or another item subtype).

Use allowedTypes to restrict which item types can be assigned. When omitted, any item type is allowed:

MyBehaviour:addProperty("mesh", Property.Link, nil, {
    allowedTypes = { "Mesh" },
})

Array Properties

See array-types for examples of each array property type. In the inspector, array properties appear as an editable list. Options such as minValue, maxValue, info, and allowedTypes apply the same way they do for scalar properties.

Implicit Properties

In addition to any user-defined properties, each script automatically has access to one implicit property:

• node: This is of type node and provides a reference to the scene graph node to which the script is attached.
  This allows scripts to interact directly with their host node, manipulating fields or responding to changes in the scene graph.

function MyBehaviour:init()
    print("The script is attached to node:", self.node:getDisplayName())
end

It's important to utilize these properties effectively to create flexible and reusable scripts. By leveraging both explicit and implicit properties, scripts can be made more adaptable to various game scenarios and design requirements.