====== 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:
<code lua>
event = {
    type = "<type>",
    <type> = true,
    -- additional content
}
</code>

Usually, programs will branch based on the type of event received. You can check for a specific event type by using either
<code lua>
if event.type == "<wanted>" then
    -- ... do stuff
end
</code>
or
<code lua>
if event.<wanted> == true then
    -- ... do stuff
end
</code>
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 [[usage:atlatc:environment#Initialization Code]] is always ''{type="init", init=true}''.

==== int ====
<code lua>
event = {
    type = "int",
    int = true,
    msg = <message>,
    message = <message>, -- For backwards compatibility only!
}
</code>
Fired when an interrupt set by the ''[[usage:atlatc:api#interrupt_time_message|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 ====
<code lua>
event = {
    type = "ext_int",
    ext_int = true,
    message = <message>,
}
</code>
Fired when a node called ''[[usage:atlatc:api#interrupt_pos_pos_message|interrupt_pos]]'' on this node's position. ''<message>'' is the message passed to the function.

==== schedule ====
<code lua>
event = {
    type = "schedule",
    schedule = true,
    msg = <message>,
}
</code>
Fired when an interrupt set by the ''[[usage:atlatc:api#schedule_rwtime_msg|schedule()]]'' (or ''schedule_in()'') function runs out. ''<message>'' is the message passed to the function.

==== digiline ====
<code lua>
event = {
    type = "digiline",
    digiline = true,
    channel = <channel>,
    msg = <message>,
}
</code>
Fired when the component receives a [[usage:mods:digiline|Digiline]] message.

==== punch ====
**Applicable for:** LuaATC Operation Panel
<code lua>
event = {
    type = "punch",
    punch = true,
    name = name of puncher
}
</code>
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
<code lua>
event = {
    type = "train",
    train = true,
    id = <train_id>,
}
</code>
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 (''.'').

==== approach ====
**Applicable for:** LuaATC Rail
<code lua>
event = {
    type = "approach",
    approach = true,
    id = <train_id>,
    has_entered = <boolean>, (latest development version only)
}
</code>
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|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.

=== Approach callback mechanism ===

//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 [[usage:nodes:npr|Point Speed Restriction Rails]] (from ''advtrains_interlocking'') or by [[usage:nodes:stoprail|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:
<code lua>
-- To enable approach callback only in arrow direction
__approach_callback_mode = 1

-- To enable approach callback in both directions
__approach_callback_mode = 2
</code>

The event ''[[#approach|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_speed|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_time_message|interrupt()]]''. Here are things that are safe to run from an approach callback:
    * Accessing and setting global environment
    * ''[[#digiline_send_channel_message|digiline_send(channel, message)]]''
    * ''[[#atc_set_text_inside_text|atc_set_text_inside(text)]]''/''[[#atc_set_text_outside_text|atc_set_text_outside(text)]]''
    * ''[[#atc_set_lzb_tsr_speed|atc_set_lzb_tsr(speed)]]''
    * ''[[#atc_set_ars_disable|atc_set_ars_disable(ars_disable)]]''