Passenger and cargo distribution
In stock Openttd it is hard to distribute cargo from one source among multiple destinations. You either have to use different vehicles for each destination or set up complicated order systems to do so. Suppose you have a train going between towns A and B. In each of the towns you have a bus network linking several stops to the train station. You might want passengers from any of the bus stops or the train station in A to travel to any of the bus stops or the train station in B and vice versa. In openttd you can have buses in A collect passengers from the various bus stops and transfer them at the train station. There a train can pick them up and transfer then again at the train station in B. You can then have buses in B distribute the passengers among the bus stops by going back and forth between the train station and each bus stop in a star-shaped pattern. Each of the vehicles would use "transfer and leave empty" orders and this solution would not allow passengers to go for B to A, nor to any of the trains stations or between the bus stops within one town. It is possible to allow those additional routes by setting up even more complicated order systems. However, the more stations and vehicles you add the more complicated and unwieldy those systems get.
Cargodist takes care of the transfers automatically and chooses destinations for the passengers involved. In the above example you wouldn't need to specify any "transfer and leave empty" orders, nor would you need to set up star-shaped bus networks. Any bus network in A and B with simple orders will do as long as it's connected to the train station. As passengers would have their own ideas about where to go and which vehicles to take you might see more congestion and a generally higher amount of passengers waiting at any station, though.
There have been several other patches trying to achieve the same thing before. In contrast to the Cargodest project the problems of routing cargo and balancing loads on different routes are seen as inseperable in Cargodist and are thus solved together. Also the definition of transportation demand is seen as precondition to solving above problems and is handled first. The main differences to YACD are that Cargodist a, only considers reachable destinations, not the whole map and b, precomputes the whole routing scheme in separate threads for performance reasons.
The forum topic has some more information. Please post there if you have any questions about Cargodist.
The openttd compile farm builds binaries of cargodist for various platforms every night. You can download them at http://bundles.openttdcoop.org/cargodist/. Then install the same way you'd install a version of openttd without cargodist. See Installation_FAQ for details.
You can also pull from the git repository. It's located at git://github.com/ulfhermann/openttd.git and the relevant branch is "cd". So if you want the latest version of everything, do:
git clone git://github.com/ulfhermann/openttd.git git checkout origin/cd
The "cd" branch is frequently rebased on trunk.
Modes of operation
With Cargodist you get three different modes of distribution for cargo or passengers. You can choose which one to use per cargo in the "Cargo Distribution" group of the advanced settings.
- Manual distribution means that cargo isn't automatically distributed at all. It behaves just like without Cargodist.
- With symmetric distribution the distribution algorithm tries to send the same amount of cargo or passengers in both ways between two stations. This will not always succeed. If you have a single big station where more passengers are generated than in all other stations added up, then obviously there is no symmetric distribution for those. You can influence the strictness of the algorithm with the "amount of returning cargo" setting. If you set it to less than 100% any cargo going in one direction will be matched by less cargo going in the other direction.
- Asymmetric distribution will distribute the cargo or passengers in the network without such restrictions.
Extensions to the smallmap and main viewport
There is a link graph overlay for both the smallmap and the main viewport. It shows stations and available transport links. Links are shown as lines in different colors depending on how much cargo they are carrying related to their capacities. The yellow and red shades are only shown if Cargodist is enabled for the selected cargoes and the link graph calculation has determined that the link has too little capacity for the amount of cargo to be transported there. You should assign more or faster vehicles to the link in this case. White or pale green shades show that the link has too much capacity for the cargo to be transported. You can withdraw some vehicles in this case. It might be a link where vehicles intentionally return empty after delivering there cargo, though.
Stations are shown as squares in the player's color. The bigger the squares the more cargo are passengers are produced and supplied to the station by surrounding industries and houses. The legend for the link graph overlay for the main viewport can be opened from the "map" menu. You can select which players and which cargoes to display there. The overlay for the smallmap is restricted to your own links. There is a new submenu for selecting cargoes to be displayed in the menu section.
Extensions to the station GUI
The station GUI shows the sources, next hops and estimated destinations of the cargo waiting as well as those of the planned cargo flows through the station. Final destinations are only estimated. Don't expect each packet of cargo to go exactly that way. Cargo packets are never split for routing but they may be split to fit into vehicles of different sizes. That means it would be very hard to give the exact numbers here. In the long run everything is still sent to the proper destinations, though.
You can group the cargo by source station, next hop and destination in any order with the "Group by" drop down in the top menu. The subgroups are opened and closed by clicking the little "+" and "-" buttons at the end of the line. You can sort entries within the groups and subgroups by the station they represent or by the amount of cargo displayed. The dropdown above the one for grouping order combines the selection of sort criteria with the selection of mode to be shown (planned or waiting cargo).
When switching on automatic distribution for some cargo it will take a few game days until the cargo is actually distributed. This is because the distribution is periodically calculated and the effect can only be seen after the first calculation. The calculation is done based on link graphs. A link graph is a connected component for one cargo in your network. In the introductory example all stations in the towns A and B would form one link graph. If there is another bus network in a town C which isn't connected to A or B then that forms a different link graph. The more link graphs exist in a game the longer it takes until all of them are calculated.
You can influence how often a new link graph calculation shall be started and how much time to allow for each calculation with the respective settings in the "Cargo Distribution" group of the advanced settings. Indirectly this determines the maximum number of link graphs to calculated in parallel at any time. Link graph calculations are done in separate threads, decoupled from the main game. Those threads are joined at predefined times to maintain network synchronization. For most games on most computers both the interval and the time settings can be decreased quite a bit to reduce the delay between changes to orders and reactions of the link graph. If you set them too low, the game will periodically "hang" while waiting for some link graph calculation thread to finish, though. The default settings are tailored to extremely large games on slow computers so that this never happens. There is another setting which determines the accuracy of link graph calculations. The more accurate the calculation the longer it takes to finish. If you change it you should balance it against the "time" setting.
The setting for the effect of distance on demands determines how much more cargo is sent to nearby stations than to far away stations. You probably don't want to change the short path saturation settings, except for debugging purposes.
Cargodist currently doesn't take some orders with "unload all", "transfer", "no unloading" or "no loading" attributes into account when building the link graph. It does handle any order with a "leave empty" attribute somewhat adequately and it understands any "go via" order (by ignoring it). Any other combinations of "unload all", "transfer", "no unloading" or "no loading" may lead to cargo being planned for loading or unloading at the station referred to by the order even though that is in fact impossible as the respective vehicles are unable to do so with their current orders. It is possible to handle those orders correctly within the current architecture of the link graph. However, as that would be a rather large project on its own and the effect on gameplay is small there is no implementation for that, yet.
Conditional orders are problematic by definition. You can create an undecidable problem for the link graph creation algorithm by having a vehicle's orders depend on load percentage. The shape of the link graph determines which cargo a vehicle will load. The cargo loaded then determines which way it goes and that in turn determines the shape of the link graph. Some of the other conditions' outcomes are very hard to predict in advance without simulating the whole game up to the point when they are to be evaluated normally. The link graph creation and cargo routing algorithms handle that pragmatically and assume that most conditions will just yield the same result when they are evaluated for link graph creation or cargo loading and for vehicle routing. This does not work for load percentage conditions that have to be evaluated in order to decide which cargo to load. Those are evaluated based on cargo available at the station where the vehicle is loading. The condition is evaluated so that the vehicle can load the most cargo available at the station when assumed to take the same decision about the conditional order later on.