Events

LuaATC is event-based. All code is run in an asynchronous manner. There are no blocking operations, all API functions return immediately.

They are not executed in parallel. You do not need to take precautions for thread-safety. Execution of LuaATC code is never interrupted externally.

Every time an event occurs that affects a LuaATC component, the whole code contained in the component is executed. It is the responsibility of the code to branch execution based on the event type.

During execution of LuaATC code, the event table contains information on the event that triggered the execution:

event = {
    type = "<type>",
    <type> = true,
    -- additional content
}

Usually, programs will branch based on the type of event received. You can check for a specific event type by using either

if event.type == "<wanted>" then
    -- ... do stuff
end

or

if event.<wanted> == true then
    -- ... do stuff
end

The former allows to check the event type like in mesecons luacontrollers, while the latter is more lua-ish and most commonly used.

The event table of the Initialization Code is always {type=“init”, init=true}.

event = {
    type = "int",
    int = true,
    msg = <message>,
    message = <message>, -- For backwards compatibility only!
}

Fired when an interrupt set by the interrupt function runs out. <message> is the message passed to the function. For backwards compatibility reasons, the message is also contained in the event.message field.

event = {
    type = "ext_int",
    ext_int = true,
    message = <message>,
}

Fired when a node called interrupt_pos on this node's position. <message> is the message passed to the function.

event = {
    type = "schedule",
    schedule = true,
    msg = <message>,
}

Fired when an interrupt set by the schedule() (or schedule_in()) function runs out. <message> is the message passed to the function.

event = {
    type = "digiline",
    digiline = true,
    channel = <channel>,
    msg = <message>,
}

Fired when the component receives a Digiline message.

Applicable for: LuaATC Operation Panel

event = {
    type = "punch",
    punch = true,
    name = name of puncher
}

Fired when a player punches the operation panel.

Note: Nodes other than the operation panel don't emit the punch event.

Applicable for: LuaATC Rail

event = {
    type = "train",
    train = true,
    id = <train_id>,
}

Fired when a train enters the rail. The field id is the unique ID of the train, which is a 6-digit random numerical string. If the world contains trains created in very early advtrains versions (⇐2018), the string may be longer and contain a dot (.).

Applicable for: LuaATC Rail

event = {
    type = "approach",
    approach = true,
    id = <train_id>,
    has_entered = <boolean>, (latest development version only)
}

Fired when a train approaches the rail. This event may be generated multiple times for the same train.

• This function is available only when the approach callback mechanism is enabled.

`has_entered` is set to true when the tip of the train is already standing on the node, i.e. the “train” event has already fired.

since version 2.3.0

The approach callback mechanism is a new feature that allows LuaAutomation ATC rails to hook into the approach callback system, which is used by the Point Speed Restriction Rails (from advtrains_interlocking) or by Station/Stop Rails (by advtrains_line_automation). Since it is relatively a recent feature, it needs to be explicitly enabled.

To enable the feature, define the following global variable in the local environment of the ATC rail:

-- To enable approach callback only in arrow direction
__approach_callback_mode = 1
 
-- To enable approach callback in both directions
__approach_callback_mode = 2

The event approach will then be generated when a train approaches (which could happen anytime).

You'll have to consider the following when setting up approach callbacks:

• Approach callbacks might be generated multiple trains for a same train. If you call atc_set_lzb_tsr, you'll have to call it on every run of the approach callback.
• A reference to the train will be available while executing this event, so functions such as atc_send and atc_set_text_outside may be used. On subsequent interrupts however, this reference will no longer be available until the train enters the track.
• The approach callbacks are executed synchronously during the train step. This may cause unexpected side effects when performing certain actions (such as switching turnouts, setting signals/routes) from inside such a callback. It is strongly encouraged to only run things that are absolutely necessary at this point in time, and defer anything else to an interrupt(). Here are things that are safe to run from an approach callback:
  • Accessing and setting global environment
  • digiline_send(channel, message)
  • atc_set_text_inside(text)/atc_set_text_outside(text)
  • atc_set_lzb_tsr(speed)
  • atc_set_ars_disable(ars_disable)