ElementPropertyPool — Custom Entity Properties Reference - RollingQuest Lua Scripting

The ElementPropertyPool class provides read-only access to the custom properties defined on an entity (block, side, item, enemy, ball, decoration). Custom properties are defined in the level editor and allow designers to attach metadata to entities that scripts can read at runtime. Every entity exposes a properties field of this type.

To modify properties at design time (in level data), use ElementPropertiesData instead.

Properties

Property	Type	Read-only	Description
`count`	`integer`	✅	Number of properties in the pool.
`names`	`string[]`	✅	Array of all property names.
`namesArray`	`string[]`	✅	Property names as a native array.

Methods

hasProperty

Checks if a property with the given name exists.

--- @param name string
--- @return boolean
function ElementPropertyPool:hasProperty(name)

getProperty

Returns the property object with metadata.

--- @param name string
--- @return ElementProperty
function ElementPropertyPool:getProperty(name)

getPropertyValue

Returns the current value of a property.

--- @param name string
--- @return DynValue
function ElementPropertyPool:getPropertyValue(name)

Indexer

Direct value access by name:

local value = properties["myProperty"]

ElementProperty

Each property returned by getProperty() has:

Property	Type	Description
`info`	`ElementPropertyInfo`	Metadata about the property definition.
`isHidden`	`boolean`	`true` if hidden from the editor UI.
`type`	`string`	Type name of the property value.
`value`	`DynValue`	Current value of the property.

ElementPropertyInfo

Property	Type	Description
`type`	`string`	Data type (e.g., `"integer"`, `"string"`, `"boolean"`).
`isHidden`	`boolean`	Whether hidden from the editor.
`name`	`string`	Property name.
`description`	`string`	Human-readable description.
`defaultValue`	`DynValue`	Default value for this property.
`enumValues`	`string[]`	Available values if the property is an enum type.

Usage Example

Read custom properties from a block:

function OnBallRoll(self, rollIn, side, ball)
    -- self is a Block
    local props = self.properties

    if props:hasProperty("speed_multiplier") then
        local speed = props:getPropertyValue("speed_multiplier")
        Logger.info("Speed multiplier: " .. tostring(speed))
    end

    -- List all properties
    for _, name in ipairs(props.names) do
        local prop = props:getProperty(name)
        Logger.info("Property: " .. name .. " = " .. tostring(prop.value) .. " (type: " .. prop.type .. ")")
    end
end

Direct indexer access:

function OnBallRoll(self, rollIn, side, ball)
    local damage = self.properties["damage"]
    if damage ~= nil then
        Logger.info("Damage: " .. tostring(damage))
    end
end