OpenTTD GameScript API  20240328-master-gca53e134be
Public Types | Static Public Member Functions
GSCargo Class Reference

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

Inheritance diagram for GSCargo:

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 std::optional< std::string > GetName (CargoID cargo_type)
 Get the name of the cargo type. More...
 
static std::optional< std::string > 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, SQInteger distance, SQInteger 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 SQInteger GetWeight (CargoID cargo_type, SQInteger 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

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

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

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

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 GSCargo::GetCargoIncome ( CargoID  cargo_type,
SQInteger  distance,
SQInteger  days_in_transit 
)
static

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

Parameters
cargo_typeThe cargo to transport.
Precondition
GSCargo::IsValidCargo(cargo_type).
Parameters
distanceThe distance the cargo travels from begin to end. The value will be clamped to 0 .. MAX(uint32_t).
days_in_transitAmount 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 std::optional<std::string> GSCargo::GetCargoLabel ( CargoID  cargo_type)
static

Gets the string representation of the cargo label.

Parameters
cargo_typeThe cargo to get the string representation of.
Precondition
GSCargo::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 GSCargo::HasCargoClass(..., CC_PASSENGER) to decide bus vs. truck requirements.
    • Use GSCargo::GetTownEffect(...) paired with GSTown::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 GSCargo::GetDistributionType ( CargoID  cargo_type)
static

Get the cargo distribution type for a cargo.

Parameters
cargo_typeThe cargo to check on.
Returns
The cargo distribution type for the given cargo.

◆ GetName()

static std::optional<std::string> GSCargo::GetName ( CargoID  cargo_type)
static

Get the name of the cargo type.

Parameters
cargo_typeThe cargo type to get the name of.
Precondition
IsValidCargo(cargo_type).
Returns
The name of the cargo type.

◆ GetTownEffect()

static TownEffect GSCargo::GetTownEffect ( CargoID  cargo_type)
static

Get the effect this cargo has on a town.

Parameters
cargo_typeThe cargo to check on.
Precondition
GSCargo::IsValidCargo(cargo_type).
Returns
The effect this cargo has on a town, or TE_NONE if it has no effect.

◆ GetWeight()

static SQInteger GSCargo::GetWeight ( CargoID  cargo_type,
SQInteger  amount 
)
static

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

Parameters
cargo_typeThe cargo to check on.
amountThe quantity of cargo. The value will be clamped to 0 .. MAX(uint32_t).
Precondition
GSCargo::IsValidCargo(cargo_type).
Returns
The weight in tonnes for that quantity of cargo.

◆ HasCargoClass()

static bool GSCargo::HasCargoClass ( CargoID  cargo_type,
CargoClass  cargo_class 
)
static

Check if this cargo is in the requested cargo class.

Parameters
cargo_typeThe cargo to check on.
Precondition
GSCargo::IsValidCargo(cargo_type).
Parameters
cargo_classThe class to check for.
Returns
True if and only if the cargo is in the cargo class.

◆ IsFreight()

static bool GSCargo::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_typeThe cargo to check on.
Precondition
GSCargo::IsValidCargo(cargo_type).
Returns
True if and only if the cargo is freight.

◆ IsValidCargo()

static bool GSCargo::IsValidCargo ( CargoID  cargo_type)
static

Checks whether the given cargo type is valid.

Parameters
cargo_typeThe cargo to check.
Returns
True if and only if the cargo type is valid.

◆ IsValidTownEffect()

static bool GSCargo::IsValidTownEffect ( TownEffect  towneffect_type)
static

Checks whether the given town effect type is valid.

Parameters
towneffect_typeThe town effect to check.
Returns
True if and only if the town effect type is valid.