[Rails-devel] Stop properties

[Erik V. <eri...@xs...>]

I have implemented (but not yet pushed) the train stop properties that we
have discussed a while ago, all described below. 

My questions are (in particular so Stefan):
Q1. Do you like it this way?  Is it usable?
Q2. What shall I do to the repository?  Push the branch? Or push it merged
with master?  Or first redo it all because you don't like it? ;-)
Q3. See point 6: some algorithms classes currently pick up values from
HexMap.  The current code requires that these values should be taken from
Stop (see comments below).  Would that be OK for you?  Or should I add
methods to HexMap and/or Tile that honour defaults?

Here is the overview (I'll put it into the wiki later):

1. City has been renamed to Stop. This object represents a train stop on a
certain tile that has been laid on a certain hex. 
Stop will become the primary source of all properties that are required to
define routes and calculate revenues.
(I have left Station as it is, because this object name equates to the
corresponding tag names in Tile.xml, 
which I did not want to change after all.  I hope we can live with this
slight naming inconsistency.)

2. The Stop properties can be derived from either MapHex (defined in
Map.xml) or Tile (defined in TileSet.xml).  
If both exist, MapHex takes precedence, as it is more specific.
If neither is defined, it will use defaults on the Manager level in the same
XML files, with the same precedence. 
See item 5 for details and a precedence list.

3. The stop properties are:

- type = {major|minor|offmap|medium|halt|pass|port|mine|null} .
I have added offmap because usually different defaults apply. 
However, for train running purposes offmap stops should normally be treated
as major cities.
Cities on "red" tiles are marked offmap by default.
"null" applies to plain track tiles, and allows to define a non-default
"loop" value (1860), see below.

- runTo = {no|yes|tokenOnly}. Default "yes".
"no" would apply to e.g. Birmingham in 1851 before phase 4 and
Elsaß-Lothringen in 1835 except in phase 2. 
"tokenOnly" would apply to e.g. the 18Scan red cities.
This usage implies that the runTo value may be phase-dependent.

- runThrough = {no|yes|tokenOnly}.  Default "yes" (exception: offmap "no").
"yes" obviously only applies if the city is not closed (i.e. filled by
tokens of other companies).
"no" would apply to standard off-map areas, 
"tokenOnly" would apply to 1830 Altoona (PRR base, implying a PRR token).
Is there a need for "always" (i.e., even if closed)? Any other special
cases?

4. A somewhat related new MapHex property (also accessible to Stop, but not
restricted to tiles with stops) is:
- loop = {yes|no}, which defines if one train may touch a hex more than
once.  Default "yes" (exception: offmap "no").
"no" applies to *all* tiles in 1860.

5. Defaults per stop type, and generic defaults (type=null) can be defined
in Map.xml and TileSet.xml. 
These defaults are parsed and stored in MapManager and TileManager,
respectively.
The precedence is (the first non-null value found is used):
- specific Hex
- specific Tile
- Hex default per stop type
- Tile default per stop type
- generic Hex default (type=null)
- generic Tile default (type = null)
- final default as defined above.

I believe this all gives enough flexibility, but of course the proof of the
pudding is in the eating.
I have tested settings at various but not all levels.  Current usage
effectively only needs the first and last level.

6. Stop, Tile and MapHex all have these four methods:
Stop.Type getType() or getStopType(),
Stop.RunTo isRunToAllowed(), 
Stop.RunThrough isRunThroughAllowed(),
Stop.Loop isLoopAllowed().
However, only the return values from Stop follow the precedence rules. The
values from HexMap and Tile only return any *explicit* settings in <Hex> and
<Tile>, so these are of little use.
Please let me know if that could be a problem for some use cases.  I would
have to add separate methods if these return values should also honour the
defaults.

(Note: the existing HexMap.Run type has been split and moved to Stop.  The
algorithms classes still pick up values from HexMap, which is no longer
correct, see above.)

I have so far added explicit settings to the following cases (all in
Map.xml):
1830: The PRR [and Reading] bases: runThrough="tokenOnly".
1856 Goderich/18EU Hamburg: runThrough="yes" (not really needed, because
tile -939 already behaves correctly, but that one has been manually
tweaked).
18EU Paris/Berlin/Vienna: loop="no".

The Stop code temporarily logs all Stop settings in a way that stands out,
so that checking the effects of any trial settings should be easy.

Erik.