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 Station/Stop Rail.

See the article 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 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).

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:

 LN 1
 # For operator Boris trains
 RC BorisDepot
 E

Invalid lines, which cannot be parsed as ARS rules, will be automatically converted to comments with a question mark prepended. For example, the E above will become “# ? E”. When this happens, you made a syntax 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.

!RC FREIGHT

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).

This feature has been newly introduced in 2.6.0.

ARS rules can now include a priority number. Specifying a priority for a rule enables the Multi-ARS mode. If the ARS rules of multiple routes match a given train (and all of these rules have a priority set), then all the matching routes will be requested simultaneously, and the first one that can be set without conflicts is being set.

Example:

Route 1 has rule:
  2 RC abc
Route 2 has rule:
  1 RC abc

The number (here 1 or 2) in the beginning is the priority, it can be any positive whole number. A train with routingcode abc will match both of these routes.

The signal will now attempt to set Route 2, and if unsuccessful Route 1. Route 2 is tried first because its priority number is smaller (it's like a ranking - 1st, 2nd, 3rd etc). If none of the routes can be set, the signal waits until any of them becomes available (just like in the single-route case) and set it.

Multi-ARS also works with the default route:

Route 1 has rule:
  RC def
Route 2 has rule:
  1 *
Route 3 has rule:
  2 *

Trains with routingcode def will go to Route 1. Any other train will go to either Route 2 or Route 3, whichever is available first.

Priorities are useless for station/stop rails and have no effect there.

ARS rules normally are or-combined, that is, any of the rules need to match the train. However sometimes two or more conditions need to be fulfilled.

Consider this example for a stop rail:

• only passenger trains should stop (freight trains have RC FREIGHT)
• Line 2 trains should not stop, because they are an express service

Below rules are wrong:

!RC FREIGHT
!LN 2

This is because a line 2 train, although it doesn't match the “!LN 2” rule, nevertheless is not a freight train so it matches the !RC FREIGHT rule and stops anyway. The other way round, freight trains will also stop because they are not of line 2.

The correct rules are:

!RC FREIGHT
& !LN 2

The & symbol on the second line indicates that both conditions need to be fulfilled for the rule to match. Now only trains that are not freight trains AND are not of line 2 will stop.

Regarding the syntax, note that the & !LN 2 part must be on a new line. Also, there cannot be comments between a rule and its attached & clauses. This is a limitation of the ARS rule parser.

Conditions can also be attached to the default route this way, although this is probably only needed in special situations and should be avoided:

*
& !LN 2

A route marked like this will be used for any train that doesn't match explicit rules, EXCEPT if its line is 2.

Rules are considered in this order:

• Explicit rules: a rule of the form LN x, RC x, !LN x or !RC x (and its following & clauses) matches the train

1. The first matching route, if any rule has no priority
2. All matching routes (Multi-ARS), if all matching rules have a priority (in order of that priority)

• Default routes: if none of the explicit rules matched, the routes set as default routes (*) (except if the following & clauses did not match the train)

1. The (only) default route, if there is a default route without priority
2. All default routes, if multiple exist and all of them have priority set

Rules without priority always take precendence over rules with priority. For simplicity, avoid mixing rules with and without priority.