town_cargo¶

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

Notes

Town experience and level state of the town growth script (town_cargo.gs) and its configuration.

TownsGrowthState¶

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

global record TownsGrowthState

Notes

State of the town growth game script town_cargo.gs (town_growth.script). Read it with TownCargoUtil.getTownCargoState.

Fields

Name	Type	Description
`townState`	`{Engine.Entity : TownData}`	Growth data per town entity.
`cargoDemandsSorted`	`{CargoTypeId}`	Sorted ids of all cargo types that any town demands. When the list changes, the script sends the `Towns`/`CargoDemandsChanged` event.
`disabledCelebratoryFireworks`	`boolean`	True after the `DisableCelebratoryFireworks` event; level-ups then start no fireworks.

TownsGrowthState.TownData¶

record base/tealdef/game_mechanics/towns/town_cargo.d.tl:4

record TownData

Notes

Experience and level of one town.

Used in the base game: 2 times in 1 file

base/content/game_mechanics/game_mechanics/towns/town_cargo_util.tl:64

town_cargo_util.getTownCargoState = function(entity : Engine.Entity) : TownsGrowthState.TownData

Fields

Name	Type	Description
`experience`	`integer`	Experience points the town has collected in total.
`initialLevel`	`integer`	Town level when the state was first created. `TownCargoUtil.getGrowthFactor` counts levels from here.
`level`	`integer`	Current town level. Each increase sends the `Towns`/`OnLevelUp` script event and a level-up notification.
`cargoDelivered`	`boolean`	True once any cargo item was delivered to a building of the town. Until then a level-up adds no new cargo demands.
`accumulatedExperience`	`{string : {integer : TownsGrowthState.TownData.AddedExperience}}`	per category (cargo, passenger) and tier

TownsGrowthState.TownData.AddedExperience¶

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

record AddedExperience

Notes

Experience gained from one source and tier since the last journal log.

Fields

Name	Type	Description
`rawExperience`	`integer`	Experience before the town's experience factor (`TownUtil.getXpFactor`) was applied. Logged as `experience_raw_<tier>_<source>`.
`multipliedExperience`	`integer`	Experience after the experience factor was applied, as added to `experience`. Logged as `experience_gain_<tier>_<source>`.

TownCargoUtil¶

record global base/tealdef/game_mechanics/towns/town_cargo.d.tl:20

global record TownCargoUtil

Load: local town_cargo_util = ug_require "/game_mechanics/towns/town_cargo_util.tl"

Notes

Constants and state access of the town growth script (game_mechanics/towns/town_cargo_util.tl).

Fields

Name	Type	Description
`growthPerTick`	`number`	Experience added to every town on each script update. The base game sets it to `0` (off). used 2× in the base game
`levelUpSizeFactor`	`number`	Set to `1.25` with the code comment "Level up size increase (compound)". No base-game script reads it.
`levelUpFactorRange`	`number`	Set to `0.02` with the code comment "Level up size increase (compound)". No base-game script reads it.
`townExpScaling`	`number`	Ratio between the experience needed for a level and for the level before it. The base game sets it to `1.5`.
`authority2xpFactor`	`{RatingLevel : number}`	Experience multiplier per town growth level, from `0.0` at `VeryPoor` to `1.0` at `Excellent` in steps of `0.2`. used 2× in the base game

Functions

ensureState(scriptState : TownsGrowthState, townEntity : Engine.Entity) base/tealdef/game_mechanics/towns/town_cargo.d.tl:27

Call as town_cargo_util.ensureState

Notes

Creates the growth data of a town if it is missing. A new town starts at level 2, 3 or 4 when its initial residential capacity is above 100, 150 or 200 (otherwise level 1), with the experience that level needs.

Parameter	Type	Description
`scriptState`	`TownsGrowthState`	State of the town growth script; changed in place.
`townEntity`	`Engine.Entity`	Town entity.

Used in the base game: 1 time in 1 file

base/content/game_mechanics/game_mechanics/towns/town_growth.script.tl:195

town_cargo_util.ensureState(scriptState, townEntity)

getTownCargoState(entity : Engine.Entity) : TownsGrowthState.TownData base/tealdef/game_mechanics/towns/town_cargo.d.tl:29

Call as town_cargo_util.getTownCargoState

Notes

Reads the growth data of a town from the town_cargo.gs game script component.

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

Returns TownsGrowthState.TownData: The town's experience and level data.

Used in the base game: 7 times in 6 files

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

local townCargoState = town_cargo_util.getTownCargoState(entityAndRevisionState:old().entity)

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

local state = town_cargo_util.getTownCargoState(params.entity)

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

local state = town_cargo_util.getTownCargoState(entity)

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

local state = town_cargo_util.getTownCargoState(townEntity)

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

local state = town_cargo_util.getTownCargoState(params.entity)

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

local townCargoState = town_cargo_util.getTownCargoState(townEntity)

getLevelAndFraction(exp : integer) : integer, number, integer, integer base/tealdef/game_mechanics/towns/town_cargo.d.tl:32

Call as town_cargo_util.getLevelAndFraction

return: current level, fraction/percentage reached of current level, experience needed for current level, experience needed for next level

Returns integer, number, integer, integer

Used in the base game: 8 times in 6 files

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

local __level, __fraction, expForCurrLevel, expForNextLevel : integer, number, integer, integer = town_cargo_util.getLevelAndFraction(exp)

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

local __level, fraction, __expForCurrLevel, __expForNextLevel : integer, number, integer, integer = town_cargo_util.getLevelAndFraction(state.experience)

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

local level : integer = town_cargo_util.getLevelAndFraction(state.experience)

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

local level, fraction, __expForCurrLevel, __expForNextLevel : integer, number, integer, integer = town_cargo_util.getLevelAndFraction(exp)

base/content/game_mechanics/game_mechanics/towns/town_growth.script.tl:87

local newLevel = town_cargo_util.getLevelAndFraction(exp)

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

local level, __fraction, __, expForNextLevel : integer, number, integer, integer = town_cargo_util.getLevelAndFraction(expState:old())

getGrowthFactor(townEntity : Engine.Entity, scriptState : TownsGrowthState) : number base/tealdef/game_mechanics/towns/town_cargo.d.tl:33

Call as town_cargo_util.getGrowthFactor

Notes

Growth factor of a town from TownGrowthFunction.getGrowthFactor, based on the levels gained since initialLevel plus the fraction of the current level.

Parameter	Type	Description
`townEntity`	`Engine.Entity`	Town entity.
`scriptState`	`TownsGrowthState`	State of the town growth script.

Returns number: Growth factor of the town.

Used in the base game: 3 times in 3 files

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

local growthFactor =  town_cargo_util.getGrowthFactor(entityAndRevisionState:old().entity, scriptState.state)

base/content/game_mechanics/game_mechanics/towns/town_growth.script.tl:373

local baseFactor = town_cargo_util.getGrowthFactor(townEntity, scriptState)

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

local growthFactor =  town_cargo_util.getGrowthFactor(townEntity, scriptState.state)

TownGrowthConfig¶

record global base/tealdef/game_mechanics/towns/town_cargo.d.tl:36

global record TownGrowthConfig

Notes

Experience settings of the town growth script, loaded from town_growth_config.res.

Fields

Name	Type	Description
`expPerCargoItemToTown`	`integer`	Base experience for each cargo item delivered to a town building (`10`). Multiplied by `2^tier` of the cargo category and by the town's experience factor.
`expPerPersonArriveAtTown`	`integer`	Base experience for each person who arrives in the town by line (`5`). Multiplied by `2^tier`, where the tier is 0 for trips inside the town, 1 from a neighbour town and 2 from any other town.
`expBaseTownLevel`	`integer`	Experience needed to reach level 2 (`1000`). Each further level needs `TownCargoUtil.townExpScaling` times as much as the one before.