Advanced Trains

User Tools

Site Tools

You are here: Advanced Trains » User Guide » Lua ATC » Events
usage:atlatc:events

Differences

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

Link to this comparison view

Next revision 		Previous revision
Next revision Both sides next revision
usage:atlatc:events [2020-01-24 10:09]
orwell incomplete! 		usage:atlatc:events [2020-01-28 10:16]
orwell fix it
Line 1: Line 1:
-==== Events ====+====== Events ======
  
-In a LuaAutomation ATC controller, an event has the following format:+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> <code lua>
 event = { event = {
Line 10: Line 18:
 </code> </code>
  
-You can check for a specific event type by using+Usually, programs will branch based on the type of event received. You can check for a specific event type by using either
 <code lua> <code lua>
 if event.type == "<wanted>" then if event.type == "<wanted>" then
Line 22: Line 30:
 end end
 </code> </code>
 +The former allows to check the event type like in mesecons luacontrollers, while the latter is more lua-ish and most commonly used.
  
-=== int ===+===== Event Types ===== 
 + 
 +==== int ====
 <code lua> <code lua>
 event = { event = {
Line 35: Line 46:
 For backwards compatibility reasons, the message is also contained in the ''event.message'' field. For backwards compatibility reasons, the message is also contained in the ''event.message'' field.
  
-=== ext_int ===+==== ext_int ====
 <code lua> <code lua>
 event = { event = {
Line 45: Line 56:
 Fired when a node called ''[[#interrupt_pos_pos_message|interrupt_pos]]'' on this node's position. ''<message>'' is the message passed to the function. Fired when a node called ''[[#interrupt_pos_pos_message|interrupt_pos]]'' on this node's position. ''<message>'' is the message passed to the function.
  
-=== digiline ===+==== digiline ====
 <code lua> <code lua>
 event = { event = {
Line 54: Line 65:
 } }
 </code> </code>
-Fired when the rail receives a [[usage:mods:digiline|Digiline]] message.+Fired when the component receives a [[usage:mods:digiline|Digiline]] message. 
 + 
 +==== 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 from an older Advtrains version, the string may be longer and contain a dot (''.''). 
 + 
 +==== approach ==== 
 +**Applicable for:** LuaATC Rail 
 +<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)]]'' 
usage/atlatc/events.txt · Last modified: 2023-10-29 16:30 by orwell

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki