src/script/common

\documentclass[notitlepage]{article}
\ifdefined\HCode
  \def\pgfsysdriver{pgfsys-dvisvgm4ht.def} % for HTML output
\fi
\usepackage[a4paper,margin=2cm]{geometry}
\usepackage[T1]{fontenc}
\ifx\HCode\undefined
\usepackage{beton}
\usepackage{eulervm}
\fi
\setlength{\parindent}{0pt}
\setlength{\parskip}{1ex}
\usepackage{listings}
\usepackage{hyperref}
\usepackage{amsmath,amssymb,siunitx}
\usepackage[x11names,svgnames]{xcolor}
\usepackage{tikz}
\usetikzlibrary{arrows,backgrounds,calc,patterns,shapes.geometric}

\usepackage{imakeidx}
\makeindex[columns=1,title=Alphabetical Index,intoc]

% Font substitution: taken from https://ctan.org/tex-archive/macros/latex/contrib/beton/beton.pdf
\ifx\HCode\undefined
\AtBeginDocument{
  \DeclareFontShape\encodingdefault{ccr}{bx}{n}{<->sub*cmss/sbc/n}{}
  \DeclareFontShape\encodingdefault{ccr}{bx}{it}{<->sub*cmss/sbc/it}{}
  \DeclareFontShape\encodingdefault{ccr}{bx}{sl}{<->sub*cmss/sbc/sl}{}
  \DeclareFontShape\encodingdefault{ccr}{bx}{sc}{<->sub*cmss/sbc/sc}{}
}
\fi

\lstdefinestyle{luastyle}{
  language=[5.1]Lua,
  basicstyle=\ttfamily,
  columns=spaceflexible,
  tabsize=2
}

\ifdefined\HCode
\newcommand{\var}[1]{$\langle$\texttt{#1}$\rangle$}
\newcommand{\varnth}[2]{\var{#1\HCode{<sub>}#2\HCode{</sub>}}}
\newcommand{\ovar}[1]{$[\langle$\texttt{#1}$\rangle]$}
\else
\newcommand{\var}[1]{$\mathit{\langle}$\textrm{\textmd{\textit{#1}}}$\mathit{\rangle}$}
\newcommand{\varnth}[2]{\var{#1$_{#2}$}}
\newcommand{\ovar}[1]{$\mathit{[\langle}$\textrm{\textmd{\textit{#1}}}$\mathit{\rangle]}$}
\fi

\newcommand{\varzero}[1]{\varnth{#1}{0}}
\newcommand{\vari}[1]{\varnth{#1}{1}}
\newcommand{\varii}[1]{\varnth{#1}{2}}

\def\luatrue{\texttt{true}}
\def\luafalse{\texttt{false}}
\def\luanil{\texttt{nil}}
\def\luanan{\texttt{nan}}
\def\advtrains{\textsc{advtrains}}

\newenvironment{centeredtikzpicture}[1][]{
  \begin{center}
    \begin{tikzpicture}[#1]
    }{
    \end{tikzpicture}
  \end{center}
}

\newenvironment{apidoc}[1]{
  \begin{list}{}{
  \setlength{\labelwidth}{0pt}
  \setlength{\labelsep}{0pt}
  \setlength{\leftmargin}{0pt}
  \setlength{\listparindent}{1em}
}
\index{#1}
\ifdefined\HCode
\providecommand{\apientp}[2]{\HCode{<br/>}##1\HCode{<span style="float:right">}##2\HCode{</span><br/>}}
\else
\providecommand{\apientp}[2]{##1\hfill {##2}\par}
\fi
\providecommand{\apient}[2]{\apientp{##1}{##2}\index{##1}}
\providecommand{\apip}[2]{\apientp{\texttt{##1}}{##2}}
\providecommand{\api}[2]{\apient{\texttt{##1}}{##2}}
\providecommand{\apiasp}[1]{\apientp{##1}{signal aspect}\index{#1!##1}}
\providecommand{\apicmd}[1]{\api{##1}{command}}
\providecommand{\apienum}[1]{\apip{##1}{enumeration}}
\providecommand{\apifield}[1]{\apip{##1}{field}}
\providecommand{\apiitem}[1]{\apient{##1}{item}}
\providecommand{\apivar}[1]{\apip{##1}{variable}\index{#1!\texttt{##1}}}
\providecommand{\apifunc}[2]{\apip{##1(##2)}{function}\index{#1!\texttt{##1}}}
\providecommand{\apilex}[1]{\apip{##1}{lexical syntax}}
\providecommand{\apipat}[1]{\apip{##1}{pattern}}
\providecommand{\apiterm}[1]{\apient{##1}{term}}
\providecommand{\apitrainmode}[1]{\apient{##1}{train mode}}
\providecommand{\apiui}[1]{\apientp{##1}{UI element}}
}{\end{list}}

\tikzset{
  signal/.pic = {
    \draw (0,0) -- (0,0.2) -- (0.15,0.2);
    \draw [fill=#1] (0.15,0.2) circle [radius=0.05];
  },
  tcb/.pic = {
    \draw (0,0) -- (0,0.2);
    \draw [<->] (-0.15,0.2) -- (0.15,0.2);
  },
  Ks signal/.pic = {
    \fill[black] (-1,-1.3) rectangle (1,1.6);
    \fill[gray] (-0.7,1.3) circle [radius=0.1];
    \fill[gray] (0,1) circle [radius=0.2];
    \fill[gray] (-0.4,0.2) circle [radius=0.2];
    \fill[gray] (0.4,0.2) circle [radius=0.2];
    \foreach \x in {-0.3,0,0.3} {
      \fill[gray] (\x,-0.5) circle [radius=0.1];
    }
    \foreach \x in {-0.3,0} {
      \fill[gray] (\x,-0.8) circle [radius=0.1];
    }
  },
  Ks signal Hp 0/.pic = {
    \pic at (0,0) {Ks signal};
    \fill[red] (0,1) circle [radius=0.2];
  },
  Ks signal Hp 0 with Sh 1/.pic = {
    \pic at (0,0) {Ks signal Hp 0};
    \foreach \x/\y in {0/-0.5,-0.3/-0.8} {
      \fill[white] (\x,\y) circle [radius=0.1];
    }
  },
  Ks signal Ks 1/.pic = {
    \pic at (0,0) {Ks signal};
    \fill[green] (-0.4,0.2) circle [radius=0.2];
  },
  Ks signal Ks 2/.pic = {
    \pic at (0,0) {Ks signal};
    \fill[orange] (0.4,0.2) circle [radius=0.2];
  },
  shunt signal/.pic = {
    \fill[black] (-1,0) -- (-1,-1) -- (1,-1) -- (1,0) -- (0.5,0.5) -- (-0.5,0.5) -- cycle;
    \fill[gray] (-0.5,0) circle [radius=0.1];
    \fill[gray] (0.5,0) circle [radius=0.1];
    \fill[gray] (-0.5,-0.7) circle [radius=0.1];
    \fill[gray] (0.2,0) circle [radius=0.1];
  },
  shunt signal Sh 0/.pic = {
    \pic at (0,0) {shunt signal};
    \fill[red] (-0.5,0) circle [radius=0.1];
    \fill[red] (0.5,0) circle [radius=0.1];
  },
  shunt signal Sh 1/.pic = {
    \pic at (0,0) {shunt signal};
    \fill[white] (-0.5,-0.7) circle [radius=0.1];
    \fill[white] (0.2,0) circle [radius=0.1];
  },
  signal sign Zs 3/.pic = {
    \node[fill=black,text=white,regular polygon,regular polygon sides=3,inner sep=0.5ex,shape border rotate=180] at (0,0) {\Huge #1};
  },
  signal sign Zs 10/.pic = {
    \fill[black] (-1,-1) -- (0,0) -- (1,-1) -- (1,4) -- (0,5) -- (-1,4) -- cycle;
    \fill[white] (-0.8,-0.6) -- (0,0.2) -- (0.8,-0.6) -- (0.8,4) -- (0,4.8) -- (-0.8,4) -- cycle;
    \fill[black] (-0.6,-0.2) -- (0,0.4) -- (0.6,-0.2) -- (0.6,4) -- (0,4.6) -- (-0.6,4) -- cycle;
  },
  signal sign Lf 1 and 2/.pic = {
    \draw[fill=orange] (-0.5,-0.75) rectangle (0.5,0.75);
    \node at (0,0) {\Huge #1};
  },
  signal sign Lf 3/.pic = {
    \draw (-0.5,-0.75) rectangle (0.5,0.75);
    \node at (0,0) {\Huge E};
  },
  signal sign Lf 7/.pic = {
    \draw (-0.5,-0.75) rectangle (0.5,0.75);
    \node at (0,0) {\Huge #1};
  },
  signal sign Ra 10/.pic = {
    \draw (-1.5,0) -- (1.5,0) arc [start angle=0, end angle=180, radius=1.5];
    \node [above] at ($(0,0)+(0,2.4em)$) {\large Halt};
    \node [above] at ($(0,0)+(0,1.2em)$) {für};
    \node [above] at (0,0) {Rangierfahrten};
  },
  signal sign PAM/.pic = {
    \draw (-0.5,-0.5) rectangle (0.5,1);
    \node at (0,0) {\huge S};
    \draw [green,->,very thick,line width=2pt] (0,0.4) -- (0,0.8);
  }
}
\ifdefined\HCode
\tikzset{
  pattern or line fill/.style={fill=cyan}
}
\else
\tikzset{
  pattern or line fill/.style={pattern=north west lines,pattern color=gray}
}
\fi

\title{The \advtrains{} mod for Minetest}
\author{}

\begin{document}

\ifx\HCode\undefined
\thispagestyle{empty}
\begin{tikzpicture}[remember picture,overlay]
  \newcommand{\HUGE}[1]{\scalebox{2}{\Huge #1}}
  \fill[Turquoise] (current page.south west) rectangle (current page.north east);
  \node [below,inner sep=0,outer sep=0,name=coverimage] at (current page.north) {\includegraphics[width=2\paperwidth]{../../screenshot.png}};
  \draw ($0.5*(coverimage.south)+0.5*(current page.south)$)
  +(0,0.5) node [above] {\HUGE{Advanced Trains}}
  +(0,-0.5) node [below] {\HUGE{for Minetest}};
\end{tikzpicture}
\fi

\newpage
\maketitle
\tableofcontents

\newpage
\section*{Introduction}
\addcontentsline{toc}{section}{Introduction}
\advtrains{} is a mod with the goal of introducing realistic trains and rail equipments. It also has features allowing automated trains on a large scale, including interlocking and a few methods of scripting.

This manual is written for the specific version of \advtrains{} that the corresponding \LaTeX{} source is distributed with. It is divided into two parts, where the first part mainly documents the various features of \advtrains, and the second part focuses on the internals of \advtrains.

\subsection*{Acknowledgments}

A notable portion of the manual is influenced by various other guides and manuals for \advtrains. In particular:
\begin{itemize}
\item The format of the API documentation is influenced by R$^7$RS.
\item Section \ref{s:interlocking} is written with reference to orwell's interlocking guide and Blockhead's video explaining the three-station setup. The links to both sources can be found in that section.
\item Section \ref{s:luaatc} is a reformatted and restructured version of the LuaATC documentation, written by orwell and Maverick2797.
\item Section \ref{s:tilrwt} is a modified version of the railway time API documentation written by orwell. Part of the section is also taken from \texttt{advtrains\_line\_automation/railwaytime.lua}
\end{itemize}

\subsection*{Conventions}
\begin{itemize}
\item Unless otherwise specified, the unit of length is meter (or, more technically, nodes).
\item Unless otherwise specified, the unit of speed is meter per second.
\item Unless otherwise specified, the unit of acceleration is meter per second squared.
\item The \tikz \pic at (0,0) {tcb}; symbol stands for a TCB assigned to the track.
\item The \tikz \pic (0,0) {signal=red}; symbol stands for a TCB assigned to the track with a signal assigned to the TCB side opposite of that of the direction in which the TCB is facing (here: the signal is assigned to the left side of the TCB).
\item Arguments to functions and ATC commands are delimited using angle brackets \var{like this}.
\item Argument names are generally lowercase, but the first letter may be capitalized.
\item Lua string constants are written without quotation marks when the content does not resemble any numeric or symbolic constant and when used as enumerators or table indices.
\item Like in other parts of \advtrains, Lua code is indented with tabs.
\item An error situation that may or may not be reported are referred to as \textit{an error}. An error situation that is always reported is one where \textit{an error is signaled}.
\item Unless otherwise specified, the return value of any Lua API function is undefined.
\item The action of left-clicking a node with a trackworker is called \textit{rotation}. The action of right-clicking a node with a trackworker is called \textit{adjustment}.
\end{itemize}

\newpage
\part{User Guide}

\section{Tracks}

\subsection{Angles}

Unlike regular carts in Minetest, tracks can connect in 16 cardinal directions instead of four:

\begin{centeredtikzpicture}
  \draw[step=1,gray,very thin] (0,0) grid (5,5);
  \def\dirs{
    0/1,1/2,1/1,2/1,1/0,2/-1,1/-1,1/-2,
    0/-1,-1/-2,-1/-1,-2/-1,-1/0,-2/1,-1/1,-1/2
  }
  \foreach \dx/\dy in \dirs {
    \draw[pattern or line fill,shift={(\dx,\dy)}] (2,2) rectangle +(1,1);
  }
  \foreach \dx/\dy in \dirs {
    \draw[very thick,->] (2.5,2.5) -- +(\dx,\dy);
  }
  \node[circle,draw=black,fill=white,text=black] at (2.5,2.5) {A};
\end{centeredtikzpicture}

In the figure above, the filled squares show possible connections from the track at A.

Tracks that are not axis-aligned are sometimes referred to as 30\textdegree{} (although it is technically $\arcsin 0.5$) or 45\textdegree{} tracks. However, the specific meaning of the terms may depend on the context of the discussion.

The use of 16 cardinal directions instead of four allows the creation of curves that are more realistic than their counterparts made using minecart rails. A typical 90\textdegree{} curve looks like this:

\begin{centeredtikzpicture}
  \draw[step=1,gray,very thin] (0,0) grid (6,6);
  \foreach \x/\y in {0/0,0/1,1/3,2/4,4/5,5/5} {
    \draw[pattern or line fill] (\x,\y) rectangle +(1,1);
  }
  \draw[<->,very thick] (0.5,0.5) -- ++(0,1) -- ++(1,2) -- ++(1,1) -- ++(2,1) -- ++(1,0);
\end{centeredtikzpicture}

However, this is still notably smaller than in real life. For comparison, the smallest curve for the H0 model (1:87) has a radius of 360mm, which is 31.32m when scaled to real life.

\subsection{Track placement}

The usual way of placing a track is with a ``track placer'', a tool that places the tracks and, in many cases, automatically adjusts them to connect to nearby tracks.

You can get track placers from the creative inventory or by crafting. Please refer to the crafting guide for the recipe.

To place the track, simply right click the node to place the track on with the trace placer. To place slopes, face the upper end of the slope and click on the $n$th node before the upper end of the slope for a slope with an incline of $1/n$. For example, if you want to build a slope with an incline of 50\% (the slope marked gray), you would look at node A and click on node B while standing in such a way that the direction you are looking at is also the direction in which the slope goes up (e.g. at node P):
\begin{centeredtikzpicture}
  \draw[step=1,gray!50!white,thin] (-2,0) grid (3,2);
  \draw[fill=black!40!gray] (0,1) -- ++(2,0) -- ++(0,1) -- cycle;
  \foreach \x/\y/\l in {0/0/B,1/0/,2/1/A}{
    \draw[fill=cyan] (\x,\y) rectangle +(1,1);
    \node[text=black,shift={(0.5,0.5)}] at (\x,\y) {\l};
  }
  \node[text=black] at (-1.5,1.5) {P};
\end{centeredtikzpicture}

Please note that, in the figure above, the three colored nodes must already be placed.

\subsection{Track adjustment}
You can use a trackworker to make certain adjustments to tracks. Specifically,
\begin{itemize}
\item Left-clicking on a track with the trackworker toggles between the variants of the particular track, if any.
\item Right-clicking on a track with the trackworker rotates the track counterclockwise.
\end{itemize}

Typical examples of ``variants'' of tracks include turnouts and curves. Please note that Y-turnouts and different types of crossings have their own variants. These variants are described below. Additionally, special tracks (ATC track, station tracks, etc.) are usually only straight, and certain mods that provide additional tracks (e.g. linetrack) may not provide a full set of tracks available in the official track set.

\subsection{Turnouts}
Turnouts are tracks that connect tracks from more than one direction. Some examples of turnouts are shown below.

\begin{centeredtikzpicture}
  \draw[step=1,gray,thin,shift={(-0.5,-0.5)}] (0,0) grid (10,4);
  \def\turnouts{
    1/{0/-1, 0/1, -1/2},
    2/{0/-1, 0/1, 1/2},
    5/{0/-1, -1/2, 1/2},
    8/{0/-1, 0/1, -1/2, 1/2},
  }
  \foreach \base/\dirs in \turnouts {
    \draw[->, very thick] (\base,1) -- +(0,-1);
    \foreach \dx/\dy in \dirs {
      \draw[->, very thick] (\base,1) -- +(\dx,\dy);
    }
  }
\end{centeredtikzpicture}

The figure above aligns the tracks in a way that they always merge into the track that connects to the south. This is mainly done for intuitivity - you can rotate the turnouts freely in any of the 16 directions.

\subsection{Crossings}\label{s:xings}
There are a few crossing nodes that allow you to create intersections:
\begin{itemize}
\item Perpendicular crossings: intersections where two tracks are perpendicular to each other
\item $90^\circ+x$ crossings: intersections where only one of the two tracks is axis-aligned
\item diagonal crossings: other crossings that do not fit in the two categories mentioned above
\end{itemize}

Each type of crossing has its own track placer. The trackworker can not be used to switch between the different types of crossing tracks.

The figure below shows a few examples of crossings that are available.
\begin{centeredtikzpicture}[scale=0.9]
  \draw[gray,thin, shift={(-0.5,-0.5)}] (0,0) grid (11,11);
  \def\xings{
    2/2/1/2/2/1,
    2/8/2/1/1/-2,
    8/1/2/1/1/0,
    8/5/2/1/2/-1,
    8/9/2/1/1/-1
  }
  \foreach \x/\y/\ax/\ay/\bx/\by in \xings {
    \foreach \dx/\dy in {\ax/\ay,\bx/\by} {
      \draw [<->, very thick] ($(\x,\y)-(\dx,\dy)$) -- +($2*(\dx,\dy)$);
    }
  }
\end{centeredtikzpicture}

It is also possible to create track layouts without using crossings. Some examples are shown below.

\begin{centeredtikzpicture}[scale=0.9]
  \draw[gray,thin, shift={(-0.5,-0.5)}] (0,0) grid (12,4);
  \def\lines{
    0/0/3/3,0/3/3/0,
    5/0/11/3,6/3/9/0
  }
  \def\squares{
    0/0,1/1,2/2,3/3,0/3,1/2,2/1,3/0,
    5/0,7/1,9/2,11/3,6/3,7/2,8/1,9/0
  }
  \foreach \x/\y in \squares {
    \draw [pattern or line fill,shift={(-0.5,-0.5)}] (\x,\y) rectangle +(1,1);
  }
  \foreach \ax/\ay/\bx/\by in \lines {
    \draw [<->, very thick] (\ax,\ay) -- (\bx,\by);
  }
\end{centeredtikzpicture}

Exercise: Build a T junction. You will need this later in section \ref{s:iljunctions}. You can also look at the scheme in that section if you need a hint.

\subsection{Special tracks}

\advtrains{} also have a few special tracks, some of which are explain in their own sections.

\begin{apidoc}{Special tracks}
\item \apiitem{ATC track} Track that sends ATC commands to a train (see section \ref{s:atc} for more information)
\item \apiitem{Loading track} Track that makes a train load as many items as possible from a chest below the track if the train is moving in the direction indicated by the arrow on the track at a speed lower than 2m/s.
\item \apiitem{Unloading track} Track that makes a train unload as many items as possible into a chest below the track if the train is moving in the direction indicated by the arrow on the track at a speed lower than 2m/s.
\item \apiitem{Temporary speed restriction rail} Track that forces a train to pass with an arbitrary speed limit.
\item \apiitem{Station track} Track that makes trains temporarily stop at a given point (see section \ref{s:stoprail} for more information)
\item \apiitem{LuaATC track} Track that can be programmed in Lua (see section \ref{s:luaatc} for more information).
\end{apidoc}

\section{Train controls}\label{s:controls}
To get on a train, click on the train while its doors are open, or click on the train while holding the Sneak key. You need to be in the driver stand in order to control the train.

Train movement currently depends on two factors: the lever of the train and the percentage of locomotives in the train. Details on train physics can be found in section \ref{s:physics}.

Unlike in real life, levers are not moved continuously. Instead, there are a few lever ``positions'' that are recognized by \advtrains{}:

\begin{itemize}
\item The lever 0 triggers the emergency brake. It can be triggered by the ATC \texttt{BB} command (see section \ref{s:atc}).
\item The lever 1 triggers the default brake.
\item The lever 2 (``roll'') slows down a train as if it was on a horizontal surface without any traction
\item The lever 3 does not affect the speed of the train.
\item The lever 4 accelerates the train.
\end{itemize}

\subsection{Train formspec}\label{s:trainformspec}
If you have access to the driver stand of the wagon, right-clicking the train will open up a formspec will a few buttons, depending on the status of the train:
\begin{apidoc}{Train formspec}
\item \apiui{Passenger area} Move to the passenger area.
\item \apiui{Driver stand} Move to the driver stand.
\item \apiui{Onboard computer} Open the onboard computer.
\item \apiui{Wagon properties} Allow setting wagon properties.
\item \apiui{Get off} Get off the train.
\item \apiui{(Doors closed)} Get off the train by right-clicking the train while holding the Sneak key.
\end{apidoc}

\subsection{Onboard computer}\label{s:bordcom}
The onboard computer allow setting certain properties of the train. Feel free to explore it yourself. A few fields are explained here in detail:
\begin{apidoc}{Onboard computer}
\item \apiui{Line number} The line name of the train. Despite the label, you can set this to anything. This field is mainly used for interlocking.
\item \apiui{Routing code} The routing code of the train. This field is mainly used for interlocking. Unlike line numbers, you can specify multiple entries in this field, separated by spaces.
\item \apiui{Train overview} This section is only shown when the train is not moving. It allows you to couple and decouple wagons from the train.
\end{apidoc}

\subsection{Wagon properties formspec}
The ``wagon properties'' formspec allows setting properties that apply to each wagon. The following fields are present in the formspec:
\begin{apidoc}{Wagon properties}
\item \apiui{Whitelist} (``Allow these players to access your wagon'') A list of other player that may access the inventory and the driver stand of the wagon.
\item \apiui{Wagon road number} An identifier that is applied to the wagon. It is mainly intended to be a human-readable alternative to wagon IDs.
\item \apiui{Freight code} The freight code of the wagon. Please refer to section \ref{s:freightcode} for more information.
\end{apidoc}

\subsection{HUD}\label{s:trainhud}

The HUD is a visual representation of certain information about the train. An overview of the HUD is as follows:

\begin{centeredtikzpicture}[xscale=0.025,yscale=-0.025]
  \footnotesize
  \newcommand{\rect}[3]{
    \draw[#1] #2 rectangle #3;
  }
  \newcommand{\frect}[3]{
    \rect{#1,fill=#1}{#2}{#3}
  }
  \newcommand{\sevenseg}[5]{
    \def\x{#2}
    \def\y{#3}
    \def\w{#4}
    \def\h{#5}
    \def\segs{
      {(\h,0)}/\w/\h,
      {(0,\h)}/\h/\w,
      {($(\w,0)+(\h,\h)$)}/\h/\w,
      {($(0,\w)+(\h,\h)$)}/\w/\h,
      {($(0,\w)+2*(0,\h)$)}/\h/\w,
      {($(\w,\w)+\h*(1,2)$)}/\h/\w,
      {($2*(0,\w)+\h*(1,2)$)}/\w/\h
    }
    \foreach \off/\sx/\sy in \segs {
      \frect{#1}{(\x,\y) ++\off}{++(\sx,\sy)};
    }
  }
  \newcommand{\filledcirclelabel}[2]{
    \node[circle,text=black,fill=white,draw=black] at #1 {#2};
  }
  \newcommand{\plainlabel}[2]{
    \node[text=black] at #1 {#2};
  }
  \frect{black}{(0,0)}{+(440,110)}
  \frect{cyan}{(10,10)}{++(30,30)}
  \plainlabel{(25,25)}{1}
  \frect{red}{(50,10)}{++(30,30)}
  \plainlabel{(65,25)}{2}
  \frect{orange}{(90,10)}{++(30,30)}
  \plainlabel{(105,25)}{3}
  \frect{orange}{(130,10)}{++(30,5)}
  \frect{orange}{(130,35)}{++(30,5)}
  \foreach \i in {130,141,152}{\sevenseg{orange}{\i}{18}{4}{2}}
  \filledcirclelabel{(145,25)}{4}
  \frect{white}{(187,10)}{++(26,30)}
  \frect{black}{(189,12)}{++(22,11)}
  \frect{white}{(170,10)}{++(15,30)}
  \frect{black}{(172,12)}{++(11,11)}
  \frect{white}{(215,10)}{++(15,30)}
  \frect{black}{(217,12)}{++(11,11)}
  \filledcirclelabel{(200,25)}{5}
  \draw[cyan,fill=cyan] (245,10)++(0,15) -- +(15,0) -- +(7.5,-15);
  \draw[orange,fill=orange] (245,85) -- +(15,0) -- +(7.5,15);
  \frect{DarkSlateGray}{(250,35)}{++(5,40)}
  \filledcirclelabel{(252.5,55)}{6}
  \frect{cyan}{(275,10)}{++(5,18)}
  \frect{white}{(275,28)}{++(5,18)}
  \frect{orange}{(275,46)}{++(5,36)}
  \frect{red}{(275,82)}{++(5,18)}
  \frect{DarkSlateGray}{(292,16)}{++(6,78)}
  \filledcirclelabel{(295,55)}{7}
  \foreach \x in {10,21,...,120}{\frect{white}{(\x,65)}{++(8,20)}}
  \filledcirclelabel{(69,75)}{8}
  \foreach \x in {197,208,219}{\frect{DarkSlateGray}{(\x,65)}{++(8,20)}}
  \filledcirclelabel{(212,75)}{9}
  \frect{red}{(183,60)}{++(3,30)}
  \filledcirclelabel{(184.5,75)}{10}
  \draw[red,fill=red] (133,50) -- +(15,0) -- +(7.5,15);
  \plainlabel{(140.5,54)}{4}
  \draw[cyan,fill=cyan] (89,100) -- +(15,0) -- +(7.5,-15);
  \plainlabel{(96.5,96)}{11}
  \sevenseg{red}{320}{10}{30}{10}
  \sevenseg{red}{380}{10}{30}{10}
  \filledcirclelabel{(375,55)}{8}
\end{centeredtikzpicture}

\begin{enumerate}
\item ATC indicator
\item LZB indicator
\item Shunt indicator
\item Aspect of and distance to the upcoming LZB entry (usually a signal)
\item Door indicator
\item Reverser
\item Lever
\item Speed indicator
\item Max speed indicator
\item Speed restriction indicator
\item ATC target speed indicator
\end{enumerate}

\subsection{Keybindings}\label{s:keybindings}
Hitting any movement key as a passenger will drop you off the train when a door is open or when the wagon has no doors. Alternatively, the Sneak+Aux1 keystroke will drop you off a train, regardless of whether doors are open.

The following keybindings are available to the driver, regardless of the mode of the train.
\begin{itemize}
\item Sneak+Forward: Set the ATC target speed to the maximum speed
\item Sneak+Backward: Set the ATC target speed to 0
\item Sneak+Left: Set the ATC target speed to 4
\item Sneak+Right: Set the ATC target speed to 8
\item Sneak+Jump: Open the onboard computer
\item Jump+Backward: Emergency brake
\end{itemize}

\subsection{Manual control}\label{s:manual-control}
Manual control makes the user in charge controlling the train. The following keybindings are available when manually controlling the train:
\begin{itemize}
\item Forward: Accelerate.
\item Backward: Roll when the train is moving, reverse otherwise.
\item Left: Open/Close the door on the left side and, if the door on the right side is open, close the door on the right side.
\item Right: Open/Close the door on the right side and, if the door on the left side is open, close the door on the left side.
\item Jump: Brake or, in ATC mode, switch to manual control
\end{itemize}

These keybindings (except for the jump key) do not work in ATC mode. The lever is moved to a specific level only as long as the corresponding key is pressed.

\subsection{ATC}\label{s:atc}

ATC is a method of automatically controlling trains. Certain modes can be directly activated using specific keybindings, but more common ways of using ATC include:
\begin{itemize}
\item Directly using ATC tracks,
\item Using station/stop tracks, and
\item Using LuaATC
\end{itemize}

ATC tracks can be used to send custom ATC commands to the train passing the track. The ATC commands available are listed below:

\begin{apidoc}{ATC}
\item \apilex{A0} Disables ARS.
\item \apilex{A1} Enables ARS.
\item \apilex{BB} Actives the emergency brake until the train stops.
\item \apilex{B\var{speed}} Brakes until \var{speed} is reached.
\item \apilex{Cpl} Enables autocouple mode.
\item \apilex{D\var{time}} Waits for \var{time} seconds before continuing execution.
\item \apilex{I\var{condition}\var{consequent};} Executes \var{consequent} if \var{condition} is met.
\item \apilex{I\var{condition}\var{consequent}E\var{alternate};} Executes \var{consequent} if \var{condition} is met, \var{alternate} otherwise.
\item \apilex{K} Kicks all passengers (players not driving the train) off the train only when the train is stopped and its doors are open.
\item \apilex{OC} Closes doors on both sides.
\item \apilex{OL} Opens doors on the left side and closes doors on the right side (if open).
\item \apilex{OR} Opens doors on the right side and closes doors on the left side (if open).
\item \apilex{R} Reverses the train only when the train is not moving.
\item \apilex{S\var{speed}} Accelerates to \var{speed} or roll if the train is faster then \var{speed}.
\item \apilex{W} Waits until the target set by \texttt{S} or \texttt{B} command is reached.
\end{apidoc}

For the \texttt{B}, \texttt{D}, and \texttt{S} commands, the argument should be written immediately after the command, without any whitespace.

The following \var{condition}s are available for the ATC \texttt{I} command:

\begin{apidoc}{ATC conditions}
\item \apilex{+} True when the train is driving in the same direction as the arrows on the ATC rail.
\item \apilex{-} True when the train is driving in the opposite direction of the arrow on the ATC rail.
\item \apilex{<\var{speed}} True when the train is slower than \var{speed}.
\item \apilex{>\var{speed}} True when the train is faster than \var{speed}.
\item \apilex{<=\var{speed}} True when the train is not faster than \var{speed}.
\item \apilex{>=\var{speed}} True when the train is not slower than \var{speed}.
\end{apidoc}

\subsection{LZB}\label{s:lzb}

\fbox{\parbox{\textwidth}{The explanation of LZB is specific to \advtrains. Please refer to other sources, such as Wikipedia, for information on the use of LZB in real-life rail lines.}}

In \advtrains, LZB is a system that makes sure that trains realistically brake to the desired speed, overriding ATC and manual control if necessary.

LZB speed targets are temporary and associated to a specific point - it only makes sure that the front part of the train passes that point at the desired speed. For example, a point speed restriction rail with a speed target of 3 will only make sure that the front of the train passes the PSR rail at the speed of 3, but the train is allowed to accelerate up to the speed limit (or the maximum speed, if there is no speed limit) after the head of the train passes the PSR rail.

\subsection{ARS}
Signals using ARS will select the appropriate route for the train only if ARS is also enabled on the train. This mode is enabled by default. This feature is mainly used by station tracks, which disables ARS for the train when it arrives at the station and re-enables ARS before departure.

\subsection{Autocouple mode}
If enabled, the train automatically couples with any train it collides with. This mode is disabled by default.

Historically, a train would also automatically couple with any train is collides with. This behavior was changed with the introduction of the autocouple mode.

\subsection{Shunt mode}
This mode restricts the velocity of the train to 6m/s and, allows a train to proceed past a signal at danger if the signal allows the train to proceed in shunt mode. It is disabled by default and automatically enabled when the train reverses in an interlocked section.

\section{Interlocking and line automation}\label{s:interlocking}

Interlocking is a set of equipments employed to prevent train collisions while allowing trains to go to their destinations. This chapter will explain some basic concepts and includes a task at the end that you can try to do yourself.

Please note that this chapter is also intended to be used as a reference, so some things may be explained in a way that is not easy to understand at first. If that is the case, the following links may be helpful, albeit possibly outdated:
\begin{itemize}
\item The online interlocking guide: \url{https://advtrains.de/interlocking}
\item Blockhead's Youtube video showing a simple three-station setup (see section \ref{s:ilbasicsetup}): \url{https://www.youtube.com/watch?v=ylG1vHj4zjg}
\end{itemize}

It is also recommended for new players to read through the entire section (or at least the first few subsections) to understand various concepts of the interlocking system before following the instructions in the subsections.

\subsection{TCBs}\label{s:iltcbs}
Track circuit breaks (TCBs) are nodes that can be assigned to two-way tracks and indicate the limits of track sections. TCBs have two sides - each corresponding to a direction of the track that the TCB is assigned to - that can be assigned to two track sections.

To assign a TCB to a track:
\begin{itemize}
\item Place a TCB, ideally adjacent to the track it will be assigned to.
\item Right-click the TCB.
\item You will be told in the chat to punch a track to assign the TCB to. Punch the track to assign the TCB to - this track will, in later subsections, be the boundary of track sections.
\item A TCB marker showing the two sides (A and B) will appear on the track you have assigned the TCB to. This will be explained in further detail below.
\end{itemize}

After assigning the TCB, you can right click it to open the TCB formspec. This will be used in the following sections. Please note that the TCB formspec has a section for side A and one for side B - when following the instructions in the following subsections, make sure you click the button for the right TCB side.

The two sides of the TCB are assigned based on the orientation of the tracks. In particular, straight tracks with different orientations can still appear visually the same. For this reason, most graphs in the rest of this chapter will use cardinal directions instead of actual TCB sides, or omit TCB sides if these are irrelevant.

For new players, it is recommended to set up all TCBs before creating new track sections.

\subsection{Track sections}\label{s:ilts}

In terms of interlocking, track sections are segments of tracks that can be occupied by a train or reserved for a train to pass. The following graph shows TCBs and sections along a line segment. For simplicity, letters are used instead of actual coordinates and IDs.

\begin{centeredtikzpicture}
  \draw[<->] (-2,0) node [left] {W} -- (7,0) node [right] {E};
  % first TCB
  \draw (0,-0.5) -- ++(0,2) node [above] {TCB assigned to $P$};
  \draw (0,1) node [left] {Section $a$} node [right] {Section $b$};
  \draw[->,Red] (0,0.5) -- +(-1.5,0) node [left] {A};
  \draw[->,ForestGreen] (0,0.5) -- +(1.5,0) node [right] {B};
  %second TCB
  \draw (5,-0.5) -- ++(0,2) node [above] {TCB assigned to $Q$};
  \draw (5,1) node [left] {Section $b$} node [right] {EOI};
  \draw[->,Red] (5,0.5) -- +(-1.5,0) node [left] {A};
  \draw[->,ForestGreen] (5,0.5) -- +(1.5,0) node [right] {B};
\end{centeredtikzpicture}

Section $a$ begins at the side A of $P$ (sometimes written as $P/\mathrm{A}$) and extends to the west beyond the graph. Section $b$ is limited by $P/\mathrm{B}$ and $Q/\mathrm{A}$, effectively spanning the line segment $\overline{PQ}$. $Q/\mathrm{B}$ is not part of any track section and is therefore known as \textit{end of interlocking} or \textit{EOI}, as the track beyond it is not part of the interlocking system.

The graph below shows a track segment where $P$, $Q$, and $R$ form a section around the turnout $T$. Notice that a train entering from $Q$ cannot directly reach $R$ without reversing (or vice versa),  while a train entering from $P$ can reach both $Q$ and $R$.

\begin{centeredtikzpicture}
  \draw[<->] (0,0) -- (7,0);
  \draw[->] (3,0) .. controls(4,0) .. (5,1) -- (7,3);
  \foreach \x/\y/\c in {1/0/$P$,6/0/$Q$,6/2/$R$,3/0/$T$} {
    \node[circle,fill=white,draw=black] at (\x,\y) {\c};
  }
  \node at (-0.5,0) {W};
  \node at (7.5,0) {E};
\end{centeredtikzpicture}

To create a track section, click on ``Create new track section'' in the TCB formspec. This should create a new track section and add the TCB side to the track section. Other track sides that face the track side you created the TCB with will also be added to the track section. In the graph above, creating a track section at the west side of $Q$ will automatically add the south-west side of $R$ and the east side of $P$ to the track section.

After the track section is created, you can click on ``Show track section'' to open the track section formspec, or ``Remove from section'' to move the TCB side from the track section.

In some cases, such as crossings, you may need to manually add TCB sides to a track section. This can only be done by creating a track section for the TCB side and then merging the two track sections.

To merge two track sections:
\begin{itemize}
\item Click ``Join into other section'' in the formspec of the section that needs to be merged.
\item Click ``Join with \var{section}'' in the formspec of the section to merge the other section into, where \var{section} is the ID of the section that needs to be merged.
\end{itemize}
To abort the procedure above, click on the ``X'' button on the right.

The track section formspec also has a button labeled ``Dissolve section''. Clicking on that button will remove the track section entirely.

In most cases, the two sides of the TCB should belong to different sections, or at least one side belongs to EOI. If this is not the case (i.e., both sides of the TCB belong to the same track section), it likely means that the presence of the TCB is irrelevant for the track section. With the current implementation of the section occupation system, this is problematic as the section behind the train is always freed, even when the train passes a TCB with both sides belonging to the same section. If you run into such a situation, dissolve the track section and make sure that every TCB is assigned to a track and delimits the track sections that the two sides of the TCB are assigned to, and then create the sections again.

\subsection{Signals}\label{s:ilsignals}

Each TCB side can have a signal assigned to the side. The signal will then indicate whether the train is allowed to enter the section to which the same TCB side is assigned to. Signals need to be set up in order to be able to set up routes. In the previous graph, in order to let trains move from $P$ to $Q$ or $R$, a signal needs to be set up on the side of $P$ that faces the track section (i.e. the east side of $P$). For an overview of the signals available in \advtrains, refer to section \ref{s:signals}. Signals should conventionally face the opposite direction of the side of the TCB so that the driver can see the signals.

Every signal can optionally have an influence point. This is the point where the aspect of the signal becomes effective, and should be located before the train passes the TCB side that the signal is assigned to. The influence point for signals that are independent of track sections is irrelevant, but should conventionally be close to the signal.

To assign a signal to a TCB:
\begin{itemize}
\item Click on ``Assign a signal'' in the TCB formspec.
\item You will be asked to punch a signal. Punch the signal to assign to the TCB side.
\item If you are prompted to set the influence point, you can do so by left clicking the track you want to assign the influence point to while looking in the same direction that the train drives in.
\end{itemize}

You can also set the influence point of a signal without assigning it to the TCB. To do so, right click the signal while holding the Aux1 key. For signal signs, right-clicking the signal will bring up the same prompt.

After assigning a signal to a TCB side, you can right click it to open up the signal formspec. The ``Influence point'' button will open a formspec let allows you to change or remove the influence point. The ``Unassign signal'' button will unassign the signal from the TCB side while keeping the influence point (if present).

\subsection{Routes}\label{s:ilroutes}

Routes contain information on where a train goes to, which section should be reserved for the train to pass, and how certain components, such as turnouts, should be set up. Routes are bound to TCB sides, but they usually need to start at ones with a signal assigned. In most cases, routes should also end in such a way that a train leaving the route can immediately enter the next route, with the most common exception being situations where dead ends are involved, such as train yards and termini where the line physically ends (e.g. Stuttgart Hauptbahnhof).

A relatively simple example can be seen in the graph below.

\begin{centeredtikzpicture}
  \draw[<->] (-0.5,0) -- (8.5,0);
  \draw[->] (4,0) .. controls +(1,0) .. ++(2,1) -- ++(2.5,2.5);
  \foreach \x/\y/\c in {0/0/$P_{1}$,2/0/$P_{2}$, 4/0/$T$,6/0/$Q_{2}$,8/0/$Q_{1}$,6/1/$R_{2}$,8/3/$R_{1}$} {
    \draw [fill=white] (\x,\y) circle [radius=0.3];
    \node at (\x,\y) {\c};
  }
  \foreach \x/\y in {0/0,2/0,8/0,8/3} {
    \pic [xscale=-1,shift={(0,0.3)}] at (\x,\y) {signal=red};
  }
  \foreach \x/\y in {6/0,6/1} {
    \pic [shift={(0,0.3)}] at (\x,\y) {tcb};
  }
  \node at (-1,0) {W};
  \node at (9,0) {E};
\end{centeredtikzpicture}

A train going from west to east (or north-east) would go through the following points in order:
\begin{itemize}
\item $P_{1} \to P_{2} \to T \to Q_{2} \to Q_{1}$
\item $P_{1} \to P_{2} \to T \to R_{2} \to R_{1}$
\end{itemize}

Note that the train goes through $\overline{P_{1}P_{2}}$ in both cases. $\overline{P_{2}T}$ is also shared, but $T$ needs to be set up based on the destination and the point cannot be assigned to a TCB. It is also encouraged to set up routes in a way that trains do not occupy the section containing any turnout while the train waits for a red signal (or stops in any way). This means that three routes can be set up for this example:
\begin{itemize}
\item $P_{1} \to P_{2}$
\item \(P_{2} \to \text{(locking $T$ to point at $Q_{2}$)} \to Q_{2} \to Q_{1}\)
\item \(P_{2} \to \text{(locking $T$ to point at $R_{2}$)} \to R_{2} \to R_{1}\)
\end{itemize}

To create a route:
\begin{enumerate}
\item Click on ``New route'' in the formspec of the signal assigned to the starting TCB side.
\item Set up passive components (e.g. turnouts) in the section appropriately and lock them by punching, if necessary.
\item Punch the next TCB that the train should pass. The track that the TCB is assigned to should have a marker showing ``END ROUTE''.
\item If the following track section is the last track section in the route and does not require any setup require in step 2 or have more than two TCB sides, click ``Finish route at the end of NEXT section''.
\item If the route leads to the end of the physical line, click ``Finish route at the end of NEXT section''.
\item If the route ends at the TCB, click ``Finish route HERE''.
\item If the route continues beyond the TCB, click ``Advance to next route section'' and repeat the above steps, starting from step 2.
\end{enumerate}

You can also click ``Finish route at the end of NEXT section'' at the starting TCB. This can be useful for the $\overline{P_1P_2}$ route in the previous graph.

If the TCB is not considered suitable for route continuation, please check that the side of the TCB from which the train passes the TCB is part of a track section and that the train can reach there without passing a point assigned to another TCB. If you see ``Advancing over next section is impossible at this place. End of interlocking.'', please check that the side of the TCB corresponding to the driving direction is part of a track section.

\begin{centeredtikzpicture}
  \draw [->] (-0.5,1) node [left] {Finish route HERE} -- (4.5,1);
  \draw [->,blue,very thick] (0,1) -- (2,1);
  \draw [->] (-0.5,0) node [left] {Finish route at the end of NEXT section}-- (4.5,0);
  \draw [->,blue,very thick] (0,0) -- (4,0);
  \foreach \y in {1,0} {
    \draw (0,\y) pic [xscale=-1] {signal=red} node [below] {$P$};
    \foreach \x/\l in {2/Q,4/R} {
      \draw (\x,\y) pic {tcb} node [below] {$\l$};
    }
  }
\end{centeredtikzpicture}

After finishing the route, you are prompted for the name of the route. It is recommended to use a sensible name. You should then see the route formspec. If you don't, click on the name of the route you just created and click ``Edit route'', and proceed to the next section regarding ARS.

\subsection{Automatic routesetting}\label{s:ilars}
Automatic routesetting (ARS) is a method of choosing a route based on a set of matching patterns. In the previous section, you learned to set up a route, and there is a text input box where you can enter the ARS rules. This area is empty by default, which means that the route is not selected in any case.

ARS rules are delimited by a newline. Each line can be one of the following:
\begin{apidoc}{ARS rules}
\item \apipat{\# \var{comment}} Comment
\item \apipat{LN \var{line}} Matches trains with the exact line name \var{line}.
\item \apipat{RC \var{routing code}} Matches trains that contain the routing code \var{routing code}.
\item \apipat{!LN \var{line}} Matches trains with a different line name than \var{line}.
\item \apipat{!RC \var{routing code}} Matches trains that do not contain the routing code \var{routing code}.
\item \apipat{*} Matches all trains
\end{apidoc}

A whitespace is required before the argument.

ARS rules are designed to short-circuit. The route is selected if a train matches any of the rules.

In some cases, you may want to disable ARS. To do so, click on ``Disable ARS'' in the signal formspec. Clicking on the same button will enable ARS.

\subsection{Automatic working}\label{s:ilaw}
Automatic working is a system that sets the route after the train passes the signal. To enable automatic working, click on ``Enable Automatic Working'' in the signal formspec after the route is set. Clicking on the same button again will disable automatic working.

\subsection{Station/stop tracks}\label{s:stoprail}
Station/stop tracks (sometimes simply called \textit{station tracks}) are special tracks that register a station where a train should stop. The interface of the formspec should be self-explanatory, with a few things to notice:
\begin{itemize}
\item You need to click ``Save'' after changing the settings.
\item The station code is used to identify the station. The station name is shared among all tracks with the same station code (not vice versa).
\item Station tracks disable ARS for the specific train when the train arrives at the station and enables ARS on the train before departure.
\end{itemize}

\subsection{Considerations for interlocking}\label{s:ilconsiderations}

The previous sections were mainly theoretical in that the sections mostly introduced new concepts or described how to do things. This section will focus on the practical part of interlocking, in particular certain things to consider when setting up interlocking on a rail line.

\subsubsection{Junctions}\label{s:iljunctions}

One of the most important considerations when setting up interlocking at a junction is to make sure that multiple trains can go through the junction at the same time when possible.

As an exercise in section \ref{s:xings}, you were asked to build a T junction. A scheme is shown below if you are stuck. Try to interlock the junction based on what you have learned in the last few sections.

\begin{centeredtikzpicture}[ultra thick]
  \draw [->] (-0.5,-1.5) -- (-0.5,0) arc [start angle=0,end angle=90,radius=1] -- (-3,1);
  \draw [->] (-3,2) -- (-1.5,2) arc [start angle=90,end angle=0,radius=2] -- (0.5,-1.5);
  \draw [->] (0.5,-1.5) -- (0.5,0) arc [start angle=180,end angle=90,radius=1] -- (3,1);
  \draw [->] (3,2) -- (1.5,2) arc [start angle=90,end angle=180,radius=2] -- (-0.5,-1.5);
  \draw [<->] (-3,2) -- (3,2);
  \draw (-3,1) -- (3,1);
\end{centeredtikzpicture}

The lazy method would be to set up the entire junction as a single track section - you only need 6 TCBs for that. However, a train passing through would occupy the entire junction, even when two trains could use the junction at the same time - for example, a train going from east to west and another one from west to east. This can be solved by a slightly more complicated setup with four sections, each shown below with a different color:

\begin{centeredtikzpicture}[ultra thick]
  \draw [<-,red] (-3,2) -- (-1.5,2) arc [start angle=90,end angle=60,radius=2];
  \draw [<-,red] (3,2) -- (1.5,2) arc [start angle=90,end angle=120,radius=2];
  \draw [red] (-1.5,2) -- (1.5,2);
  \draw [blue] (60:2) ++(-1.5,0) arc [start angle=60,end angle=15,radius=2];
  \draw [blue] (120:2) ++(1.5,0) arc [start angle=120,end angle=165,radius=2];
  \draw [blue] (-0.75,1) -- (0.75,1);
  \draw [<->,orange] (-3,1) -- ++(1.5,0) arc [start angle=90,end angle=0,radius=1] -- +(0,-1.5);
  \draw [orange] (-1.5,1) -- ++(0.75,0);
  \draw [orange] (-0.5,0) arc [start angle=180,end angle=165,radius=2];
  \draw [<->,green] (3,1) -- ++(-1.5,0) arc [start angle=90,end angle=180,radius=1] -- +(0,-1.5);
  \draw [green] (1.5,1) -- ++(-0.75,0);
  \draw [green] (0.5,0) arc [start angle=0,end angle=15,radius=2];
\end{centeredtikzpicture}

It is also possible to build the junction on multiple levels. This is known as grade separation. In real life, grade-separated railway junctions are not common, mostly because of the larger curve radii and slopes that are notably less steep (for example, the steepest slope of the Schwarzwaldbahn in Baden, which has an altitude between 384m and 832m, is only 2\%). As an exercise, you can try to make the T junction grade-separated.

\subsubsection{Track capacity and deadlock}\label{s:ilcapacity}
You can not infinitely add trains to a line. If you do, you will end up with a deadlock, where every train is stuck at a red light, waiting for the previous train to clear the track section ahead, while the previous train is also stuck at a red light, waiting for the train ahead of it to leave the section ahead, and so on:

\begin{centeredtikzpicture}
  \draw (0,1) arc [start angle=90,end angle=270,radius=0.5] -- (8.5,0) arc [start angle=270,end angle=450,radius=0.5] -- cycle;
  \foreach \i in {0,2,...,6} {
    \draw[->,very thick,blue] (\i,0) ++(0.5,0) -- +(1,0);
    \pic at (\i,0) [shift={(2,0)},xscale=-1] {signal=red};
    \draw[<-,very thick,blue] (\i,1) ++(1,0) -- +(1,0);
    \pic at (\i,1) [shift={(0.5,0)}] {signal=red};
  }
\end{centeredtikzpicture}

This problem can be trivially solved by removing a train and, if necessary, resetting the track section that the train previously occupied (this can be done in the track section formspec):

\begin{centeredtikzpicture}
  \draw (0,1) arc [start angle=90,end angle=270,radius=0.5] -- (8.5,0) arc [start angle=270,end angle=450,radius=0.5] -- cycle;
  \foreach \i in {0,2,...,6} {
    \draw[->,very thick,blue] (\i,0) ++(0.5,0) -- +(1,0);
    \pic at (\i,1) [shift={(0.5,0)}] {signal=red};
  }
  \foreach \i in {2,4,...,6} {
    \pic at (\i,0) [xscale=-1] {signal=red};
    \draw[->,very thick,blue] (\i,1) -- +(-1,0);
  }
  \pic at (8,0) [xscale=-1] {signal=green};
\end{centeredtikzpicture}

However, as you may notice, only the train at the bottom-right can move; other trains have to wait for the trains ahead to leave the section. The ideal situation is that the section length and the number of trains are decided in such a way that trains do not have to stop or slow down between stations.

When actually building a rail line, signals are spaced away much further than in the illustration above. On servers, the distance between signals typically range between about 50 nodes to a few hundred, depending on the speed at which trains run on the line and the number of trains using the line. The distance between signals in station areas usually depend on the size of the station.

Single-track sections can also be a source of deadlocks:

\begin{centeredtikzpicture}[scale=0.6]
  \draw [<-] (-2.5,1) -- (-2,1) .. controls (-1,1) .. (-0.5,0.5) .. controls (0,0) .. (1,0) -- (3,0) .. controls (4,0) .. (4.5,0.5) .. controls (5,1) .. (6,1) -- (8,1) .. controls (9,1) .. (9.5,0.5) .. controls (10,0) .. (11,0) -- (13,0);
  \draw [<-] (-2.5,0) -- (13,0);
  \draw (13,-0.1) -- (13,0.1);
  \foreach \x/\y/\s in {-2/0/-1,1/0/1,3/0/-1,6/1/1,8/0/-1,11/0/1} {
    \pic at (\x,\y) [xscale=\s] {signal=red};
  }
  \foreach \x/\y in {-2/1,6/0,8/1} {
    \pic at (\x,\y) {tcb};
  }
  \foreach \x/\y/\d in {1.5/0/->,6.5/1/<-,6.5/0/->,11.5/0/<-} {
    \draw [\d,very thick,blue] (\x,\y) -- +(1,0);
  }
\end{centeredtikzpicture}

With single-track sections, routes should generally be set up in a way that the train does not stop in single track sections. Exceptions include the end of track, where the train has to stop and reverse:

\begin{centeredtikzpicture}[scale=0.6]
  \draw [<-] (-2.5,1) -- (-2,1) .. controls (-1,1) .. (-0.5,0.5) .. controls (0,0) .. (1,0) -- (3,0) .. controls (4,0) .. (4.5,0.5) .. controls (5,1) .. (6,1) -- (8,1) .. controls (9,1) .. (9.5,0.5) .. controls (10,0) .. (11,0) -- (13,0);
  \draw [<-] (-2.5,0) -- (13,0);
  \draw (13,-0.1) -- (13,0.1);
  \foreach \x/\y/\s in {-2/0/-1,8/0/-1,11/0/1} {
    \pic at (\x,\y) [xscale=\s] {signal=red};
  }
  \pic at (6,1) {signal=green};
  \foreach \x/\y in {-2/1,1/0,3/0,6/0,8/1} {
    \pic at (\x,\y) {tcb};
  }
  \foreach \x/\y/\d in {6.5/1/<-,6.5/0/->,11.5/0/<-} {
    \draw [\d,very thick,blue] (\x,\y) -- +(1,0);
  }
\end{centeredtikzpicture}

Notice that the deadlock is prevented at the cost of lower capacity of the line.

\subsubsection{Short routes}
In some cases, there may be setups with very short routes:

\begin{centeredtikzpicture}
  \draw [->] (0,0) -- (4.5,0);
  \draw [very thick, blue, ->] (0.5,0) -- (1.5,0);
  \pic at (2,0) [xscale=-1] {signal=green};
  \node [below] at (2,0) {$P$};
  \pic at (4,0) [xscale=-1] {signal=green};
  \node [below] at (4,0) {$Q$};
\end{centeredtikzpicture}

In the setup illustrated above, if $\overline{PQ}$ is short enough, or, more specifically, if $\overline{PQ}$ is shorter than the braking distance of the train at $P$, the signal at $Q$ will be triggered to set a route.

If short routes are desired, such as at stations, it is generally recommended to disable ARS for the train, such as by using the \texttt{A0} ATC command, and keep some distance between the influence point of the signal and the point at which the train is expected to stop. Alternatively, you can also limit the speed of the train to trigger the routesetting system later, but this is not the ideal solution in most use cases of short routes.

\subsection{Basic three-station setup}\label{s:ilbasicsetup}
Now that you have learned to use interlocking, create a simple three-station setup shown below.
\begin{centeredtikzpicture}[scale=0.6]
  \draw (0,0) -- (3,0) .. controls (4,0) .. (4.5,0.5) .. controls (5,1) .. (6,1) -- (8,1) .. controls (9,1) .. (9.5,0.5) .. controls (10,0) .. (11,0) -- (14,0);
  \draw (0,0) -- (14,0);
  \node at (1.5,0.5) {Station A};
  \node at (7,0.5) {Station B};
  \node at (12.5,0.5) {Station C};
\end{centeredtikzpicture}

If you are stuck at some point or want something to compare your set up to, you can watch Blockhead's introduction video, where he creates a three-station setup. The link is provided at the beginning of this chapter.

\section{Signals}\label{s:signals}
Signals are devices that give trains certain instructions and/or impose certain limitations on trains. \advtrains{} comes with a few signals, which are explained in the corresponding sections.

\subsection{Types of speed restrictions}\label{s:srtypes}
There are a few types of speed restrictions that a signal can give. These speed restrictions are independent of each other, and the strictest restriction is chosen as the speed restriction of the train. The speed restrictions need to be set by the specific signs that do so - every signal can only set (and lift) one type of speed restriction and do not affect other speed restrictions. The naming of the speed restriction types are mainly aesthetic and does not give any particular information for \advtrains{} - in real life, these are mainly informative for the driver.

The following types of speed restrictions are used by signals in \advtrains{}:

\begin{apidoc}{speed restriction type}
\item \apiterm{Permanent (``main'') speed restriction (\texttt{main})} The default type of speed restriction. This one is most commonly given by signal lights.
\item \apiterm{Temporary speed restriction (\texttt{temp})} Speed restrictions that are temporarily set up, such as near construction sites.
\item \apiterm{Line speed restriction (\texttt{line})} Speed restriction that applies to the entire rail line.
\end{apidoc}

The following is an example of a train running with speed restrictions. You may want to read the section on German signal signs first.
\begin{itemize}
\item The train starts without any speed restriction.
\item The train drives past a Lf 1/2 sign with a speed restriction of 8. The train now has a speed restriction of 8.
\item The train drives past a Ks 1 with the Zs 3 indicator showing 12. The train now has a main speed restriction of 12 and a temporary speed restriction of 8, so the train still has a speed restriction of 8.
\item The train drives past a Lf 3 sign. The temporary speed restriction is lifted, and the train now has a speed restriction of 12, set by the main speed restriction (described above).
\item The train drives past a Zs 10 sign. The main speed restriction is lifted, and the train now has no speed restriction.
\end{itemize}

\subsection{Basic signals}

The core mod of \advtrains{} comes with wallmounted signals and a signal with two lights. These signals can only stop the train and lift the main speed restriction of the train.

\subsection{German signals}
The \texttt{advtrains\_signals\_ks} mod provides a set of signals used in Germany, including (but not limited to) Ks signals that the mod gets its name from.

Due to historical reasons, the phrases \textit{ex-DB} and \textit{ex-DR} refer to the former Deutsche Bundesbahn (West Germany) and Deutsche Reichsbahn (East Germany) respectively.

The signal placement conventions assume right-hand traffic.

\subsubsection{Ks signals}
Ks signals are combined signals that combines the features of main signals and distant signals. The system was developed by the Deutsche Bahn AG after the Deutsche Bundesbahn in West Germany and the Deutsche Reichsbahn in East Germany merged, and the goal was to replace the other four signaling system in use in Germany, which still exist today.

A real-life Ks signal looks similar to this:
\begin{centeredtikzpicture}
  \pic at (0,0) {Ks signal};
Mode	Name	Size
-rw-r--r--	CMakeLists.txt	265	log plain
-rw-r--r--	c_content.cpp	33890	log plain
-rw-r--r--	c_content.h	6943	log plain
-rw-r--r--	c_converter.cpp	9591	log plain
-rw-r--r--	c_converter.h	5129	log plain
-rw-r--r--	c_internal.cpp	3874	log plain
-rw-r--r--	c_internal.h	3073	log plain
-rw-r--r--	c_types.cpp	1036	log plain
-rw-r--r--	c_types.h	1413	log plain