====== ARS (Automatic RouteSetting) ======

ARS, short for Automatic RouteSetting, is a system of rules for to accept/deny trains for certain actions. True to the name, it is used for automatically setting routes on signals. Additionally, it is used for deciding whether to stop trains at a [[usage:lines:stoprail|Station/Stop Rail]].

===== About Line Numbers and Routing Codes =====
See the article [[usage:using_stock:train_fields]] for info about these properties.

In case you're unfamiliar with Line Numbers and Routing Codes: You may recall the Line and Routingcode fields from the Onboard Computer, available from any driver's seat in the train. You've probably already used the text fields for text displayed inside and out of the train. Well, that information is for passengers, whereas Line and Routing Code are for the ARS system (and others, like Basic ATC, but this article is about ARS).

//Please note that Line Numbers and Routing Codes are case-sensitive, so RC FREIGHT is different from RC Freight.//

When ARS tries to match a rule for a Line Number, it will look for an exact match of the entire Line Number field.  

When ARS tries to match a rule for a Routing Code, it will look for that routing code anywhere in the whole routing code field of the train for a partial match.

You can set all the train properties such as Line Number and Routing Code (plus the texts) automatically with [[usage:atlatc:start|LuaATC]]; this is how you would change the LN at the end of the line if you're using different LNs for each direction of service or alternating short-run and full-run (many algorithms are possible with LuaATC after all).

===== The ARS Syntax =====
ARS rules are written with a text syntax into two important textboxes: The Route Editor on signals, and the "Trains stopping here (ARS Rules)" box on Station/Stop "rails" (tracks). ARS Rules for a signal will allow a route to be set automatically, while ARS rules for Station/Stop tracks will decide whether the train is going to stop at that station.

ARS rules are parsed from the input textboxes and placed into data structures inside Advtrains. If your ARS rules didn't parse, they don't get added. When the formspec is next shown, only the valid rules that successfully saved get added.

The syntax is straightforward. There are three types of rules: Line Number rules, Routing Code Rules and the * rule. There is also the comment, which is any line that starts with a #, so you can write notes in your ARS rule list. Each rule is on its own line. Here's a valid LN rule, a comment, a valid RC rule, and one invalid line written out:
<code>
 LN 1
 # For operator Boris trains
 RC BorisDepot
 E
</code>

You will notice that the "E" line disappears if you exit and return to the same formspec. This is a potential source of confusion - if you haven't gotten the syntax right, the lines will just disappear without feedback about your error.

There is also ! operator for negation of the rule, applicable only the LN and RC rules (there's no ''!*'' rule). If you start a line with a !, it only matches trains that do NOT have that LN or RC. Here's the rules for a passenger stop that doesn't allow trains with RC Freight and also doesn't allow line 2 trains to stop.
<code>
!RC FREIGHT
#2 Runs express
!LN 2
</code>

===== Manage your RCs and LNs =====
The RC FREIGHT convention is used on LinuxForks server to identify freight trains to prevent them stopping at passenger stations.

It is incumbent on railway operators and network owners to manage LNs and RCs properly and make their meanings clear. Line Numbers may end up not being globally unique*, but it does not matter unless the systems using them are located nearby and may end up sharing tracks. Some RCs may be specific to junctions, telling the train which way to go at that specific point; others may separate types of traffic like passengers and freight; still others might identify that a train is out of service, or headed to the nearest depot available. Use what conventions and management makes sense to you.

*but station codes on the Station/Stop track need to be; thankfully there is an owner system for those that was introduced to stop people just putting anything in that overlaps and overwriting other peoples' station names unless you have ''train_admin'' (I digress, that's a topic for another wiki edit or forum post).