custom_entity_util¶

Source: base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl

Notes

Helpers to spawn, move and remove custom entities (script-controlled models), plus movement maths for flying ones.

CustomEntityUtil¶

record global base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl:3

global record CustomEntityUtil

Load: local custom_entity_util = ug_require "::/game_mechanics/fun_elements/custom_entity_util.tl"

Notes

Helpers for custom entities (models placed and moved by script) and movement maths for flying ones.

Functions

convertMatrixToTable(Mat4f) : {{number, number, number, number}, {number, number, number, number}, {number, number, number, number}, {number, number, number, number}} base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl:12

Call as custom_entity_util.convertMatrixToTable

Notes

Converts a matrix to a plain table that can be saved in game script state or sent as event parameter.

Parameter	Type	Description
`#1`	`Mat4f`	Matrix.

Returns {{number, number, number, number}, {number, number, number, number}, {number, number, number, number}, {number, number, number, number}}: Table of rows; see MatCols.

Used in the base game: 4 times in 3 files

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

local transf = custom_entity_util.convertMatrixToTable(

mods/release/urbangames_campaign_mission_08/content/mission/mission/mission_story_cutscenes_only.tl:53

return custom_entity_util.convertMatrixToTable(transf)

mods/release/urbangames_campaign_mission_08/content/mission/mission/mission_story.tl:50

return custom_entity_util.convertMatrixToTable(transf)

convertTableToMatrix({{number, number, number, number}, {number, number, number, number}, {number, number, number, number}, {number, number, number, number}}) : Mat4f base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl:13

Call as custom_entity_util.convertTableToMatrix

Notes

Converts a table from convertMatrixToTable back to a matrix.

Parameter	Type	Description
`#1`	`{{number, number, number, number}, {number, number, number, number}, {number, number, number, number}, {number, number, number, number}}`	Table of rows.

Returns Mat4f: The matrix.

Used in the base game: 2 times in 1 file

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

local mat = custom_entity_util.convertTableToMatrix(transf)

spawn(string, transf : Mat4f, callback : function(Engine.Entity)) base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl:15

Call as custom_entity_util.spawn

Notes

Creates a custom entity of a model and sets its transformation. Logs an error and does nothing if the model does not exist.

Parameter	Type	Description
`#1`	`string`	Model res name.
`transf`	`Mat4f`	Transformation.
`callback`	`function(Engine.Entity)`	Receives the new entity once it is placed.

Used in the base game: 5 times in 5 files

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

custom_entity_util.spawn(params.models[math.random(#params.models)], newTransf, function(runtimeEntity : Engine.Entity)

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

custom_entity_util.spawn(params.models[i], newTransf, function(runtimeEntity : Engine.Entity)

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

custom_entity_util.spawn(model, mat, function(rocketEntity:Engine.Entity)

mods/release/urbangames_campaign_mission_03/content/mission/mission/tasks/fatal_maintenance/fatal_maintenance.tl:77

custom_entity_util.spawn(model, newTransf, function(newEntity : Engine.Entity)

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

custom_entity_util.spawn("urbangames_campaign_mission_05::assets/sound_hack/sound_hack.mdl", newTransf, function(runtimeEntity : Engine.Entity)

getTransf(entity : Engine.Entity) : Mat4f base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl:16

Call as custom_entity_util.getTransf

Notes

Transformation of the entity's first model instance.

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

Returns Mat4f: The transformation.

setTransf(entity : Engine.Entity, transf : Mat4f) base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl:17

Call as custom_entity_util.setTransf

Notes

Sets the transformation of a custom entity.

Parameter	Type	Description
`entity`	`Engine.Entity`	Custom entity.
`transf`	`Mat4f`	New transformation.

Used in the base game: 1 time in 1 file

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

custom_entity_util.setTransf(rocketData.rocketEntity.entity, newTransf)

destroy(entity : Engine.Entity) base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl:18

Call as custom_entity_util.destroy

Notes

Removes a custom entity.

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

Used in the base game: 5 times in 3 files

base/content/mission/mission/tasks/click_and_collect_custom_entity/collect_entity.tl:41

custom_entity_util.destroy(entity)

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

custom_entity_util.destroy(rocketData.rocketEntity.entity)

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

custom_entity_util.destroy(activeDrilling.soundHackEntity)

getPos(entity : Engine.Entity) : Vec3f base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl:20

Call as custom_entity_util.getPos

Notes

Position of a custom entity.

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

Returns Vec3f: World position.

setPos(entity : Engine.Entity, pos : Vec3f) base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl:21

Call as custom_entity_util.setPos

Notes

Moves a custom entity and keeps its rotation.

Parameter	Type	Description
`entity`	`Engine.Entity`	Custom entity.
`pos`	`Vec3f`	New world position.

findSpawnPoint(pos : Vec3f, xyOffset : number, zOffset : number) : Vec3f base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl:23

Call as custom_entity_util.findSpawnPoint

Notes

Random point in a square around a position, at a height above the terrain.

Parameter	Type	Description
`pos`	`Vec3f`	Centre of the square.
`xyOffset`	`number`	Half the side of the square (metres).
`zOffset`	`number`	Height above the terrain (metres).

Returns Vec3f: The point.

Used in the base game: 2 times in 2 files

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

local pos = custom_entity_util.findSpawnPoint(vec, 0.5, params.alignTerrain and 0 or position[3])

mods/release/urbangames_campaign_mission_03/content/mission/mission/tasks/fatal_maintenance/fatal_maintenance.tl:73

local pos = custom_entity_util.findSpawnPoint(vec, 0.1, 0)

findSpawnPointClosestOffMap(pos : Vec3f, xyOffset : number, zOffset : number) : Vec3f, Vec3f base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl:30

Call as custom_entity_util.findSpawnPointClosestOffMap

Returns a position and direction (pointing inside the map) at the edge of the map that is closest to pos

Parameter	Type	Description
`pos`	`Vec3f`	the world position for which to find a closest edge position
`xyOffset`	`number`	the offset from the border of the map for the point (in meters)
`zOffset`	`number`	the altitude of the point

Returns Vec3f, Vec3f: a position and direction

Used in the base game: 2 times in 1 file

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

local startPos, startDir = custom_entity_util.findSpawnPointClosestOffMap(nextTarget3D, offmap, altitude)

approach(current : number, target : number, shift : number) : number base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl:32

Call as custom_entity_util.approach

Notes

Moves a number towards a target by at most shift, without overshooting.

Parameter	Type	Description
`current`	`number`	Start value.
`target`	`number`	Target value.
`shift`	`number`	Maximum change; the sign is ignored.

Returns number: The new value.

approachVec3f(current : Vec3f, target : Vec3f, shift : number) : Vec3f base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl:33

Call as custom_entity_util.approachVec3f

Notes

Moves a point towards a target by about shift along the straight line, without overshooting.

Parameter	Type	Description
`current`	`Vec3f`	Start point.
`target`	`Vec3f`	Target point.
`shift`	`number`	Step length.

Returns Vec3f: The new point.

approachAngularVec2f(current : Vec2f, target : Vec2f, shift : number) : Vec2f base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl:34

Call as custom_entity_util.approachAngularVec2f

Notes

Turns a 2D direction towards a target direction along the shorter way.

Parameter	Type	Description
`current`	`Vec2f`	Current direction.
`target`	`Vec2f`	Target direction.
`shift`	`number`	Share of the angle difference to turn.

Returns Vec2f: The new unit direction.

approachAngularVec3f(current : Vec3f, target : Vec3f, shift : number) : Vec3f base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl:35

Call as custom_entity_util.approachAngularVec3f

Notes

Turns a 3D direction towards a target direction; heading as in approachAngularVec2f, the z part as in approach.

Parameter	Type	Description
`current`	`Vec3f`	Current direction.
`target`	`Vec3f`	Target direction.
`shift`	`number`	Turn amount.

Returns Vec3f: The new unit direction.

vec2fToYaw(v : Vec2f) : number base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl:37

Call as custom_entity_util.vec2fToYaw

Notes

Heading of a 2D vector.

Parameter	Type	Description
`v`	`Vec2f`	Vector.

Returns number: Angle in radians (atan2(y, x)).

Used in the base game: 2 times in 2 files

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

local angle = custom_entity_util.vec2fToYaw(api.type.Vec2f.new(-normal.x, -normal.y))

mods/release/urbangames_campaign_mission_03/content/mission/mission/tasks/fatal_maintenance/fatal_maintenance.tl:74

local angle = custom_entity_util.vec2fToYaw(api.type.Vec2f.new(dir.x, dir.y))

yawToVec2f(angle : number) : Vec2f base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl:38

Call as custom_entity_util.yawToVec2f

Notes

Unit vector for a heading.

Parameter	Type	Description
`angle`	`number`	Angle in radians.

Returns Vec2f: The unit vector.

calcAirshipMovement(position : Vec3f, velocity : Vec3f, targetPos : Vec3f, minGroundOffset : number, minSpeed : number, maxSpeed : number, acceleration : number, steering : number, speedLerpMult : number, dt : number) : MovementData base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl:40

Call as custom_entity_util.calcAirshipMovement

Notes

Computes one movement step of a flying entity that steers towards a target and slows down near it.

Parameter	Type	Description
`position`	`Vec3f`	Current position.
`velocity`	`Vec3f`	Current velocity.
`targetPos`	`Vec3f`	Target position.
`minGroundOffset`	`number`	Minimum height above the terrain (metres).
`minSpeed`	`number`	Speed used within 50 metres of the target.
`maxSpeed`	`number`	Speed used further away.
`acceleration`	`number`	Maximum speed change per second.
`steering`	`number`	Turn rate; also sets the reach distance (`2 / steering` metres).
`speedLerpMult`	`number`	Smoothing of the speed change; 0 uses the target speed directly.
`dt`	`number`	Time step in seconds.

Returns MovementData: The new movement state; apply it with applyAirshipMovement.

applyAirshipMovement(entity : Engine.Entity, data : MovementData) base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl:52

Call as custom_entity_util.applyAirshipMovement

Notes

Places the entity at the new position, turned to the heading of the new direction.

Parameter	Type	Description
`entity`	`Engine.Entity`	Custom entity.
`data`	`MovementData`	Result of `calcAirshipMovement`.

getModelInstanceList(entity : Engine.Entity) : Engine.Component.ModelInstanceList base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl:54

Call as custom_entity_util.getModelInstanceList

Notes

Model instance list of an entity, or of the first carriage of a vehicle that has none of its own.

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

Returns Engine.Component.ModelInstanceList: The model instance list.

Used in the base game: 2 times in 2 files

base/content/gui/gui/main/game_tooltips.tl:83

local mil = custom_entity_util.getModelInstanceList(entity)

base/content/gui/gui/entity_window/make_entity_window.tl:708

local mil = custom_entity_util.getModelInstanceList(entity)

CustomEntityUtil.MovementData¶

record base/tealdef/game_mechanics/fun_elements/custom_entity_util.d.tl:4

record MovementData

Notes

Result of one movement step, from calcAirshipMovement.

Used in the base game: 5 times in 3 files

base/content/game_mechanics/game_mechanics/fun_elements/custom_entity_util.tl:185

) : CustomEntityUtil.MovementData

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

local movementData : CustomEntityUtil.MovementData = custom_entity_util.calcAirshipMovement(

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

local movementData : CustomEntityUtil.MovementData = custom_entity_util.calcAirshipMovement(

Fields

Name	Type	Description
`velocity`	`Vec3f`	New velocity.
`position`	`Vec3f`	New position, kept at least the minimum ground offset above the terrain.
`direction`	`Vec3f`	New unit direction.
`distanceToTarget`	`number`	Distance from the new position to the target.
`targetReached`	`boolean`	True when the target counts as reached.