OpenTTD GameScript API: GSStation Class Reference

OpenTTD GameScript API 14.0-RC3

Public Types | Static Public Member Functions
GSStation Class Reference

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

Inheritance diagram for GSStation:

## Public Types
enum | ErrorMessages { ERR_STATION_BASE, ERR_STATION_TOO_CLOSE_TO_ANOTHER_STATION, ERR_STATION_TOO_MANY_STATIONS, ERR_STATION_TOO_MANY_STATIONS_IN_TOWN }
| All station related error messages. More...
enum | StationType { STATION_TRAIN, STATION_TRUCK_STOP, STATION_BUS_STOP, STATION_AIRPORT, STATION_DOCK, STATION_ANY }
| Type of stations known in the game. More...
Public Types inherited from GSBaseStation
enum | SpecialStationIDs { STATION_NEW, STATION_JOIN_ADJACENT, STATION_INVALID }
| Special station IDs for building adjacent/new stations when the adjacent/distant join features are enabled. More...

## Static Public Member Functions
static bool | IsValidStation (StationID station_id)
| Checks whether the given station is valid and owned by you. More...
static GSCompany::CompanyID | GetOwner (StationID station_id)
| Get the owner of a station. More...
static StationID | GetStationID (TileIndex tile)
| Get the StationID of a tile, if there is a station. More...
static SQInteger | GetCargoWaiting (StationID station_id, CargoID cargo_id)
| See how much cargo there is waiting on a station. More...
static SQInteger | GetCargoWaitingFrom (StationID station_id, StationID from_station_id, CargoID cargo_id)
| See how much cargo with a specific source station there is waiting on a station. More...
static SQInteger | GetCargoWaitingVia (StationID station_id, StationID via_station_id, CargoID cargo_id)
| See how much cargo with a specific via-station there is waiting on a station. More...
static SQInteger | GetCargoWaitingFromVia (StationID station_id, StationID from_station_id, StationID via_station_id, CargoID cargo_id)
| See how much cargo with a specific via-station and source station there is waiting on a station. More...
static SQInteger | GetCargoPlanned (StationID station_id, CargoID cargo_id)
| See how much cargo was planned to pass (including production and consumption) this station per month. More...
static SQInteger | GetCargoPlannedFrom (StationID station_id, StationID from_station_id, CargoID cargo_id)
| See how much cargo from the specified origin was planned to pass (including production and consumption) this station per month. More...
static SQInteger | GetCargoPlannedVia (StationID station_id, StationID via_station_id, CargoID cargo_id)
| See how much cargo was planned to pass (including production and consumption) this station per month, heading for the specified next hop. More...
static SQInteger | GetCargoPlannedFromVia (StationID station_id, StationID from_station_id, StationID via_station_id, CargoID cargo_id)
| See how much cargo from the specified origin was planned to pass this station per month, heading for the specified next hop. More...
static bool | HasCargoRating (StationID station_id, CargoID cargo_id)
| Check whether the given cargo at the given station a rating. More...
static SQInteger | GetCargoRating (StationID station_id, CargoID cargo_id)
| See how high the rating is of a cargo on a station. More...
static SQInteger | GetCoverageRadius (GSStation::StationType station_type)
| Get the coverage radius of this type of station. More...
static SQInteger | GetStationCoverageRadius (StationID station_id)
| Get the coverage radius of this station. More...
static SQInteger | GetDistanceManhattanToTile (StationID station_id, TileIndex tile)
| Get the manhattan distance from the tile to the GSStation::GetLocation() of the station. More...
static SQInteger | GetDistanceSquareToTile (StationID station_id, TileIndex tile)
| Get the square distance from the tile to the GSStation::GetLocation() of the station. More...
static bool | IsWithinTownInfluence (StationID station_id, TownID town_id)
| Find out if this station is within the rating influence of a town. More...
static bool | HasStationType (StationID station_id, StationType station_type)
| Check if any part of the station contains a station of the type StationType. More...
static bool | HasRoadType (StationID station_id, GSRoad::RoadType road_type)
| Check if any part of the station contains a station of the type RoadType. More...
static TownID | GetNearestTown (StationID station_id)
| Get the town that was nearest to the given station when the station was built. More...
static bool | IsAirportClosed (StationID station_id)
| Get the open/closed state of an airport. More...
static bool | OpenCloseAirport (StationID station_id)
| Toggle the open/closed state of an airport. More...
Static Public Member Functions inherited from GSBaseStation
static bool | IsValidBaseStation (StationID station_id)
| Checks whether the given basestation is valid and owned by you. More...
static std::optional< std::string > | GetName (StationID station_id)
| Get the name of a basestation. More...
static bool | SetName (StationID station_id, Text *name)
| Set the name this basestation. More...
static TileIndex | GetLocation (StationID station_id)
| Get the current location of a basestation. More...
static GSDate::Date | GetConstructionDate (StationID station_id)
| Get the last date a station part was added to this station. More...

## Detailed Description

Class that handles all station related functions.

## Member Enumeration Documentation

## ◆ ErrorMessages

enum GSStation::ErrorMessages

All station related error messages.

Enumerator
ERR_STATION_BASE | Base for station related errors.
ERR_STATION_TOO_CLOSE_TO_ANOTHER_STATION | The station is build too close to another station, airport or dock.
ERR_STATION_TOO_MANY_STATIONS | There are too many stations, airports and docks in the game.
ERR_STATION_TOO_MANY_STATIONS_IN_TOWN | There are too many stations, airports of docks in a town.

## ◆ StationType

enum GSStation::StationType

Type of stations known in the game.

Enumerator
STATION_TRAIN | Train station.
STATION_TRUCK_STOP | Truck station.
STATION_BUS_STOP | Bus station.
STATION_AIRPORT | Airport.
STATION_DOCK | Dock.
STATION_ANY | All station types.

## Member Function Documentation

## ◆ GetCargoPlanned()

static SQInteger GSStation::GetCargoPlanned | ( | StationID | station_id,
|  | CargoID | cargo_id
| ) |  |
| static

See how much cargo was planned to pass (including production and consumption) this station per month.

Parameters

  station_id | The station to get the planned flow for.
  cargo_id | The cargo type to get the planned flow for.

Precondition
  IsValidStation(station_id).
  IsValidCargo(cargo_id).

Returns
  The amount of cargo units planned to pass the station per month.

## ◆ GetCargoPlannedFrom()

static SQInteger GSStation::GetCargoPlannedFrom | ( | StationID | station_id,
|  | StationID | from_station_id,
|  | CargoID | cargo_id
| ) |  |
| static

See how much cargo from the specified origin was planned to pass (including production and consumption) this station per month.

Parameters

  station_id | The station to get the planned flow for.
  from_station_id | The station the cargo originates at.
  cargo_id | The cargo type to get the planned flow for.

Precondition
  IsValidStation(station_id).
  IsValidStation(from_station_id) || from_station_id == STATION_INVALID.
  IsValidCargo(cargo_id).

Returns
  The amount of cargo units from the specified origin planned to pass the station per month.

## ◆ GetCargoPlannedFromVia()

static SQInteger GSStation::GetCargoPlannedFromVia | ( | StationID | station_id,
|  | StationID | from_station_id,
|  | StationID | via_station_id,
|  | CargoID | cargo_id
| ) |  |
| static

See how much cargo from the specified origin was planned to pass this station per month, heading for the specified next hop.

Parameters

  station_id | The station to get the planned flow for.
  from_station_id | The station the cargo originates at.
  via_station_id | The next station the cargo will go on to.
  cargo_id | The cargo type to get the planned flow for.

Precondition
  IsValidStation(station_id).
  IsValidStation(from_station_id) || from_station_id == STATION_INVALID.
  IsValidStation(via_station_id) || via_station_id == STATION_INVALID.
  IsValidCargo(cargo_id).

Returns
  The amount of cargo units from the specified origin planned to pass the station per month, going via the specified next hop.

Note
  Cargo planned to go "via" the same station that's being queried is actually planned to be consumed there.
  Cargo planned to pass "from" the same station that's being queried is actually produced there.

## ◆ GetCargoPlannedVia()

static SQInteger GSStation::GetCargoPlannedVia | ( | StationID | station_id,
|  | StationID | via_station_id,
|  | CargoID | cargo_id
| ) |  |
| static

See how much cargo was planned to pass (including production and consumption) this station per month, heading for the specified next hop.

Parameters

  station_id | The station to get the planned flow for.
  via_station_id | The next station the cargo will go on to.
  cargo_id | The cargo type to get the planned flow for.

Precondition
  IsValidStation(station_id).
  IsValidStation(via_station_id) || via_station_id == STATION_INVALID.
  IsValidCargo(cargo_id).

Returns
  The amount of cargo units planned to pass the station per month, going via the specified next hop.

Note
  Cargo planned to go "via" the same station that's being queried is actually planned to be consumed there.

## ◆ GetCargoRating()

static SQInteger GSStation::GetCargoRating | ( | StationID | station_id,
|  | CargoID | cargo_id
| ) |  |
| static

See how high the rating is of a cargo on a station.

Parameters

  station_id | The station to get the cargo-rating of.
  cargo_id | The cargo to get the cargo-rating of.

Precondition
  IsValidStation(station_id).
  IsValidCargo(cargo_id).
  HasCargoRating(station_id, cargo_id).

Returns
  The rating in percent of the cargo on the station.

## ◆ GetCargoWaiting()

static SQInteger GSStation::GetCargoWaiting | ( | StationID | station_id,
|  | CargoID | cargo_id
| ) |  |
| static

See how much cargo there is waiting on a station.

Parameters

  station_id | The station to get the cargo-waiting of.
  cargo_id | The cargo to get the cargo-waiting of.

Precondition
  IsValidStation(station_id).
  IsValidCargo(cargo_id).

Returns
  The amount of units waiting at the station.

## ◆ GetCargoWaitingFrom()

static SQInteger GSStation::GetCargoWaitingFrom | ( | StationID | station_id,
|  | StationID | from_station_id,
|  | CargoID | cargo_id
| ) |  |
| static

See how much cargo with a specific source station there is waiting on a station.

Parameters

  station_id | The station to get the cargo-waiting of.
  from_station_id | The source station of the cargo. Pass STATION_INVALID to get cargo of which the source has been deleted.
  cargo_id | The cargo to get the cargo-waiting of.

Precondition
  IsValidStation(station_id).
  IsValidStation(from_station_id) || from_station_id == STATION_INVALID.
  IsValidCargo(cargo_id).

Returns
  The amount of units waiting at the station originating from from_station_id.

Note
  source station means, the station where cargo was first loaded.

## ◆ GetCargoWaitingFromVia()

static SQInteger GSStation::GetCargoWaitingFromVia | ( | StationID | station_id,
|  | StationID | from_station_id,
|  | StationID | via_station_id,
|  | CargoID | cargo_id
| ) |  |
| static

See how much cargo with a specific via-station and source station there is waiting on a station.

Parameters

  station_id | The station to get the cargo-waiting of.
  from_station_id | The source station of the cargo. Pass STATION_INVALID to get cargo of which the source has been deleted.
  via_station_id | The next station the cargo is going to. Pass STATION_INVALID to get waiting cargo for "via any station".
  cargo_id | The cargo to get the cargo-waiting of.

Precondition
  IsValidStation(station_id).
  IsValidStation(from_station_id) || from_station_id == STATION_INVALID.
  IsValidStation(via_station_id) || via_station_id == STATION_INVALID.
  IsValidCargo(cargo_id).

Returns
  The amount of units waiting at the station with from_station_id as source and via_station_id as next hop.

Note
  if GSCargo.GetCargoDistributionType(cargo_id) == GSCargo.DT_MANUAL, then all waiting cargo will have STATION_INVALID as next hop.

## ◆ GetCargoWaitingVia()

static SQInteger GSStation::GetCargoWaitingVia | ( | StationID | station_id,
|  | StationID | via_station_id,
|  | CargoID | cargo_id
| ) |  |
| static

See how much cargo with a specific via-station there is waiting on a station.

Parameters

  station_id | The station to get the cargo-waiting of.
  via_station_id | The next station the cargo is going to. Pass STATION_INVALID to get waiting cargo for "via any station".
  cargo_id | The cargo to get the cargo-waiting of.

Precondition
  IsValidStation(station_id).
  IsValidStation(via_station_id) || via_station_id == STATION_INVALID.
  IsValidCargo(cargo_id).

Returns
  The amount of units waiting at the station with via_station_id as next hop.

Note
  if GSCargo.GetCargoDistributionType(cargo_id) == GSCargo.DT_MANUAL, then all waiting cargo will have STATION_INVALID as next hop.

## ◆ GetCoverageRadius()

static SQInteger GSStation::GetCoverageRadius | ( | GSStation::StationType | station_type | ) |
| static

Get the coverage radius of this type of station.

Parameters

  station_type | The type of station.

Precondition
  station_type != STATION_AIRPORT.

Returns
  The radius in tiles.

Note
  Coverage radius of airports needs to be requested via GSAirport::GetAirportCoverageRadius(), as it requires AirportType.

## ◆ GetDistanceManhattanToTile()

static SQInteger GSStation::GetDistanceManhattanToTile | ( | StationID | station_id,
|  | TileIndex | tile
| ) |  |
| static

Get the manhattan distance from the tile to the GSStation::GetLocation() of the station.

Parameters

  station_id | The station to get the distance to.
  tile | The tile to get the distance to.

Precondition
  IsValidStation(station_id).

Returns
  The distance between station and tile.

## ◆ GetDistanceSquareToTile()

static SQInteger GSStation::GetDistanceSquareToTile | ( | StationID | station_id,
|  | TileIndex | tile
| ) |  |
| static

Get the square distance from the tile to the GSStation::GetLocation() of the station.

Parameters

  station_id | The station to get the distance to.
  tile | The tile to get the distance to.

Precondition
  IsValidStation(station_id).

Returns
  The distance between station and tile.

## ◆ GetNearestTown()

static TownID GSStation::GetNearestTown | ( | StationID | station_id | ) |
| static

Get the town that was nearest to the given station when the station was built.

Parameters

  station_id | The station to look at.

Returns
  The TownID of the town whose center tile was closest to the station at the time the station was built.

Note
  There is no guarantee that the station is even near the returned town nor that the returns town is closest to the station now. A station that was 'walked' to the other end of the map will still return the same town. Also, towns grow, towns change. So don't depend on this value too much.

## ◆ GetOwner()

static GSCompany::CompanyID GSStation::GetOwner | ( | StationID | station_id | ) |
| static

Get the owner of a station.

Parameters

  station_id | The station to get the owner of.

Precondition
  IsValidStation(station_id).

Returns
  The owner the station has.

## ◆ GetStationCoverageRadius()

static SQInteger GSStation::GetStationCoverageRadius | ( | StationID | station_id | ) |
| static

Get the coverage radius of this station.

Parameters

  station_id | The station to get the coverage radius of.

Precondition
  IsValidStation(station_id).

Returns
  The radius in tiles.

## ◆ GetStationID()

static StationID GSStation::GetStationID | ( | TileIndex | tile | ) |
| static

Get the StationID of a tile, if there is a station.

Parameters

  tile | The tile to find the stationID of

Returns
  StationID of the station.

Postcondition
  Use IsValidStation() to see if the station is valid.

## ◆ HasCargoRating()

static bool GSStation::HasCargoRating | ( | StationID | station_id,
|  | CargoID | cargo_id
| ) |  |
| static

Check whether the given cargo at the given station a rating.

Parameters

  station_id | The station to get the cargo-rating state of.
  cargo_id | The cargo to get the cargo-rating state of.

Precondition
  IsValidStation(station_id).
  IsValidCargo(cargo_id).

Returns
  True if the cargo has a rating, otherwise false.

## ◆ HasRoadType()

static bool GSStation::HasRoadType | ( | StationID | station_id,
|  | GSRoad::RoadType | road_type
| ) |  |
| static

Check if any part of the station contains a station of the type RoadType.

Parameters

  station_id | The station to look at.
  road_type | The RoadType to look for.

Returns
  True if the station has a station part of the type RoadType.

## ◆ HasStationType()

static bool GSStation::HasStationType | ( | StationID | station_id,
|  | StationType | station_type
| ) |  |
| static

Check if any part of the station contains a station of the type StationType.

Parameters

  station_id | The station to look at.
  station_type | The StationType to look for.

Returns
  True if the station has a station part of the type StationType.

## ◆ IsAirportClosed()

static bool GSStation::IsAirportClosed | ( | StationID | station_id | ) |
| static

Get the open/closed state of an airport.

Parameters

  station_id | The airport to look at.

Precondition
  IsValidStation(station_id).
  HasStationType(station_id, STATION_AIRPORT).

Returns
  True if the airport is currently closed to incoming traffic.

## ◆ IsValidStation()

static bool GSStation::IsValidStation | ( | StationID | station_id | ) |
| static

Checks whether the given station is valid and owned by you.

Parameters

  station_id | The station to check.

Returns
  True if and only if the station is valid.

## ◆ IsWithinTownInfluence()

static bool GSStation::IsWithinTownInfluence | ( | StationID | station_id,
|  | TownID | town_id
| ) |  |
| static

Find out if this station is within the rating influence of a town.

The service quality of stations with signs within this radius influences the rating of the town.

Parameters

  station_id | The station to check.
  town_id | The town to check.

Returns
  True if the tile is within the rating influence of the town.

## ◆ OpenCloseAirport()

static bool GSStation::OpenCloseAirport | ( | StationID | station_id | ) |
| static

Toggle the open/closed state of an airport.

Parameters

  station_id | The airport to modify.

Precondition
  GSCompanyMode::IsValid().
  IsValidStation(station_id).
  HasStationType(station_id, STATION_AIRPORT).

Returns
  True if the state was toggled successfully.