towns¶

Source: base/tealdef/game_mechanics/towns/towns.d.tl

Notes

State records of the town reputation script (town.gs) and the shared town types (ratings, supply and demand, proposal statistics).

Globals¶

Types

Name	Definition	Description
`TownRatingsSensitivityConfig`	`{TownRatingsSensitivityConfigName : integer}`	Option index per sensitivity key, as stored in `town_ratings_sensitivity.res` (`2` for urban care, `4` for the others). `difficulty_util.getScale` turns the index into the sensitivity value.

TownAuthoritySeveredConnection¶

record global base/tealdef/game_mechanics/towns/towns.d.tl:3

global record TownAuthoritySeveredConnection

No description in the game files yet.

Fields

Name	Type	Description
`penalty`	`number`
`refund`	`number`
`severedTimestamp`	`integer`

TownProposalImpact¶

record global base/tealdef/game_mechanics/towns/towns.d.tl:9

global record TownProposalImpact

Notes

Reputation penalties of one town caused by a construction proposal, from TownUtil.calculateProposalImpact. Positive values lower the reputation.

Fields

Name	Type	Description
`trees`	`number`	Penalty for removed trees minus planted trees (`0.0025` per weighted tree).
`rocks`	`number`	Penalty for removed rocks minus placed rocks (`0.0025` per weighted rock).
`terrainModification`	`number`	Penalty for terrain brush, terrain alignment and tunnel volume (about 2 million cubic metres for a full penalty of 1).
`demolishedTownBuilding`	`number`	Penalty for demolished town buildings, `fractionDistrictRemoved / 0.405`.
`landscaping`	`number`	Combined landscaping value; `TownUtil.applyEventStats` does not use it.

TownAuthorityEventFactors¶

record global base/tealdef/game_mechanics/towns/towns.d.tl:17

global record TownAuthorityEventFactors

Notes

Reputation state of a town (TownState.eventFactors). It holds the score, the penalty per reason, item delivery statistics and the running marketing campaign.

Fields

Name	Type	Description
`score`	`number`	range 0 .. 1
`marketingInitiatedTimestamp`	`integer`	Game time (ms) when the current marketing campaign started; `0` when there is none.
`marketingParams`	`TownMarketingMetadata.ConstructionDesc`	Settings of the current marketing campaign.
`itemDelivery`	`number`	range 0 .. 1
`numItemsDelivered`	`integer`	Items delivered to the town since the last town update.
`averageItemsDelivered`	`number`	Items delivered within a moving window of half a game year.
`onTimeItemDelivery`	`number`	range 0 .. 1
`reasonToPenalty`	`{EventType : number}`	Current reputation penalty per reason, each between 0 and 1.

TownAuthorityEventFactors.EventType¶

enum base/tealdef/game_mechanics/towns/towns.d.tl:18

enum EventType

Notes

Reasons for a reputation penalty.

Used in the base game: 13 times in 4 files

base/content/gui/gui/construction/construction_react_util.tl:3818

local aggregatedPenalty : {TownAuthorityEventFactors.EventType : number} = {}

base/content/game_mechanics/game_mechanics/towns/towns.script.tl:131

local penaltyOverrides : {TownAuthorityEventFactors.EventType : number} = {}

base/content/game_mechanics/game_mechanics/towns/town_react_util.tl:30

function town_react_util.getStringForTownAuthorityEventFactors(event : TownAuthorityEventFactors.EventType) : string

base/content/game_mechanics/game_mechanics/towns/town_util.tl:1598

town_util.changeTownAuthorityPenalty = function(currFactors : TownAuthorityEventFactors, reason : TownAuthorityEventFactors.EventType, penaltyDelta : number, ma

Value	Description
`"Unknown"`	Penalty from an older save that had no reasons stored.
`"Trees"`	Trees removed near the town.
`"Rocks"`	Rocks removed near the town.
`"TerrainModification"`	Terrain changed near the town (terrain brush, terrain alignment, tunnels).
`"SeveredConnection"`	A main connection to another town is disconnected or too long.
`"FailedSubsidy"`	Failed subsidy; the default reason of the `decreaseReputation` event.
`"DemolishedTownBuilding"`	Town buildings demolished.

TownConstructionBoni¶

record global base/tealdef/game_mechanics/towns/towns.d.tl:37

global record TownConstructionBoni

Notes

Bonuses of a town from nearby constructions with town_growth metadata, summed and refreshed every 20 updates.

Fields

Name	Type	Description
`xpIncrease`	`number`	Sum of `xpIncrease`; the experience multiplier is `1 + xpIncrease`.
`trafficRatingIncrease`	`number`	Sum of `trafficRatingIncrease`, added to the traffic rating.
`reputationRecoveryBoost`	`number`	Sum of `reputationRecoveryBoost`, passed to `TownUtil.applyEventDecay`.

TownRatingsSensitivityConfigName¶

enum global base/tealdef/game_mechanics/towns/towns.d.tl:43

global enum TownRatingsSensitivityConfigName

Notes

Keys of the default rating sensitivities in town_ratings_sensitivity.res, one per TownRatingKey.

Value	Description
`"SensitivityUrbanCare"`	Default sensitivity of the reputation rating (`urban_care`).
`"SensitivityTrafficCongestion"`	Default sensitivity of the traffic rating.
`"SensitivityPeopleHappiness"`	Default sensitivity of the happiness rating.
`"SensitivityCargoDelivery"`	Default sensitivity of the delivery time rating.
`"SensitivityNoise"`	Default sensitivity of the noise rating.
`"SensitivityPollution"`	Default sensitivity of the pollution rating.

TownState¶

record global base/tealdef/game_mechanics/towns/towns.d.tl:54

global record TownState

Notes

Reputation and rating state of one town in the town.gs game script. Get it with TownUtil.getTownState or TownUtil.externalGetTownState.

Fields

Name	Type	Description
`townEntity`	`EntityUtil.EntityAndRevision`	Town entity with its revision.
`sizeFactors`	`{number}`
`authorityScore`	`number`	Overall town rating between 0 and 1, the lowest of the six ratings (`TownUtil.calcAuthorityScore`).
`deliveryRating`	`RatingLevel`	Supplies rating level, updated on each town update. A change sends the `Towns`/`DeliveryRatingChanged` event.
`constructionBoni`	`TownConstructionBoni`	Bonuses from nearby constructions.
`eventFactors`	`TownAuthorityEventFactors`	Reputation state of the town.
`lastApplyTime`	`integer`	Game time (ms) of the last town update.
`cachedRatings`	`{string : CachedRating}`	Last computed ratings per rating key, written by `TownUtil.calcAuthorityScore`.
`ratingSensitivity`	`{string : number}`	Sensitivity per rating key set for this town with the `setTownRatingSensitivity` event; `nil` uses the defaults.

TownState.CachedRating¶

record base/tealdef/game_mechanics/towns/towns.d.tl:62

record CachedRating

Notes

Last computed value of one rating.

Used in the base game: 1 time in 1 file

base/content/game_mechanics/game_mechanics/towns/town_util.tl:738

function town_util.getRatingFromCache(rating : TownUtil.Rating, townEntity : Engine.Entity, townState : TownState) : TownState.CachedRating

Fields

Name	Type	Description
`value`	`number`	Rating value between 0 and 1.
`critical`	`boolean`	Set when the rating falls to `VeryPoor`; cleared once it is above `Poor` again.

TownsState¶

record global base/tealdef/game_mechanics/towns/towns.d.tl:70

global record TownsState

Notes

State of the town game script town.gs (towns.script).

Fields

Name	Type	Description
`townStates`	`{TownState}`	State of each town.
`version`	`integer`	Version of the state layout; `TownLegacyUtil.updateLegacyState` migrates older versions.

CargoTypeSupplyDemand¶

record global base/tealdef/game_mechanics/towns/towns.d.tl:75

global record CargoTypeSupplyDemand

Notes

Supply and demand of one cargo type in a town district.

Fields

Name	Type	Description
`cargoTypeId`	`CargoTypeId`	Cargo type.
`supply`	`integer`	Supplied amount, capped at `demand`.
`demand`	`integer`	Demanded amount.

CargoTypeSupplyDemands¶

record global base/tealdef/game_mechanics/towns/towns.d.tl:81

global record CargoTypeSupplyDemands

Notes

Supply and demand per cargo type for each district type.

Fields

Name	Type	Description
`residential`	`{CargoTypeSupplyDemand}`	Cargo supply and demand of the residential district.
`commercial`	`{CargoTypeSupplyDemand}`	Cargo supply and demand of the commercial district.
`industrial`	`{CargoTypeSupplyDemand}`	Cargo supply and demand of the industrial district.

TownCapacities¶

record global base/tealdef/game_mechanics/towns/towns.d.tl:87

global record TownCapacities

Notes

Person capacity of a town per district type.

Fields

Name	Type	Description
`residential`	`integer`	Person capacity of the residential district.
`commercial`	`integer`	Person capacity of the commercial district.
`industrial`	`integer`	Person capacity of the industrial district.

TownCapacityUsages¶

record global base/tealdef/game_mechanics/towns/towns.d.tl:93

global record TownCapacityUsages

Notes

Used and total capacity of a town per district type.

Fields

Name	Type	Description
`residential`	`UtilTown.TownCapacityUsage`	Capacity usage of the residential district.
`commercial`	`UtilTown.TownCapacityUsage`	Capacity usage of the commercial district.
`industrial`	`UtilTown.TownCapacityUsage`	Capacity usage of the industrial district.

GrowthSummand¶

record global base/tealdef/game_mechanics/towns/towns.d.tl:99

global record GrowthSummand

No description in the game files yet.

Fields

Name	Type	Description
`label`	`string`
`value`	`integer`

LandUseGrowth¶

record global base/tealdef/game_mechanics/towns/towns.d.tl:104

global record LandUseGrowth

No description in the game files yet.

Fields

Name	Type	Description
`summands`	`{GrowthSummand}`

RatingLevel¶

enum global base/tealdef/game_mechanics/towns/towns.d.tl:108

global enum RatingLevel

Notes

Six-step level of a town rating. TownUtil.getFactorRatingLevel maps a value between 0 and 1 to a level in steps of 1/6.

Value	Description
`"VeryPoor"`	Lowest level (value below 1/6).
`"Poor"`	Second level.
`"Mediocre"`	Third level.
`"Good"`	Fourth level.
`"VeryGood"`	Fifth level. Towns allow subsidies at this level (`TownUtil.getSubventionsEnabled`).
`"Excellent"`	Highest level (value of 5/6 or more).

StationSamples¶

record global base/tealdef/game_mechanics/towns/towns.d.tl:117

global record StationSamples

Notes

Loaded and lost items per year of a town's stations. Only commented-out code in town_util.tl uses it.

Fields

Name	Type	Description
`loaded`	`integer`	Items loaded per year (logbook value `itemsLoaded`).
`lost`	`integer`	Items lost per year (logbook value `itemsLost`).

ProposalStats¶

record global base/tealdef/game_mechanics/towns/towns.d.tl:122

global record ProposalStats

Notes

Effects of a construction proposal on each town nearby, from TownUtil.getProposalStats. The town script turns them into reputation penalties before the proposal is built.

Fields

Name	Type	Description
`townStats`	`{Engine.Entity : TownProposalStats}`	Effects per affected town entity. Empty when the proposal is not player-initiated.

ProposalStats.TownProposalStats¶

record base/tealdef/game_mechanics/towns/towns.d.tl:123

record TownProposalStats

Notes

Effects of the proposal on one town. Tree and rock counts are weighted by distance to the town (api.engine.util.town.getImpactFromDistance).

Used in the base game: 3 times in 1 file

base/content/game_mechanics/game_mechanics/towns/town_util.tl:851

function town_util.calculateProposalImpact(stats : ProposalStats.TownProposalStats) : TownProposalImpact

Fields

Name	Type	Description
`addedTrees`	`number`	Weighted number of trees planted, after cancelling out trees removed in the same proposal.
`removedTrees`	`number`	Weighted number of trees removed, scaled by each tree model's `reputationFactor`.
`addedRocks`	`number`	Weighted number of rocks placed, after cancelling out rocks removed in the same proposal.
`removedRocks`	`number`	Weighted number of rocks removed.
`removedBuildings`	`{Building}`	Town buildings the proposal removes without replacing them.
`fractionDistrictRemoved`	`number`	Removed person capacity divided by the capacity of the building's district, summed over all removed buildings.
`terrainMod`	`TerrainMod`	Terrain volume changes.
`tunnelVolumeAdded`	`number`	Net tunnel volume added (length times width times height), weighted by distance to the town.

ProposalStats.TownProposalStats.Building¶

record base/tealdef/game_mechanics/towns/towns.d.tl:124

record Building

Notes

A town building the proposal removes.

Used in the base game: 1 time in 1 file

base/content/game_mechanics/game_mechanics/towns/town_util.tl:1161

local building : ProposalStats.TownProposalStats.Building = {plotSize = plotSize, level = townBuilding.level}

Fields

Name	Type	Description
`plotSize`	`integer`	Plot size of the building, parcel count times depth.
`level`	`integer`	Level of the town building.

ProposalStats.TownProposalStats.TerrainMod¶

record base/tealdef/game_mechanics/towns/towns.d.tl:128

record TerrainMod

Notes

Terrain volume changes of the proposal.

Fields

Name	Type	Description
`brushVolumeAdded`	`number`	Terrain volume added with the terrain brush, in cubic metres.
`brushVolumeRemoved`	`number`	Terrain volume removed with the terrain brush, in cubic metres.
`terrainAlignmentVolumeAdded`	`number`	Terrain volume added by terrain alignment of constructions. It is scaled by a factor that falls from 1 to 0.5 while the proposal's construction area grows between 10 000 and 50 000.
`terrainAlignmentVolumeRemoved`	`number`	Terrain volume removed by terrain alignment of constructions, scaled like `terrainAlignmentVolumeAdded`.

TownProposalActions¶

record global base/tealdef/game_mechanics/towns/towns.d.tl:148

global record TownProposalActions

Notes

Actions of a proposal that a town's rating may forbid, per affected town (TownUtil.getProposalActions).

Details

The base game checks these only in code that is commented out (guiHandleEvent in towns.script.tl). In getProposalActions the catchments of stations with an airport go to BuildStation and those without one to BuildAirport.

Fields

Name	Type	Description
`townActions`	`{Engine.Entity : {Action}}`	Actions per affected town entity.

TownProposalActions.Action¶

enum base/tealdef/game_mechanics/towns/towns.d.tl:149

enum Action

Notes

Action types checked by TownUtil.getActionAllowed.

Used in the base game: 2 times in 1 file

base/content/game_mechanics/game_mechanics/towns/town_util.tl:1509

local function appendResult(catchments : {Type.CatchmentArea}, action : TownProposalActions.Action)

Value	Description
`"BuildStation"`	Build a station or stop; allowed above `VeryPoor`.
`"DestroyBuilding"`	Demolish a town building; allowed above `Poor`.
`"BuildAirport"`	Build an airport; allowed above `Mediocre`.

TownLegacyUtil¶

record global base/tealdef/game_mechanics/towns/towns.d.tl:158

global record TownLegacyUtil

Notes

Migration of old TownsState layouts (game_mechanics/towns/town_legacy_util.tl).

Fields

Name	Type	Description
`currentVersion`	`integer`	Current state version (`8`).

Functions

updateLegacyState(townsState : TownsState) base/tealdef/game_mechanics/towns/towns.d.tl:160

Notes

Migrates a town script state from an older version to currentVersion and sets version. The town script calls it on the handleLegacy event.

Parameter	Type	Description
`townsState`	`TownsState`	State of the town script; changed in place.