entity_util

Source: base/tealdef/scripts/entity_util.d.tl

Notes

Types of /scripts/entity_util.tl (EntityUtil): helpers to remember an entity together with its revision (so a script can detect later that it changed or was removed), and ownership/position lookups.

EntityUtil

record global base/tealdef/scripts/entity_util.d.tl:3

global record EntityUtil

Load: local entity_util = ug_require "::/scripts/entity_util.tl"

Notes

Entity helpers returned by ug_require "/scripts/entity_util.tl".

Functions

makeEntityAndRevision(Engine.Entity) : EntityAndRevision base/tealdef/scripts/entity_util.d.tl:9

Call as entity_util.makeEntityAndRevision

Notes

Records an entity with its full current revision.

Returns EntityAndRevision: The record, or nil if the entity does not exist.

Used in the base game: 54 times in 31 files

base/content/industries/industry_workers.script.tl:116

entity = entity_util.makeEntityAndRevision(entity),

base/content/landmarks/landmarks.script.tl:52

entity =  entity_util.makeEntityAndRevision(entity),

base/content/mission/mission/tasks/spawn_sims/spawn_sims.tl:93

runtimeEntityIds[i] = entity_util.makeEntityAndRevision(runtimeEntity).entity

base/content/mission/mission/tasks/click_and_collect_custom_entity/spawn_entity.tl:31

runtimeEntityIds[i] = entity_util.makeEntityAndRevision(runtimeEntity).entity

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

return entity_util.makeEntityAndRevision(entity)

base/content/gui/gui/line_vehicle_mgmt/vehicle_store_window.tl:3448

t[entityAndEntry.vehicleEntity] = entity_util.makeEntityAndRevision(entityAndEntry.vehicleEntity)

… and 25 more files.

makeEntityAndRevision0(Engine.Entity) : EntityAndRevision base/tealdef/scripts/entity_util.d.tl:10

Call as entity_util.makeEntityAndRevision0

Notes

Records an entity with only the first revision number (the other two set to 0).

Returns EntityAndRevision: The record, or nil if the entity does not exist.

Details

Use with entityChanged0, which compares only the first revision number.

Used in the base game: 31 times in 6 files

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

local townEntity = entity_util.makeEntityAndRevision0(entity)

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

entities = {entity_util.makeEntityAndRevision0(lineEntity)},

base/content/game_mechanics/game_mechanics/company/company.script.tl:441

local townEntity = entity_util.makeEntityAndRevision0(param.townEntity)

base/content/game_mechanics/game_mechanics/company/company_legacy_util.tl:49

pendingProspection.townEntity = entity_util.makeEntityAndRevision0(oldTownEntity)

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

local entityAndRev0 = entity_util.makeEntityAndRevision0(townBuildingComponent.town)

dlcs/urbangames_deluxe_upgrade_pack/content/fun_elements/fun_elements/balloon.script.tl:142

entity = entity_util.makeEntityAndRevision0(balloon.entity),

makeEntityAndRevision0Array({Engine.Entity}) : {EntityUtil.EntityAndRevision} base/tealdef/scripts/entity_util.d.tl:11

Call as entity_util.makeEntityAndRevision0Array

Notes

Applies makeEntityAndRevision0 to each entity and returns the records of those that exist.

Returns {EntityUtil.EntityAndRevision}

Used in the base game: 5 times in 2 files

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

entities = entity_util.makeEntityAndRevision0Array(entitiesAndProblem[1]),

mods/release/urbangames_campaign_mission_05/content/mission/mission/tasks/drilling/drilling.tl:20

entities = entity_util.makeEntityAndRevision0Array(getEntititesForNotification(entity)),

entityEquals(EntityAndRevision, EntityAndRevision) : boolean base/tealdef/scripts/entity_util.d.tl:12

Call as entity_util.entityEquals

Notes

True if both records have the same entity id and the same first revision number.

Returns boolean

Used in the base game: 6 times in 6 files

base/content/industries/industry_workers.script.tl:63

if entity_util.entityEquals(pendingVisitor.entity, currentVisitor.entity) then

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

if ecoLevel and ecoLevel[1] and entity_util.entityEquals(ecoLevel[1], entityAndRev) then

base/content/game_mechanics/game_mechanics/company/company.script.tl:491

if ecoLevel and ecoLevel[1] and entity_util.entityEquals(ecoLevel[1], entityAndRev) then

base/content/game_mechanics/game_mechanics/company/company_util.tl:246

if entity_util.entityEquals(companyState.companyEntity, companyEntityAndRevision) then

base/content/game_mechanics/game_mechanics/emission/emissions.script.tl:189

if ecoLevel and entity_util.entityEquals(ecoLevel[1], entityAndRev) then

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

if entity_util.entityEquals(townState.townEntity, townEntityAndRevision) then

entityChanged0(EntityAndRevision) : boolean base/tealdef/scripts/entity_util.d.tl:13

Call as entity_util.entityChanged0

Notes

True if the entity no longer exists or its first revision number has increased since the record was made.

Returns boolean

Used in the base game: 84 times in 42 files

base/content/landmarks/landmarks_notification.script.tl:16

if entity_util.entityChanged0(notificationParams.entity) then

base/content/gui/gui/hud/greenification_display.script.tl:96

if not entity_util.entityChanged0(ecoLevel[1]) then

base/content/gui/gui/line_vehicle_mgmt/vehicle_store_window.tl:3492

if entityAndEntry.vehicleEntity < 0 or not entity_util.entityChanged0(initialSelection:get()[entityAndEntry.vehicleEntity]) then

base/content/gui/gui/line_vehicle_mgmt/manager_window.tl:465

if lineEAR and not entity_util.entityChanged0(lineEAR) then

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

if not entity_util.entityChanged0(visitor.entity) then

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

if not entity_util.entityChanged0(entity) then

… and 36 more files.

entityChanged(EntityAndRevision) : boolean base/tealdef/scripts/entity_util.d.tl:14

Call as entity_util.entityChanged

Notes

True if the entity no longer exists or its first or second revision number has increased since the record was made.

Returns boolean

Used in the base game: 2 times in 2 files

base/content/gui/gui/entity_window/bridge_and_tunnel.tl:199

if not entity_util.entityChanged({ entity = entityRevision[1], revision = entityRevision[2] }) then

mods/release/urbangames_campaign_mission_03/content/mission/mission/mission_story.tl:90

if not entity_util.entityChanged(entityAndRev) and getOasisLevel(entityAndRev.entity) == 1 then

getPosition(Engine.Entity) : Vec3f base/tealdef/scripts/entity_util.d.tl:15

Call as entity_util.getPosition

Notes

Centre of the entity's bounding box (BOUNDING_VOLUME component).

Returns Vec3f: The centre position, or nil if the entity has no bounding volume.

Used in the base game: 75 times in 26 files

base/content/mission/mission/params_mt.lua:7

local position = entity_util.getPosition(self[key:sub(n + 1)])

base/content/mission/mission/mission_task_util.tl:25

local pos = entity_util.getPosition(entity)

base/content/mission/mission/name_util.tl:150

local p = entity_util.getPosition(entities[j])

base/content/mission/mission/tutorial/tutorial_story.tl:89

local townCenter = entity_util.getPosition(town)

base/content/mission/mission/tutorial/tutorial_story_branch_b.tl:783

local pos = entity_util.getPosition(conTask.specific.resultEntities[1])

base/content/mission/mission/tutorial/tutorial_story_branch_a.tl:637

local pos = entity_util.getPosition(conTask.specific.resultEntities[1])

… and 20 more files.

sameRevision(Engine.Revision, Engine.Revision) : boolean base/tealdef/scripts/entity_util.d.tl:16

Call as entity_util.sameRevision

Notes

True if all three revision numbers are equal.

Returns boolean

getEntityName(Engine.Entity) : string base/tealdef/scripts/entity_util.d.tl:17

Call as entity_util.getEntityName

Notes

Display name of the entity (api.engine.util.getEntityName).

Returns string

Used in the base game: 34 times in 23 files

base/content/gui/gui/line_vehicle_mgmt/line_manager_panel.tl:1171

name = entity_util.getEntityName(stopPick.stationGroup),

base/content/gui/gui/line_vehicle_mgmt/manager_tooltips_util.tl:20

name = entity_util.getEntityName(entity)

base/content/game_mechanics/game_mechanics/notifications/notification_legacy_util.tl:99

simParams.mapping[entityAndRev[1]] = entity_util.getEntityName(entityAndRev[1])

base/content/game_mechanics/game_mechanics/company/company_notification_marketing.sim.script.tl:7

old.townEntityName = entity_util.getEntityName(notificationParams.townEntity.entity)

base/content/game_mechanics/game_mechanics/company/company_notification_prospection.sim.script.tl:6

old.townEntityName = entity_util.getEntityName(notificationParams.townEntity.entity)

base/content/game_mechanics/game_mechanics/company/company_notification_greenify.sim.script.tl:7

old.constructionEntityName = entity_util.getEntityName(notificationParams.constructionEntity.entity)

… and 17 more files.

getPlayerOwned(Engine.Entity) : Engine.Component.PlayerOwned base/tealdef/scripts/entity_util.d.tl:18

Call as entity_util.getPlayerOwned

Notes

The entity's PLAYER_OWNED component, or nil if no player owns it.

Returns Engine.Component.PlayerOwned

Used in the base game: 1 time in 1 file

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

local po = entity_util.getPlayerOwned(e)

isOwnedByPlayer(Engine.Entity) : boolean base/tealdef/scripts/entity_util.d.tl:19

Call as entity_util.isOwnedByPlayer

Notes

True if the entity is owned by the current player (api.engine.util.getPlayer()).

Returns boolean

Used in the base game: 30 times in 16 files

base/content/mission/mission/mission_sim.script.tl:324

if entity_util.isOwnedByPlayer(entity) then

base/content/mission/mission/tutorial/tutorial_story_util.tl:350

if entity_util.isOwnedByPlayer(vehicle) then

base/content/mission/mission/tasks/buy_vehicle/buy_vehicle.tl:93

if entity_util.isOwnedByPlayer(vehicle) then

base/content/mission/mission/tasks/assign_vehicle/assign_vehicle.tl:55

if entity_util.isOwnedByPlayer(line) then

base/content/mission/mission/tasks/assign_vehicle/visit_stations_ordered.tl:45

if entity_util.isOwnedByPlayer(vehicle) then

base/content/gui/gui/hud/happy_change_display.script.tl:26

if atTerminal and not entity_util.isOwnedByPlayer(atTerminal.line) then

… and 10 more files.

isOwnedByPlayerOrNotOwned(Engine.Entity) : boolean base/tealdef/scripts/entity_util.d.tl:20

Call as entity_util.isOwnedByPlayerOrNotOwned

Notes

True if the entity is owned by the current player or has no owner.

Returns boolean

Used in the base game: 12 times in 8 files

base/content/mission/mission/tasks/create_line/create_line_for_towns.tl:52

if entity_util.isOwnedByPlayerOrNotOwned(entity) then

base/content/gui/gui/line_vehicle_mgmt/manager_window.tl:49

if construction and construction.stations and entity_util.isOwnedByPlayerOrNotOwned(conEntity) then

base/content/gui/gui/line_vehicle_mgmt/line_util.tl:1218

if oldContext.player and not entity_util.isOwnedByPlayerOrNotOwned(entity) then

base/content/gui/gui/main/hud_icon_toolbox.tl:196

if not entity_util.isOwnedByPlayerOrNotOwned(constructionEntity) then

base/content/gui/gui/statistics/statistic_stations.tl:264

if entity_util.isOwnedByPlayerOrNotOwned(entity) then

base/content/gui/gui/entity_window/warehouse/warehouse.tl:38

isModifiable = entity_util.isOwnedByPlayerOrNotOwned(constructionEntity),

… and 2 more files.

getBoundingVolumePosition(Engine.Component.BoundingVolume) : Vec3f base/tealdef/scripts/entity_util.d.tl:22

Call as entity_util.getBoundingVolumePosition

Notes

Centre of the given bounding volume's box.

Returns Vec3f

Used in the base game: 2 times in 2 files

base/content/mission/mission/mission_outline.tl:126

local pos = entity_util.getBoundingVolumePosition(bv)

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

local location = entity_util.getBoundingVolumePosition(proposalData.toAddData_native:at(index).boundingVolume)

EntityUtil.EntityAndRevision

record base/tealdef/scripts/entity_util.d.tl:4

record EntityAndRevision

Notes

An entity id stored together with the revision it had when it was recorded. Scripts keep these in their state and later call entityChanged / entityChanged0 to see whether the entity was modified, rebuilt or removed in the meantime.

Used in the base game: 91 times in 27 files

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

local entityAndRevisionState = engine_react_util.useStepState(function() : EntityUtil.EntityAndRevision

base/content/gui/gui/hud/greenification_display.script.tl:92

local ecoLevels = emissionsScriptState and emissionsScriptState.ecoLevels as {Engine.Entity : {EntityUtil.EntityAndRevision, integer}} or nil

base/content/gui/gui/line_vehicle_mgmt/vehicle_store_window.tl:3443

local initialSelection = react.useRefLazy(function() : {Engine.Entity : EntityUtil.EntityAndRevision}

base/content/gui/gui/line_vehicle_mgmt/manager_window.tl:457

local lineEAR : EntityUtil.EntityAndRevision = nil

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

local ecoLevels = emissionsScriptState and emissionsScriptState.ecoLevels as {Engine.Entity : {EntityUtil.EntityAndRevision, integer}} or nil

base/content/scripts/scripts/entity_util.tl:3

function entity_util.makeEntityAndRevision(entity : Engine.Entity) : EntityUtil.EntityAndRevision

… and 21 more files.

Fields

Name	Type	Description
entity	Engine.Entity	The entity id.
revision	Engine.Revision	The revision of the entity at the time it was recorded.