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

Type TRANSFORM

TRANSFORM.identity

Empty transform.

TRANSFORM.move(offset)

Movement by given vector.

TRANSFORM.rotate(angle, axis)

Rotation (any axis).

TRANSFORM.rotateX(angle)

X-axis rotation.

TRANSFORM.rotateY(angle)

Y-axis rotation.

TRANSFORM.rotateZ(angle)

Z-axis rotation.

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

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 (any axis).

Parameters

Return value

#Transform:

TRANSFORM.rotateX(angle)

X-axis rotation.

Parameter

  • #number angle :

Return value

#Transform:

TRANSFORM.rotateY(angle)

Y-axis rotation.

Parameter

  • #number angle :

Return value

#Transform:

TRANSFORM.rotateZ(angle)

Z-axis rotation.

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 clockwise (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