Help

RailScript (as of 12.01)

RailScript is RailKernel’s built-in automation language. It reads live railway state, changes supported values, waits for events and starts or queues saved routes without bypassing RailKernel’s routing and safety rules.

What RailScript can do

A RailScript can inspect command stations, feedbacks, accessories, signals, blocks, trains, locomotives, train types, routes, variables, counters, timers and system state. Scripts can make decisions, wait for a condition, repeat work, write to the script log, operate writable attributes and start an existing Route Move. Project scripts and their language are stored with the project.

RailScript menu entries

Settings → RailScripts…: Create, edit, validate, translate, enable, save and manually run project scripts.
Settings → RailScript logging…: Open the dockable chronological log. Every entry includes its timestamp, script name, event type and message.
Settings → RailScript Monitor…: See running, waiting, completed, failed and cancelled scripts; stop or restart an execution and clear finished entries.
Settings → RailScript system…: Inspect current system attributes exposed to scripts.
Settings → RailScript user variables…: Maintain project variables that can be read and, unless marked read-only, changed by scripts.
Settings → RailScript timers / counters…: Maintain reusable project timers and counters.
Preferences → Startup RailScript: Select one enabled project script that starts automatically after the project opens.
RailScript buttons in definition dialogs: Inspect the namespace attributes belonging to the selected object. Writable values can be changed there for a small direct test.

The script editor

Each script has a name, an enabled flag, a language and source text. Validate checks the complete program without running it. Run starts the current source. Stop cancels the current execution. Changing between English, Dutch and German translates RailScript keywords while preserving object names, strings and comments. Tab or Ctrl+Space opens context-sensitive completion for keywords, objects and attributes.

Execution and safety

IF and WHILE evaluate immediately. FOR EACH walks through a snapshot of every object in a collection such as block[] or feedback[]. The loop variable exposes that object’s normal namespace attributes. WHEN waits without blocking RailKernel and resumes when its condition becomes true or its optional UNTIL condition wins. PROMPT pauses only the current script while asking the user for confirmation or a typed value; RailKernel and other scripts continue running. A train’s newFeedback event is consumed by the successful WHEN that reads it and then becomes false again. MOVE delegates to the normal Route Move engine, so its safety rules remain active. RESERVE and RELEASE atomically acquire or release blocks, accessories or routes for a placed train and return TRUE when the requested change succeeds. SWITCH directly operates one decoder address; DCC and the sole connected command station are defaults. RUN starts another project script; RUN THIS restarts the current script and immediately completes the old execution, ignoring all following statements.

Example: departure from a station

This extended example shows a complete departure sequence: detect a train at its platform, stop it, observe a station dwell timer, sound the conductor’s whistle and start a saved departure route. Replace the object names and function number with values from your own project.

-- Departure from the station with a conductor's whistle

WHEN train["Intercity 1200"].currentBlock = "Platform 1"
     AND train["Intercity 1200"].placed
DO
    LOG "Intercity 1200 has arrived at platform 1"

    SET locomotive["NS 1200"].speed = 0

    SET timer["station dwell"].durationMillis = 30000
    SET timer["station dwell"].running = true

    WHEN timer["station dwell"].expired
    DO
        -- Function 3 is assumed to contain the conductor's whistle.
        SET locomotive["NS 1200"].function[3].active = true

        SET timer["whistle"].durationMillis = 1500
        SET timer["whistle"].running = true

        WHEN timer["whistle"].expired
        DO
            SET locomotive["NS 1200"].function[3].active = false

            LOG "Departure signal given"
            MOVE "Intercity 1200" USING "Depart platform 1"
        END
    END
END