User Tools

Site Tools


Sidebar



Minetest Forum
Content Database
Git Repository
Bug Tracker
Website

usage:atlatc:events

This is an old revision of the document!


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.

The ''event'' table

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.

Event Types

init

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

int

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.

ext_int

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.

schedule

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.

digiline

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

Fired when the component receives a Digiline message.

punch

Applicable for: LuaATC Operation Panel

event = {
    type = "punch",
    punch = true,
}

Fired when a player punches the operation panel.

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

train

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 from an older Advtrains version, the string may be longer and contain a dot (.).

approach

Applicable for: LuaATC Rail

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

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

Approach callback mechanism

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.

At the time of writing (2019-12-18), this feature is available only in luaatc-extensions branch of Advtrains. To use this branch, clone the Git repo in the Minetest mods directory and then git checkout luaatc-extensions on the mod directory.

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:
usage/atlatc/events.1580203663.txt.gz · Last modified: 2020-01-28 10:27 by orwell