Lua Scripting

Several features in the platform evaluate Lua scripts at runtime. Scripts are used to compute entity keys, display labels, virtual property values, and inline action logic. All scripts receive the current entity instance via the self variable.

Scripting Contexts

Feature	Field	Location	Description
Key computation	key_script	On EntityType or RelationshipType	Computes the human-readable key for instances
Label computation	label_script	On EntityType or RelationshipType	Computes the display label for instances
Virtual property	script	On has_virtual_prop edge	Computes a read-only derived value
Action	script	On executable_script	Inline logic executed when the action is triggered

The self Variable

Inside every script, self refers to the current entity instance. The available fields mirror the entity's wire format:

Access	Returns
self.properties["<name>"]	The value of a property
self.properties["<name>"][LangCode.en_US]	A specific locale from a multi-language property
self.id	The entity's id (UUID of this version)
self.root_id	The entity's root_id (stable identity)

Examples

Key Script: Use a Property as the Key

Define a key_script on the entity type so that instances are keyed by a business identifier rather than a UUID:

return self.properties["material_number"]

With this script, a part entity with material_number = "MAT-001" would be addressable as part/MAT-001.

warning

Properties used in a key_script should be marked as unique on the has_prop edge to avoid key collisions. The engine enforces key uniqueness at write time and will reject the operation if a duplicate key is detected.

Key Script: Composite Key

Combine multiple properties into a single key:

return self.properties["country"] .. "_" .. self.properties["city"]

Label Script: Localized Display Name

Use a multi-language property as the display label:

return self.properties["name"][LangCode.en_US]

If the entity has name: { "en_us": "Potato", "de_de": "Kartoffel" }, the @label field will be "Potato".

Label Script: Formatted Label

Combine multiple properties into a formatted label:

return self.properties["name"][LangCode.en_US] .. " (" .. tostring(self.properties["weight"]) .. " kg)"

Result: "Potato (5 kg)".

Virtual Property: Derived Calculation

Compute a value from other properties without storing it:

return tostring(self.properties["weight"] * 2)

See Virtual Properties for how to declare virtual properties on an entity type.

Action Script: Inline Logic

A simple action that returns a string:

return "Action executed for " .. self.properties["name"][LangCode.en_US]

See Actions & Hooks for how to declare and invoke actions.

Best Practices

• Keep scripts simple. Complex business logic should live in external services (via service_function), not in inline Lua scripts.
• Always return a value. Key scripts and label scripts must return a string. Virtual property scripts must return a value matching the declared output type.
• Handle missing values. If a property might be nil, guard against it to avoid runtime errors:

local name = self.properties["name"]
if name then
    return name[LangCode.en_US] or "unnamed"
end
return "unnamed"