1 files changed, 79 insertions, 0 deletions
diff --git a/assets/manual/dev-advtrains.tex b/assets/manual/dev-advtrains.tex
new file mode 100644
index 0000000..6b0c0bb
--- /dev/null
+++ b/assets/manual/dev-advtrains.tex
@@ -0,0 +1,79 @@
+\part{Developer's Manual}
+
+This part is mostly relevant only to those interested in working on internal mechanisms of \advtrains{} or making mods related to \advtrains{}. Please note that this part is still incomplete.
+
+\section{The \texttt{advtrains} table}\label{s:tadvtrains}
+
+\subsection{Railway time}\label{s:tilrwt}
+\advtrains{} depends on Minetest's ``dtime'' for most operations, and may slow itself down when necessary (e.g. in a situation with a lot of lag) to prevent unexpected behavior. As a result, the internal time used by \advtrains{} is not synchronized to real-life time due to lag and server restarts. Railway time was therefore introduced as a method of accurately measuring internal time, as well as to provide a scheduling system. It can, however, be set up to keep in sync with real-life time, depending on the real-life time adaptation mode (\texttt{advtrains\_lines\_rwt\_realtime}):
+\begin{apidoc}{Railway time adaptation mode}
+\item \apienum{independent} Do not adapt to real-life time and instead keep in sync with \advtrains{}' internal dtime.
+\item \apienum{follow\_real} Independent of real-life time, but counts up in real-life time.
+\item \apienum{adapt\_real} Use \texttt{os.time} for RWT.
+\end{apidoc}
+
+Railway time is counted in cycles, minutes, and seconds, roughly corresponding to their real-life counterparts, with cycles roughly corresponding to hours.
+
+Railway time can be represented in three formats:
+\begin{itemize}
+\item As a table with the fields \texttt{c}, \texttt{m}, and \texttt{s}, holding the cycles, minutes, and seconds, respectively.
+\item As a string: The number of cycles, minutes, and seconds, delimited with a semicolon, such as \texttt{245;50;32}. The cycles may be absent, in which case the string is formatted as the number of minutes and seconds delimited with a semicolon, such as \texttt{37;25}. Fields do not have to be padded with zeroes, but the field should not be empty unless it is at the beginning or the end of the string; this criteria allows RWT values such as \texttt{43;3} (equivalent to \texttt{43;03}), \texttt{22;} (equivalent to \texttt{22;00}), \texttt{;10} (equivalent to \texttt{0;10}) and even \texttt{;} (equivalent to \texttt{0;00}).
+\item As a number: the number of seconds since \texttt{0;0;0}.
+\end{itemize}
+
+For a railway time object \texttt{$c$;$m$;$s$}, the following properties are expected to apply:
+\begin{itemize}
+\item $c \in \mathbb{Z}$,
+\item $m \in \mathbb{Z} \cap \left[0,60\right)$, and
+\item $s \in \mathbb{Z} \cap \left[0,60\right)$
+\end{itemize}
+It is an error if at least one of the above properties do not apply.
+
+The following entries are present in \texttt{advtrains.interlocking.rwt}. \var{Time}, \var{t}, \var{interval}, and \var{offset} refer to a railway time object represented in one of the methods described above. \var{Interval} and \var{offset} represent the interval and offset of a repetition, respectively. \var{Cycles}, \var{minutes}, and \var{seconds} should be the value of the \texttt{c}, \texttt{m} and \texttt{s} fields of a railway time table.
+
+\begin{apidoc}{\texttt{advtrains}!\texttt{interlocking.rwt}}
+\item \apifunc{add}{\vari{t},\varii{t}} Returns \( t_1 + t_2 \).
+\item \apifunc{copy}{\var{time}} Returns a copy of \var{time}.
+\item \apifunc{diff}{\vari{t},\varii{t}} Returns \( t_2 - t_1 \) in seconds.
+\item \apifunc{last\_rpt}{\varzero{t},\var{interval},\var{offset}} Returns $t$ in the range \( (t_0-\text{\var{interval}},t_0] \) such that \( t = n \cdot \text{\var{interval}} + \text{\var{offset}} \) for \( n \in \mathbb{Z} \).
+\item \apifunc{new}{\var{cycles},\var{minutes},\var{seconds}} Returns a railway time table.
+\item \apifunc{next\_rpt}{\varzero{t},\var{interval},\var{offset}} Returns $t$ in the range \( [t_0,t_0+\text{\var{interval}}) \) such that \( t = n \cdot \text{\var{interval}} + \text{\var{offset}} \) for \( n \in \mathbb{Z} \).
+\item \apifunc{now}{} Returns a table corresponding to the current railway time.
+\item \apifunc{sub}{\vari{t},\varii{t}} Returns \( t_1 - t_2 \) in seconds.
+\item \apifunc{time\_from\_last\_rpt}{\varzero{t},\var{interval},\var{offset}} Returns $t$ in the range \( [0,\text{\var{interval}}) \) such that \( t_0 - t = n \cdot \text{\var{interval}} + \text{\var{offset}} \) for \( n \in \mathbb{Z} \).
+\item \apifunc{time\_to\_next\_rpt}{\varzero{t},\var{interval},\var{offset}} Returns $t$ in the range \( [0,\text{\var{interval}}) \) such that \( t_0 + t = n \cdot \text{\var{interval}} + \text{\var{offset}} \) for \(n \in \mathbb{Z} \).
+\item \apifunc{to\_table}{\var{time}} Returns a railway time table corresponding to \var{time}.
+\item \apifunc{to\_secs}{\var{time},\ovar{cycles}} Returns the railway time in number representation corresponding to \var{time}. \var{Cycles} is used as the number of cycles, if present.
+\item \apifunc{to\_string}{\var{time},\ovar{no cycle}} Returns a railway time string corresponding to \var{time}. If \var{no cycle} is true, the number of cycles is omitted from the return value.
+\end{apidoc}
+
+\subsection{\texttt{advtrains.speed}}\label{s:tspeed}
+The \texttt{speed} library allows comparison of speed limits, which can be represented with:
+\begin{itemize}
+\item $v \geq 0$, which stands for a speed restriction of $v$.
+\item $-1$ or \luanil, which lifts the speed restriction.
+\end{itemize}
+The use of other values (in particular, \luanan{} and $\pm\infty$) may result in undefined behavior.
+
+Note that the meaning of \luanil{} here differ from the meaning used in signal aspect tables (see section \ref{s:sigasp}): \luanil{} lifts the speed limit instead of keeping it.
+
+For speed limits, it is said that $a < b$ if $a$ is more strict than $b$, and $a = b$ if $a$ and $b$ refer to the same speed limit.
+
+The following entries are present in \texttt{advtrains.speed}:
+
+\begin{apidoc}{\texttt{advtrains}!\texttt{speed}}
+\item \apifunc{lessp}{\var{a},\var{b}} Returns a boolean indicating whether $a < b$.
+\item \apifunc{greaterp}{\var{a},\var{b}} Returns a boolean indicating whether $a > b$.
+\item \apifunc{equalp}{\var{a},\var{b}} Returns a boolean indicating whether $a = b$.
+\item \apifunc{not\_lessp}{\var{a},\var{b}} Returns a boolean indicating whether $a \ge b$.
+\item \apifunc{not\_greaterp}{\var{a},\var{b}} Returns a boolean indicating whether $a \le b$.
+\item \apifunc{not\_equalp}{\var{a},\var{b}} Returns a boolean indicating whether $a \ne b$.
+\item \apifunc{min}{\var{a},\var{b}} Returns the strictest limit of \var{a} and \var{b}.
+\item \apifunc{max}{\var{a},\var{b}} Returns the less strict limit of \var{a} and \var{b}.
+\item \apifunc{set\_restriction}{\var{train},\var{type},\var{val}} Set speed restriction of type \var{type} of \var{train} to \var{val} and update the \texttt{speed\_restriction} field of \var{train} accordingly. \var{Type} defaults to \texttt{main}.
+\item \apifunc{merge\_aspect}{\var{train},\var{asp}} Merge the signal aspect \var{asp} into the speed restriction table of \var{train} and update the \texttt{speed\_restriction} field of \var{train} accordingly.
+\end{apidoc}
+
+%%% Local Variables:
+%%% TeX-master: "a4manual"
+%%% End:
+\ No newline at end of file