Package openmw.util¶

openmw.util defines utility functions and classes like 3D vectors, that don't depend on the game world.

Usage:

local util = require('openmw.util')

Type `util`

util.bitAnd(A, B)	Bitwise And (supports any number of arguments).
util.bitNot(A)	Bitwise inversion.
util.bitOr(A, B)	Bitwise Or (supports any number of arguments).
util.bitXor(A, B)	Bitwise Xor (supports any number of arguments).
util.clamp(value, from, to)	Limits given value to the interval [`from`, `to`].
util.color	Methods for creating #Color values from different formats.
util.loadCode(code, table)	Parses Lua code from string and returns as a function.
util.makeReadOnly(table)	Makes a table read only.
util.makeStrictReadOnly(table)	Makes a table read only and overrides `__index` with the strict version that throws an error if the key is not found.
util.normalizeAngle(angle)	Adds `2pi*k` and puts the angle in range `[-pi, pi]`.
util.transform	3D transforms (scale/move/rotate) that can be applied to 3D vectors.
util.vector2(x, y)	Creates a new 2D vector.
util.vector3(x, y, z)	Creates a new 3D vector.
util.vector4(x, y, z, w)	Creates a new 4D vector.

Type `COLOR`

COLOR.hex(hex)	Parses a hex color string into a Color.
COLOR.rgb(r, g, b)	Creates a Color from RGB format.
COLOR.rgba(r, g, b, a)	Creates a Color from RGBA format

Type `Color`

Color.a	Alpha (transparency) component
Color:asHex()	Converts the color into a HEX string.
Color:asRgb()	Returns a Vector3 with RGB components of the Color.
Color:asRgba()	Returns a Vector4 with RGBA components of the Color.
Color.b	Blue component
Color.g	Green component
Color.r	Red component

Type `TRANSFORM`

TRANSFORM.identity	Empty transform.
TRANSFORM.move(offset)	Movement by given vector.
TRANSFORM.rotate(angle, axis)	Rotation around a vector (counterclockwise if the vector points to us).
TRANSFORM.rotateX(angle)	X-axis rotation (equivalent to `rotate(angle, vector3(-1, 0, 0))`).
TRANSFORM.rotateY(angle)	Y-axis rotation (equivalent to `rotate(angle, vector3(0, -1, 0))`).
TRANSFORM.rotateZ(angle)	Z-axis rotation (equivalent to `rotate(angle, vector3(0, 0, -1))`).
TRANSFORM.scale(scaleX, scaleY, scaleZ)	Scale transform.

Type `Transform`

Transform:inverse()

Returns the inverse transform.

Type `Vector2`

Vector2:dot(v)	Dot product.
Vector2:ediv(v)	Element-wise division
Vector2:emul(v)	Element-wise multiplication
Vector2:length()	Length of the vector.
Vector2:length2()	Square of the length of the vector.
Vector2:normalize()	Normalizes vector.
Vector2:rotate(angle)	Rotates 2D vector clockwise.
Vector2.x
Vector2.y

Type `Vector3`

Vector3:cross(v)	Cross product.
Vector3:dot(v)	Dot product.
Vector3:ediv(v)	Element-wise division
Vector3:emul(v)	Element-wise multiplication
Vector3:length()	Length of the vector
Vector3:length2()	Square of the length of the vector
Vector3:normalize()	Normalizes vector.
Vector3.x
Vector3.y
Vector3.z

Type `Vector4`

Vector4:dot(v)	Dot product.
Vector4:ediv(v)	Element-wise division
Vector4:emul(v)	Element-wise multiplication
Vector4:length()	Length of the vector
Vector4:length2()	Square of the length of the vector
Vector4:normalize()	Normalizes vector.
Vector4.w
Vector4.x
Vector4.y
Vector4.z

Type `util`

Field(s)

util.bitAnd(A, B)

Bitwise And (supports any number of arguments).

Parameters

#number A : First argument (integer).
#number B : Second argument (integer).

Return value

#number: Bitwise And of A and B.

util.bitNot(A)

Bitwise inversion.

Parameter

#number A : Argument (integer).

Return value

#number: Bitwise Not of A.

util.bitOr(A, B)

Bitwise Or (supports any number of arguments).

Parameters

#number A : First argument (integer).
#number B : Second argument (integer).

Return value

#number: Bitwise Or of A and B.

util.bitXor(A, B)

Bitwise Xor (supports any number of arguments).

Parameters

#number A : First argument (integer).
#number B : Second argument (integer).

Return value

#number: Bitwise Xor of A and B.

util.clamp(value, from, to)

Limits given value to the interval [from, to].

Parameters

#number value :
#number from :
#number to :

Return value

#number: min(max(value, from), to)

#COLOR util.color: Methods for creating #Color values from different formats.

util.loadCode(code, table)

Parses Lua code from string and returns as a function.

Parameters

#string code : Lua code.
#table table : Environment to run the code in.

Return value

#function: The loaded code.

util.makeReadOnly(table)

Makes a table read only.

Parameter

#table table : Any table.

Return value

#table: The same table wrapped with read only userdata.

util.makeStrictReadOnly(table)

Makes a table read only and overrides __index with the strict version that throws an error if the key is not found.

Parameter

#table table : Any table.

Return value

#table: The same table wrapped with read only userdata.

util.normalizeAngle(angle)

Adds 2pi*k and puts the angle in range [-pi, pi].

Parameter

#number angle : Angle in radians

Return value

#number: Angle in range [-pi, pi]

#TRANSFORM util.transform

3D transforms (scale/move/rotate) that can be applied to 3D vectors.

Several transforms can be combined and applied to a vector using multiplication. Combined transforms apply in reverse order (from right to left).

Usage:

local util = require('openmw.util')
local trans = util.transform
local fromActorSpace = trans.move(actor.position) * trans.rotateZ(actor.rotation.z)

-- rotation is applied first, movement is second
local posBehindActor = fromActorSpace * util.vector3(0, -100, 0)

-- equivalent to trans.rotateZ(-actor.rotation.z) * trans.move(-actor.position)
local toActorSpace = fromActorSpace:inverse()
local relativeTargetPos = toActorSpace * target.position
local deltaAngle = math.atan2(relativeTargetPos.y, relativeTargetPos.x)

util.vector2(x, y)

Creates a new 2D vector.

Vectors are immutable and can not be changed after creation.

Parameters

#number x :
#number y :

Return value

#Vector2:

util.vector3(x, y, z)

Creates a new 3D vector.

Vectors are immutable and can not be changed after creation.

Parameters

#number x :
#number y :
#number z :

Return value

#Vector3:

util.vector4(x, y, z, w)

Creates a new 4D vector.

Vectors are immutable and can not be changed after creation.

Parameters

#number x :
#number y :
#number z :
#number w :

Return value

#Vector4:

Type `COLOR`

Methods for creating #Color values from different formats.

Field(s)

COLOR.hex(hex)

Parses a hex color string into a Color.

Parameter

#string hex : A hex color string in RRGGBB format (e. g. "ff0000").

Return value

#Color:

COLOR.rgb(r, g, b)

Creates a Color from RGB format.

Equivalent to calling util.rgba with a = 1.

Parameters

#number r :
#number g :
#number b :

Return value

#Color:

COLOR.rgba(r, g, b, a)

Creates a Color from RGBA format

Parameters

#number r :
#number g :
#number b :
#number a :

Return value

#Color:

Type `Color`

Color in RGBA format.

All of the component values are in the range [0, 1].

Field(s)

#number Color.a: Alpha (transparency) component

Color:asHex()

Converts the color into a HEX string.

Return value

#string:

Color:asRgb()

Returns a Vector3 with RGB components of the Color.

Return value

#Vector3:

Color:asRgba()

Returns a Vector4 with RGBA components of the Color.

Return value

#Vector4:

#number Color.b: Blue component

#number Color.g: Green component

#number Color.r: Red component

Type `TRANSFORM`

Field(s)

#Transform TRANSFORM.identity: Empty transform.

TRANSFORM.move(offset)

Movement by given vector.

Parameter

#Vector3 offset :

Return value

#Transform:

Usage:

-- Accepts either 3 numbers or a 3D vector
util.transform.move(x, y, z)
util.transform.move(util.vector3(x, y, z))

TRANSFORM.rotate(angle, axis)

Rotation around a vector (counterclockwise if the vector points to us).

Parameters

#number angle :
#Vector3 axis :

Return value

#Transform:

TRANSFORM.rotateX(angle)

X-axis rotation (equivalent to rotate(angle, vector3(-1, 0, 0))).

Parameter

#number angle :

Return value

#Transform:

TRANSFORM.rotateY(angle)

Y-axis rotation (equivalent to rotate(angle, vector3(0, -1, 0))).

Parameter

#number angle :

Return value

#Transform:

TRANSFORM.rotateZ(angle)

Z-axis rotation (equivalent to rotate(angle, vector3(0, 0, -1))).

Parameter

#number angle :

Return value

#Transform:

TRANSFORM.scale(scaleX, scaleY, scaleZ)

Scale transform.

Parameters

#number scaleX :
#number scaleY :
#number scaleZ :

Return value

#Transform:

Usage:

-- Accepts either 3 numbers or a 3D vector
util.transform.scale(x, y, z)
util.transform.scale(util.vector3(x, y, z))

Type `Transform`

Field(s)

Transform:inverse()

Returns the inverse transform.

Return value

#Transform:

Type `Vector2`

Immutable 2D vector

Usage:

v = util.vector2(3, 4)
v.x, v.y       -- 3.0, 4.0
str(v)         -- "(3.0, 4.0)"
v:length()     -- 5.0    length
v:length2()    -- 25.0   square of the length
v:normalize()  -- vector2(3/5, 4/5)
v:rotate(radians)    -- rotate counterclockwise (returns rotated vector)
v1:dot(v2)     -- dot product (returns a number)
v1 * v2        -- dot product
v1 + v2        -- vector addition
v1 - v2        -- vector subtraction
v1 * x         -- multiplication by a number
v1 / x         -- division by a number

Field(s)

Vector2:dot(v)

Dot product.

Parameter

#Vector2 v :

Return value

#number:

Vector2:ediv(v)

Element-wise division

Parameter

#Vector2 v :

Return value

#Vector2:

Vector2:emul(v)

Element-wise multiplication

Parameter

#Vector2 v :

Return value

#Vector2:

Vector2:length()

Length of the vector.

Return value

#number:

Vector2:length2()

Square of the length of the vector.

Return value

#number:

Vector2:normalize()

Normalizes vector.

Returns two values: normalized vector and the length of the original vector. It doesn't change the original vector.

Return value

#Vector2, #number:

Vector2:rotate(angle)

Rotates 2D vector clockwise.

Parameter

#number angle : Angle in radians

Return value

#Vector2: Rotated vector.

#number Vector2.x

#number Vector2.y

Type `Vector3`

Immutable 3D vector

Usage:

v = util.vector3(3, 4, 5)
v.x, v.y, v.z  -- 3.0, 4.0, 5.0
str(v)         -- "(3.0, 4.0, 4.5)"
v:length()     -- length
v:length2()    -- square of the length
v:normalize()  -- normalized vector
v1:dot(v2)     -- dot product (returns a number)
v1 * v2        -- dot product (returns a number)
v1:cross(v2)   -- cross product (returns a vector)
v1 ^ v2        -- cross product (returns a vector)
v1 + v2        -- vector addition
v1 - v2        -- vector subtraction
v1 * x         -- multiplication by a number
v1 / x         -- division by a number

Field(s)

Vector3:cross(v)

Cross product.

Parameter

#Vector3 v :

Return value

#Vector3:

Vector3:dot(v)

Dot product.

Parameter

#Vector3 v :

Return value

#number:

Vector3:ediv(v)

Element-wise division

Parameter

#Vector3 v :

Return value

#Vector3:

Vector3:emul(v)

Element-wise multiplication

Parameter

#Vector3 v :

Return value

#Vector3:

Vector3:length()

Length of the vector

Return value

#number:

Vector3:length2()

Square of the length of the vector

Return value

#number:

Vector3:normalize()

Normalizes vector.

Returns two values: normalized vector and the length of the original vector. It doesn't change the original vector.

Return value

#Vector3, #number:

#number Vector3.x

#number Vector3.y

#number Vector3.z

Type `Vector4`

Immutable 4D vector.

Usage:

v = util.vector4(3, 4, 5, 6)
v.x, v.y, v.z, v.w  -- 3.0, 4.0, 5.0, 6.0
str(v)         -- "(3.0, 4.0, 5.0, 6.0)"
v:length()     -- length
v:length2()    -- square of the length
v:normalize()  -- normalized vector
v1:dot(v2)     -- dot product (returns a number)
v1 * v2        -- dot product (returns a number)
v1 + v2        -- vector addition
v1 - v2        -- vector subtraction
v1 * x         -- multiplication by a number
v1 / x         -- division by a number