OpenTTD AI API: AICargo Class Reference

OpenTTD AI API 13.1

Public Types | Static Public Member Functions
AICargo Class Reference

Class that handles all cargo related functions. More...

Inheritance diagram for AICargo:

## Public Types
enum | CargoClass { CC_PASSENGERS, CC_MAIL, CC_EXPRESS, CC_ARMOURED, CC_BULK, CC_PIECE_GOODS, CC_LIQUID, CC_REFRIGERATED, CC_HAZARDOUS, CC_COVERED }
| The classes of cargo. More...
enum | TownEffect { TE_NONE, TE_PASSENGERS, TE_MAIL, TE_GOODS, TE_WATER, TE_FOOD }
| The effects a cargo can have on a town. More...
enum | SpecialCargoID { CT_AUTO_REFIT, CT_NO_REFIT, CT_INVALID }
| Special cargo types. More...
enum | DistributionType { DT_MANUAL, DT_ASYMMETRIC, DT_SYMMETRIC, INVALID_DISTRIBUTION_TYPE }
| Type of cargo distribution. More...

## Static Public Member Functions
static bool | IsValidCargo (CargoID cargo_type)
| Checks whether the given cargo type is valid. More...
static bool | IsValidTownEffect (TownEffect towneffect_type)
| Checks whether the given town effect type is valid. More...
static char * | GetName (CargoID cargo_type)
| Get the name of the cargo type. More...
static char * | GetCargoLabel (CargoID cargo_type)
| Gets the string representation of the cargo label. More...
static bool | IsFreight (CargoID cargo_type)
| Checks whether the give cargo is a freight or not. More...
static bool | HasCargoClass (CargoID cargo_type, CargoClass cargo_class)
| Check if this cargo is in the requested cargo class. More...
static TownEffect | GetTownEffect (CargoID cargo_type)
| Get the effect this cargo has on a town. More...
static Money | GetCargoIncome (CargoID cargo_type, uint32 distance, uint32 days_in_transit)
| Get the income for transporting a piece of cargo over the given distance within the specified time. More...
static DistributionType | GetDistributionType (CargoID cargo_type)
| Get the cargo distribution type for a cargo. More...
static int64 | GetWeight (CargoID cargo_type, uint32 amount)
| Get the weight in tonnes for the given amount of cargo for the specified type. More...

## Detailed Description

Class that handles all cargo related functions.

## Member Enumeration Documentation

## ◆ CargoClass

enum AICargo::CargoClass

The classes of cargo.

Enumerator
CC_PASSENGERS | Passengers. Cargoes of this class appear at bus stops. Cargoes not of this class appear at truck stops.
CC_MAIL | Mail.
CC_EXPRESS | Express cargo (Goods, Food, Candy, but also possible for passengers)
CC_ARMOURED | Armoured cargo (Valuables, Gold, Diamonds)
CC_BULK | Bulk cargo (Coal, Grain etc., Ores, Fruit)
CC_PIECE_GOODS | Piece goods (Livestock, Wood, Steel, Paper)
CC_LIQUID | Liquids (Oil, Water, Rubber)
CC_REFRIGERATED | Refrigerated cargo (Food, Fruit)
CC_HAZARDOUS | Hazardous cargo (Nuclear Fuel, Explosives, etc.)
CC_COVERED | Covered/Sheltered Freight (Transportation in Box Vans, Silo Wagons, etc.)

## ◆ DistributionType

enum AICargo::DistributionType

Type of cargo distribution.

Enumerator
DT_MANUAL | Manual distribution.
DT_ASYMMETRIC | Asymmetric distribution. Usually cargo will only travel in one direction.
DT_SYMMETRIC | Symmetric distribution. The same amount of cargo travels in each direction between each pair of nodes.
INVALID_DISTRIBUTION_TYPE | Invalid distribution type.

## ◆ SpecialCargoID

enum AICargo::SpecialCargoID

Special cargo types.

Enumerator
CT_AUTO_REFIT | Automatically choose cargo type when doing auto-refitting.
CT_NO_REFIT | Do not refit cargo of a vehicle.
CT_INVALID | An invalid cargo type.

## ◆ TownEffect

enum AICargo::TownEffect

The effects a cargo can have on a town.

Enumerator
TE_NONE | This cargo has no effect on a town.
TE_PASSENGERS | This cargo supplies passengers to a town.
TE_MAIL | This cargo supplies mail to a town.
TE_GOODS | This cargo supplies goods to a town.
TE_WATER | This cargo supplies water to a town.
TE_FOOD | This cargo supplies food to a town.

## Member Function Documentation

## ◆ GetCargoIncome()

static Money AICargo::GetCargoIncome | ( | CargoID | cargo_type,
|  | uint32 | distance,
|  | uint32 | days_in_transit
| ) |  |
| static

Get the income for transporting a piece of cargo over the given distance within the specified time.

Parameters

  cargo_type | The cargo to transport.

Precondition
  AICargo::IsValidCargo(cargo_type).

Parameters

  distance | The distance the cargo travels from begin to end.
  days_in_transit | Amount of (game) days the cargo is in transit. The max value of this variable is 637. Any value higher returns the same as 637 would.

Returns
  The amount of money that would be earned by this trip.

## ◆ GetCargoLabel()

static char* AICargo::GetCargoLabel | ( | CargoID | cargo_type | ) |
| static

Gets the string representation of the cargo label.

Parameters

  cargo_type | The cargo to get the string representation of.

Precondition
  AICargo::IsValidCargo(cargo_type).

Returns
  The cargo label.

Note
  - The label uniquely identifies a specific cargo. Use this if you want to detect special cargos from specific industry set (like production booster cargos, supplies, ...).
  - For more generic cargo support, rather check cargo properties though. For example:
    - Use AICargo::HasCargoClass(..., CC_PASSENGER) to decide bus vs. truck requirements.
    - Use AICargo::GetTownEffect(...) paired with AITown::GetCargoGoal(...) to determine town growth requirements.
  - In other words: Only use the cargo label, if you know more about the behaviour of a specific cargo from a specific industry set, than the API methods can tell you.

## ◆ GetDistributionType()

static DistributionType AICargo::GetDistributionType | ( | CargoID | cargo_type | ) |
| static

Get the cargo distribution type for a cargo.

Parameters

  cargo_type | The cargo to check on.

Returns
  The cargo distribution type for the given cargo.

## ◆ GetName()

static char* AICargo::GetName | ( | CargoID | cargo_type | ) |
| static

Get the name of the cargo type.

Parameters

  cargo_type | The cargo type to get the name of.

Precondition
  IsValidCargo(cargo_type).

Returns
  The name of the cargo type.

## ◆ GetTownEffect()

static TownEffect AICargo::GetTownEffect | ( | CargoID | cargo_type | ) |
| static

Get the effect this cargo has on a town.

Parameters

  cargo_type | The cargo to check on.

Precondition
  AICargo::IsValidCargo(cargo_type).

Returns
  The effect this cargo has on a town, or TE_NONE if it has no effect.

## ◆ GetWeight()

static int64 AICargo::GetWeight | ( | CargoID | cargo_type,
|  | uint32 | amount
| ) |  |
| static

Get the weight in tonnes for the given amount of cargo for the specified type.

Parameters

  cargo_type | The cargo to check on.
  amount | The quantity of cargo.

Precondition
  AICargo::IsValidCargo(cargo_type).

Returns
  The weight in tonnes for that quantity of cargo.

## ◆ HasCargoClass()

static bool AICargo::HasCargoClass | ( | CargoID | cargo_type,
|  | CargoClass | cargo_class
| ) |  |
| static

Check if this cargo is in the requested cargo class.

Parameters

  cargo_type | The cargo to check on.

Precondition
  AICargo::IsValidCargo(cargo_type).

Parameters

  cargo_class | The class to check for.

Returns
  True if and only if the cargo is in the cargo class.

## ◆ IsFreight()

static bool AICargo::IsFreight | ( | CargoID | cargo_type | ) |
| static

Checks whether the give cargo is a freight or not.

This defines whether the "freight train weight multiplier" will apply to trains transporting this cargo.

Parameters

  cargo_type | The cargo to check on.

Precondition
  AICargo::IsValidCargo(cargo_type).

Returns
  True if and only if the cargo is freight.

## ◆ IsValidCargo()

static bool AICargo::IsValidCargo | ( | CargoID | cargo_type | ) |
| static

Checks whether the given cargo type is valid.

Parameters

  cargo_type | The cargo to check.

Returns
  True if and only if the cargo type is valid.

## ◆ IsValidTownEffect()

static bool AICargo::IsValidTownEffect | ( | TownEffect | towneffect_type | ) |
| static

Checks whether the given town effect type is valid.

Parameters

  towneffect_type | The town effect to check.

Returns
  True if and only if the town effect type is valid.