NML documentation

# Cargoes

## Cargo variables

Cargos have no variables (yet).

## Cargo properties

name | value range | comment
--- | --- | ---
number | 0..31 | Number of the cargo for bitmasks.
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(cargo callbacks) | Callback flags

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. To combine multiple cargo classes, use the builtin 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 | 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_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 | All cargo classes except CC_SPECIAL. This is the same as `bitmask(CC_PASSENGERS, CC_MAIL, ..., CC_OVERSIZED)`.
ALL_CARGO_CLASSES | All cargo classes. Same as `ALL_NORMAL_CARGO_CLASSES | bitmask(CC_SPECIAL)`

### 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 callbacks

value | description
--- | ---
CARGO_CB_PROFIT | Custom profit calculation
CARGO_CB_STATION_RATING | Custom station rating calculation