Add LuaATC documentation

1 files changed, 187 insertions, 2 deletions

diff --git a/assets/manual2/manual.tex b/assets/manual2/manual.tex
index 3d7502e..6444d23 100644
--- a/assets/manual2/manual.tex
+++ b/assets/manual2/manual.tex
@@ -4,7 +4,7 @@
 \setlength{\parindent}{0pt}
 \usepackage{listings}
 \usepackage{hyperref}
-\usepackage{amsmath,siunitx}
+\usepackage{amsmath,amssymb,siunitx}
 \usepackage[x11names,svgnames]{xcolor}
 \usepackage{tikz}
 \usetikzlibrary{arrows,backgrounds,calc}
@@ -17,6 +17,7 @@
 }
 
 \newcommand{\argname}[1]{$\mathit{\langle}$\textrm{\textmd{\textit{#1}}}$\mathit{\rangle}$}
+\newcommand{\optargname}[1]{$\mathit{[\langle}$\textrm{\textmd{\textit{#1}}}$\mathit{\rangle]}$}
 
 \newcommand{\luatrue}{\texttt{true}}
 \newcommand{\luafalse}{\texttt{false}}
@@ -809,7 +810,191 @@ The signal book at \url{https://www.bahnstatistik.de/Signale_pdf/SB-DBAG.pdf} is
 
 \chapter{LuaATC}\label{s:luaatc}
 
-LuaATC offers the ability to run Lua code. It is provided by the \texttt{advtrains\_luaautomation} mod. The documentation for LuaATC can be found in \texttt{advtrains\_luaautomation/README.md} file, but it may be included here in the future.
+LuaATC (sometimes also called \textit{atlatc} for \textit{Advtrains Lua ATC}) offers the ability to run Lua code. It is provided by the \texttt{advtrains\_luaautomation} mod.
+
+Players need the \texttt{atlatc} privilege to perform any operation with this mod (except punching operation panels to trigger an event). The Lua environment is only sandboxed with Lua's \texttt{pcall} and is therefore not protected against infinite loops or fork bombs. It is therefore advised to grant the privilege with care.
+
+In this chapter, an \textit{active component} is a LuaATC component that can run Lua code, triggered by specific events. A \textit{passive component} cannot perform actions on its own; its state can be read and set by active components or other players.
+
+\section{Environments}
+
+Each active component in LuaATC is assigned to an environment where all relevant information is held. Components in different environments cannot interfere with each other via LuaATC, but can communicate using other methods (e.g. digilines). The separation of LuaATC environments allows multiple systems to run simultaneously and independently without polluting each other's environment.
+
+The following chat commands are available. These commands also require the \texttt{atlatc} privilege.
+
+\begin{ttdescription}
+\item[/env\_create \argname{name}] Create an environment named \argname{name}. Please choose the name wisely, as you can't rename environments without deleting and recreating the environment.
+\item[/env\_setup \argname{name}] Edit the initialization code for the environment named \argname{name}. You can also delete the environment from the editor or re-run the init code.
+\item[/env\_subscribe \argname{name}] Subscribe to the environment named \argname{name}.
+\item[/env\_unsubscribe \argname{name}] Unsubscribe from the environment named \argname{name}.
+\item[/env\_subscriptions \optargname{name}] List your subscriptions or, if \argname{name} is provided, list the players subscribed to the environment named \argname{name}.
+\end{ttdescription}
+
+After subscribing to an environment, you will recieve messages related to the environment.
+
+Each environment can contain some \textit{initialization code} (called \textit{init code} for short). The initialization code is run every time the server starts or when the ``Run InitCode'' button in the init code editor is clicked. Please note that you need to click the button to apply the changes to the init code.
+
+The init code is typically used to add functions shared among LuaATC components.
+
+\section{LuaATC components}
+\begin{description}
+\item[LuaATC track] Tracks that can execute LuaATC code.
+\item[LuaATC operator panel] Simple node that can execute LuaATC code (similar to Luacontrollers in the mesecons modpack).
+\end{description}
+
+\section{Standard Lua variables}
+The following standard Lua libraries are available:
+\begin{itemize} \ttfamily
+\item math
+\item os
+\item string
+\item table
+\end{itemize}
+
+Please note that the libraries mentioned above are still limited to the ones in Minetest's own sandbox. Certain function-specific modifications may exist for safety reasons.
+
+The following standard Lua functions are available:
+\begin{itemize} \ttfamily
+\item assert
+\item error
+\item ipairs
+\item next
+\item pairs
+\item select
+\item tonumber
+\item tostring
+\item type
+\item unpack
+\end{itemize}
+
+It is an error to globally override the provided Lua library functions.
+
+\section{LuaATC conventions}
+\begin{itemize}
+\item \argname{Pos} parameters can be a position vector or the name of an existing passive component.
+\end{itemize}
+
+\section{Environment-specific variables}
+\begin{ttdescription}
+\item[F] Global table shared between all components of the environment. The content of this table is discarded on server shutdown or execution of the init code. Functions are allowed in the table.
+\item[S] Global table persistently shared between all components of the environment. This variable may not contain functions.
+\end{ttdescription}
+
+\section{LuaATC helpers}
+\begin{ttdescription}
+\item[POS(\argname{x},\argname{y},\argname{z})] Shorthand function to create a position vector of the form \texttt{\{x=\argname{x}, y=\argname{y}, z=\argname{z}\}}.
+\end{ttdescription}
+
+\section{Passive components}
+\begin{ttdescription}
+\item[getstate(\argname{pos})] Gets the state of the passive component at \argname{pos}.
+\item[setstate(\argname{pos},\argname{state})] Sets the state of the passive component at \argname{pos} to \argname{state}.
+\item[is\_passive(\argname{pos})] Returns whether a passive component exists at \argname{pos} and whether \argname{pos} is a name of an existing passive component.
+\end{ttdescription}
+
+The primitive red/green light signals can be accessed with this API. The values \texttt{red} and \texttt{green} correspond to the status when the signal shows a red or green light, respectively.
+
+Two-way turnouts with one straight direction can have the \texttt{st} status for the straight direction or the \texttt{cr} direction for the other direction that is not straight.
+
+The Y-shaped and three-way turnouts can have a few states, looking from the convergence point:
+\begin{ttdescription}
+\item[l] The turnout points to the left.
+\item[c] The turnout is straight (three-way turnouts only).
+\item[r] The turnout points to the right.
+\end{ttdescription}
+
+Unprotected full-node mesecon switches can have the states \texttt{on} or \texttt{off}, corresponding to the status of being switched on and off, respectively.
+
+Andrew's crosses are similar to the mesecon switches mentioned above, except the status controls whether the light blinks or is off.
+
+Passive components can be named using the passive component naming tool. Passive component names (as strings) can be used as coordinates, provided that the passive component with the name exists. Please note that the ``Signal Name'' field in the signal formspec is unrelated to the passive component name of the signal.
+
+\section{Interrupts}
+\begin{ttdescription}
+\item[interrupt(\argname{time},\argname{message})] Triggers an \texttt{int} event on this component after \argname{time} seconds with \argname{message} as the message. \argname{Message} can be any Lua data type. This function is not available for the init code.
+\item[interrupt\_safe(\argname{time},\argname{message})] Like \texttt{interrupt}, but does not add an interrupt and returns \luafalse{} when an interrupt of any type is present for this component. This function returns \luafalse{} when the interrupt was successfully added.
+\item[interrupt\_pos(\argname{pos},\argname{message})] Immediately triggers an \texttt{ext\_int} event on the active component at \argname{pos} with \argname{message} passed like with \texttt{interrupt}. Please keep in mind that this function can be a source of a fork bomb.
+\item[clear\_interrupts()] Removes any pending interrupts of this node.
+\end{ttdescription}
+
+\section{External communication}
+\begin{ttdescription}
+\item[digiline\_send(\argname{channel},\argname{message})] Sends \argname{message} to the digiline channel named \argname{channel}. This function is only available for active components.
+\end{ttdescription}
+
+\section{Interlocking}
+The following are available if \texttt{advtrains\_interlocking} is enabled.
+\begin{ttdescription}
+\item[can\_set\_route(\argname{pos},\argname{name})] Returns whether the route named \argname{name} of the signal at \argname{pos} can be set.
+\item[set\_route(\argname{pos},\argname{name})] Sets the route named \argname{name} of the signal at \argname{pos}.
+\item[cancel\_route(\argname{pos})] Cancels the route that is set from the signal at \argname{pos}.
+\item[get\_aspect(\argname{pos})] Returns the signal aspect of the signal at \argname{pos}. Please refer to section \ref{s:sigasp} for the structure of signal aspect tables.
+\end{ttdescription}
+
+\section{Railway time}
+All railway time functions are available in the \texttt{rwt} table.
+\begin{ttdescription}
+\item[schedule(\argname{time},\argname{message})] Triggers a \texttt{schedule} event at \argname{time} with the message \argname{message}. Only one event can be scheduled this way.
+\item[schedule\_in(\argname{time},\argname{message})] Like \texttt{schedule}, but \argname{time} is given as the time until the event is triggered.
+\end{ttdescription}
+
+\section{Train control}
+These functions and variables described in this section are only available to LuaATC tracks. Exceptions are noted. These function, except \texttt{atc\_send\_to\_train}, requires that a reference to the train can be made, i.e. when a train is on (or passing) the track or when execution of the code takes place as part of the approach callback.
+\begin{ttdescription}
+\item[atc\_arrow] Whether the train is driving in the direction of the arrow indicated on the ATC track; \luanil{} when there is no train.
+\item[atc\_id] The ID of the train; \luanil{} if there is no train.
+\item[atc\_reset()] Resets the ATC command of the train; returns false if there is no train.
+\item[atc\_send(\argname{command})] Sends the ATC command \argname{command} to the train and returns true; returns false if there is no train.
+\item[atc\_send\_to\_train(\argname{id},\argname{command})] Sends the ATC command \argname{command} to the train with the ID \argname{id}. This function is not limited to LuaATC tracks.
+\item[atc\_set\_ars\_disable(\argname{bool})] Disables ARS for the train when \argname{bool} is \luatrue{}; enables ARS for the train when \argname{bool} is \luafalse{}.
+\item[atc\_set\_text\_inside(\argname{text})] Sets \argname{text} as the text shown on the inside of the train.
+\item[atc\_set\_text\_outside(\argname{text})] Sets \argname{text} as the text shown on the outside of the train.
+\item[get\_line()] Returns the line name of the train.
+\item[get\_rc()] Returns the routing code of the train.
+\item[set\_line(\argname{text})] Sets \argname{text} as the line name of the train.
+\item[set\_rc(\argname{text})] Sets \argname{text} as the routing code of the train.
+\item[train\_length()] Returns the number of wagons in the train.
+\end{ttdescription}
+
+\subsection{Shunting and freight code}
+Freight codes are delimited with exclamation marks (\texttt{!}).
+\begin{ttdescription}
+\item[set\_autocouple()] Enables autocouple mode for the train.
+\item[unset\_autocouple()] Disables autocouple mode for the train.
+\item[split\_at\_fc(\argname{command},\argname{len})] Like \texttt{split\_at\_index}, but the train is split in a way that all wagons in the first part of the train have an empty freight code or the same freight code. \argname{Len} specifies the maximum length of the first part of the train. The freight code of the wagons of the first part is returned.
+\item[split\_at\_index(\argname{index},\argname{command})] Splits the train at \argname{index}, where all wagons with an index greater than or equal to \argname{index} are in the second train, and sends the ATC command \argname{command} to the second train.
+\item[split\_off\_locomotive(\argname{command},\argname{len})] Like \texttt{split\_at\_fc}, but the train is split in a way that the locomotives at the beginning of the train make up the first part of the train.
+\item[step\_fc()] Steps the freight codes of all wagos forward. The first code is selected if the end of the freight code string is reached, unless the string ends with a question mark (\texttt{?}), in which case the order of the freight code is reversed.
+\end{ttdescription}
+
+\section{Events}
+The event table is passed as the \texttt{event} global variable when an event is triggered. The \texttt{type} field of the event is a string indicating the type of the event, and the field indexed by the event type string includes the \luatrue{} constant. Additional fields may be provided, depending on the event type.
+
+The following events are available in LuaATC:
+\begin{ttdescription}
+\item[approach] Triggered when a train approaches the track. This event can be triggered multiple times for the same train.
+\item[digiline] Like \texttt{int} (see below), but triggered with digiline. The channel and message are included in the \texttt{channel} and \texttt{message} fields, respectively.
+\item[ext\_int] Like \texttt{int} (see below), but triggered when the interrupt is called by a different active component. The message is only included in the \texttt{message} field.
+\item[int] Triggered by a call to \texttt{interrupt}. The message is included in the \texttt{msg} and (supposedly for backward compatibility) \texttt{message} fields.
+\item[punch] Trigged when the LuaATC operator panel is punched.
+\item[schedule] Like \texttt{int}, but triggered by the scheduler instead. The message is included in the \texttt{msg} field.
+\item[train] Triggered when a train drives pass the LuaATC track. The event table contains an \texttt{id} field, which holds the train ID. This event is only available to LuaATC tracks.
+\end{ttdescription}
+
+\subsection{Approach callback}
+This subsection is relevant to the \texttt{approach} event.
+\begin{ttdescription}
+\item[atc\_set\_lzb\_tsr(\argname{speed})] Set the temporary speed restriciton of the train to \argname{speed} at the position of the track. This needs to be called every time the \texttt{approach} callback is triggered.
+\end{ttdescription}
+Approach callbacks are executing during the train step. This may be problematic when proforming actions with side effects on the environment that the train is in, such as switching turnouts or setting routes. It is encouraged to only run things that are necessary and defer everything else to an interrupt or a schedule.
+
+The following operations are safe in the approach callback:
+\begin{itemize}
+\item Anything related only to the LuaATC environment.
+\item Sending information via digilines.
+\item Setting the display text of the train.
+\item Using the functions specific to the \texttt{approach} event.
+\end{itemize}
 
 \chapter{Example setups}\label{s:sexamples}
 This chapter shows some example setups that you can use on your rail lines. These are intended as examples and not standards - it is up to you to develop your own standards.