OpenTTD AI API: AITown Class Reference

OpenTTD AI API 12.1

Public Types | Static Public Member Functions
AITown Class Reference

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

Inheritance diagram for AITown:

## 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_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 int32 | GetTownCount ()
| Gets the number of towns. More...
static bool | IsValidTown (TownID town_id)
| Checks whether the given town index is valid. More...
static char * | GetName (TownID town_id)
| Get the name of the town. More...
static int32 | GetPopulation (TownID town_id)
| Gets the number of inhabitants in the town. More...
static int32 | GetHouseCount (TownID town_id)
| Gets the number of houses in the town. More...
static TileIndex | GetLocation (TownID town_id)
| Gets the location of the town. More...
static int32 | GetLastMonthProduction (TownID town_id, CargoID cargo_id)
| Get the total last month's production of the given cargo at a town. More...
static int32 | GetLastMonthSupplied (TownID town_id, CargoID cargo_id)
| Get the total amount of cargo supplied from a town last month. More...
static int32 | GetLastMonthTransportedPercentage (TownID town_id, CargoID cargo_id)
| Get the percentage of transported production of the given cargo at a town. More...
static int32 | GetLastMonthReceived (TownID town_id, AICargo::TownEffect towneffect_id)
| Get the total amount of cargo effects received by a town last month. More...
static uint32 | GetCargoGoal (TownID town_id, AICargo::TownEffect towneffect_id)
| Get the amount of cargo that needs to be delivered (per TownEffect) for a town to grow. More...
static int32 | GetGrowthRate (TownID town_id)
| Get the amount of days between town growth. More...
static int32 | GetDistanceManhattanToTile (TownID town_id, TileIndex tile)
| Get the manhattan distance from the tile to the AITown::GetLocation() of the town. More...
static int32 | GetDistanceSquareToTile (TownID town_id, TileIndex tile)
| Get the square distance from the tile to the AITown::GetLocation() of the town. More...
static bool | IsWithinTownInfluence (TownID town_id, TileIndex tile)
| Find out if this tile is within the rating influence of a town. More...
static bool | HasStatue (TownID town_id)
| Find out if this town has a statue for the current company. More...
static bool | IsCity (TownID town_id)
| Find out if the town is a city. More...
static int | GetRoadReworkDuration (TownID town_id)
| Find out how long the town is undergoing road reconstructions. More...
static int | GetFundBuildingsDuration (TownID town_id)
| Find out how long new buildings are still being funded in a town. More...
static AICompany::CompanyID | GetExclusiveRightsCompany (TownID town_id)
| Find out which company currently has the exclusive rights of this town. More...
static int32 | GetExclusiveRightsDuration (TownID town_id)
| Find out how long the town is under influence of the exclusive rights. More...
static bool | IsActionAvailable (TownID town_id, TownAction town_action)
| Find out if an action can currently be performed on the town. More...
static bool | PerformTownAction (TownID town_id, TownAction town_action)
| Perform a town action on this town. More...
static bool | FoundTown (TileIndex tile, TownSize size, bool city, RoadLayout layout, Text *name)
| Found a new town. More...
static TownRating | GetRating (TownID town_id, AICompany::CompanyID company_id)
| Get the rating of a company within a town. More...
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. More...
static RoadLayout | GetRoadLayout (TownID town_id)
| Get the road layout for a town. More...

## Detailed Description

Class that handles all town related functions.

## Member Enumeration Documentation

## ◆ RoadLayout

enum AITown::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_INVALID | The layout for invalid towns.

## ◆ TownAction

enum AITown::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 months.
TOWN_ACTION_BUILD_STATUE | Build a statue in this town.
TOWN_ACTION_FUND_BUILDINGS | Fund the creation of extra buildings for 3 months.
TOWN_ACTION_BUY_RIGHTS | Buy exclusive rights for this town for 12 months.
TOWN_ACTION_BRIBE | Bribe the town in order to get a higher rating.

## ◆ TownGrowth

enum AITown::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 AITown::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 AITown::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

## ◆ FoundTown()

static bool AITown::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 nullptr to use a random town name.

Precondition
  AISettings.GetValue("economy.found_town") != 0.
  size != TOWN_SIZE_LARGE.
  size != TOWN_SIZE_INVALID.
  layout != ROAD_LAYOUT_INVALID.

Returns
  True if the action succeeded.

Note
  AIs are restricted by the advanced setting that controls if funding towns is allowed or not. If custom road layout is forbidden, the layout parameter will be ignored.

## ◆ GetAllowedNoise()

static int AITown::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 uint32 AITown::GetCargoGoal | ( | TownID | town_id,
|  | AICargo::TownEffect | towneffect_id
| ) |  |
| static

Get the amount of cargo 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).
  AICargo::IsValidTownEffect(towneffect_id).

Returns
  The goal of the cargo.

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

## ◆ GetDistanceManhattanToTile()

static int32 AITown::GetDistanceManhattanToTile | ( | TownID | town_id,
|  | TileIndex | tile
| ) |  |
| static

Get the manhattan distance from the tile to the AITown::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 int32 AITown::GetDistanceSquareToTile | ( | TownID | town_id,
|  | TileIndex | tile
| ) |  |
| static

Get the square distance from the tile to the AITown::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 AICompany::CompanyID AITown::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).

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

## ◆ GetExclusiveRightsDuration()

static int32 AITown::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 months the exclusive rights hold. The value 0 means that there are currently no exclusive rights given out to anyone.

## ◆ GetFundBuildingsDuration()

static int AITown::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 months building construction is still funded. The value 0 means that there is currently no funding.

## ◆ GetGrowthRate()

static int32 AITown::GetGrowthRate | ( | TownID | town_id | ) |
| static

Get the amount of days between town growth.

Parameters

  town_id | The index of the town.

Precondition
  IsValidTown(town_id).

Returns
  Amount of 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.

## ◆ GetHouseCount()

static int32 AITown::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 int32 AITown::GetLastMonthProduction | ( | TownID | town_id,
|  | CargoID | cargo_id
| ) |  |
| static

Get the total last 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).
  AICargo::IsValidCargo(cargo_id).

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

## ◆ GetLastMonthReceived()

static int32 AITown::GetLastMonthReceived | ( | TownID | town_id,
|  | AICargo::TownEffect | towneffect_id
| ) |  |
| static

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

Parameters

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

Precondition
  IsValidTown(town_id).
  AICargo::IsValidTownEffect(cargo_id).

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

## ◆ GetLastMonthSupplied()

static int32 AITown::GetLastMonthSupplied | ( | TownID | town_id,
|  | CargoID | cargo_id
| ) |  |
| static

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

Parameters

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

Precondition
  IsValidTown(town_id).
  AICargo::IsValidCargo(cargo_id).

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

## ◆ GetLastMonthTransportedPercentage()

static int32 AITown::GetLastMonthTransportedPercentage | ( | TownID | town_id,
|  | CargoID | cargo_id
| ) |  |
| static

Get the percentage of transported 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).
  AICargo::IsValidCargo(cargo_id).

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

## ◆ GetLocation()

static TileIndex AITown::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 char* AITown::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 int32 AITown::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 AITown::GetRating | ( | TownID | town_id,
|  | AICompany::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).
  AICompany.ResolveCompanyID(company) != AICompany::COMPANY_INVALID.

Returns
  The rating as shown to humans.

## ◆ GetRoadLayout()

static RoadLayout AITown::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 AITown::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 months the road reworks are still going to take. The value 0 means that there are currently no road reworks.

## ◆ GetTownCount()

static int32 AITown::GetTownCount | ( |  | ) |
| static

Gets the number of towns.

Returns
  The number of towns.

## ◆ HasStatue()

static bool AITown::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).

Returns
  True if the town has a statue.

## ◆ IsActionAvailable()

static bool AITown::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).

Returns
  True if and only if the action can performed.

## ◆ IsCity()

static bool AITown::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 AITown::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 AITown::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 AITown::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).

Returns
  True if the action succeeded.