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, CargoID cargo_id)
	Get the total last economy-month's production of the given cargo at a town.

static int	GetLastMonthSupplied (TownID town_id, CargoID cargo_id)
	Get the total amount of cargo supplied from a town last economy-month.

static int	GetLastMonthTransportedPercentage (TownID town_id, CargoID cargo_id)
	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,
		CargoID	cargo_id
	)

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_id	The index of the cargo.

Precondition: IsValidTown(town_id).; GSCargo::IsValidCargo(cargo_id).

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_id).

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,
		CargoID	cargo_id
	)

static

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

Parameters

town_id	The index of the town.
cargo_id	The index of the cargo.

Precondition: IsValidTown(town_id).; GSCargo::IsValidCargo(cargo_id).

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,
		CargoID	cargo_id
	)

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_id	The index of the cargo.

Precondition: IsValidTown(town_id).; GSCargo::IsValidCargo(cargo_id).

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.

Public Types

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ RoadLayout

◆ TownAction

◆ TownGrowth

◆ TownRating

◆ TownSize

Member Function Documentation

◆ ChangeRating()

◆ ExpandTown()

◆ FoundTown()

◆ GetAllowedNoise()

◆ GetCargoGoal()

◆ GetDetailedRating()

◆ GetDistanceManhattanToTile()

◆ GetDistanceSquareToTile()

◆ GetExclusiveRightsCompany()

◆ GetExclusiveRightsDuration()

◆ GetFundBuildingsDuration()

◆ GetGrowthRate()

◆ GetHouseCount()

◆ GetLastMonthProduction()

◆ GetLastMonthReceived()

◆ GetLastMonthSupplied()

◆ GetLastMonthTransportedPercentage()

◆ GetLocation()

◆ GetName()

◆ GetPopulation()

◆ GetRating()

◆ GetRoadLayout()

◆ GetRoadReworkDuration()

◆ GetTownCount()

◆ HasStatue()

◆ IsActionAvailable()

◆ IsCity()

◆ IsValidTown()

◆ IsWithinTownInfluence()

◆ PerformTownAction()

◆ SetCargoGoal()

◆ SetGrowthRate()

◆ SetName()

◆ SetText()