OpenTTD GameScript API: GSTown Class Reference

OpenTTD GameScript API 15.3

Public Types | Static Public Member Functions
GSTown Class Reference

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

`#include <script_town.hpp>`

Inheritance diagram for GSTown:

## Public Types
enum | TownAction { TOWN_ACTION_ADVERTISE_SMALL , TOWN_ACTION_ADVERTISE_MEDIUM , TOWN_ACTION_ADVERTISE_LARGE , TOWN_ACTION_ROAD_REBUILD , TOWN_ACTION_BUILD_STATUE , TOWN_ACTION_FUND_BUILDINGS , TOWN_ACTION_BUY_RIGHTS , TOWN_ACTION_BRIBE }
| Actions that one can perform on a town. More...
enum | TownRating { TOWN_RATING_NONE , TOWN_RATING_APPALLING , TOWN_RATING_VERY_POOR , TOWN_RATING_POOR , TOWN_RATING_MEDIOCRE , TOWN_RATING_GOOD , TOWN_RATING_VERY_GOOD , TOWN_RATING_EXCELLENT , TOWN_RATING_OUTSTANDING , TOWN_RATING_INVALID }
| Different ratings one could have in a town. More...
enum | RoadLayout { ROAD_LAYOUT_ORIGINAL , ROAD_LAYOUT_BETTER_ROADS , ROAD_LAYOUT_2x2 , ROAD_LAYOUT_3x3 , ROAD_LAYOUT_RANDOM , ROAD_LAYOUT_INVALID }
| Possible layouts for the roads in a town. More...
enum | TownSize { TOWN_SIZE_SMALL , TOWN_SIZE_MEDIUM , TOWN_SIZE_LARGE , TOWN_SIZE_INVALID }
| Possible town construction sizes. More...
enum | TownGrowth { TOWN_GROWTH_NONE , TOWN_GROWTH_NORMAL }
| Special values for SetGrowthRate. More...

## Static Public Member Functions
static int | GetTownCount ()
| Gets the number of towns.
static bool | IsValidTown (TownID town_id)
| Checks whether the given town index is valid.
static string | GetName (TownID town_id)
| Get the name of the town.
static bool | SetName (TownID town_id, Text *name)
| Rename a town.
static bool | SetText (TownID town_id, Text *text)
| Set the custom text of a town, shown in the GUI.
static int | GetPopulation (TownID town_id)
| Gets the number of inhabitants in the town.
static int | GetHouseCount (TownID town_id)
| Gets the number of houses in the town.
static TileIndex | GetLocation (TownID town_id)
| Gets the location of the town.
static int | GetLastMonthProduction (TownID town_id, CargoType cargo_type)
| Get the total last economy-month's production of the given cargo at a town.
static int | GetLastMonthSupplied (TownID town_id, CargoType cargo_type)
| Get the total amount of cargo supplied from a town last economy-month.
static int | GetLastMonthTransportedPercentage (TownID town_id, CargoType cargo_type)
| Get the percentage of transported production of the given cargo at a town last economy-month.
static int | GetLastMonthReceived (TownID town_id, GSCargo::TownEffect towneffect_id)
| Get the total amount of cargo effects received by a town last economy-month.
static bool | SetCargoGoal (TownID town_id, GSCargo::TownEffect towneffect_id, int goal)
| Set the goal of a cargo per economy-month for this town.
static int | GetCargoGoal (TownID town_id, GSCargo::TownEffect towneffect_id)
| Get the amount of cargo per economy-month that needs to be delivered (per TownEffect) for a town to grow.
static bool | SetGrowthRate (TownID town_id, int days_between_town_growth)
| Set the amount of economy-days between town growth.
static int | GetGrowthRate (TownID town_id)
| Get the amount of economy-days between town growth.
static int | GetDistanceManhattanToTile (TownID town_id, TileIndex tile)
| Get the manhattan distance from the tile to the GSTown::GetLocation() of the town.
static int | GetDistanceSquareToTile (TownID town_id, TileIndex tile)
| Get the square distance from the tile to the GSTown::GetLocation() of the town.
static bool | IsWithinTownInfluence (TownID town_id, TileIndex tile)
| Find out if this tile is within the rating influence of a town.
static bool | HasStatue (TownID town_id)
| Find out if this town has a statue for the current company.
static bool | IsCity (TownID town_id)
| Find out if the town is a city.
static int | GetRoadReworkDuration (TownID town_id)
| Find out how long the town is undergoing road reconstructions.
static int | GetFundBuildingsDuration (TownID town_id)
| Find out how long new buildings are still being funded in a town.
static GSCompany::CompanyID | GetExclusiveRightsCompany (TownID town_id)
| Find out which company currently has the exclusive rights of this town.
static int | GetExclusiveRightsDuration (TownID town_id)
| Find out how long the town is under influence of the exclusive rights.
static bool | IsActionAvailable (TownID town_id, TownAction town_action)
| Find out if an action can currently be performed on the town.
static bool | PerformTownAction (TownID town_id, TownAction town_action)
| Perform a town action on this town.
static bool | ExpandTown (TownID town_id, int houses)
| Expand the town.
static bool | FoundTown (TileIndex tile, TownSize size, bool city, RoadLayout layout, Text *name)
| Found a new town.
static TownRating | GetRating (TownID town_id, GSCompany::CompanyID company_id)
| Get the rating of a company within a town.
static int | GetDetailedRating (TownID town_id, GSCompany::CompanyID company_id)
| Get the accurate rating of a company within a town.
static bool | ChangeRating (TownID town_id, GSCompany::CompanyID company_id, int delta)
| Change the rating of a company within a town.
static int | GetAllowedNoise (TownID town_id)
| Get the maximum level of noise that still can be added by airports before the town start to refuse building a new airport.
static RoadLayout | GetRoadLayout (TownID town_id)
| Get the road layout for a town.

## Detailed Description

Class that handles all town related functions.

## Member Enumeration Documentation

## ◆ RoadLayout

enum GSTown::RoadLayout

Possible layouts for the roads in a town.

Enumerator
ROAD_LAYOUT_ORIGINAL | Original algorithm (min. 1 distance between roads).
ROAD_LAYOUT_BETTER_ROADS | Extended original algorithm (min. 2 distance between roads).
ROAD_LAYOUT_2x2 | Geometric 2x2 grid algorithm.
ROAD_LAYOUT_3x3 | Geometric 3x3 grid algorithm.
ROAD_LAYOUT_RANDOM | Random road layout.
ROAD_LAYOUT_INVALID | The layout for invalid towns.

## ◆ TownAction

enum GSTown::TownAction

Actions that one can perform on a town.

Enumerator
TOWN_ACTION_ADVERTISE_SMALL | The cargo ratings temporary gains 25% of rating (in absolute percentage, so 10% becomes 35%, with a max of 99%) for all stations within 10 tiles.
TOWN_ACTION_ADVERTISE_MEDIUM | The cargo ratings temporary gains 44% of rating (in absolute percentage, so 10% becomes 54%, with a max of 99%) for all stations within 15 tiles.
TOWN_ACTION_ADVERTISE_LARGE | The cargo ratings temporary gains 63% of rating (in absolute percentage, so 10% becomes 73%, with a max of 99%) for all stations within 20 tiles.
TOWN_ACTION_ROAD_REBUILD | Rebuild the roads of this town for 6 economy-months. See also GSEconomyTime
TOWN_ACTION_BUILD_STATUE | Build a statue in this town.
TOWN_ACTION_FUND_BUILDINGS | Fund the creation of extra buildings for 3 economy-months. See also GSEconomyTime
TOWN_ACTION_BUY_RIGHTS | Buy exclusive rights for this town for 12 economy-months. See also GSEconomyTime
TOWN_ACTION_BRIBE | Bribe the town in order to get a higher rating.

## ◆ TownGrowth

enum GSTown::TownGrowth

Special values for SetGrowthRate.

Enumerator
TOWN_GROWTH_NONE | Town does not grow at all.
TOWN_GROWTH_NORMAL | Use default town growth algorithm instead of custom growth rate.

## ◆ TownRating

enum GSTown::TownRating

Different ratings one could have in a town.

Enumerator
TOWN_RATING_NONE | The company got no rating in the town.
TOWN_RATING_APPALLING | The company got an appalling rating in the town .
TOWN_RATING_VERY_POOR | The company got an very poor rating in the town.
TOWN_RATING_POOR | The company got an poor rating in the town.
TOWN_RATING_MEDIOCRE | The company got an mediocre rating in the town.
TOWN_RATING_GOOD | The company got an good rating in the town.
TOWN_RATING_VERY_GOOD | The company got an very good rating in the town.
TOWN_RATING_EXCELLENT | The company got an excellent rating in the town.
TOWN_RATING_OUTSTANDING | The company got an outstanding rating in the town.
TOWN_RATING_INVALID | The town rating for invalid towns/companies.

## ◆ TownSize

enum GSTown::TownSize

Possible town construction sizes.

Enumerator
TOWN_SIZE_SMALL | Small town.
TOWN_SIZE_MEDIUM | Medium town.
TOWN_SIZE_LARGE | Large town.
TOWN_SIZE_INVALID | Invalid town size.

## Member Function Documentation

## ◆ ChangeRating()

static bool GSTown::ChangeRating | ( | TownID | town_id,
|  | GSCompany::CompanyID | company_id,
|  | int | delta
| ) |  |
| static

Change the rating of a company within a town.

Parameters

  town_id | The town to change the rating in.
  company_id | The company to change the rating for.
  delta | How much to change rating by (range -1000 to +1000).

Returns
  True if the rating was changed.

Precondition
  IsValidTown(town_id).
  GSCompany.ResolveCompanyID(company) != GSCompany::COMPANY_INVALID.
  GSCompanyMode::IsDeity().

## ◆ ExpandTown()

static bool GSTown::ExpandTown | ( | TownID | town_id,
|  | int | houses
| ) |  |
| static

Expand the town.

Parameters

  town_id | The town to expand.
  houses | The amount of houses to grow the town with. The value will be clamped to 0 .. MAX(int).

Precondition
  IsValidTown(town_id).
  houses > 0.
  GSCompanyMode::IsDeity().

Returns
  True if the action succeeded.

## ◆ FoundTown()

static bool GSTown::FoundTown | ( | TileIndex | tile,
|  | TownSize | size,
|  | bool | city,
|  | RoadLayout | layout,
|  | Text * | name
| ) |  |
| static

Found a new town.

Parameters

  tile | The location of the new town.
  size | The town size of the new town.
  city | True if the new town should be a city.
  layout | The town layout of the new town.
  name | The name of the new town. Pass null, or an empty string, to use a random town name.

Precondition
  GSCompanyMode::IsDeity() || GSSettings.GetValue("economy.found_town") != 0.
  GSCompanyMode::IsDeity() || size != TOWN_SIZE_LARGE.
  size != TOWN_SIZE_INVALID.
  layout != ROAD_LAYOUT_INVALID.

Returns
  True if the action succeeded.

Note
  Companies are restricted by the advanced setting that controls if funding towns is allowed or not. If custom road layout is forbidden and there is a company mode in scope (GSCompanyMode::IsValid()), the layout parameter will be ignored.

## ◆ GetAllowedNoise()

static int GSTown::GetAllowedNoise | ( | TownID | town_id | ) |
| static

Get the maximum level of noise that still can be added by airports before the town start to refuse building a new airport.

Parameters

  town_id | The town to get the allowed noise from.

Returns
  The noise that still can be added.

## ◆ GetCargoGoal()

static int GSTown::GetCargoGoal | ( | TownID | town_id,
|  | GSCargo::TownEffect | towneffect_id
| ) |  |
| static

Get the amount of cargo per economy-month that needs to be delivered (per TownEffect) for a town to grow.

All goals need to be reached before a town will grow.

Parameters

  town_id | The index of the town.
  towneffect_id | The index of the towneffect.

Precondition
  IsValidTown(town_id).
  GSCargo::IsValidTownEffect(towneffect_id).

Returns
  The goal of the cargo (amount per economy-month).

Note
  Goals can change over time. For example with a changing snowline, or with a growing town.

See also
  GSEconomyTime

## ◆ GetDetailedRating()

static int GSTown::GetDetailedRating | ( | TownID | town_id,
|  | GSCompany::CompanyID | company_id
| ) |  |
| static

Get the accurate rating of a company within a town.

Parameters

  town_id | The town to get the rating for.
  company_id | The company to get the rating for.

Precondition
  IsValidTown(town_id).
  GSCompany.ResolveCompanyID(company) != GSCompany::COMPANY_INVALID.

Returns
  The rating as a number between -1000 (worst) and 1000 (best).

## ◆ GetDistanceManhattanToTile()

static int GSTown::GetDistanceManhattanToTile | ( | TownID | town_id,
|  | TileIndex | tile
| ) |  |
| static

Get the manhattan distance from the tile to the GSTown::GetLocation() of the town.

Parameters

  town_id | The town to get the distance to.
  tile | The tile to get the distance to.

Precondition
  IsValidTown(town_id).

Returns
  The distance between town and tile.

## ◆ GetDistanceSquareToTile()

static int GSTown::GetDistanceSquareToTile | ( | TownID | town_id,
|  | TileIndex | tile
| ) |  |
| static

Get the square distance from the tile to the GSTown::GetLocation() of the town.

Parameters

  town_id | The town to get the distance to.
  tile | The tile to get the distance to.

Precondition
  IsValidTown(town_id).

Returns
  The distance between town and tile.

## ◆ GetExclusiveRightsCompany()

static GSCompany::CompanyID GSTown::GetExclusiveRightsCompany | ( | TownID | town_id | ) |
| static

Find out which company currently has the exclusive rights of this town.

Parameters

  town_id | The town to check.

Precondition
  IsValidTown(town_id).
  GSCompanyMode::IsValid().

Returns
  The company that has the exclusive rights. The value GSCompany::COMPANY_INVALID means that there are currently no exclusive rights given out to anyone.

## ◆ GetExclusiveRightsDuration()

static int GSTown::GetExclusiveRightsDuration | ( | TownID | town_id | ) |
| static

Find out how long the town is under influence of the exclusive rights.

Parameters

  town_id | The town to check.

Precondition
  IsValidTown(town_id).

Returns
  The number of economy-months the exclusive rights hold. The value 0 means that there are currently no exclusive rights given out to anyone.

See also
  GSEconomyTime

## ◆ GetFundBuildingsDuration()

static int GSTown::GetFundBuildingsDuration | ( | TownID | town_id | ) |
| static

Find out how long new buildings are still being funded in a town.

Parameters

  town_id | The town to check.

Precondition
  IsValidTown(town_id).

Returns
  The number of economy-months building construction is still funded. The value 0 means that there is currently no funding.

See also
  GSEconomyTime

## ◆ GetGrowthRate()

static int GSTown::GetGrowthRate | ( | TownID | town_id | ) |
| static

Get the amount of economy-days between town growth.

Parameters

  town_id | The index of the town.

Precondition
  IsValidTown(town_id).

Returns
  Amount of economy-days between town growth, or TOWN_GROWTH_NONE.

Note
  This function does not indicate when it will grow next. It only tells you the time between growths.

See also
  GSEconomyTime

## ◆ GetHouseCount()

static int GSTown::GetHouseCount | ( | TownID | town_id | ) |
| static

Gets the number of houses in the town.

Parameters

  town_id | The town to get the number of houses of.

Precondition
  IsValidTown(town_id).

Returns
  The number of houses.

## ◆ GetLastMonthProduction()

static int GSTown::GetLastMonthProduction | ( | TownID | town_id,
|  | CargoType | cargo_type
| ) |  |
| static

Get the total last economy-month's production of the given cargo at a town.

Parameters

  town_id | The index of the town.
  cargo_type | The index of the cargo.

Precondition
  IsValidTown(town_id).
  GSCargo::IsValidCargo(cargo_type).

Returns
  The last economy-month's production of the given cargo for this town.

See also
  GSEconomyTime

## ◆ GetLastMonthReceived()

static int GSTown::GetLastMonthReceived | ( | TownID | town_id,
|  | GSCargo::TownEffect | towneffect_id
| ) |  |
| static

Get the total amount of cargo effects received by a town last economy-month.

Parameters

  town_id | The index of the town.
  towneffect_id | The index of the cargo.

Precondition
  IsValidTown(town_id).
  GSCargo::IsValidTownEffect(cargo_type).

Returns
  The amount of cargo received by this town last economy-month for this cargo effect.

See also
  GSEconomyTime

## ◆ GetLastMonthSupplied()

static int GSTown::GetLastMonthSupplied | ( | TownID | town_id,
|  | CargoType | cargo_type
| ) |  |
| static

Get the total amount of cargo supplied from a town last economy-month.

Parameters

  town_id | The index of the town.
  cargo_type | The index of the cargo.

Precondition
  IsValidTown(town_id).
  GSCargo::IsValidCargo(cargo_type).

Returns
  The amount of cargo supplied for transport from this town last economy-month.

See also
  GSEconomyTime

## ◆ GetLastMonthTransportedPercentage()

static int GSTown::GetLastMonthTransportedPercentage | ( | TownID | town_id,
|  | CargoType | cargo_type
| ) |  |
| static

Get the percentage of transported production of the given cargo at a town last economy-month.

Parameters

  town_id | The index of the town.
  cargo_type | The index of the cargo.

Precondition
  IsValidTown(town_id).
  GSCargo::IsValidCargo(cargo_type).

Returns
  The percentage of given cargo transported from this town last economy-month.

See also
  GSEconomyTime

## ◆ GetLocation()

static TileIndex GSTown::GetLocation | ( | TownID | town_id | ) |
| static

Gets the location of the town.

Parameters

  town_id | The town to get the location of.

Precondition
  IsValidTown(town_id).

Returns
  The location of the town.

## ◆ GetName()

static string GSTown::GetName | ( | TownID | town_id | ) |
| static

Get the name of the town.

Parameters

  town_id | The town to get the name of.

Precondition
  IsValidTown(town_id).

Returns
  The name of the town.

## ◆ GetPopulation()

static int GSTown::GetPopulation | ( | TownID | town_id | ) |
| static

Gets the number of inhabitants in the town.

Parameters

  town_id | The town to get the population of.

Precondition
  IsValidTown(town_id).

Returns
  The number of inhabitants.

## ◆ GetRating()

static TownRating GSTown::GetRating | ( | TownID | town_id,
|  | GSCompany::CompanyID | company_id
| ) |  |
| static

Get the rating of a company within a town.

Parameters

  town_id | The town to get the rating for.
  company_id | The company to get the rating for.

Precondition
  IsValidTown(town_id).
  GSCompany.ResolveCompanyID(company) != GSCompany::COMPANY_INVALID.

Returns
  The rating as shown to humans.

## ◆ GetRoadLayout()

static RoadLayout GSTown::GetRoadLayout | ( | TownID | town_id | ) |
| static

Get the road layout for a town.

Parameters

  town_id | The town to get the road layout from.

Returns
  The RoadLayout for the town.

## ◆ GetRoadReworkDuration()

static int GSTown::GetRoadReworkDuration | ( | TownID | town_id | ) |
| static

Find out how long the town is undergoing road reconstructions.

Parameters

  town_id | The town to check.

Precondition
  IsValidTown(town_id).

Returns
  The number of economy-months the road reworks are still going to take. The value 0 means that there are currently no road reworks.

See also
  GSEconomyTime

## ◆ GetTownCount()

static int GSTown::GetTownCount | ( |  | ) |
| static

Gets the number of towns.

Returns
  The number of towns.

## ◆ HasStatue()

static bool GSTown::HasStatue | ( | TownID | town_id | ) |
| static

Find out if this town has a statue for the current company.

Parameters

  town_id | The town to check.

Precondition
  IsValidTown(town_id).
  GSCompanyMode::IsValid().

Returns
  True if the town has a statue.

## ◆ IsActionAvailable()

static bool GSTown::IsActionAvailable | ( | TownID | town_id,
|  | TownAction | town_action
| ) |  |
| static

Find out if an action can currently be performed on the town.

Parameters

  town_id | The town to perform the action on.
  town_action | The action to perform on the town.

Precondition
  IsValidTown(town_id).
  GSCompanyMode::IsValid().

Returns
  True if and only if the action can performed.

## ◆ IsCity()

static bool GSTown::IsCity | ( | TownID | town_id | ) |
| static

Find out if the town is a city.

Parameters

  town_id | The town to check.

Precondition
  IsValidTown(town_id).

Returns
  True if the town is a city.

## ◆ IsValidTown()

static bool GSTown::IsValidTown | ( | TownID | town_id | ) |
| static

Checks whether the given town index is valid.

Parameters

  town_id | The index to check.

Returns
  True if and only if the town is valid.

## ◆ IsWithinTownInfluence()

static bool GSTown::IsWithinTownInfluence | ( | TownID | town_id,
|  | TileIndex | tile
| ) |  |
| static

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

If a station sign would be on this tile, the servicing quality of the station would influence the rating of the town.

Parameters

  town_id | The town to check.
  tile | The tile to check.

Precondition
  IsValidTown(town_id).

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

## ◆ PerformTownAction()

static bool GSTown::PerformTownAction | ( | TownID | town_id,
|  | TownAction | town_action
| ) |  |
| static

Perform a town action on this town.

Parameters

  town_id | The town to perform the action on.
  town_action | The action to perform on the town.

Precondition
  IsValidTown(town_id).
  IsActionAvailable(town_id, town_action).
  GSCompanyMode::IsValid().

Returns
  True if the action succeeded.

## ◆ SetCargoGoal()

static bool GSTown::SetCargoGoal | ( | TownID | town_id,
|  | GSCargo::TownEffect | towneffect_id,
|  | int | goal
| ) |  |
| static

Set the goal of a cargo per economy-month for this town.

Parameters

  town_id | The index of the town.
  towneffect_id | The index of the towneffect.
  goal | The new goal amount for cargo delivered per economy-month. The value will be clamped to 0 .. MAX(int).

Precondition
  IsValidTown(town_id).
  GSCargo::IsValidTownEffect(towneffect_id).
  GSCompanyMode::IsDeity().

Returns
  True if the action succeeded.

See also
  GSEconomyTime

## ◆ SetGrowthRate()

static bool GSTown::SetGrowthRate | ( | TownID | town_id,
|  | int | days_between_town_growth
| ) |  |
| static

Set the amount of economy-days between town growth.

Parameters

  town_id | The index of the town.
  days_between_town_growth | The amount of economy-days between town growth, TOWN_GROWTH_NONE or TOWN_GROWTH_NORMAL.

Precondition
  IsValidTown(town_id).
  days_between_town_growth <= 880 || days_between_town_growth == TOWN_GROWTH_NONE || days_between_town_growth == TOWN_GROWTH_NORMAL.

Returns
  True if the action succeeded.

Note
  Even when setting a growth rate, towns only grow when the conditions for growth (SetCargoCoal) are met, and the game settings (economy.town_growth_rate) allow town growth at all.
  When changing the growth rate, the relative progress is preserved and scaled to the new rate.

See also
  GSEconomyTime

## ◆ SetName()

static bool GSTown::SetName | ( | TownID | town_id,
|  | Text * | name
| ) |  |
| static

Rename a town.

Parameters

  town_id | The town to rename
  name | The new name of the town. If null, or an empty string, is passed, the town name will be reset to the default name.

Precondition
  IsValidTown(town_id).
  GSCompanyMode::IsDeity().

Returns
  True if the action succeeded.

## ◆ SetText()

static bool GSTown::SetText | ( | TownID | town_id,
|  | Text * | text
| ) |  |
| static

Set the custom text of a town, shown in the GUI.

Parameters

  town_id | The town to set the custom text of.
  text | The text to set it to (can be either a raw string, or a GSText object). If null, or an empty string, is passed, the text will be removed.

Precondition
  IsValidTown(town_id).
  GSCompanyMode::IsDeity().

Returns
  True if the action succeeded.