1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
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:
|
