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.clamp(value, from, to)

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

util.makeReadOnly(table)

Makes a table read only.

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.color

Methods for creating #Color values from different formats.

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: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: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: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.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)

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.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

Field(s)

#COLOR COLOR.color

Methods for creating #Color values from different formats.

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

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

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

Return value

#number:

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

Return value

#Vector3:

Vector3:dot(v)

Dot product.

Parameter

Return value

#number:

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

Field(s)

Vector4:dot(v)

Dot product.

Parameter

Return value

#number:

Vector4:length()

Length of the vector

Return value

#number:

Vector4:length2()

Square of the length of the vector

Return value

#number:

Vector4:normalize()

Normalizes vector.

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

Return value

#Vector4, #number:

#number Vector4.w
#number Vector4.x
#number Vector4.y
#number Vector4.z