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" as EntityUtil

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/game_mechanics/game_mechanics/company/company.script.tl:151

resultEntity = entity_util.makeEntityAndRevision(resultEntities[1][1]),

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

local companyEntityAndRevision = entity_util.makeEntityAndRevision(companyEntity)

base/content/game_mechanics/game_mechanics/emission/emission_legacy_util.tl:30

ecoLevels[k] = {entity_util.makeEntityAndRevision(k), v}

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

local entityAndRev = entity_util.makeEntityAndRevision(entity)

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

blimpData.blimpEntity = entity_util.makeEntityAndRevision(blimpEntity)

base/content/game_mechanics/game_mechanics/fun_elements/rocket_util.tl:38

rocketData.rocketEntity = entity_util.makeEntityAndRevision(rocketEntity)

… 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: 34 times in 8 files

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

local entityAndRev0 = entity_util.makeEntityAndRevision0(townBuildingComponent.town)

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/notifications/notifications.script.tl:145

entities = {entity_util.makeEntityAndRevision0(lineEntity)},

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

local townEntity = entity_util.makeEntityAndRevision0(entity)

base/content/mission/mission/tasks/utility/store_entity.tl:8

local snapshot = entity_util.makeEntityAndRevision0(entity)

… and 2 more files.

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

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

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

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

return params.vehicleEntities and entity_util.makeEntityAndRevision0Array(params.vehicleEntities) or nil

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/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:209

if entity_util.entityEquals(townState.townEntity, townEntityAndRevision) 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/industries/industry_workers.script.tl:63

if entity_util.entityEquals(pendingVisitor.entity, currentVisitor.entity) 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: 87 times in 43 files

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

if celebration.entity and entity_util.entityChanged0(celebration.entity) then

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

proposal = api.engine.util.proposal.makeIndustrySpawnProposal(industryType, (not entity_util.entityChanged0(pending.townEntity)) and pending.townEntity.entity o

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

if notificationParams.constructionEntity and not entity_util.entityChanged0(notificationParams.constructionEntity) then

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

if notificationParams.townEntity and not entity_util.entityChanged0(notificationParams.townEntity) then

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

if notificationParams.townEntity and not entity_util.entityChanged0(notificationParams.townEntity) then

base/content/game_mechanics/game_mechanics/notifications/notification_util.tl:444

and not entity_util.entityChanged0(entityAndRevision))

… and 37 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: 54 times in 26 files

base/content/game_mechanics/game_mechanics/achievements/achievements.script.tl:412

local position = entity_util.getPosition(headCarriage)

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

local origin = entity_util.getPosition(townEntity)

base/content/game_mechanics/game_mechanics/fun_elements/fireworks.script.tl:152

local townPostion = entity_util.getPosition(townEntity)

base/content/game_mechanics/game_mechanics/fun_elements/ufo_util.tl:122

local centerPos = entity_util.getPosition(selectedField)

base/content/game_mechanics/game_mechanics/subventions/deliver_cargo/deliver_cargo.script.tl:74

local targetIndustryPosition = entity_util.getPosition(industry.stockList)

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

local targetTownPosition = entity_util.getPosition(townEntityAndCargoTypeId[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/game_mechanics/game_mechanics/celebrations/celebration_react_util.tl:31

townName = entity_util.getEntityName(target.entity)

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

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

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/notifications/notification_legacy_util.tl:99

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

base/content/game_mechanics/game_mechanics/notifications/types/cargo_rtc_warning.sim.script.tl:17

currentValues = {entity_util.getEntityName(entityAndRev.entity), vehiclesWithRoundTrips[entityAndRev.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/game_mechanics/game_mechanics/achievements/achievements.script.tl:403

if entity_util.isOwnedByPlayer(vehicleEntity) then

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

if not entity_util.isOwnedByPlayer(vehicleEntity) then

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

if not entity_util.isOwnedByPlayer(constructionEntity) then

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

if entity_util.isOwnedByPlayer(constructionEntity) then

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

if entity_util.isOwnedByPlayer(constructionEntity) then

base/content/gui/gui/entity_window/station_group/station_group.tl:623

return entity_util.isOwnedByPlayer(stationGroupEntityId)

… 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/game_mechanics/game_mechanics/notifications/notifications.script.tl:522

if entity_util.isOwnedByPlayerOrNotOwned(constructionEntity) then

base/content/gui/gui/entity_window/vehicle/vehicle.tl:377

result.isModifiable = entity_util.isOwnedByPlayerOrNotOwned(vehicleEntityId)

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

isModifiable = entity_util.isOwnedByPlayerOrNotOwned(constructionEntity),

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/line_vehicle_mgmt/manager_window.tl:49

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

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

if not entity_util.isOwnedByPlayerOrNotOwned(constructionEntity) then

… 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/game_mechanics/game_mechanics/towns/town_util.tl:1202

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

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

local pos = entity_util.getBoundingVolumePosition(bv)

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

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

entity : EntityUtil.EntityAndRevision

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

reputationEffectEntity : EntityUtil.EntityAndRevision

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

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

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

function company_util.findStateIndex(companiesState : CompaniesState, companyEntityAndRevision : EntityUtil.EntityAndRevision) : integer

base/content/game_mechanics/game_mechanics/company/explorations/exploration_plane.script.tl:27

entity : EntityUtil.EntityAndRevision

base/content/game_mechanics/game_mechanics/emission/emission_legacy_util.tl:22

local ecoLevels : {Engine.Entity : {EntityUtil.EntityAndRevision, integer}} = {}

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