Game configuration 1: Trains
The trains of an 18xx game are configured in file Game.xml within the tag <Component name="TrainManager">.
The details have considerably been changed in June 2020 with the introduction of "dual trains", i.e. train cards with a different train type on each side. However, the original way of describing one-sided train cards only, still works.
The new style train definition distinguishes between TrainCardType and TrainType.
TrainCardType refers to the train card as it is usually described in the rules by names such as 5 (1830) or 6H (1826) for single-sided train cards, and 4/3+3 (18Scan) or 3/2G (18VA) for double-sided train cards. These names are defined in <TrainType> XML tags, in which the attributes name and also quantity, specifying the number of cards of that type, must always be present. For instance (18Scan):
<TrainType name="2/1+1" quantity="6">
TrainType refers to the single train type as it is used during play. When buying a two-sided train card, the buyer usually must decide which side to use as an actual train. To specify the properties of each such train type, the inner tag <Train> must be used. This tag should then specify the properties of that train type, such as cost, and number and type of its allowed stops. For instance (18Scan):
<Train name="2" majorStops="2" cost="100"/>
A complete description of a dual train card may therefore look like (18Scan):
<TrainType name="2/1+1" quantity="6">
<Train name="2" majorStops="2" cost="100"/>
<Train name="1+1" majorStops="1" minorStops="1" cost="80"/>
</TrainType>
A single-sided train card can also be described that way, but for simplicity (and backwards compatibility) the per-train properties can equally well be described in the <TrainType> tag, for example (1830):
<TrainType name="2" majorStops="2" cost="80" quantity="6"/>
Here all required and optional attributes of the <TrainType>and <Train>tags are described.
The <TrainType> tag defines the attributes of class TrainCardType, from which the individual TrainCard instances are created. In case the train card is single-sided, all attributes of class TrainType can also be defined here. If the card is double sided, any such specifications in this tag act as defaults for the required separate <Train> tags, see below.
XML attribute Mode Default Description/usage
name required -none- see above
quantity required -none- a number > 0, or -1 which means unlimited
class optional TrainCardType the Java class representing the TrainCardType
initialPortfolio optional IPO where the cards are at game start. Values: IPO, POOL
obsoleting optional no if the train can become 'obsolete'. Values: yes, no
category optional passenger if some trains (e.g. "goods") have different Stop properties
Inner tags (all optional):
Tag name XML attribute Mode Default Description
<Train> see below
<NewPhase> phaseName required -none- phase started when first train of this type is bought.
phase name as defined under <PhaseManager>.
trainIndex optional 1 which train card of that type starts the new Phase (18TN).
The <Train> tag, if present, must be enclosed by the <TrainType> tag. It defines the attributes of class TrainType,
from which the individual Train instances are created. This tag is optional if the train card is single-sided, but required if it is double-sided.
XML attribute Mode Default Description
name required -none- see above
cost required -none- initial train price
exchangeCost optional no exchange price if an older train can be exchanged for this one
majorStops required -none- number of 'major' stops the train can call at.
-1 means this is not a normally running train (e.g. Pullmann)
minorStops optional none number of 'minor' stops the train can call at.
Only for 'n+m' type trains.
The meaning of 'major' and 'minor' stops is game-dependent. Games with no '+' trains only have major stops.
Inner tags (all optional):
Tag name XML attribute Mode Default Description
<Reach> base optional stops Values: stops, hexes (for H-trains)
countTowns optional yes Values: yes, no (against train length)
<Score> cities optional single Values: single, double
towns optional yes Values: yes, no
The optional <Defaults> tag can include settings of all attributes that apply to all or most trains.
It is mainly used to set the <Reach> and <Score> attributes, which often apply to all trains of a game.
Any settings in <TrainType> and <Train> will override the default settings.
In addition, the following attribute is sometimes used:
XML attribute Mode Default Description
class optional all trains The train class to which these defaults apply.
This optional tag can include any number of the following inner tags:
Tag name Description
<DualTrainBecomesUndecidedInPool/> A two-sided train card may be flipped if bought from the Pool.
The default is that the original train choice persists.
<FaceValueIfDifferentPresidents/> Buying a train between companies with different presidents can
only take place at face value (1851). By default this does not apply.
The <Component> tag that defines the TrainManager may, in addition to the mandatory name and class attributes, have one additional attribute:
XML attribute Mode Default Description
ObsoleteTrainFor optional EXCEPT_TRIGGERING Values: ALL and EXCEPT_TRIGGERING
This attribute is only used in 18AL and 18TN, and, in my opinion, misplaced. For further study.
Two more tags within the TrainManager component:
Tag name Attribute Values Default Description
<DiscardTrain> to Pool, Scrapheap Pool Where discarded trains go to.
<RemoveTrainBeforeSR/> Bought by foreigners.
To achieve the dual train card functionality, the implicit data model (or class diagram) needed an update.
The current implementation is based upon the following model:
The two boxes at the left-hand side refer to the TrainCardType and TrainType described before.
These classes are defined by the <TrainType> and <Train> XML tags. These tag names should perhaps have been made equal to the class names, but for now I have left <TrainType> as is, and consequently needed <Train>.
The TrainCard and Train boxes in the centre refer to the individual cards and trains, as these are bought and used. Their number is here denoted by (q) and equal to the value of the quantity attribute.
Each TrainCardType may be related to 1 or 2 TrainType instances, and similarly TrainCard and Train, but TrainCard also knows which Train has actually been chosen once the card has been bought.
The TrainManager knows all these instances, and each company Portfolio knows which train cards it owns, and, as said, each card knows the actual train once it is chosen.