NML:Cargos
Vehicles, Stations, Canals, Bridges, Towns, Houses, Industries (Tiles), Cargos, Airports+Tiles, Objects, Railtypes, Roadtypes, Tramtypes, Terrain
- common props | vars | CBs
- train | roadveh | ship | aircr props
- common variables
- industry props | vars | CBs
- tile props | vars | CBs
- airport props | vars | CBs
- tile props | vars | CBs
Cargo IDs
For cargos, the item ID corresponds to the cargo type slot of the cargo. TTD default cargos occupy slots 0-11, so if you want to define a new cargo be sure to set this ID to 12 or higher. It is recommended to set the 'number'-property to the same value as the item ID.
Cargo properties
| name | value range | comment |
|---|---|---|
| number | 0..31 | Number of the cargo for bitmasks. This mostly affects old NewGRFs that don't have a cargo translation table. |
| type_name | string | TextID for the cargo type name. Example string: "Passengers" |
| unit_name | string | TextID for the name of one unit from the cargo type. Currently used for subsidies only (First Passenger service to..). Example string: "Passenger" |
| single_unit_text | string | TextID to be displayed for 1 unit of cargo. Example string: "{WORD_S} ton of Stuff" |
| multiple_units_text | string | TextID to be displayed for multiple units of cargo. Example string: "{WORD_S} tonnes of Stuff" |
| type_abbreviation | string | TextID for cargo type abbreviation. Example string: "{TINYFONT}XX" |
| sprite | sprite | TTD sprite number for the icon of the cargo. Alternatively, set to NEW_CARGO_SPRITE and use a graphics block to define a custom sprite. |
| weight | float 0..255 | Weight of one unit of the cargo (in tons) |
| penalty_lowerbound | 0..255 | Delivery time until penalty is applied |
| single_penalty_length | 0..255 | Length of the interval where a single penalty is applied |
| price_factor | float | Payment for delivering 10 units of cargo across a distance of 20 squares (in British Pounds). |
| station_list_colour | 0..255 |
Colour for the station list window (index from the DOS palette) |
| cargo_payment_list_colour | 0..255 |
Colour for the cargo payment list window (index from the DOS palette) |
| is_freight | 0 or 1 | Freight status (for the freighttrains switch); 0=not freight, 1=is freight |
| cargo_classes |
bitmask(cargo classes) |
Cargo classes |
| cargo_label | 4 letters | Cargo label, as used in the cargo table |
| town_growth_effect | TOWNGROWTH_XXX |
Effect for town growth, see Cargo effects on town growth |
| town_growth_multiplier | float 0..255 | Multiplier for town growth. To be used in conjuction with town_growth_effect, when that is not TOWNGROWTH_NONE. For example, a value of 4 makes your cargo have the same effect on town growth as 4 units of food/goods/etc. |
| callback_flags | bitmask(flags) |
Do not set this, unless you use old-style callbacks. |
| capacity_multiplier | float 0 .. 255 |  1.2 This defines the capacity of vehicles carrying this cargo type, if the vehicle sets no specific capacity to this specific cargo type. Set this property to the amount of cargo a vehicle shall carry, which can carry 1 ton of coal or 1000 thousand litres of water (whatever comparison is more suitable for your cargotype). Depending on whether your cargo type is light or heavy you should set this property either comparing the weight or the volume. Default values are 4 for passengers, 2 for mail, goods and sweets and 1 for all other cargos.
|
Cargo payment is computed from price_factor, amount of cargo transported, distance, and a time delivery factor. Unit of the delivery time is 185 ticks, roughly 2.5 days. The factor is constant (with value 255) if delivery time is less than penalty_lowerbound. It goes down with rate 1 between penalty_lowerbound + single_penalty_length, and goes down with rate 2 if the delivery time is even longer. Time delivery factor is never less than 31.
Cargo classes
Available cargo classes are listed in the following table. Cargos may be in more than one class. Cargo classes are always used as a bitmask, use the built-in function bitmask(). For example, bitmask(CC_EXPRESS, CC_REFRIGERATED) is used for food.
| name | type of cargo |
|---|---|
| CC_PASSENGERS | passengers, also tourists (ECS) |
| CC_MAIL | |
| CC_EXPRESS | express goods, also tourists (ECS) |
| CC_ARMOURED | valuables, diamonds, gold and alike |
| CC_BULK | coal, ore, grain,... |
| CC_PIECE_GOODS | containers, crates, livestock |
| CC_LIQUID | oil, milk, water, ... |
| CC_REFRIGERATED | food, milk, ... |
| CC_HAZARDOUS | chemicals?, uranium, ... |
| CC_COVERED | grain, cement, fruit, ... |
| CC_OVERSIZED | vehicles, ... |
| CC_POWDERIZED | cement, ... |
| CC_NON_POURABLE CC_NEO_BULK |
sugar cane, wool or straw bales, ... |
| CC_SPECIAL | Special cargo, used for refit tricks. (e.g. regearing in NARS) |
| NO_CARGO_CLASS | Special value that you can used to instead of 0. |
| ALL_NORMAL_CARGO_CLASSES | Bitmask of all cargo classes except CC_SPECIAL. This is the same as bitmask(CC_PASSENGERS, CC_MAIL, ..., CC_OVERSIZED). Note: This is already a bitmask, don't use the bitmask(..) function with this.
|
| ALL_CARGO_CLASSES | bitmask(CC_SPECIAL) Note: This is already a bitmask, don't use the bitmask(..) function with this.
|
Cargo effects on town growth
| value | effect |
|---|---|
| TOWNGROWTH_PASSENGERS | Affect towns as passengers do |
| TOWNGROWTH_MAIL | Affect towns as mail does |
| TOWNGROWTH_GOODS | Affect towns as goods/candy does |
| TOWNGROWTH_WATER | Affect towns as water does (second required cargo for towngrowth in the desert) |
| TOWNGROWTH_FOOD | Affect towns as food/fizzy drinks do (first required cargo for towngrowth in desert/above snowline) |
| TOWNGROWTH_NONE | Don't affect town growth (default) |
Cargo variables
Cargos have no variables (yet).
Cargo callbacks
| callback | return value | comment |
|---|---|---|
| default | Sprite set (with 1 sprite) | Graphics for the cargo icon (only if property sprite is set to NEW_CARGO_SPRITE)
|
| station_rating | -16384 .. 16383 | See detailed explanation below |
| profit | -12748 .. 12748 | Called whenever cargo is delivered. extra_callback_info2 contains 0xttaadddd with tt being the time spent en-route (1 unit = 2.5 days), aa the amount of cargo delivered and dddd the manhattan distance it was transported. The returned value is multiplied by the amount and the price_factor and then divided by 256 to determine the income the player receives. Returning negative values is possible, it makes players pay for the delivery.
|
Station rating callback
The station rating callback is quite complicated and deserves some detailed explanation. The default station rating calculation works as follows:
Internally, station rating is byte with values 0 .. 255, representing respectively 0% and 100%. Every 2.5 days, the transportation 'performance' is calculated using some factors outlined below. The station rating is then set to this performance value, with the caveat that the rating change cannot exceed 2 points. Therefore, rating changes are always slow, this callback cannot change this. The initial rating is 175 points (69%). The following factors are parts of the performance, their effects are summed.
Time since the cargo was last picked up
| Time units (days) | Score (%, rounded) |
|---|---|
| >21 (>52.5 days) | 0 (0%) |
| 13 .. 21 (32.5 days .. 52.5 days) | 25 (10%) |
| 7 .. 12 (17.5 days .. 32.5 days) | 50 (20%) |
| 4 .. 6 (10 days .. 17.5 days) | 95 (37%) |
| 0..3 (0 days..10 days) | 130 (51%) |
The time unit used equals 185 engine ticks, or 2.5 TTD days. For ships, the time units are divided by 4 before calculating this component, so ships have four times more time before the ratings start dropping.
Amount of cargo waiting
| Amount of cargo | Score (%, rounded) |
|---|---|
| >1500 | -90 (-35%) |
| 1001..1500 | -35 (-14%) |
| 601..1000 | 0 (0%) |
| 301..600 | 10 (4%) |
| 101..300 | 30 (12%) |
| 0..100 | 40 (16%) |
Max. speed of the last vehicle picking up the cargo
This calculation is somewhat complicated. The maximum speed of the vehicle is expressed in "speed units". For trains and road vehicles, the speed unit is 1 km/h; for ships, it's 0.5 km/h; for aircraft, it's 8 mph. If the max. speed is above 255 speed units, 255 is used instead. If the vehicle is slower than 85 units, no points are awarded; otherwise, you get (speed_units-85)/4 points. Therefore, the maximum you can get is 42 points, or 16%.
Age of the last carrier picking up the cargo
| Age of vehicle (years) | Score (%, rounded) |
|---|---|
| 2 | 10 (4%) |
| 1 | 20 (8%) |
| 0 | 33 (13%) |
In TTDPatch this changes when the 'newagerating' switch is enabled
Bonus for AI companies (TTDPatch only)
| AI intelligence setting | Score (%, rounded) |
|---|---|
| Low | 0 (0%) |
| Medium | 31 (12%) |
| High | 63 (25%) |
Bonus for statue in nearest town
If your company has erected a statue in the nearest town, you get 26 points (10%) bonus to all cargo ratings.
Callback parameters
During the callback, extra_callback_info1 contains one of the following values in the lowest byte:
| value | meaning |
|---|---|
| 0x10 | the last vehicle entering the station was a train |
| 0x11 | the last vehicle entering the station was a road vehicle |
| 0x12 | the last vehicle entering the station was a ship |
| 0x13 | the last vehicle entering the station was an aircraft |
| 0 | no vehicle entered the station yet, or (TTDPatch) the last one entering was sold |
Please note that there's only one "last vehicle type" field per station, so the vehicle this refers to may not have picked up any of your cargo.
extra_callback_info2 has the value 0xssaaaatt, where
ttis the time since the cargo was last picked up, in the time units described above (1 unit = 2.5 days independent of vehicle type)aaaais the amount of cargo waitingssis the speed of the last vehicle picking the cargo up, in the speed units described above (if no vehicle entered the station yet, the value is 0xFF)
Effect of callback
The return value of the callback replaces the first three components (time since pickup, amount of cargo, max speed) of the calculation. The bonus for statues, TTDPatch AIs and new vehicles is always in effect, you cannot (yet) change this.
