Skip to content

mat4

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

Notes

Types of the plain-Lua 4x4 matrix library /scripts/mat4.tl (Mat4Serialized). A matrix is a flat table of 16 numbers in column-major order (elements 13, 14, 15 hold the translation), the same layout the game uses for model and construction transforms (transf). The base game usually loads it as local mat4 = ug_require "/scripts/mat4.tl" as Mat4Serialized.

Example

-- from base/content/landmarks/hq/hq/headquarter.script.tl
coll.transf = mat4.mul(transf2, mat4.transl(vec3.new(0, 0, 14)))
-- from base/content/landmarks/hq/hq/headquarter_addon.script.tl
transf2 = mat4.mul(transf2, mat4.rotZ((params.modules[slotId].variant or 0) * math.pi / 2))

Mat4Serialized

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

global record Mat4Serialized

Load: local transf = require "/scripts/mat4.tl"

Notes

The 4x4 matrix library returned by ug_require "/scripts/mat4.tl", and the namespace of its Mat4 type. Matrices are flat 16-number tables in column-major order; the translation is in elements 13-15.

Functions

new(col1 : Vec4Serialized.Vec4, col2 : Vec4Serialized.Vec4, col3 : Vec4Serialized.Vec4, col4 : Vec4Serialized.Vec4) : Mat4 base/tealdef/scripts/mat4.d.tl:10

Call as transf.new

Notes

Creates a matrix from four column vectors and attaches the +, - and * operators.

Parameter Type Description
col1 Vec4Serialized.Vec4 First column (elements 1-4).
col2 Vec4Serialized.Vec4 Second column (elements 5-8).
col3 Vec4Serialized.Vec4 Third column (elements 9-12).
col4 Vec4Serialized.Vec4 Fourth column (elements 13-16); x, y, z are the translation for affine transforms.

Returns Mat4: The matrix as a flat 16-element table.

identity() : Mat4 base/tealdef/scripts/mat4.d.tl:11

Call as transf.identity

Notes

Returns the 4x4 identity matrix.

Returns Mat4

Example

-- from base/content/landmarks/landmark_util_serialized.tl
lane.transf = mat4.identity()
Used in the base game: 33 times in 12 files

base/content/industries/industryutil.lua:104 

lane.transf = transf.identity()
base/content/landmarks/landmark_util_serialized.tl:41 
lane.transf = mat4.identity()
base/content/depots/rail/rail/rail_depot.script.lua:359 
local transform = transf.identity
base/content/stations/air/air/airfield/airfield_modules.script.lua:219 
local transform = transf.identity()
base/content/stations/air/air/heliport/heliport.script.lua:294 
lane.transf = transf.identity()
base/content/stations/air/air/helipad/helipad.script.lua:148 
--lane.transf = transf.identity()
… and 6 more files.

add(m1 : Mat4, m2 : Mat4) : Mat4 base/tealdef/scripts/mat4.d.tl:13

Call as transf.add

Notes

Returns the element-wise sum m1 + m2.

Returns Mat4

sub(m1 : Mat4, m2 : Mat4) : Mat4 base/tealdef/scripts/mat4.d.tl:14

Call as transf.sub

Notes

Returns the element-wise difference m1 - m2.

Returns Mat4

mul(m1 : Mat4, m2 : Mat4) : Mat4 base/tealdef/scripts/mat4.d.tl:15

Call as transf.mul

Notes

Returns the matrix product m1 * m2, i.e. the transform that applies m2 first and then m1.

Returns Mat4

Details

To place a part relative to a parent transform, write mat4.mul(parentTransf, localTransf).

Example

-- from base/content/landmarks/hq/hq/headquarter.script.tl
coll.transf = mat4.mul(transf2, mat4.transl(vec3.new(0, 0, 14)))
Used in the base game: 65 times in 21 files

base/content/industries/fieldutil.lua:282 

transf = transf.mul(fieldTransf, transf.scaleRotZTransl(
base/content/buildings/townbuildingutil.lua:154 
model.transf = transf.mul(transf.transl({ x = 0, y = 0, z = math.lerp(p1[3], p2[3], (alignmentPos[1] - p1[1]) / dx) }), model.transf)
base/content/landmarks/landmark_util_serialized.tl:158 
-- transform = mat4.mul(transform, mat4.rotZ( math.rad(270))) -- tmp rotate
base/content/warehouses/warehouses/warehouse.script.lua:109 
coll.transf = transf.mul(transf2, transf.transl(vec3.new(0, 0, 11)))
base/content/landmarks/hq/hq/headquarter.script.tl:371 
coll.transf = mat4.mul(transf2, mat4.transl(vec3.new(0, 0, 14)))
base/content/landmarks/hq/hq/headquarter_addon.script.tl:50 
transf2 = mat4.mul(transf2, mat4.rotZ((params.modules[slotId].variant or 0) * math.pi / 2))
… and 15 more files.

gemv(m : Mat4, v : Vec4Serialized.Vec4) : Vec4Serialized.Vec4 base/tealdef/scripts/mat4.d.tl:21

Call as transf.gemv

General matrix-vector multiplication.

Parameter Type Description
m Mat4 matrix
v Vec4Serialized.Vec4 vector

Returns Vec4Serialized.Vec4: resulting vector

Used in the base game: 30 times in 4 files

base/content/stations/air/air/airport/airport_modules.script.lua:16 

local center = transf.gemv(transform, vec4.new(20.0, 0.0, -1.0, 1.0))
base/content/stations/water/water/modules.script.lua:844 
local entryGlob = transf.gemv(transform, entry)
base/content/stations/street/street/modular_street_station/modules.script.lua:105 
local tng = vec4.toArray(transf.gemv(transform, vec4.new(0.0, -20.0, 0.0, 0.0)))
base/content/scripts/scripts/construction/modulesutil.lua:358 
modulesutil.mul = transf.gemv

flipY(m : Mat4) : Mat4 base/tealdef/scripts/mat4.d.tl:26

Call as transf.flipY

Multiply the y coordinate of each column with -1.

Parameter Type Description
m Mat4 matrix

Returns Mat4: matrix with Y flipped

transl(t : Vec3Serialized.Vec3) : Mat4 base/tealdef/scripts/mat4.d.tl:30

Call as transf.transl

Create translation matrix from a translation vector.

Parameter Type Description
t Vec3Serialized.Vec3 translation vector

Returns Mat4: translation matrix

Used in the base game: 227 times in 36 files

base/content/industries/fieldutil.lua:401 

transf = transf.transl( {x = fieldConfig.fields[i].pos[1] , y = fieldConfig.fields[i].pos[2], z = 0,}),
base/content/buildings/townbuildingutil.lua:154 
model.transf = transf.mul(transf.transl({ x = 0, y = 0, z = math.lerp(p1[3], p2[3], (alignmentPos[1] - p1[1]) / dx) }), model.transf)
base/content/landmarks/landmark_util_serialized.tl:156 
-- transform = mat4.transl( vec3.new(0, 0, -2)) -- counter hack for IsWaterConstructionHACK)
base/content/warehouses/warehouses/warehouse.script.lua:109 
coll.transf = transf.mul(transf2, transf.transl(vec3.new(0, 0, 11)))
base/content/landmarks/hq/hq/headquarter.script.tl:371 
coll.transf = mat4.mul(transf2, mat4.transl(vec3.new(0, 0, 14)))
base/content/landmarks/hq/hq/headquarter_addon.script.tl:37 
transf = mat4.transl(vec3.new(0, -22, 0)),
… and 30 more files.

scale(t : Vec3Serialized.Vec3) : Mat4 base/tealdef/scripts/mat4.d.tl:34

Call as transf.scale

Create scale matrix.

Parameter Type Description
t Vec3Serialized.Vec3 scale vector

Returns Mat4: scale matrix

Used in the base game: 48 times in 11 files

base/content/warehouses/warehouses/modules.script.lua:353 

transf = transf.scale(vec3.new(1, 1, 1)),
base/content/base/base/metadataanimationutil.lua:79 
return { times = { 0 }, transfs = { transf.scale(vec3.new(1,1,1)) }, interpolation = "NEAREST" }
base/content/gui/gui/menu/main_menu.css.lua:245 
transform = transf.scale(vec3.new(1.0, 1.0, 1.0)),
base/content/gui/gui/construction/construction.css.lua:415 
transform = transf.scale(vec3.new(1.0, 1.0, 1.0)),
base/content/gui/gui/main/tile_list_react_util.css.lua:118 
transform = transf.scale(vec3.new(1.0, 1.0, 1.0)),
base/content/gui/gui/main/hud_icon_master.css.lua:19 
transform = transf.scale(vec3.new(0.1, 0.1, 0.1)),
… and 5 more files.

rotZ(rotZ : number) : Mat4 base/tealdef/scripts/mat4.d.tl:38

Call as transf.rotZ

Create rotation matrix for the rotation around Z axis.

Parameter Type Description
rotZ number rotation angle in radians

Returns Mat4: rotation matrix

Used in the base game: 19 times in 12 files

base/content/landmarks/landmark_util_serialized.tl:158 

-- transform = mat4.mul(transform, mat4.rotZ( math.rad(270))) -- tmp rotate
base/content/landmarks/hq/hq/headquarter_addon.script.tl:50 
transf2 = mat4.mul(transf2, mat4.rotZ((params.modules[slotId].variant or 0) * math.pi / 2))
base/content/base/base/metadataanimationutil.lua:304 
local animation = generateRotateAnimation(maxAngle, transf.rotZ)
base/content/infrastructure/tunnel/tunnel/tunnel.script.lua:158 
local rot = transf.rotZ(math.pi)
base/content/industries/fishing_grounds/fishing_grounds/modules.script.lua:28 
transform = transf.mul(transform, transf.rotZ( math.rad(randomRotation[rnd])))
base/content/industries/oil_well/oil_well/modules.script.lua:20 
transform = transf.mul(transform, transf.rotZ( math.rad(90)))
… and 6 more files.

rotY(rotY : number) : Mat4 base/tealdef/scripts/mat4.d.tl:42

Call as transf.rotY

Create rotation matrix for the rotation around Y axis.

Parameter Type Description
rotY number rotation angle in radians

Returns Mat4: rotation matrix

Used in the base game: 2 times in 2 files

base/content/base/base/metadataanimationutil.lua:296 

local animation = generateRotateAnimation(maxAngle, transf.rotY)
base/content/scripts/scripts/construction/constructionutil.lua:19 
transf.rotY(params.constructOpt78 and params.constructOpt78 or 0)

rotX(rotX : number) : Mat4 base/tealdef/scripts/mat4.d.tl:46

Call as transf.rotX

Create rotation matrix around X axis.

Parameter Type Description
rotX number rotation angle in radians

Returns Mat4: rotation matrix

Used in the base game: 7 times in 2 files

base/content/base/base/metadataanimationutil.lua:323 

local animation = generateRotateAnimation(maxAngle, transf.rotX)
base/content/scripts/scripts/construction/constructionutil.lua:18 
transf.rotX(params.constructOpt56 and params.constructOpt56 or 0),

rotZTransl(rotZ : number, transl : Vec3Serialized.Vec3) : Mat4 base/tealdef/scripts/mat4.d.tl:52

Call as transf.rotZTransl

Create matrix who has rotation around Z and translation

Parameter Type Description
rotZ number rotation angle
transl Vec3Serialized.Vec3 translation vector

Returns Mat4: combined matrix

Used in the base game: 323 times in 30 files

base/content/landmarks/landmark_util_serialized.tl:413 

transf = mat4.rotZTransl(math.pi, vec3.new(0, 10, 0)),
base/content/landmarks/hq/hq/headquarter.script.tl:427 
addFence(mat4.rotZTransl(0, vec3.new((i + 0.5) * GridSize.x, j * GridSize.y, 0)))
base/content/depots/rail/rail/rail_depot.script.lua:360 
transform = transf.rotZTransl(4.71238898,vec3.new(-21, 0, 0.00000))
base/content/depots/water/water/water_depot.script.lua:419 
transf = transf.rotZTransl(math.pi, vec3.new(0, 0, 0)),
base/content/depots/water/water/water_maint_station.script.lua:311 
transf = transf.rotZTransl(math.pi, vec3.new(0, 0, 0)),
base/content/infrastructure/traffic_light/traffic_light/trafficlightutil.lua:188 
result[#result + 1] = transf.mul(p, transf.rotZTransl(rot, vec3.new(0, o, 0)))
… and 24 more files.

rotZYXTransl(rot : Vec3Serialized.Vec3, transl : Vec3Serialized.Vec3) : Mat4 base/tealdef/scripts/mat4.d.tl:57

Call as transf.rotZYXTransl

Create matrix for ZYX rotations and translation.

Parameter Type Description
rot Vec3Serialized.Vec3 rotation vector (x is rotZ, y is rotY, z is rotX) and performed in this order
transl Vec3Serialized.Vec3 translation vector

Returns Mat4: combined matrix

Used in the base game: 34 times in 8 files

base/content/warehouses/warehouses/warehouse.script.lua:233 

transf = transf.rotZYXTransl(vec3.degToRad(0, 0, 0), center),
base/content/warehouses/warehouses/modules.script.lua:29 
local transf2 = transf.rotZYXTransl(vec3.degToRad(0, 0, 0), center)
base/content/landmarks/hq/hq/headquarter.script.tl:337 
transf = mat4.rotZYXTransl(vec3.degToRad(orientation and orientation * 90 or 0, 0, 0), center),
base/content/stations/rail/rail/modular_station/modular_station.script.lua:534 
transf = transf.rotZYXTransl(vec3.degToRad(0.0, 0.0, 0.0), vec3.new(i * platformWidth + offset, j * platformLength, 0)),
base/content/stations/air/air/airfield.script.lua:261 
transf = transf.rotZYXTransl(vec3.degToRad(0.0, 0.0, 0.0),  vec3.new( 140, 0, 0))
base/content/stations/air/air/airport.script.lua:172 
transf = transf.rotZYXTransl(vec3.degToRad(0, 0, 0), vec3.new(airportLimitEnd - 5, runway1YCoord, 0 )),
… and 2 more files.

rotZYTransl(rot : Vec3Serialized.Vec3, transl : Vec3Serialized.Vec3) : Mat4 base/tealdef/scripts/mat4.d.tl:62

Call as transf.rotZYTransl

Create a matrix for ZY rotations and translation.

Parameter Type Description
rot Vec3Serialized.Vec3 rotation vector (x is rotZ, y is rotY, z is unused) and performed in this order
transl Vec3Serialized.Vec3 translation vector

Returns Mat4: combined matrix

rotYCntTransl(rotY : number, cnt : Vec3Serialized.Vec3, transl : Vec3Serialized.Vec3) : Mat4 base/tealdef/scripts/mat4.d.tl:68

Call as transf.rotYCntTransl

Create matrix for rotation around Y with a center specified and a translation.

Parameter Type Description
rotY number rotation angle
cnt Vec3Serialized.Vec3 center point
transl Vec3Serialized.Vec3 translation vector

Returns Mat4: combined matrix

rotZY(rot : Vec3Serialized.Vec3) : Mat4 base/tealdef/scripts/mat4.d.tl:73

Call as transf.rotZY

Create a matrix for ZY rotations.

Parameter Type Description
rot Vec3Serialized.Vec3 rotation vector (x is rotZ, y is rotY, z is unused) and performed in this order

Returns Mat4: rotation matrix

scaleRotZTransl(scale : number, rotZ : number, transl : Vec3Serialized.Vec3) : Mat4 base/tealdef/scripts/mat4.d.tl:80

Call as transf.scaleRotZTransl

Create matrix for (homogenous) scaling, rotation around Z, and translation.

Parameter Type Description
scale number scale factor
rotZ number rotation angle
transl Vec3Serialized.Vec3 translation vector

Returns Mat4: combined matrix

Used in the base game: 93 times in 20 files

base/content/industries/fieldutil.lua:282 

transf = transf.mul(fieldTransf, transf.scaleRotZTransl(
base/content/gui/gui/music_player/music_player.css.lua:15 
transform = transf.scaleRotZTransl(1.0, 0, vec3.new(0.0, 200.0, 0.0)),
base/content/gui/gui/layers/layers.css.lua:21 
transform = transf.scaleRotZTransl(1.0, 0, vec3.new(0.0, -200.0, 0.0)),
base/content/gui/gui/context_helper/context_helper.css.lua:19 
transform = transf.scaleRotZTransl(0.1, 0, vec3.new(0.0, 0.0, 0.0)),
base/content/gui/gui/line_vehicle_mgmt/vehicle_store.css.lua:65 
transform = transf.scaleRotZTransl(1.0, 0, vec3.new(0.0, 200.0, 0.0)),
base/content/gui/gui/line_vehicle_mgmt/line_vehicle_mgmt.css.lua:110 
transform = transf.scaleRotZTransl(1.0, 0.0, vec3.new(0.0, 0.0, 0.0)),
… and 14 more files.

scaleXYZRotZTransl(scale : Vec3Serialized.Vec3, rotZ : number, transl : Vec3Serialized.Vec3) : Mat4 base/tealdef/scripts/mat4.d.tl:86

Call as transf.scaleXYZRotZTransl

Create matrix for (inhomogenous) scaling, rotation around Z, and translation.

Parameter Type Description
scale Vec3Serialized.Vec3 scale vector
rotZ number rotation angle
transl Vec3Serialized.Vec3 translation vector

Returns Mat4: combined matrix

Used in the base game: 6 times in 4 files

base/content/infrastructure/tunnel/tunnel/tunnel.script.lua:125 

--      local modelTransf2 = transf.scaleXYZRotZTransl(scaleVec, .0, posVec)
base/content/infrastructure/bridge/bridge/bridgeutil.lua:223 
local modelTransf = transf.scaleXYZRotZTransl(scaleVec, .0, posVec)
base/content/infrastructure/bridge/bridge/bridgeutil2.lua:234 
local modelTransf = transf.scaleXYZRotZTransl(scaleVec, .0, posVec)
base/content/scripts/scripts/construction/constructionutil.lua:487 
transf = transf.scaleXYZRotZTransl(vec3.new(remainder, 1, 1), vec3.xyAngle(fenceVector) + (angle or 0), fence_point),

scaleRotZYXTransl(scale : Vec3Serialized.Vec3, rot : Vec3Serialized.Vec3, transl : Vec3Serialized.Vec3) : Mat4 base/tealdef/scripts/mat4.d.tl:92

Call as transf.scaleRotZYXTransl

Create matrix for (inhomogenous) scaling, ZYX rotations and translation.

Parameter Type Description
scale Vec3Serialized.Vec3 scale vector
rot Vec3Serialized.Vec3 rotation vector (x is rotZ, y is rotY, z is rotX) and performed in this order
transl Vec3Serialized.Vec3 translation vector

Returns Mat4: combined matrix

getTransl(m : Mat4) : Vec3Serialized.Vec3 base/tealdef/scripts/mat4.d.tl:97

Call as transf.getTransl

Extract translation vector from matrix.

Parameter Type Description
m Mat4 matrix

Returns Vec3Serialized.Vec3: translation vector

print(v : Mat4) : string base/tealdef/scripts/mat4.d.tl:102

Call as transf.print

Convert matrix to a string representation.

Parameter Type Description
v Mat4 matrix

Returns string: string representation

Mat4Serialized.Mat4

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

record Mat4 is {number}

16 entries, column major

Used in the base game: 48 times in 5 files

base/content/landmarks/hq/hq/headquarter.script.tl:344 

result.addAlignmentColliderAndGroundTexture = function(cellSize : {Vec2Serialized.Vec2}, fenceCellSize : {Vec2Serialized.Vec2}, transf2 : Mat4Serialized.Mat4)
base/content/landmarks/hq/hq/headquarter_addon.script.tl:7 
function data.updateFn(captureParams : table, result : HeadquarterUtilSerialized.HeadquarterConstructionResult, _transform : Mat4Serialized.Mat4, tag : string,
base/content/stations/air/air/heliport/modules.script.tl:7 
function data.updateFn(captureParams : table, result : HeadquarterUtilSerialized.HeadquarterConstructionResult, transform : Mat4Serialized.Mat4, tag : string, s
base/content/scripts/scripts/mat4.tl:6 
mat4_util.new = function(col1 : Vec4Serialized.Vec4, col2 : Vec4Serialized.Vec4, col3 : Vec4Serialized.Vec4, col4 : Vec4Serialized.Vec4) : Mat4Serialized.Mat4
base/content/scripts/scripts/construction/construction.script.tl:85 
local function addModel(name : string, mtransf : Mat4Serialized.Mat4, tag2 : string, models : {ConstructionUtilSerialized.TransformedModel}) : integer

Functions

metamethod __add(m1 : Mat4, m2 : Mat4) : Mat4 base/tealdef/scripts/mat4.d.tl:5

Notes

Element-wise sum m1 + m2.

Returns Mat4

metamethod __sub(m1 : Mat4, m2 : Mat4) : Mat4 base/tealdef/scripts/mat4.d.tl:6

Notes

Element-wise difference m1 - m2.

Returns Mat4

metamethod __mul(m1 : Mat4, m2 : Mat4) : Mat4 base/tealdef/scripts/mat4.d.tl:7

Notes

Matrix product m1 * m2. Applied to a point, m1 * m2 first applies m2, then m1 (column vectors).

Returns Mat4