Differences

This shows you the differences between two versions of the page.

--- usage:atlatc:events [2020-01-24 10:09]
orwell incomplete!
+++ usage:atlatc:events [2020-01-24 10:21]
orwell Temp 2
@@ Line 55: / Line 55: @@
 </code>
 Fired when the rail receives a [[usage:mods:digiline|Digiline]] message.
+=== Events ===
+The LuaATC rail currently supports the following events:
+== train ==
+<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 from an older Advtrains version, the string may be longer and contain a dot (''.'').
+== approach ==
+<code lua>
+event = {
+    type = "approach",
+    approach = true,
+    id = <train_id>,
+}
+</code>
+Fired when a train approaches the rail. This event may be generated multiple times for the same train.
+  * **This function is available only in the ''[[http://git.bananach.space/advtrains.git/tree/?h=luaatc-extensions|luaatc-extensions]]'' branch of Advtrains.**
+  * **This function is available only when the [[#approach_callback_mechanism|approach callback mechanism]] is enabled.**
+=== 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 [[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.
+**At the time of writing (2019-12-18), this feature is available only in ''[[http://git.bananach.space/advtrains.git/tree/?h=luaatc-extensions|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:
+<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)]]''

Advanced Trains

User Tools

Site Tools

Differences

Page Tools