[Rails-devel] Implementation details for revenue calculation

[Stefan F. (web.de) <ste...@we...>]

Back after some travel: Fortunately I could assign some travel time (it is 
special fun to work on Rails at times you travel on rails) to think about the 
special rules and prepare some refactoring for it. 
And I thank for all the comments on the revenue details.

Stefan

I assume that the order of games supported will be
1. 1830, 1889
2. 1856, 18AL
3. 1835, 18Kaas
4. 18EU, 1851

Most likely only 1830 and 1889 will be supported in the first release of 
revenue calculation.

Some general remark  first:
The revenue calculator works on a abstract level, where vertexes consists only 
of the numerical id, the value and their neighbors.  The trains are only 
defined by their length and if they count minors(towns).

In a similar fashion bonuses will be defined on the abstract objects.
The transformation of the specific (and usually more complex) rules is the 
task of the revenue adapter and if the rules are game specific only of 
classes that use defined interfaces of the revenue adapter. 

The main idea is to protect the revenue calculator against the specific rules 
of the games which could potentially conflict with the correctness of the 
calculation and to allow refactoring of the calculator without breaking the 
implementation of the specific rules.


The general special rules:

A) Vertex value can be train dependent
For the revenue calculator the vertex value is also dependent on the train 
identifier. This allows to add train dependent bonuses to each vertex.
Another advantage is that no special properties for trains that for example
double station values is required anymore. Instead simply the vertex value are 
changed.

B) Bonus combinations
A bonus combination consists of #N vertexes, if all of them are visited the 
bonus value is added to this train run.

C) Linked vertexes
If vertex A is visited then vertex B is considered as visited (without 
counting its value).

D) Definition of additional vertexes
In the xml files additional (virtual) vertexes can be defined.

This should allow to cover many rules, some examples (and an exception) are 
given in the following section. 

Specific implementations:

1) Multi-Hex offboard areas (several games)
It is an application of linked vertexes (C). Another issue is the definition 
of the offboard city. It is usually a sink, thus I define those as stations 
with zero token slots, thus they are always tokened out. But that will not 
work for Hamburg in 18EU, which is a zero-slot, but run-through station.

2) 1889
Offboard hexes have a special value for diesels only. This is done via train 
dependent vertex values (A).

3) 1835
Berlin: No revisit of Berlin stations allowed is an example for linked 
vertexes (C).

Hamburg: The reduced value for the Elbe ferry  is defined as several 
(negative) bonus (-10) combinations: Those are all combinations of two hex 
sides of the Hamburg hex, that define a crossing of the Elbe (B).

4) 18EU
Offboard-2-Offboard: That is a very long list of all potential combinations of 
the vertexes with station tokens and the offboard vertexes in the reach of 
the running company (B).
This clearly shows the principle: Instead of implementing the precise rule of 
18EU in the calculator, a long list of basic bonus types is used.

Paris, Berlin, Vienna: as in 1835 (C).

Hamburg: I have to admit that I do not like the Hamburg offboard tile: The 
graphical representation does not define exactly, where the value vertex is, 
as it does not contain any type of station.
I assume the most natural interpretation is to assume a non-tokenable station 
in the middle of the hex (similar to tile 12, only that the slot cannot be 
filled). To work with the offboard bonuses, an additional vertex is connected 
to the station vertex, which acts as a sink (has no neighbors defined, thus 
similar to a tokened out station). All of the bonus combinations for Hamburg 
use that vertex to enforce the restriction that the bonus runs have to stop 
in Hamburg. (D)

Pullman: If I understand the 18EU rules correctly, the Pullman is an exception 
to the second sentence under 4.4.3: "... must calculate the maximum possible 
earnings". 4.4.9., second paragraph defines that "... doubles the value of 
any City or Off-Map Location of the President's choice".
To capture the spirit of the rules and to simplify things the Pullman will not 
be part of the maximization process, but the President will be prompted to 
select one the city values of the runs. 

5) 1851
Offboard-2-Offboard: see 18EU

6) 1856
Bonus tokens: Simple application of (A)

7) 18AL
Named trains: Train dependent application of (A)

8) 18Kaas
Ruhr: Long list of all cities/value vertexes combined with the Ruhr vertex, 
that doubles the value of each city (B).