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.
`"traffic_congestion"`	Traffic rating.
`"people_happiness"`	Happiness rating.
`"cargo_delivery"`	Delivery time rating.
`"noise"`	Noise rating.
`"pollution"`	Pollution rating.

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"

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
`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/gui/gui/layers/layer_react_util.tl:104

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

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

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

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

for __, rating 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

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

local ratings = town_util.GetRatings()

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

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

… 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.

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/mission/mission/mission_framework/mission_framework_react_util.tl:150

local staticRating = town_util.GetRating(progress.townRatingKey)

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

local staticRating = town_util.GetRating(key)

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:55

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/mission/mission/tasks/town_rating/town_rating.tl:75

local rank = town_util.getMultiplierToRankClass(rating)

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

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

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

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:57

Call as town_util.getRatingLabel

Notes

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

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

Returns string: Localized label.

Used in the base game: 12 times in 3 files

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

local reputationLabel = town_util.getRatingLabel(reputationRatingLevel)

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

getRatingLabel = town_util.getRatingLabel,

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

text = town_util.getRatingLabel(ratingLevel),

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

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/mission/mission/mission_framework/mission_framework_react_util.tl:149

local ratingName = town_util.getRatingNameFromKey(progress.townRatingKey)

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

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

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

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: 7 times in 6 files

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

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

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

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

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

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

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/game_mechanics/game_mechanics/towns/town_react_util.tl:1037

-- local urbanCare = town_util.getRatingUrbanCare(params.entity, townState)

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

local ratingUrbanCare = town_util.getRatingUrbanCare(townEntity, townState)

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

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/mission/mission/tasks/town_rating/town_rating.tl:22

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

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

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

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/game_mechanics/game_mechanics/towns/town_react_util.tl:1790

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

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

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/mission/mission/tasks/town_rating/town_rating.tl:25

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

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

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

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)

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

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/mission/mission/tasks/town_rating/town_rating.tl:13

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

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

local ratingTraffic = town_util.getRatingTraffic(townEntity, townState)

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

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:64

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/mission/mission/tasks/town_rating/town_rating.tl:16

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

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

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

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

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

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

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/mission/mission/tasks/town_rating/town_rating.tl:19

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

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

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

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

local cargoDeliveryRating = town_util.getRatingCargoDelivery(townEntity, townState)

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

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:67

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_util_parallel.script.tl:26

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

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

local ratingDeliveries = town_util.getRatingDeliveries(params.entity)

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

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.

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/gui/gui/main/town_hud_react_util.tl:77

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

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

local growthLevel = town_util.getGrowthLevelMult(townEntity, townState)

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

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_util_parallel.script.tl:260

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

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

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

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

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:72

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:73

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:75

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:76

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/gui/gui/layers/layer_cargo_flow.tl:73

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

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

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

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

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/mission/mission/tasks/town_rating/town_rating.tl:64

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

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/game_mechanics/game_mechanics/subventions/deliver_cargo_town/deliver_cargo_town.script.tl:138

local cargoSupplyDemands : CargoTypeSupplyDemands = town_util.getCargoSupplyDemands(townEntity)

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

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:79

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/mission/mission/tasks/town_size/town_size_task_util.tl:9

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

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

state.capacities = town_util.getTownCapacityUsages(entity)

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

local userdataResult = town_util.getTownCapacityUsages(townEntity)

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

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

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:80

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:81

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:82

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:83

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:84

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:85

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:86

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:87

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:88

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:89

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:90

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/mission/mission/tasks/town_rating/town_rating.tl:10

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

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

local townState = town_util.externalGetTownState(entity)

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

local townState = town_util.externalGetTownState(entityId)

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

local townState = town_util.externalGetTownState(params.entity)

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

local townState = town_util.externalGetTownState(entity)

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:91

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/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()

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

local townsState = town_util.externalGetTownsState()

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

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:95

Call as town_util.getItemsAtDestinationPerYear

getStationSamples : function(Engine.Entity) : StationSamples getStationRating : function(StationSamples, number) : number -- range -1 .. 1

Returns integer

Used in the base game: 3 times in 2 files

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

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

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

return town_util.getItemsAtDestinationPerYear(townEntity, cargoTypeId)

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

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:97

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:98

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:99

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:3822

local impact = town_util.calculateProposalImpact(townStats)

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

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:101

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:102

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:103

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:104

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:105

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/towns/town_react_util.tl:1048

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

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

local numSeveredConnections = #town_util.getSeveredMainConnections(townEntity)

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

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:107

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:108

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:110

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_util_parallel.script.tl:15

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

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

local ratingValueShort : integer = town_util.getFactorLevelNumber(ratingValue)

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

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: 10 times in 2 files

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

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

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

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

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

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/gui/gui/debug_panel/make_entity_debug_panel.tl:468

local authorityLevel = town_util.getFactorRatingLevel(townState.authorityScore)

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

local ratingLevelName = town_util.getFactorRatingLevel(ratingLevel)

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

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

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_util_parallel.script.tl:39

ratingLevel = town_util.getFactorRatingLevel(ratingTraffic)

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

local ratingLevel = town_util.getFactorRatingLevel(params.value)

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

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:114

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/gui/gui/entity_window/town/town_eow.script.tl:889

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

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

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

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

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

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

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:117

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:118

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:119

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:3816

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

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

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:121

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:122

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:123

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:124

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.

Used in the base game: 6 times in 2 files

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

-- local subventionsEnabled = town_util.getSubventionsEnabled(townEntity)

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

-- local subventionsEnabled = town_util.getSubventionsEnabled(e)

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

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:126

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:3828

town_util.addTownAuthorityPenalties(

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

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:128

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:129

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:131

Call as town_util.level2name

Notes

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

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/gui/gui/statistics/statistic_towns.tl:68

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

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

text = town_util.level2name(level),

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

local currentRankTownName = town_util.level2name(level)

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

townType = town_util.level2name(notificationParams.level),

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

townType = town_util.level2name(value),

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

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/mission/mission/tasks/transport_cargo/transport_passengers.tl:45

local fromTown = town_util.getTownForSimEntity(simEntity, true)

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

local fromTown = town_util.getTownForSimEntity(simEntity, true)

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

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:137

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:140

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:634

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:36

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:559

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:41

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_util_parallel.script.tl:92

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

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:1751

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

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