Passengers and Cargo distribution, commonly known as "Cargodist", is a feature that enables passengers, mail and all other types of cargo to specify a destination. The cargo will only board vehicles that are bound for their specific destination. Cargodist was originally a patch. As of June 2013, Cargodist is included in trunk; the first stable release to include it was 1.4.0.

Introduction

In classic 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 classic 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 them 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 inseparable 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.

Since June 2013 Cargodist is included in trunk.

Modes of operation

Screenshot of linkgraph overlays

Screenshot of station GUI

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).

Advanced settings

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.

Limitations

Cargodist used to not take some orders with "unload all", "transfer", "no unloading" or "no loading" attributes into account when building the link graph. It still cannot estimate the capacity of related links correctly if you have both vehicles with such modifications and without them on the same route. It will find out if the orders allow cargo from any source to be transported on those links at all, though. That means you shouldn't be able to produce unroutable cargo with those orders.

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 always load greedily. That means they'll load cargo for any station that can potentially be reached with the given conditionals and they won't unload cargo that goes to one of those stations.

The algorithm used to evaluate the conditions and load/unload based on that but this strategy was suboptimal as the same cargo would be loaded and unloaded at the same station.

With the latest changes (in OpenTTD 1.4) you can do things like this, without creating any problems:

Go to LOADING STATION
Go to DROP1
If load percentage equals 0 go to LOADING STATION
Go to DROP2
If load percentage equals 0 go to LOADING STATION
Go to DROP3