[Rails-devel] Stop properties framework

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

Stefan (and possibly others),

Sorry, this is long.  I intend to put an even longer version in the Wiki
later on.

I'm happy to report that I have made quite some progress with the new Stop
properties framework, that was discussed a while ago.
It's almost ready to be pushed, but I would first like to present its main
aspects and reopen it for discussion.  I would like to publish it as a
whole.

This framework is intended to provide maximum flexibility in stop property
configuration, on many levels. It is also intended to address the following
requirements and bugs:
- 1837: the need to assign different types to different stops with different
properties on one mine tile.
- 1835: the Berlin loop bug, also relevant to 18EU.  As discussed, Stefan's
existing method is not maintainable.
- 1837 (and other games): the requirement that certain trains may only
access one stop of a given type (i.e. mine). 

Please note, that this framework only addresses the problems mentioned (and
several others) in *configuring* such properties.  Currently, just one of
these properties is being used by Stefan's route and revenue calculation
code, so there is a lot more work to do to bridge our two worlds.  See the
end of this message for more remarks on this aspect.

The stop properties are now collected in a new class named Access.  The
properties are unchanged from the previous situation, except that one new
property has been added:

- stopType (city, town, port, mine, pass etc.). The list of values is
hardcoded, but easily extendable if needed.

- runTo (can a train run to a certain station?).  Still unused.  It is
intended to configure initial access restrictions like those of 1851
Birmingham and 1835 Elsass-Lothringen.

- runThrough (can a train run through a certain station?). Still unused.
Probably useful for off-map areas, Goderich and other cases.

- loop (can a train re-enter a hex visited before?). Still unused, and
perhaps redundant.  It was intended to prevent the Paris/Berlin/Vienna loop
problems in 18EU and 1835, but that issue can be equally well addressed by
the trainMutexID, to be discussed below. 'loop' may still prove useful for
1860, where no train may re-enter ANY hex. 

- score type: major or minor (e.g. for 1835 n+m trains and for the many
games where towns do not count against the train size).  This is the only
stop property already in use.  The new framework allows more fine-grained
configuration.

- trainMutexID (provisional name).  The value can be any string.  This stop
property is new, and intends to replace the 'city name' that Stefan
currently is using to prevent the Berlin (etc.) loops.  As discussed
earlier, that solution is not well sustainable. Another potential use of
trainMutexID is to address the rule in 1837 and 18VA that goods trains may
hit only one mine station each.

In principle, all stop properties can be defined per hex, per tile, per
station, per stop type, or even globally, but several (pretty obvious)
exceptions exist.
The configuration levels are, in order of precedence:

 1. Specific MapHex station (defined in Map.xml with 'station' value > 0).
 2. Specific Tile station (defined in TileSet.xml with 'station' value > 0).
For preprinted tiles (id<=0) only.
 3. MapHex (defined in Map.xml with 'station' value absent or 0).
 4. Tile (defined in TileSet.xml with 'station' value absent or 0).  For
preprinted tiles (id<=0) only.
 5. MapManager default per stop type (defined as default in Map.xml).
 6. TileManager default per stop type (defined as default in TileSet.xml).
 7. MapManager general default (defined in Map.xml).
 8. TileManager general default (defined in TileSet.xml).
 9. Generic default per stop-type (hardcoded).

Any property still undefined on a certain level "falls through" to the next
level.  It's probably preferable to define properties per hex rather than
per tile, but (at least for preprinted tiles) both are possible.

Both property parsing and the precedence "fall-through" mechanism are
methods of class Access.  This refactoring has allowed to clean up some
repetitive code in various classes.

Comments per property:

- stop type can only be defined on levels 1-4, as it is required further
down. If still undefined after level 4, it is derived from the tile Station
type.  
- runTo and runThrough: levels 1-8.
- scoreType and trainMutexID: levels 1-6.

I could only test the fall-through mechanism with scoreType, as that is the
only item currently used by Stefan's code.  Testing was easy, by setting
conflicting score type values ('major' and 'minor') on different levels for
ports and villages in 18EU, and watching the displayed train routes.

I have also tested trainMutexId, after (temporarily) changing lines 257 and
258 in NetworkVertex to call city.getTrainMutexID() instead of
station.getCityName().
This way, I could switch the Berlin loop allowance on and off.

Stefan, I was wondering why your setting of city="B/V" for the Berlin/Vienna
tiles in 18EU did prevent one-hex loopback, but not the Berlin-Vienna route.
I guess you are doing this check per hex only.  If you could lift that
restriction, and look at duplicate city names (or whatever) on all stops of
a route, I think we would have a strong mechanism to achieve all kinds of
train access limitations.

Configuring stop properties is done with the <Access> XML tag, as follows 
	<Access station="1" type="city" runTo="yes" runThrough="no"
score="minor" trainMutexID="X"/>
where all attributes are optional (and in this example all or most are
redundant anyway).  
The <Access> tag can be put inside <Tile>, <Hex> or in the <Defaults>
sections of Map.xml and TiIeSet.xml. Multiple occurrences are allowed.

I have added stop types like "port", "mine", "halt", "pass", just in case.
For instance, in 18EU I can now declare the port properties in Map.xml:
<Defaults>
	<Access type="port" score="minor"/>
</Defaults>

If only a stop type needs be declared, a shortcut is possible by putting its
definition inside the <Tile> or <Hex> tags.
So, for the 18EU port of Amsterdam, we could have
	<Hex name="A4" value="10" tile="-800" orientation="0">
		<Access type="port"/>
	</Hex>
but this can be merged to 
	<Hex name="A4" type="port" value="10" tile="-800" orientation="0"/>
BTW 'type="port"' has replaced the (completely unused) 'port="yes"' in
18EU/Map.xml.

Whether or not this all will turn out to be useful remains an open question,
because Stefan appears to have implemented some restrictions in ways that
may not directly correlate with this framework.  So, to make it work, some
bridge must be built somewhere.  I am also open to add <Access> attributes
that would directly call Stefan's classes, as I understand he has suggested,
provided that the new attribute names are a bit user-friendly.  I am
thinking of attributes like accessModifier and/or revenueModifier.  The
latter may be needed anyway.

Comments welcome.  No hurry.

Erik.