town_util¶

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

Notes

Town ratings, reputation bookkeeping and helper functions (game_mechanics/towns/town_util.tl).

TownRatingKey¶

enum global base/tealdef/game_mechanics/towns/town_util.d.tl:3

global enum TownRatingKey

Notes

Keys of the six town ratings (TownUtil.Rating.key).

Value	Description
`"urban_care"`	Reputation rating.In game Reputation
`"traffic_congestion"`	Traffic rating.In game Traffic
`"people_happiness"`	Happiness rating.In game Happiness
`"cargo_delivery"`	Delivery time rating.In game Delivery
`"noise"`	Noise rating.In game Noise
`"pollution"`	Pollution rating.In game Pollution

TownUtil¶

record global base/tealdef/game_mechanics/towns/town_util.d.tl:12

global record TownUtil

Load: local town_util = ug_require "::/game_mechanics/towns/town_util.tl" as TownUtil

Notes

Town ratings, reputation and helper functions (game_mechanics/towns/town_util.tl).

Example

local town_util = ug_require "/game_mechanics/towns/town_util.tl" as TownUtil
local townState = town_util.externalGetTownState(townEntity)
local level = town_util.getFactorRatingLevel(townState.authorityScore)

Fields

Name	Type	Description
`SeveredConnectionPenalty`	`number`	Reputation penalty per severed main connection (`1/3`). used 2× in the base game
`NumLinesForHappinessStats`	`integer`	Number of lines listed in the happiness statistics (`5`). used 1× in the base game
`GrowthLevelCacheKey`	`string`	Key (`"growth_level"`) in `TownState.cachedRatings` that holds the town's growth level. `calcAuthorityScore` stores it, `getGrowthLevelMult` reads it instead of recalculating, and starting a new game from a map (`initNewGameFromMap`) clears it.
`LineUsageRatingMultiplier`	`number`	Factor on the town's line usage when computing the passenger supply (`2.0`).

Functions

GetRatings() : {Rating} base/tealdef/game_mechanics/towns/town_util.d.tl:30

Call as town_util.GetRatings(…)

Notes

The six town ratings in the order urban care, traffic, happiness, delivery, noise, pollution.

Returns {Rating}: List of ratings.

Used in the base game: 10 times in 8 files

base/content/game_mechanics/game_mechanics/notifications/notifications.script.tl:224

local ratings = town_util.GetRatings()

base/content/game_mechanics/game_mechanics/notifications/types/town_rating_warning.script.tl:20

for __, rating in ipairs(town_util.GetRatings()) do

base/content/game_mechanics/game_mechanics/notifications/types/town_rating_warning_nonperistent.script.tl:27

for __, rating in ipairs(town_util.GetRatings()) do

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

local rating = town_util.GetRatings()[params.ratingIndex]

base/content/gui/gui/debug_panel/make_entity_debug_panel.tl:437

for __, v in ipairs(town_util.GetRatings()) do

base/content/gui/gui/entity_window/town/town_eow.script.tl:479

for __, rating in ipairs(town_util.GetRatings()) do

… and 2 more files.

GetRating(key : string) : Rating base/tealdef/game_mechanics/towns/town_util.d.tl:31

Call as town_util.GetRating(…)

Notes

Rating description for a rating key.

In game Reputation · Traffic · Happiness

Parameter	Type	Description
`key`	`string`	A `TownRatingKey`.

Returns Rating: The rating, or nil for an unknown key.

Used in the base game: 3 times in 2 files

base/content/gui/gui/statistics/statistic_towns.tl:277

local staticRating = town_util.GetRating(key)

base/content/mission/mission/mission_framework/mission_framework_react_util.tl:150

local staticRating = town_util.GetRating(progress.townRatingKey)

GetRatingsToLog() : {Rating} base/tealdef/game_mechanics/towns/town_util.d.tl:32

Call as town_util.GetRatingsToLog(…)

Notes

Ratings written to the town journal; GetRatings plus the supply ratings supplies_cargo_0 to supplies_cargo_2 and supplies_passenger.

Returns {Rating}: List of ratings.

getMultiplierToRankClass(multiplier : number) : string base/tealdef/game_mechanics/towns/town_util.d.tl:56

Call as town_util.getMultiplierToRankClass(…)

Notes

CSS class for a growth multiplier, from town-growth-rank-1 (below 0.15) to town-growth-rank-6 (0.8 or more).

Parameter	Type	Description
`multiplier`	`number`	Multiplier between 0 and 1.

Returns string: CSS class name.

Used in the base game: 3 times in 2 files

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

class = "font-scale-body,last-year-multiplier-icon," .. town_util.getMultiplierToRankClass(multiplier),

base/content/mission/mission/tasks/town_rating/town_rating.tl:75

local rank = town_util.getMultiplierToRankClass(rating)

getRatingSensitivityOptionName(ratingName : TownRatingKey) : string base/tealdef/game_mechanics/towns/town_util.d.tl:57

Call as town_util.getRatingSensitivityOptionName(…)

Notes

Name of the script option that holds the sensitivity of a rating, for example townConfig.sensitivityNoise.

Parameter	Type	Description
`ratingName`	`TownRatingKey`	Rating key.

Returns string: Option name, or an empty string for an unknown key.

Used in the base game: 1 time in 1 file

base/content/gui/gui/entity_window/town/town_eow.script.tl:906

local optionName = town_util.getRatingSensitivityOptionName(params.rating)

getRatingLabel(RatingLevel) : string base/tealdef/game_mechanics/towns/town_util.d.tl:58

Call as town_util.getRatingLabel(…)

Notes

Localized label of a rating level, such as "Very Poor".

In game Very Poor · Mediocre · Excellent

Parameter	Type	Description
`#1`	`RatingLevel`	Rating level.

Returns string: Localized label.

Used in the base game: 11 times in 3 files

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

text = town_util.getRatingLabel(ratingLevel),

base/content/gui/gui/entity_window/town_building/town_building.tl:180

getRatingLabel = town_util.getRatingLabel,

base/content/gui/gui/statistics/statistic_towns.tl:567

local reputationLabel = town_util.getRatingLabel(reputationRatingLevel)

getRatingNameFromKey(name : TownRatingKey) : string base/tealdef/game_mechanics/towns/town_util.d.tl:59

Call as town_util.getRatingNameFromKey(…)

Notes

Localized display name of a rating.

Parameter	Type	Description
`name`	`TownRatingKey`	Rating key.

Returns string: Display name, or nil for an unknown key.

Used in the base game: 7 times in 2 files

base/content/gui/gui/statistics/statistic_towns.tl:507

{ path = getRatingIconFromKey("urban_care"), tooltip = town_util.getRatingNameFromKey("urban_care"), recipe = TownUrbanCareCell, getCompareValue = getUrbanCareC

base/content/mission/mission/mission_framework/mission_framework_react_util.tl:149

local ratingName = town_util.getRatingNameFromKey(progress.townRatingKey)

getRatingUrbanCare(entity : Engine.Entity, townState : TownState) : number base/tealdef/game_mechanics/towns/town_util.d.tl:60

Call as town_util.getRatingUrbanCare(…)

Notes

Reputation rating of a town. Each severed main connection counts as a penalty of SeveredConnectionPenalty.

Parameter	Type	Description
`entity`	`Engine.Entity`	Town entity.
`townState`	`TownState`	State of the town.

Returns number: Reputation between 0 and 1; 1 when the sensitivity is 0.

Used in the base game: 6 times in 6 files

base/content/game_mechanics/game_mechanics/celebrations/celebrations.script.tl:81

local ratingUrbanCare = town_util.getRatingUrbanCare(townEntity, townState)

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

local ratingUrbanCare = town_util.getRatingUrbanCare(params.entity, townState)

base/content/game_mechanics/game_mechanics/towns/town_util_parallel.script.tl:235

return town_util.getFactorRatingLevel(town_util.getRatingUrbanCare(param.townEntity, townState))

base/content/gui/gui/entity_window/town/town_eow.script.tl:256

return town_util.getRatingUrbanCare(params.entityId, townState) * 1000

base/content/gui/gui/statistics/statistic_towns.tl:447

return town_util.getRatingUrbanCare(townEntity, town_util.externalGetTownState(townEntity))

base/content/mission/mission/tasks/town_rating/town_rating.tl:10

return town_util.getRatingUrbanCare(townEntity, town_util.externalGetTownState(townEntity))

getRatingNoise(entity : Engine.Entity, townState : TownState) : number base/tealdef/game_mechanics/towns/town_util.d.tl:61

Call as town_util.getRatingNoise(…)

Notes

Noise rating of a town. The town's noise in dB, plus a per-town random offset and 10 * log10(sensitivity), is mapped linearly between the noise bounds of emission_config.

Parameter	Type	Description
`entity`	`Engine.Entity`	Town entity.
`townState`	`TownState`	State of the town.

Returns number: Rating between 0 and 1 (1 is quiet); 1 when the sensitivity is 0.

Used in the base game: 5 times in 4 files

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

local noiseRating = town_util.getRatingNoise(params.entity, townState)

base/content/game_mechanics/game_mechanics/towns/town_util_parallel.script.tl:80

local emissionRating = params.pollution and town_util.getRatingPollution(params.townEntity, townState) or town_util.getRatingNoise(params.townEntity, townState)

base/content/gui/gui/statistics/statistic_towns.tl:453

return town_util.getRatingNoise(townEntity, town_util.externalGetTownState(townEntity))

base/content/mission/mission/tasks/town_rating/town_rating.tl:22

return town_util.getRatingNoise(townEntity, town_util.externalGetTownState(townEntity))

getRatingPollution(entity : Engine.Entity, townState : TownState) : number base/tealdef/game_mechanics/towns/town_util.d.tl:62

Call as town_util.getRatingPollution(…)

Notes

Pollution rating of a town. The average pollution per 16 m by 16 m cell of the settlement area is converted to dB, adjusted for sensitivity and mapped between the pollution bounds of emission_config.

Parameter	Type	Description
`entity`	`Engine.Entity`	Town entity.
`townState`	`TownState`	State of the town.

Returns number: Rating between 0 and 1 (1 is clean); 1 when the sensitivity is 0.

Used in the base game: 4 times in 3 files

base/content/game_mechanics/game_mechanics/towns/town_util_parallel.script.tl:80

local emissionRating = params.pollution and town_util.getRatingPollution(params.townEntity, townState) or town_util.getRatingNoise(params.townEntity, townState)

base/content/gui/gui/statistics/statistic_towns.tl:450

return town_util.getRatingPollution(townEntity, town_util.externalGetTownState(townEntity))

base/content/mission/mission/tasks/town_rating/town_rating.tl:25

return town_util.getRatingPollution(townEntity, town_util.externalGetTownState(townEntity))

getRatingTraffic(entity : Engine.Entity, townState : TownState) : number base/tealdef/game_mechanics/towns/town_util.d.tl:63

Call as town_util.getRatingTraffic(…)

Notes

Traffic rating of a town from the engine's traffic speed rating, raised to the power of the sensitivity, plus constructionBoni.trafficRatingIncrease.

Parameter	Type	Description
`entity`	`Engine.Entity`	Town entity.
`townState`	`TownState`	State of the town.

Returns number: Rating between 0 and 1; 1 when the sensitivity is 0.

Used in the base game: 3 times in 2 files

base/content/game_mechanics/game_mechanics/towns/town_util_parallel.script.tl:35

local ratingTraffic = town_util.getRatingTraffic(townEntity, townState)

base/content/mission/mission/tasks/town_rating/town_rating.tl:13

return town_util.getRatingTraffic(townEntity, town_util.externalGetTownState(townEntity))

getRatingTrafficAllTowns(townStates : {TownState}) : {Engine.Entity : number} base/tealdef/game_mechanics/towns/town_util.d.tl:64

Call as town_util.getRatingTrafficAllTowns(…)

Notes

Traffic ratings of several towns from one engine call. Unlike getRatingTraffic it ignores the per-town sensitivity.

Parameter	Type	Description
`townStates`	`{TownState}`	States of the towns.

Returns {Engine.Entity : number}: Rating between 0 and 1 per town entity.

Used in the base game: 1 time in 1 file

base/content/gui/gui/statistics/statistic_towns.tl:479

local allTrafficRatings = town_util.getRatingTrafficAllTowns(townsState.townStates or {})

getRatingHappiness(entity : Engine.Entity, townState : TownState) : number base/tealdef/game_mechanics/towns/town_util.d.tl:65

Call as town_util.getRatingHappiness(…)

Notes

Happiness rating of a town from api.engine.util.town.getTownHappinessStats; see getRatingHappinessFromStats.

Parameter	Type	Description
`entity`	`Engine.Entity`	Town entity.
`townState`	`TownState`	State of the town.

Returns number: Rating between 0 and 1.

Used in the base game: 3 times in 3 files

base/content/game_mechanics/game_mechanics/towns/town_util_parallel.script.tl:243

return town_util.getFactorRatingLevel(town_util.getRatingHappiness(param.townEntity, townState))

base/content/gui/gui/statistics/statistic_towns.tl:456

return town_util.getRatingHappiness(townEntity, town_util.externalGetTownState(townEntity))

base/content/mission/mission/tasks/town_rating/town_rating.tl:16

return town_util.getRatingHappiness(townEntity, town_util.externalGetTownState(townEntity))

getRatingCargoDelivery(entity : Engine.Entity, townState : TownState) : number base/tealdef/game_mechanics/towns/town_util.d.tl:66

Call as town_util.getRatingCargoDelivery(…)

Notes

Delivery time rating of a town. The share of cargo delivered on time in the last half game year (at least 10 items assumed) is mapped between bounds that depend on the sensitivity.

Parameter	Type	Description
`entity`	`Engine.Entity`	Town entity.
`townState`	`TownState`	State of the town.

Returns number: Rating between 0 and 1; 1 when the sensitivity is 0.

Used in the base game: 5 times in 3 files

base/content/game_mechanics/game_mechanics/towns/town_util_parallel.script.tl:139

local cargoDeliveryRating = town_util.getRatingCargoDelivery(townEntity, townState)

base/content/gui/gui/statistics/statistic_towns.tl:459

return town_util.getRatingCargoDelivery(townEntity, town_util.externalGetTownState(townEntity))

base/content/mission/mission/tasks/town_rating/town_rating.tl:19

return town_util.getRatingCargoDelivery(townEntity, town_util.externalGetTownState(townEntity))

getRatingDeliveriesLegacy(entity : Engine.Entity) : number base/tealdef/game_mechanics/towns/town_util.d.tl:67

Call as town_util.getRatingDeliveriesLegacy(…)

Notes

Old supplies rating, the average of the cargo and passenger supply ratings. No base-game script calls it.

Parameter	Type	Description
`entity`	`Engine.Entity`	Town entity.

Returns number: Rating between 0 and 1; 0 when the town has no demand.

getRatingDeliveries(entity : Engine.Entity) : TownUtil.RatingDeliveries base/tealdef/game_mechanics/towns/town_util.d.tl:68

Call as town_util.getRatingDeliveries(…)

Notes

Supplies rating level of a town. The level numbers of the cargo and passenger supply ratings are averaged and rounded up.

Parameter	Type	Description
`entity`	`Engine.Entity`	Town entity.

Returns TownUtil.RatingDeliveries: Level number and a flag for "no deliveries". A town without any demand gets level 5.

Used in the base game: 3 times in 2 files

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

local ratingDeliveries = town_util.getRatingDeliveries(params.entity)

base/content/game_mechanics/game_mechanics/towns/town_util_parallel.script.tl:26

result.suppliesRating = town_util.getRatingLevel(town_util.getRatingDeliveries(townEntity).ratingLevelNumber)

getGrowthLevelMult(entity : Engine.Entity, townState : TownState) : RatingLevel base/tealdef/game_mechanics/towns/town_util.d.tl:69

Call as town_util.getGrowthLevelMult(…)

Notes

Growth level of a town from the product of its rating level (authorityScore) and its supplies level. Higher levels need a larger product. Uses the value cached under GrowthLevelCacheKey when there is one.

Parameter	Type	Description
`entity`	`Engine.Entity`	Town entity.
`townState`	`TownState`	State of the town.

Returns RatingLevel: Growth level; TownCargoUtil.authority2xpFactor maps it to the experience factor.

Used in the base game: 2 times in 2 files

base/content/game_mechanics/game_mechanics/towns/town_util_parallel.script.tl:282

local growthLevel = town_util.getGrowthLevelMult(townEntity, townState)

base/content/gui/gui/main/town_hud_react_util.tl:84

growthLevel = town_util.getGrowthLevelMult(params.entity, townState)

getRatingBonuses(entity : Engine.Entity, townState : TownState) : number base/tealdef/game_mechanics/towns/town_util.d.tl:70

Call as town_util.getRatingBonuses(…)

Notes

Bonus rating shown in the town window.

Parameter	Type	Description
`entity`	`Engine.Entity`	Town entity (not used).
`townState`	`TownState`	State of the town.

Returns number: 1.0 when the town has an experience bonus from constructions, otherwise 0.5.

Used in the base game: 2 times in 2 files

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

local ratingBonuses = town_util.getRatingBonuses(params.entity, townState)

base/content/game_mechanics/game_mechanics/towns/town_util_parallel.script.tl:260

return town_util.getFactorRatingLevel(town_util.getRatingBonuses(param.townEntity, townState))

getRatingDeliveriesCargo(entity : Engine.Entity) : number base/tealdef/game_mechanics/towns/town_util.d.tl:72

Call as town_util.getRatingDeliveriesCargo(…)

Notes

Cargo supply rating of a town, the best of the three districts.

Parameter	Type	Description
`entity`	`Engine.Entity`	Town entity.

Returns number: Supply divided by demand (0 to 1), or nil when no district demands cargo.

getRatingDeliveriesCargoLandUse(entity : Engine.Entity, landUse : LandUseType) : number base/tealdef/game_mechanics/towns/town_util.d.tl:73

Call as town_util.getRatingDeliveriesCargoLandUse(…)

Notes

Cargo supply rating of one district, total supply divided by total demand.

Parameter	Type	Description
`entity`	`Engine.Entity`	Town entity.
`landUse`	`LandUseType`	District type.

Returns number: Rating between 0 and 1, or nil when the district demands no cargo.

Used in the base game: 3 times in 1 file

base/content/game_mechanics/game_mechanics/towns/town_util_parallel.script.tl:17

local cargoRatingResidential = town_util.getRatingDeliveriesCargoLandUse(townEntity, api.type["enum"].LandUseType.RESIDENTIAL)

getRatingDeliveriesPassenger(entity : Engine.Entity) : number base/tealdef/game_mechanics/towns/town_util.d.tl:74

Call as town_util.getRatingDeliveriesPassenger(…)

Notes

Passenger supply rating of a town, twice the town's line usage.

Parameter	Type	Description
`entity`	`Engine.Entity`	Town entity.

Returns number: Rating between 0 and 1, or nil when the town has no residential capacity.

Used in the base game: 1 time in 1 file

base/content/game_mechanics/game_mechanics/towns/town_util_parallel.script.tl:14

local passengerRating = town_util.getRatingDeliveriesPassenger(townEntity)

getCargoSupplyDemandsLandUse(Engine.Entity, LandUseType) : {CargoTypeSupplyDemand} base/tealdef/game_mechanics/towns/town_util.d.tl:76

Call as town_util.getCargoSupplyDemandsLandUse(…)

Notes

Supply and demand per cargo type of one district, from api.engine.system.townBuildingSystem.getCargoSupplyAndLimit.

Parameter	Type	Description
`#1`	`Engine.Entity`	Town entity.
`#2`	`LandUseType`	District type.

Returns {CargoTypeSupplyDemand}: List sorted by demand (highest first), then by cargo type id.

Used in the base game: 1 time in 1 file

base/content/gui/gui/layers/layer_cargo_flow.tl:75

districtSupplyDemand = town_util.getCargoSupplyDemandsLandUse(param.entity, townSelectionDetails.districtType)

getCargoSupplyDemandsLandUseWithResidentialLineUsage(townEntity : Engine.Entity, landUse : LandUseType) : {CargoTypeSupplyDemand} base/tealdef/game_mechanics/towns/town_util.d.tl:77

Call as town_util.getCargoSupplyDemandsLandUseWithResidentialLineUsage(…)

Notes

Like getCargoSupplyDemandsLandUse. For the residential district it puts a passenger entry first, with the residential person capacity as demand and the capacity times lineUsage * LineUsageRatingMultiplier (at most 1) as supply.

Parameter	Type	Description
`townEntity`	`Engine.Entity`	Town entity.
`landUse`	`LandUseType`	District type.

Returns {CargoTypeSupplyDemand}: List of supply and demand entries.

Used in the base game: 2 times in 2 files

base/content/game_mechanics/game_mechanics/towns/town_util_parallel.script.tl:8

local result = town_util.getCargoSupplyDemandsLandUseWithResidentialLineUsage(param.townEntity, param.landUse)

base/content/gui/gui/layers/layer_cargo_flow.tl:73

districtSupplyDemand = town_util.getCargoSupplyDemandsLandUseWithResidentialLineUsage(param.entity, townSelectionDetails.districtType)

getCargoSupplyDemands(Engine.Entity) : CargoTypeSupplyDemands base/tealdef/game_mechanics/towns/town_util.d.tl:78

Call as town_util.getCargoSupplyDemands(…)

Notes

Cargo supply and demand of all three districts of a town.

Parameter	Type	Description
`#1`	`Engine.Entity`	Town entity.

Returns CargoTypeSupplyDemands: Supply and demand per district.

Used in the base game: 12 times in 4 files

base/content/game_mechanics/game_mechanics/subventions/deliver_cargo_town/deliver_cargo_town.script.tl:138

local cargoSupplyDemands : CargoTypeSupplyDemands = town_util.getCargoSupplyDemands(townEntity)

base/content/gui/gui/layers/layer_react_util.tl:160

state.demands = town_util.getCargoSupplyDemands(entity)

base/content/gui/gui/statistics/statistic_towns.tl:176

return town_util.getCargoSupplyDemands(entity)

base/content/mission/mission/tasks/town_rating/town_rating.tl:64

local supplyDemands = town_util.getCargoSupplyDemands(ctx.params.entity)

getLandUseCapacities(Engine.Entity) : TownCapacities base/tealdef/game_mechanics/towns/town_util.d.tl:79

Call as town_util.getLandUseCapacities(…)

Notes

Person capacity of each district of a town.

Parameter	Type	Description
`#1`	`Engine.Entity`	Town entity.

Returns TownCapacities: Capacity per district.

getTownCapacityUsages(Engine.Entity) : TownCapacityUsages base/tealdef/game_mechanics/towns/town_util.d.tl:80

Call as town_util.getTownCapacityUsages(…)

Notes

Used and total capacity of each district of a town, from api.engine.util.town.getTownCapacityUsage.

Parameter	Type	Description
`#1`	`Engine.Entity`	Town entity.

Returns TownCapacityUsages: Capacity usage per district.

Used in the base game: 7 times in 5 files

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

local townCapacityUsages : TownCapacityUsages = town_util.getTownCapacityUsages(params.entity)

base/content/game_mechanics/game_mechanics/towns/town_util_parallel.script.tl:299

local userdataResult = town_util.getTownCapacityUsages(townEntity)

base/content/gui/gui/statistics/statistic_towns.tl:40

state.capacities = town_util.getTownCapacityUsages(entity)

base/content/mission/mission/tasks/town_size/town_size_task_util.tl:9

ctx.state.size = town_util.getTownCapacityUsages(ctx.params.entity).residential.capacity

mods/release/urbangames_campaign_mission_04/content/mission/mission/mission_story.tl:1250

local townCapacityUsages : TownCapacityUsages = town_util.getTownCapacityUsages(params.entity_camping)

getReachability(Engine.Entity) : UtilTown.TownReachability base/tealdef/game_mechanics/towns/town_util.d.tl:81

Call as town_util.getReachability(…)

Notes

Reachability data of a town; calls api.engine.util.town.getTownReachability.

Parameter	Type	Description
`#1`	`Engine.Entity`	Town entity.

Returns UtilTown.TownReachability: Reachability of the town.

Used in the base game: 4 times in 1 file

base/content/gui/gui/statistics/statistic_towns.tl:84

local reachability : UtilTown.TownReachability = town_util.getReachability(entity)

getTownEmissionDB(Engine.Entity) : UtilTown.TownEmission base/tealdef/game_mechanics/towns/town_util.d.tl:82

Call as town_util.getTownEmissionDB(…)

Notes

Noise and pollution of a town in dB, including the per-town random offset of getTownEmissionRandomOffsetDB.

Parameter	Type	Description
`#1`	`Engine.Entity`	Town entity.

Returns UtilTown.TownEmission: Emission of the town.

getTownEmissionRandomOffsetDB(Engine.Entity) : UtilTown.TownEmission base/tealdef/game_mechanics/towns/town_util.d.tl:83

Call as town_util.getTownEmissionRandomOffsetDB(…)

Notes

Fixed random offset in dB that each town adds to its noise and pollution. The random generator is seeded with the town entity id, so the offset stays the same.

Parameter	Type	Description
`#1`	`Engine.Entity`	Town entity.

Returns UtilTown.TownEmission: Noise and pollution offsets, within emission_config.noiseRatingRandomOffsetMinMax and pollutionRatingRandomOffsetMinMax.

Details

Calls math.randomseed with the town entity id.

roundRatingPrecision(number) : integer base/tealdef/game_mechanics/towns/town_util.d.tl:84

Call as town_util.roundRatingPrecision(…)

Notes

Rounds a rating value down to an integer.

Parameter	Type	Description
`#1`	`number`	Value.

Returns integer: math.floor of the value.

getReachabilityRating(integer, number) : integer base/tealdef/game_mechanics/towns/town_util.d.tl:85

Call as town_util.getReachabilityRating(…)

Notes

Rating from a number of reachable destinations, floor(destinations^0.65 * 0.55 * scale). No base-game script calls it.

Parameter	Type	Description
`#1`	`integer`	Number of destinations.
`#2`	`number`	Scale.

Returns integer: Rating as an integer.

getTownCapacityUsageRating(UtilTown.TownCapacityUsage, number) : integer base/tealdef/game_mechanics/towns/town_util.d.tl:86

Call as town_util.getTownCapacityUsageRating(…)

Notes

Capacity usage as a percentage, used * scale * 100 / capacity rounded down. No base-game script calls it.

Parameter	Type	Description
`#1`	`UtilTown.TownCapacityUsage`	Capacity usage.
`#2`	`number`	Scale.

Returns integer: Percentage; 0 when the capacity is 0.

getCargoTypeSupplyDemandRating(CargoTypeSupplyDemand, number) : integer base/tealdef/game_mechanics/towns/town_util.d.tl:87

Call as town_util.getCargoTypeSupplyDemandRating(…)

Notes

Supply as a percentage of demand, supply * 100 * scale / demand rounded down. No base-game script calls it.

Parameter	Type	Description
`#1`	`CargoTypeSupplyDemand`	Supply and demand of a cargo type.
`#2`	`number`	Scale.

Returns integer: Percentage; 0 when the demand is 0.

findStateIndex(TownsState, EntityUtil.EntityAndRevision) : integer base/tealdef/game_mechanics/towns/town_util.d.tl:88

Call as town_util.findStateIndex(…)

Notes

Index of a town's state in townStates.

Parameter	Type	Description
`#1`	`TownsState`	State of the town script.
`#2`	`EntityUtil.EntityAndRevision`	Town entity with revision.

Returns integer: Index, or -1 when the town has no stored state.

getTownState(TownsState, Engine.Entity) : TownState base/tealdef/game_mechanics/towns/town_util.d.tl:89

Call as town_util.getTownState(…)

Notes

State of a town. Missing fields of a stored state are filled with defaults. A town without stored state gets a new default state, which is not added to townsState.

Parameter	Type	Description
`#1`	`TownsState`	State of the town script.
`#2`	`Engine.Entity`	Town entity.

Returns TownState: State of the town, or nil when the entity is not a town.

Used in the base game: 1 time in 1 file

base/content/game_mechanics/game_mechanics/notifications/notifications.script.tl:227

local sanitizedTownState = town_util.getTownState(townsState, townState.townEntity.entity)

setTownState(TownsState, Engine.Entity, TownState) : TownState base/tealdef/game_mechanics/towns/town_util.d.tl:90

Call as town_util.setTownState(…)

Notes

Stores the state of a town in the script state, replacing an existing entry or appending a new one.

Parameter	Type	Description
`#1`	`TownsState`	State of the town script; changed in place.
`#2`	`Engine.Entity`	Town entity.
`#3`	`TownState`	State of the town.

Returns TownState: Declared as the town state, but the implementation returns nothing.

externalGetTownState(Engine.Entity) : TownState base/tealdef/game_mechanics/towns/town_util.d.tl:91

Call as town_util.externalGetTownState(…)

Notes

State of a town, read from the town.gs game script component. Use it outside the town script.

Parameter	Type	Description
`#1`	`Engine.Entity`	Town entity.

Returns TownState: State of the town.

Used in the base game: 38 times in 10 files

base/content/game_mechanics/game_mechanics/celebrations/celebrations.script.tl:80

local townState = town_util.externalGetTownState(townEntity)

base/content/game_mechanics/game_mechanics/fun_elements/blimp_util.tl:186

local townState = town_util.externalGetTownState(blimpData.townEntity.entity)

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

local townState = town_util.externalGetTownState(params.entity)

base/content/game_mechanics/game_mechanics/towns/town_util_parallel.script.tl:32

local townState = town_util.externalGetTownState(townEntity)

base/content/gui/gui/debug_panel/make_entity_debug_panel.tl:432

local townState = town_util.externalGetTownState(entityId)

base/content/gui/gui/entity_window/town/town_eow.script.tl:255

local townState = town_util.externalGetTownState(params.entityId)

… and 4 more files.

externalGetTownsState() : TownsState base/tealdef/game_mechanics/towns/town_util.d.tl:92

Call as town_util.externalGetTownsState(…)

Notes

Full state of the town.gs game script, read from its component.

Returns TownsState: State of the town script.

Used in the base game: 4 times in 3 files

base/content/game_mechanics/game_mechanics/notifications/notifications.script.tl:214

local townsState = town_util.externalGetTownsState()

base/content/gui/gui/hud/marketing_display.script.tl:88

local townsStates = town_util.externalGetTownsState()

base/content/gui/gui/statistics/statistic_towns.tl:478

local townsState = town_util.externalGetTownsState()

getTrafficSpeedRating(Engine.Entity, number) : {number, {integer}} base/tealdef/game_mechanics/towns/town_util.d.tl:93

Call as town_util.getTrafficSpeedRating(…)

Notes

Raw traffic data of a town from api.engine.util.town.computeTownsTrafficSpeedMap.

Parameter	Type	Description
`#1`	`Engine.Entity`	Town entity.
`#2`	`number`	Samples coefficient passed to the engine.

Returns {number, {integer}}: The raw traffic rating and the street counts per traffic level, or nil without data.

Used in the base game: 1 time in 1 file

base/content/game_mechanics/game_mechanics/towns/town_util_parallel.script.tl:34

local rating = town_util.getTrafficSpeedRating(townEntity, advancedOptions.trafficSpeedSensitivityScale)

getItemsAtDestinationPerYear(Engine.Entity, CargoTypeId) : integer base/tealdef/game_mechanics/towns/town_util.d.tl:96

Call as town_util.getItemsAtDestinationPerYear(…)

No description in the game files yet.

Returns integer

Used in the base game: 3 times in 2 files

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

return town_util.getItemsAtDestinationPerYear(townEntity, cargoTypeId)

base/content/gui/gui/debug_panel/make_entity_debug_panel.tl:449

local amount = town_util.getItemsAtDestinationPerYear(entityAndRevisionState:old().entity, cargoTypeId)

getRatingFromCache(TownUtil.Rating, Engine.Entity, TownState) : TownState.CachedRating base/tealdef/game_mechanics/towns/town_util.d.tl:97

Call as town_util.getRatingFromCache(…)

Notes

Value of a rating from townState.cachedRatings, computed with rating.getRating when it is not cached.

Parameter	Type	Description
`#1`	`TownUtil.Rating`	Rating.
`#2`	`Engine.Entity`	Town entity.
`#3`	`TownState`	State of the town.

Returns TownState.CachedRating: Value and critical flag of the rating.

Used in the base game: 1 time in 1 file

base/content/game_mechanics/game_mechanics/notifications/notifications.script.tl:231

local cachedRating = town_util.getRatingFromCache(rating, townState.townEntity.entity, sanitizedTownState)

calcAuthorityScore(Engine.Entity, TownState) : number base/tealdef/game_mechanics/towns/town_util.d.tl:98

Call as town_util.calcAuthorityScore(…)

Notes

Overall rating of a town, the lowest value of the six ratings. Also refreshes townState.cachedRatings and their critical flags.

Parameter	Type	Description
`#1`	`Engine.Entity`	Town entity.
`#2`	`TownState`	State of the town; `cachedRatings` is changed.

Returns number: Score between 0 and 1.

logAuthorityRatings(Engine.Entity, TownState) : number base/tealdef/game_mechanics/towns/town_util.d.tl:99

Call as town_util.logAuthorityRatings(…)

Notes

Writes the values of GetRatingsToLog (times 1000) to the town's journal.

Parameter	Type	Description
`#1`	`Engine.Entity`	Town entity.
`#2`	`TownState`	State of the town.

Returns number: Not used by the base game.

calculateProposalImpact(ProposalStats.TownProposalStats) : TownProposalImpact base/tealdef/game_mechanics/towns/town_util.d.tl:100

Call as town_util.calculateProposalImpact(…)

Notes

Reputation penalties of one town from the statistics of a proposal.

Parameter	Type	Description
`#1`	`ProposalStats.TownProposalStats`	Proposal statistics of the town.

Returns TownProposalImpact: Penalty per reason.

Used in the base game: 1 time in 1 file

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

local impact = town_util.calculateProposalImpact(townStats)

applyEventDecay(TownAuthorityEventFactors, integer, integer, number) : TownAuthorityEventFactors base/tealdef/game_mechanics/towns/town_util.d.tl:101

Call as town_util.applyEventDecay(…)

Notes

Advances the reputation state of a town by the time since the last update. Ends a finished marketing campaign, updates the moving item average and moves itemDelivery and onTimeItemDelivery back towards 1.

Parameter	Type	Description
`#1`	`TownAuthorityEventFactors`	Previous reputation state.
`#2`	`integer`	Time since the last update, in ms.
`#3`	`integer`	Current game time, in ms.
`#4`	`number`	Recovery bonus; `1 + bonus` scales the recovery rate of `itemDelivery`.

Returns TownAuthorityEventFactors: New reputation state; score and reasonToPenalty are copied unchanged.

applyEventStats(TownAuthorityEventFactors, ProposalStats.TownProposalStats) : TownAuthorityEventFactors base/tealdef/game_mechanics/towns/town_util.d.tl:102

Call as town_util.applyEventStats(…)

Notes

Adds the penalties of a proposal (trees, rocks, terrain modification, demolished buildings) to a copy of the reputation state.

Parameter	Type	Description
`#1`	`TownAuthorityEventFactors`	Previous reputation state.
`#2`	`ProposalStats.TownProposalStats`	Proposal statistics of the town.

Returns TownAuthorityEventFactors: New reputation state.

applyMarketingCamaign(TownAuthorityEventFactors, params : TownMarketingMetadata.ConstructionDesc) : TownAuthorityEventFactors base/tealdef/game_mechanics/towns/town_util.d.tl:103

Call as town_util.applyMarketingCamaign(…)

Notes

Starts a marketing campaign at the current game time in a copy of the reputation state.

Parameter	Type	Description
`#1`	`TownAuthorityEventFactors`	Previous reputation state.
`params`	`TownMarketingMetadata.ConstructionDesc`	Campaign settings.

Returns TownAuthorityEventFactors: New reputation state, or the previous one when params is nil.

applyItemDelivered(TownAuthorityEventFactors, boolean, Engine.Entity) : TownAuthorityEventFactors base/tealdef/game_mechanics/towns/town_util.d.tl:104

Call as town_util.applyItemDelivered(…)

Notes

Counts one delivered item in a copy of the reputation state and updates the on-time share as a running average over at least 50 items.

Parameter	Type	Description
`#1`	`TownAuthorityEventFactors`	Previous reputation state.
`#2`	`boolean`	Whether the item arrived on time.
`#3`	`Engine.Entity`	Town entity (not used).

Returns TownAuthorityEventFactors: New reputation state.

getXpFactor(Engine.Entity) : number base/tealdef/game_mechanics/towns/town_util.d.tl:105

Call as town_util.getXpFactor(…)

Notes

Experience factor of a town, authority2xpFactor[growthLevel] * (1 + constructionBoni.xpIncrease).

Parameter	Type	Description
`#1`	`Engine.Entity`	Town entity.

Returns number: Factor applied to the experience the town gains.

Used in the base game: 1 time in 1 file

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

result.currentMultiplier = town_util.getXpFactor(params.entity)

getSeveredMainConnections(townEntity : Engine.Entity) : {Engine.Entity} base/tealdef/game_mechanics/towns/town_util.d.tl:106

Call as town_util.getSeveredMainConnections(…)

Notes

Towns whose main connection with this town is disconnected or too long (town problems Disconnected and Overlength).

Parameter	Type	Description
`townEntity`	`Engine.Entity`	Town entity.

Returns {Engine.Entity}: Entities of the other towns.

Used in the base game: 2 times in 2 files

base/content/game_mechanics/game_mechanics/celebrations/celebrations.script.tl:88

local numSeveredConnections = #town_util.getSeveredMainConnections(townEntity)

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

local numSeveredConnections = #town_util.getSeveredMainConnections(params.entity)

getTownEmissionEmitters(Engine.Entity, boolean, byLine? : {Engine.Entity : number}) : {EmitterCategory : number} base/tealdef/game_mechanics/towns/town_util.d.tl:107

Call as town_util.getTownEmissionEmitters(…)

Notes

Share of each source category in the noise or pollution of a town. Noise counts the emitters within 150 m of the affected districts (getNoiseLandUseTypes).

Parameter	Type	Description
`#1`	`Engine.Entity`	Town entity.
`#2`	`boolean`	True for pollution, false for noise.
`byLine?`	`{Engine.Entity : number}`	Optional table that receives the share per line of the player's vehicles.

Returns {EmitterCategory : number}: Share per category (the shares add up to 1), or an empty table without emission.

Used in the base game: 1 time in 1 file

base/content/game_mechanics/game_mechanics/towns/town_util_parallel.script.tl:79

local emissionSources = town_util.getTownEmissionEmitters(params.townEntity, params.pollution, params.byLine and pollutionPerLine or nil)

getNoiseLandUseTypes() : {LandUseType} base/tealdef/game_mechanics/towns/town_util.d.tl:108

Call as town_util.getNoiseLandUseTypes(…)

Notes

District types affected by noise, from townNoiseResidentialAffected, townNoiseCommercialAffected and townNoiseIndustrialAffected of the base config's emission settings.

Returns {LandUseType}: List of district types.

Used in the base game: 1 time in 1 file

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

local noisePerDistrict = api.engine.util.town.getTownNoisePerDistrict(params.entity, town_util.getNoiseLandUseTypes())

getRatingHappinessFromStats(unhappyAndTotal : UtilTown.TownHappinessStats, townState : TownState) : number base/tealdef/game_mechanics/towns/town_util.d.tl:109

Call as town_util.getRatingHappinessFromStats(…)

Notes

Happiness rating from happiness statistics. People travelling inside the town count twice; at least 15 people are assumed. The share of happy people is mapped between bounds that depend on the sensitivity.

Parameter	Type	Description
`unhappyAndTotal`	`UtilTown.TownHappinessStats`	Happiness statistics of the town.
`townState`	`TownState`	State of the town.

Returns number: Rating between 0 and 1; 1 when the sensitivity is 0.

Used in the base game: 1 time in 1 file

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

local rating = town_util.getRatingHappinessFromStats(value.stats, townState)

getFactorLevelNumber(number) : integer base/tealdef/game_mechanics/towns/town_util.d.tl:111

Call as town_util.getFactorLevelNumber(…)

Notes

Level number of a rating value, floor(value * 6) limited to 0 to 5.

Parameter	Type	Description
`#1`	`number`	Rating value between 0 and 1.

Returns integer: Level number.

Used in the base game: 5 times in 2 files

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

local ratingValueShort : integer = town_util.getFactorLevelNumber(ratingValue)

base/content/game_mechanics/game_mechanics/towns/town_util_parallel.script.tl:15

result.passengerRating = passengerRating and town_util.getFactorLevelNumber(passengerRating)

getRatingLevel(integer) : RatingLevel base/tealdef/game_mechanics/towns/town_util.d.tl:112

Call as town_util.getRatingLevel(…)

Notes

Rating level of a level number; 0 is VeryPoor, 5 and above is Excellent.

Parameter	Type	Description
`#1`	`integer`	Level number.

Returns RatingLevel: Rating level.

Used in the base game: 9 times in 2 files

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

local passengerRatingLevel = town_util.getRatingLevel(state:old().passengerRating)

base/content/game_mechanics/game_mechanics/towns/town_util_parallel.script.tl:26

result.suppliesRating = town_util.getRatingLevel(town_util.getRatingDeliveries(townEntity).ratingLevelNumber)

getFactorRatingLevel(number) : RatingLevel base/tealdef/game_mechanics/towns/town_util.d.tl:113

Call as town_util.getFactorRatingLevel(…)

Notes

Rating level of a rating value.

Parameter	Type	Description
`#1`	`number`	Rating value between 0 and 1.

Returns RatingLevel: Rating level.

Used in the base game: 22 times in 6 files

base/content/game_mechanics/game_mechanics/notifications/notifications.script.tl:241

local ratingLevel = town_util.getFactorRatingLevel(ratingValue)

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

local ratingLevel = town_util.getFactorRatingLevel(params.value)

base/content/game_mechanics/game_mechanics/towns/town_util_parallel.script.tl:39

ratingLevel = town_util.getFactorRatingLevel(ratingTraffic)

base/content/gui/gui/debug_panel/make_entity_debug_panel.tl:468

local authorityLevel = town_util.getFactorRatingLevel(townState.authorityScore)

base/content/gui/gui/entity_window/entity_window_util.tl:118

or (param.getRatingLabel ~= nil) and param.getRatingLabel(town_util.getFactorRatingLevel(value))

base/content/gui/gui/statistics/statistic_towns.tl:278

local ratingLevelName = town_util.getFactorRatingLevel(ratingLevel)

isValidRating(Rating, RatingLevel) : boolean base/tealdef/game_mechanics/towns/town_util.d.tl:114

Call as town_util.isValidRating(…)

Notes

Whether a rating level is shown for a rating. Only a hidden rating at Mediocre is not valid.

Parameter	Type	Description
`#1`	`Rating`	Rating.
`#2`	`RatingLevel`	Rating level.

Returns boolean: False for a hidden rating at Mediocre, otherwise true.

Used in the base game: 1 time in 1 file

base/content/gui/gui/statistics/statistic_towns.tl:279

if town_util.isValidRating(staticRating, ratingLevelName) and key ~= "station_demand" then

getRatingSensitivity(TownState, ratingName : TownRatingKey) : number base/tealdef/game_mechanics/towns/town_util.d.tl:115

Call as town_util.getRatingSensitivity(…)

Notes

Sensitivity of a rating for a town; the town's own value from ratingSensitivity, otherwise the default from town_ratings_sensitivity.res scaled through the script option.

Parameter	Type	Description
`#1`	`TownState`	State of the town.
`ratingName`	`TownRatingKey`	Rating key.

Returns number: Sensitivity; 0 or less turns the rating off (it returns 1).

Used in the base game: 3 times in 3 files

base/content/game_mechanics/game_mechanics/celebrations/celebrations.script.tl:83

local sensitivity = town_util.getRatingSensitivity(townState, "urban_care")

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

local sensitivity = town_util.getRatingSensitivity(townState, "urban_care")

base/content/gui/gui/entity_window/town/town_eow.script.tl:889

local sensitivity = town_util.getRatingSensitivity(townState, params.rating)

getTownsToPositions() : {Engine.Entity : Vec3f} base/tealdef/game_mechanics/towns/town_util.d.tl:117

Call as town_util.getTownsToPositions(…)

Notes

Position of every town.

Returns {Engine.Entity : Vec3f}: Position per town entity.

makeGetClosestTownAndDistanceFunction() : function(Vec3f) : {Engine.Entity, number} base/tealdef/game_mechanics/towns/town_util.d.tl:118

Call as town_util.makeGetClosestTownAndDistanceFunction(…)

Notes

Builds a function that finds the closest town to a position. The town positions are read once, when this is called.

Returns function(Vec3f) : {Engine.Entity, number}: Function that returns the closest town and its distance in metres, or nil without towns.

makeGetAffectedTownsFunction() : function(Vec3f, number) : {Engine.Entity} base/tealdef/game_mechanics/towns/town_util.d.tl:119

Call as town_util.makeGetAffectedTownsFunction(…)

Notes

Builds a function that finds the towns affected by a circle (position and radius). The town positions are read once, when this is called.

Returns function(Vec3f, number) : {Engine.Entity}: Function that returns the closest town and all towns within two radii of its distance.

getProposalStats(Type.Proposal, Type.ProposalData, boolean) : ProposalStats base/tealdef/game_mechanics/towns/town_util.d.tl:120

Call as town_util.getProposalStats(…)

Notes

Effects of a construction proposal on nearby towns; removed and placed trees and rocks, demolished town buildings, terrain and tunnel volume.

Parameter	Type	Description
`#1`	`Type.Proposal`	Proposal.
`#2`	`Type.ProposalData`	Proposal data.
`#3`	`boolean`	Whether the player started the proposal.

Returns ProposalStats: Statistics per affected town; empty when not player-initiated.

Used in the base game: 1 time in 1 file

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

local proposalStats : ProposalStats = town_util.getProposalStats(proposal, proposalData, true)

getProposalActions(Proposal, data : ProposalData) : TownProposalActions base/tealdef/game_mechanics/towns/town_util.d.tl:121

Call as town_util.getProposalActions(…)

Notes

Actions of a proposal that need a minimum town rating (station, airport, demolition) and the towns they affect.

Parameter	Type	Description
`#1`	`Proposal`	Proposal.
`data`	`ProposalData`	Proposal data.

Returns TownProposalActions: Actions per affected town.

getActionAllowed(TownState, TownProposalActions.Action) : boolean base/tealdef/game_mechanics/towns/town_util.d.tl:122

Call as town_util.getActionAllowed(…)

Notes

Whether a town's rating allows an action.

Parameter	Type	Description
`#1`	`TownState`	State of the town.
`#2`	`TownProposalActions.Action`	Action.

Returns boolean: True when the rating level of authorityScore is high enough for the action.

getTownName(Engine.Entity) : string base/tealdef/game_mechanics/towns/town_util.d.tl:123

Call as town_util.getTownName(…)

Notes

Name of a town.

Parameter	Type	Description
`#1`	`Engine.Entity`	Town entity.

Returns string: Town name.

getTownSize(Engine.Entity) : integer base/tealdef/game_mechanics/towns/town_util.d.tl:124

Call as town_util.getTownSize(…)

Notes

Average person capacity of the three districts of a town, rounded. No base-game script calls it.

Parameter	Type	Description
`#1`	`Engine.Entity`	Town entity.

Returns integer: Average capacity; 0 for an unknown town.

getSubventionsEnabled(Engine.Entity) : boolean base/tealdef/game_mechanics/towns/town_util.d.tl:125

Call as town_util.getSubventionsEnabled(…)

Notes

Whether a town offers subsidies. The subsidy scripts check this.

Parameter	Type	Description
`#1`	`Engine.Entity`	Town entity.

Returns boolean: True when the town's rating level is VeryGood.

changeTownAuthorityPenalty(TownAuthorityEventFactors, TownAuthorityEventFactors.EventType, number, ?number) : number base/tealdef/game_mechanics/towns/town_util.d.tl:126

Call as town_util.changeTownAuthorityPenalty(…)

Notes

Changes the stored penalty of one reason. The new penalty stays between 0 and the larger of the maximum and the current penalty. The score is not changed.

Parameter	Type	Description
`#1`	`TownAuthorityEventFactors`	Reputation state; changed in place.
`#2`	`TownAuthorityEventFactors.EventType`	Reason.
`#3`	`number`	Change of the penalty.
`#4`	`?number`	Maximum penalty, default 1.

Returns number: Actual change of the penalty.

addTownAuthorityPenalties(TownAuthorityEventFactors, {TownAuthorityEventFactors.EventType : number}) base/tealdef/game_mechanics/towns/town_util.d.tl:127

Call as town_util.addTownAuthorityPenalties(…)

Notes

Changes the penalties of several reasons and lowers or raises score by the total change.

Parameter	Type	Description
`#1`	`TownAuthorityEventFactors`	Reputation state; changed in place.
`#2`	`{TownAuthorityEventFactors.EventType : number}`	Change of the penalty per reason.

Used in the base game: 1 time in 1 file

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

town_util.addTownAuthorityPenalties(

recoverReputation(TownAuthorityEventFactors, number, {TownAuthorityEventFactors.EventType : number}) base/tealdef/game_mechanics/towns/town_util.d.tl:128

Call as town_util.recoverReputation(…)

Notes

Raises score by up to an amount and shrinks the stored penalties in proportion. Penalties in the overrides stay at least at their override value.

Parameter	Type	Description
`#1`	`TownAuthorityEventFactors`	Reputation state; changed in place.
`#2`	`number`	Amount of score to recover.
`#3`	`{TownAuthorityEventFactors.EventType : number}`	Penalties that cannot recover, per reason (the base game passes severed connections).

getReputation(TownAuthorityEventFactors, ?{TownAuthorityEventFactors.EventType : number}) : number base/tealdef/game_mechanics/towns/town_util.d.tl:129

Call as town_util.getReputation(…)

Notes

Reputation score of a town; override penalties above the stored ones are subtracted.

Parameter	Type	Description
`#1`	`TownAuthorityEventFactors`	Reputation state.
`#2`	`?{TownAuthorityEventFactors.EventType : number}`	Optional penalties per reason that apply at least.

Returns number: Score between 0 and 1; 1 without reputation state.

getReputationBreakdown(TownAuthorityEventFactors, ?{TownAuthorityEventFactors.EventType : number}) : {TownAuthorityEventFactors.EventType : number} base/tealdef/game_mechanics/towns/town_util.d.tl:130

Call as town_util.getReputationBreakdown(…)

Notes

Lost reputation split by reason, in proportion to each reason's penalty.

Parameter	Type	Description
`#1`	`TownAuthorityEventFactors`	Reputation state.
`#2`	`?{TownAuthorityEventFactors.EventType : number}`	Optional penalties per reason that apply at least.

Returns {TownAuthorityEventFactors.EventType : number}: Share of the lost reputation per reason; the shares add up to 1 - reputation.

Used in the base game: 1 time in 1 file

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

local penalties = town_util.getReputationBreakdown(townState.eventFactors, { SeveredConnection = targetPenalty })

level2name(integer) : string base/tealdef/game_mechanics/towns/town_util.d.tl:132

Call as town_util.level2name(…)

Notes

Localized name of a town level, from "Small Hamlet" at level 1 to "Large Metropolis" at level 18.

In game Small Hamlet · Town · Large Metropolis

Parameter	Type	Description
`#1`	`integer`	Town level; values outside 1 to 18 are clamped.

Returns string: Localized level name.

Used in the base game: 7 times in 5 files

base/content/game_mechanics/game_mechanics/celebrations/celebration_react_util.tl:50

townType = town_util.level2name(value),

base/content/game_mechanics/game_mechanics/towns/town_notification.script.tl:23

townType = town_util.level2name(notificationParams.level),

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

local currentRankTownName = town_util.level2name(level)

base/content/gui/gui/entity_window/town/town_eow.script.tl:61

text = town_util.level2name(level),

base/content/gui/gui/statistics/statistic_towns.tl:68

return createCell(town_util.level2name(levelState:old()))

getTownForSimEntity(simEntity : Engine.Entity, direction : boolean) : Engine.Entity base/tealdef/game_mechanics/towns/town_util.d.tl:134

Call as town_util.getTownForSimEntity(…)

Notes

Town of the station at the start or end stop of a sim person's or cargo's current line trip.

Parameter	Type	Description
`simEntity`	`Engine.Entity`	Sim entity in a vehicle or at a terminal.
`direction`	`boolean`	True for the start stop (`lineStop0`), false for the end stop (`lineStop1`).

Returns Engine.Entity: Town entity, or nil when the station group has no stations.

Used in the base game: 6 times in 2 files

base/content/game_mechanics/game_mechanics/subventions/deliver_passengers/deliver_passengers.script.tl:268

local fromTown = town_util.getTownForSimEntity(simEntity, true)

base/content/mission/mission/tasks/transport_cargo/transport_passengers.tl:45

local fromTown = town_util.getTownForSimEntity(simEntity, true)

isMarketingActive(atTimestamp : integer, factors : TownAuthorityEventFactors) : boolean base/tealdef/game_mechanics/towns/town_util.d.tl:135

Call as town_util.isMarketingActive(…)

Notes

Whether a marketing campaign runs at a given time.

Parameter	Type	Description
`atTimestamp`	`integer`	Game time in ms.
`factors`	`TownAuthorityEventFactors`	Reputation state of the town.

Returns boolean: True when atTimestamp is before the campaign's start plus durationMs.

Used in the base game: 1 time in 1 file

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

local hasMarketingCampaign = town_util.isMarketingActive(now, townState.eventFactors)

forEachMatchingStocklist(stockList : Engine.Component.StockList, callback : function(Engine.Entity, CargoTypeId)) : {CargoTypeId : boolean} base/tealdef/game_mechanics/towns/town_util.d.tl:138

Call as town_util.forEachMatchingStocklist(…)

return input/output cargo types (depending on argument stockListType)

Returns {CargoTypeId : boolean}

Used in the base game: 1 time in 1 file

base/content/gui/gui/entity_window/industry/industry.tl:240

town_util.forEachMatchingStocklist(stockList,

isCapital(townEntity : Engine.Entity) : boolean base/tealdef/game_mechanics/towns/town_util.d.tl:141

Call as town_util.isCapital(…)

Notes

Whether a town is the player's capital, the town closest to the player's headquarters.

Parameter	Type	Description
`townEntity`	`Engine.Entity`	Town entity.

Returns boolean: True for the capital.

Used in the base game: 1 time in 1 file

base/content/gui/gui/main/town_hud_react_util.tl:63

local isHQTown = town_util.isCapital(params.entity)

TownUtil.Rating¶

record base/tealdef/game_mechanics/towns/town_util.d.tl:13

record Rating

Notes

Description of one town rating with its name, icons and the functions that compute it.

Used in the base game: 6 times in 2 files

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

town_react_util.GetRatingsDashboard = function() : {town_react_util.TownInfoTabType : {TownUtil.Rating, Recipe<TownReactUtil.TownDetailsParam>, string}}

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

town_util.GetRating = function(key : string) : TownUtil.Rating

Fields

Name	Type	Description
`name`	`string`	Localized display name.
`icon`	`string`	Path of the small icon.
`iconLarge`	`string`	Path of the 32 px icon.
`range`	`{integer, integer}`
`added`	`boolean`	When true, `calcAuthorityScore` adds `(value - 0.5) * 2` to the score instead of taking the minimum. No base-game rating sets it.
`hidden`	`boolean`	When true, `isValidRating` treats the `Mediocre` level as not valid.
`getRatingFnName`	`ResName`	Script path of the matching `TownUtilParallel` function, used by the GUI with `engine_react_util.useStepStateParallel`.
`getRatingFnExtraParam`	`any`	Passed as `extraParam` to the function named in `getRatingFnName`.
`key`	`string`	Rating key, also the key in `TownState.cachedRatings`.
`onClickEvent`	`{string, any}`	GUI event name and param fired when the rating is clicked, for example `{"openLayerRidge", { layer = "menu.layers.noiseButton", stack = true }}`.

Functions

getRating(Engine.Entity, TownState) : number base/tealdef/game_mechanics/towns/town_util.d.tl:21

Notes

Computes the rating value.

Parameter	Type	Description
`#1`	`Engine.Entity`	Town entity.
`#2`	`TownState`	State of the town.

Returns number: Rating value between 0 and 1.

debugGetInfo(Engine.Entity, TownState) : string base/tealdef/game_mechanics/towns/town_util.d.tl:26

Notes

Debug text for the rating; the noise and pollution ratings return their random offset in dB.

Parameter	Type	Description
`#1`	`Engine.Entity`	Town entity.
`#2`	`TownState`	State of the town.

Returns string: Debug text.

TownUtil.RatingDeliveries¶

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

record RatingDeliveries

Notes

Combined supplies rating of a town (getRatingDeliveries).

Used in the base game: 1 time in 1 file

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

town_util.getRatingDeliveries = function(entity : Engine.Entity) : TownUtil.RatingDeliveries

Fields

Name	Type	Description
`ratingLevelNumber`	`integer`	Level number from 0 (`VeryPoor`) to 5 (`Excellent`).
`noDeliveries`	`boolean`	True when the town has demand but nothing is supplied.

TownUtil.EmitterCategory¶

enum base/tealdef/game_mechanics/towns/town_util.d.tl:42

enum EmitterCategory

Notes

Categories of noise and pollution sources (getTownEmissionEmitters).

Used in the base game: 7 times in 3 files

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

local function EmitterCategoryToString(category : TownUtil.EmitterCategory) : string

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

town_util.getTownEmissionEmitters = function(townEntity : Engine.Entity, pollution : boolean, byLine? :{Engine.Entity : number}) : {TownUtil.EmitterCategory : n

base/content/game_mechanics/game_mechanics/towns/town_util_parallel.script.tl:92

table.sort(result.emissionPerSource, function(a : {TownUtil.EmitterCategory, integer}, b : {TownUtil.EmitterCategory, integer}) : boolean

Value	Description
`"company_vehicles"`	Vehicles of the player's transport lines.In game Company Vehicles
`"residents_vehicles"`	Other vehicles, such as the residents' cars.In game Residents' Vehicles
`"industries"`	Industries and fields.In game Industries
`"depots"`	Vehicle depots with track or street access.In game Depots
`"maintenance_buildings"`	Vehicle depots without in or out nodes.In game Maintenance Buildings
`"stations"`	Stations and station groups.In game Stations
`"tracks"`	Tracks and streets (base edges).In game Tracks
`"warehouses"`	Warehouses.In game Warehouses
`"other"`	Any other source.In game Other