Advanced Trains

User Tools

Site Tools

You are here: Advanced Trains » User Guide » Advtrains Nodes » LuaATC rail
usage:nodes:atc_rail

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
usage:nodes:atc_rail [2019-07-02 15:06] – added information to wiki article (2/4) 82.67.173.193usage:nodes:atc_rail [2023-12-12 01:41] (current) – name was changed in some version or another blockhead
Line 1: Line 1:
-====== LuaAutomation ATC rail ====== +====== LuaATC rail ====== 
-{{ http://git.bananach.space/advtrains.git/plain/advtrains_train_track/textures/advtrains_dtrack_atc_placer.png?nolink&50 }} +{{ :usage:nodes:advtrains_dtrack_atc_placer.png?80 |}}
-//Do anything you want with ATC rails.// +
- +
----- +
-FIXME This is a draft. Please improve this page by creating relevant pages, adding information and references to internal or external sources. +
----- +
- +
-//Note: this page has been written for Advtrains 2.0.1 TSS and Minetest 5.1.0. Examples and practices described in this page don't take advantage of improvements introduced in later releases.//+
  
 ===== Properties ===== ===== Properties =====
Line 31: Line 24:
   * This node is an [[usage:nodes#component_types|active component]].   * This node is an [[usage:nodes#component_types|active component]].
  
-===== Environments ===== +===== Operation =====
- +
-Each active component is assigned to an environment. This is where all data are held. Components in different environments can't interfere with each other. +
- +
-**Note: the [[#environments|Environments]] and [[#coding_guide|Coding guide]] sections also apply to the [[usage:nodes:operation_panel|LuaAutomation operation panel]].** +
- +
-==== Creating an environment ===== +
-//Main article: [[usage:commands:env_create|/env_create]]// +
- +
- +
-An environment is created by using ''[[usage:commands:env_create|/env_create]]''. We pass to this command the name of the environment to create. While this name may contain whitespaces and symbols, it is highly recommended that you use only uppercase, lowercase letters and underscores. +
- +
-==== Setting up an environment ==== +
-//Main article: [[usage:commands:env_setup|/env_setup]]// +
- +
- +
-You've created your first LuaATC environment! If you execute ''/env_setup <your_env_name>'' in the chat window, you get a formspec like this: +
- +
-{{:usage:nodes:formspec-edit-env.png?nolink&400|}} +
- +
-It allows you to edit your environment initialization code. +
- +
-  * The button "Run InitCode" runs immediately the initialization code. +
-  * The button "Clear S" removes all elements from the ''[[#s|S]]'' table. +
-  * The button "Save" saves the initialization code for the current environment. +
-  * The button "Delete Env." is to delete your environment. This may happen when you accidentally created the environment or you no longer need it. You will be asked to confirm by typing **YES** (in uppercase) into a second formspec. Once it is deleted, all data associated to the environment is lost and can't be recovered. +
-When the init code fails to execute, the ''[[#f|F]]'' table is restored to previous state. +
- +
-More information on how to use that initialization code to do amazing things is given below. +
- +
-===== Coding guide ===== +
-==== Predefined global variables ==== +
- +
-The following global variables are available inside a LuaAutomation ATC rail: +
- +
-=== S === +
- +
-A table shared between all components of an environment. Its contents are persistent over server restarts. Any value is allowed, except functions: +
- +
-**Do not store functions in this table. Calling them from another component may work, but they will be discarded on server shutdown and this may lead to unexpected results.** +
- +
-=== F === +
- +
-A table shared between all components of an environment. Its contents are discarded on server shutdown or when the init code gets re-run. Any value is allowed, **even functions**. +
- +
-This table is not made to store data, but to provide static value and function definitions. This table should be populated by the initialization code. +
- +
-==== Available Lua functions ==== +
- +
-The standard Lua globals are available in the LuaATC environment: +
- +
-  * ''string'' +
-  * ''math'' +
-  * ''table'' +
-  * ''os'' +
- +
-The standard Lua functions are available in the LuaATC environment: +
- +
-  * ''assert'' +
-  * ''error'' +
-  * ''ipairs'' +
-  * ''pairs'' +
-  * ''next'' +
-  * ''select'' +
-  * ''tonumber'' +
-  * ''tostring'' +
-  * ''type'' +
-  * ''unpack'' +
- +
-==== LuaAutomation-specific functions ==== +
- +
-In the following functions, all parameters named ''pos'' designate a position. You can use either: +
- +
-  * a default Minetest position vector (like ''{x=34, y=2, z=-18}'') +
-  * the ''[[#pos_x_y_z|POS(34,2,-18)]]'' shorthand +
-  * a string, the name of a [[#passive_component_naming|passive component]]. +
- +
-=== POS(x, y, z) === +
- +
-A shorthand function to designate a Minetest position vector like ''{x=?, y=?, z=?}''. +
- +
-=== getstate(pos) === +
- +
-Gets the state of a passive component at position ''pos''. The returned states are component-specific, but it is more likely to be a string. +
- +
-=== setstate(pos, new_state) === +
- +
-Sets the state of a passive component at position ''pos'' to the value ''new_state''. The possible states are component-specific, but it is more likely to be a string. +
- +
-=== is_passive(pos) === +
- +
-Checks whether there is a passive component at position ''pos''. If ''pos'' is a string, checks whether the passive component with the specified name exists. +
- +
-=== interrupt(time, message) === +
- +
-Causes the LuaAutomation mod to trigger an ''int'' event (the Advtrains equivalent of [[usage:mods:mesecons|Mesecons]]' ''interrupt'') on this component after the given ''time'', in seconds, with the specified ''message''. ''message'' can be of any Lua data type. +
- +
-This function is not available in init code. +
- +
-=== interrupt_pos(pos, message) === +
- +
-Triggers immediately an ''ext_int'' event on the active component at ''pos'' (can't be a string). ''message'' can be of any Lua data type. +
- +
-**Use with care! This may lead to expotential growth of interrupts.** +
- +
-=== digiline_send(channel, message) === +
- +
-Sends a [[usage:mods:digilines|digiline]] message on the specified ''channel''. +
- +
-This function is not available in init code. +
- +
-==== Interlocking functions ==== +
- +
-Interlocking functions are available when the ''[[usage:mods#advtrains_interlocking|advtrains_interlocking]]'' mod is enabled. +
- +
-=== can_set_route(pos, route_name) === +
- +
-Checks whether it is possible to set the route designated by ''route_name'' from the signal at position ''pos''. +
- +
-It emits a warning and halts execution of Lua code in the following cases: +
- +
-  * the node at specified position is not a signal: +
- +
-> 2019-01-01 15:00:00: WARNING[Server]: [advtrains]LuaAutomation ATC interface rail at (0,0,0) : LUA Error: ...ds/advtrains/advtrains_luaautomation/environment.lua:168: There's no signal at (0,0,0) +
- +
-  * ''pos'' is a string, and the named passive component does not exist: +
- +
-> 2019-01-01 15:00:00: WARNING[Server]: [advtrains]LuaAutomation ATC interface rail at (0,0,0) : LUA Error: .../mods/advtrains/advtrains_luaautomation/pcnaming.lua:22: Invalid position supplied to ???: "invalid_pcnaming" +
- +
-  * the specified route does not exist: +
- +
-> 2019-01-01 15:00:00: WARNING[Server]: [advtrains]LuaAutomation ATC interface rail at (0,0,0) : LUA Error: ...ds/advtrains/advtrains_luaautomation/environment.lua:185: No route called B at (0,0,0) +
- +
-=== set_route(pos, route_name) === +
- +
-Requests the route designated by ''route_name'' from the signal at position ''pos''. Has the same effect as clicking the "Set Route" in the formspec from the designated signal. +
- +
-Same warnings apply as for ''[[#can_set_route_pos_route_name|can_set_route]]''. +
- +
-If the route can't be set, the signal remains red and waits for conflicting problems to be solved. Execution continues **immediately**. +
- +
-=== cancel_route(pos, route_name) === +
- +
-Cancels the route designated by ''route_name'' that is set from the signal at position ''pos''. Has the same effect as clicking the "Cancel Route" in the formspec from the designated signal. +
- +
-Same warnings apply as for ''[[#can_set_route_pos_route_name|can_set_route]]''. +
- +
-If the route has already been canceled, nothing happens. +
- +
-=== get_aspect(pos) === +
- +
-Gets the aspect of the signal at ''pos''. The aspect format is described in the [[usage:nodes:signal#aspect_format|Signal]] page.+
  
-Same warnings apply as for ''[[#can_set_route_pos_route_name|can_set_route]]''.+The LuaATC Rail is an active LuaATC component. It holds Lua code that is executed on specific [[usage:atlatc:events]], and interacts with the world using the [[usage:atlatc:api]].
  
-==== Events ====+Every LuaATC rail must belong to an [[usage:atlatc:environment|Environment]]. You can select the active environment using the dropdown on the top left.
  
-In a LuaAutomation ATC controller, an event has the following format: +//Note: you have to create an environment before LuaATC components can be used. See [[usage:atlatc:environment#Creating an Environment]].//
-<code lua> +
-event = { +
-    type = "<type>", +
-    <type> = true, +
-    -- additional content +
-} +
-</code>+
  
 +===== API =====
  
 +For details how to program LuaATC rails, refer to the [[usage:atlatc:start]] section:
 +{{indexmenu>usage:atlatc}}
  
 ===== Trivia ===== ===== Trivia =====
  
-The LuaAutomation ATC rail has the same texture as the [[usage:nodes:atc_controller|ATC controller rail]], but its functions are different.+The LuaAutomation ATC rail has the same texture as the [[usage:nodes:atc_controller|ATC controller rail]], but its functions are different. A patch has been posted on the [[:usage:mailing_list|Mailing List]], and is awaiting inclusion.
usage/nodes/atc_rail.1562080000.txt.gz · Last modified: by 82.67.173.193