Lua Integration in RailCOMPLETE
RailCOMPLETE embeds the Lua programming language to enable automation of BIM modeling operations that have not been foreseen in the generic product, and to let users automate object behavior that has not yet been made available in the national DNA by the agent.
Why Lua?
Lua was chosen because it is fast (compiled to bytecode, suitable for real-time property evaluation), open source and free, well documented with a large community, similar to Python and accessible to engineers with scripting experience, and embeddable — designed to be integrated into host applications based on C++.
Where Lua appears in DNA
1. Property formulas
Every custom property in a DNA can have a Lua formula — a small program that collects information from the database and computes the property’s value.
Example: Switch number 6 has code = "6". Its
name property uses the formula "W"..code, producing
the display name W6.
Example: An axle counter’s mileage property uses
a Lua function that finds the closest opposing fouling point and places the
counter 5 m away from it.
Property formulas run automatically whenever the object or its context changes, keeping derived values always up-to-date.
2. Model checks
DNA object types contain special properties called model checks. Each model check is a Lua program that inspects the object’s context (neighboring objects, distances, relations), evaluates the result against the IM’s rules, categorizes its conclusion as OK, Warning, or Error, and displays the conclusion in text and graphics to the user.
Example: An axle counter model check measures the distance to its closest neighbours, compares against the minimum separation rule from the IM’s standards, and displays a green (OK), orange (Warning), or red (Error) indicator.
Model checks run automatically once an object is created or updated, providing continuous real-time validation.
3. Table column programs
The RC Table Editor uses Lua programs for each table column. Each program iterates through a filtered collection (e.g., signals in a specific area, or shunting routes), performs database searches via relations, and formats the text for the corresponding table cell. This enables complex tables like interlocking tables, signal tables, and earthing tables to be generated and updated automatically.
4. Embedded Lua functions in DNA
RC Agents declare reusable Lua functions in DNA, organized by discipline and category. These functions are automatically attached to RC objects at creation as declared in the DNA, locally overridable (users can modify a copy inside a particular object and propagate that change to other relevant objects), and shareable (agents incorporate user-developed functions into the next DNA version).
5. Relation traversal via Lua
Lua code can traverse the database from object to object using relations.
Forward and reverse access is available through the Relations
collection, and direct access by the relation’s Key attribute is also
supported. This returns collections of references that can be iterated,
queried, and used for computations.
User-written Lua scripts
Beyond DNA-embedded automation, users can write their own Lua scripts for ad-hoc tasks: creating, modifying, and deleting objects programmatically; importing from or exporting to external formats; applying batch changes across many objects; and converting data from other tools (e.g., converting an overhead line design from Bentley’s CATDGN into RC electrification objects).
Skilled users write small Lua scripts every day to solve ad-hoc tasks. No script is too small.
The Lua Editor
RC includes a built-in Lua editor (accessible from the Property Manager) that allows users to inspect any property’s Lua formula, edit formulas in place, test and debug them, and copy/paste formulas between properties, between objects, to other RC models, or to Excel spreadsheets.
Key differentiator
The combination of DNA-declared Lua functions and user-written Lua scripts is what makes RailCOMPLETE uniquely flexible:
- Agents encode standard automation in DNA — it works out of the box
- Users can override and extend that automation for project-specific needs
- No software update required — new behavior is added through Lua, not through RC code changes
- Knowledge capture — successful user scripts can be incorporated into the next DNA version by the agent
This means RC can handle unforeseen requirements without costly and slow software development cycles.
← Back to What is DNA?