Skip to Content
defold-typescript libraries
thejustinwalsh

thejustinwalsh/defold-xmath/xmath

Mathematical operations for vectors, quaternions, and matrices

  • GitHub: thejustinwalsh/defold-xmath — pinned to v1.0.1 (released while Defold 1.13.0 was current)
    1. Pick a release from thejustinwalsh/defold-xmath releases and add its Source code (zip) URL (or a packaged .zip asset, if the library ships one) to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as xmath from "xmath"
  • Asset Portal: defold-xmath

Functions

xmath.add(v_in_place: vector3 | vector4, v1: vector3 | vector4, v2: vector3 | vector4)

Add one vector to another.

Parameters

  • v_in_place: vector3 | vector4
  • v1: vector3 | vector4
  • v2: vector3 | vector4

xmath.sub(v_in_place: vector3 | vector4, v1: vector3 | vector4, v2: vector3 | vector4)

Subtract one vector from another.

Parameters

  • v_in_place: vector3 | vector4
  • v1: vector3 | vector4
  • v2: vector3 | vector4

xmath.mul(v_in_place: vector3 | vector4, v: vector3 | vector4, n: number)

Multiply a vector by a scalar.

Parameters

  • v_in_place: vector3 | vector4
  • v: vector3 | vector4
  • n: number

xmath.div(v_in_place: vector3 | vector4, v: vector3 | vector4, n: number)

Divide a vector by a scalar.

Parameters

  • v_in_place: vector3 | vector4
  • v: vector3 | vector4
  • n: number

xmath.cross(v_in_place: vector3, v1: vector3, v2: vector3)

Calculate the cross product of two vectors.

Parameters

  • v_in_place: vector3
  • v1: vector3
  • v2: vector3

xmath.mul_per_elem(v_in_place: vector3 | vector4, v1: vector3 | vector4, v2: vector3 | vector4)

Perform element-wise multiplication between two vectors.

Parameters

  • v_in_place: vector3 | vector4
  • v1: vector3 | vector4
  • v2: vector3 | vector4

xmath.normalize(v_in_place: vector3 | vector4, v1: vector3 | vector4)

Normalize a vector.

Parameters

  • v_in_place: vector3 | vector4
  • v1: vector3 | vector4

xmath.rotate(v_in_place: vector3, q: quaternion, v1: vector3)

Rotate a vector by a quaternion.

Parameters

  • v_in_place: vector3
  • q: quaternion
  • v1: vector3

xmath.vector(v_in_place: vector3 | vector4)

Set the value of a vector to (0, 0, 0) or (0, 0, 0, 1).

Parameters

  • v_in_place: vector3 | vector4

xmath.conj(q_in_place: quaternion, q1: quaternion)

Calculate the conjugate of a quaternion.

Parameters

  • q_in_place: quaternion
  • q1: quaternion

xmath.quat_axis_angle(q_in_place: quaternion, v: vector3, angle: number)

Set the value of a quaternion from an axis and an angle.

Parameters

  • q_in_place: quaternion
  • v: vector3
  • angle: number

xmath.quat_basis(q_in_place: quaternion, x: vector3, y: vector3, z: vector3)

Set the value of a quaternion from x, y, and z base unit vectors.

Parameters

  • q_in_place: quaternion
  • x: vector3
  • y: vector3
  • z: vector3

xmath.quat_from_to(q_in_place: quaternion, v1: vector3, v2: vector3)

Set the value of a quaternion to rotate from one vector to another.

Parameters

  • q_in_place: quaternion
  • v1: vector3
  • v2: vector3

xmath.quat_rotation_x(q_in_place: quaternion, angle: number)

Set the value of a quaternion for rotation around the x-axis.

Parameters

  • q_in_place: quaternion
  • angle: number

xmath.quat_rotation_y(q_in_place: quaternion, angle: number)

Set the value of a quaternion for rotation around the y-axis.

Parameters

  • q_in_place: quaternion
  • angle: number

xmath.quat_rotation_z(q_in_place: quaternion, angle: number)

Set the value of a quaternion for rotation around the z-axis.

Parameters

  • q_in_place: quaternion
  • angle: number

xmath.quat(q_in_place: quaternion)

Set the value of a quaternion to (0, 0, 0, 1).

Parameters

  • q_in_place: quaternion

xmath.euler_to_quat(q_in_place: quaternion, x: number | vector3, y: number, z: number)

Set the value of a quaternion from Euler angles (in degrees, YZX rotation order).

Parameters

  • q_in_place: quaternion
  • x: number | vector3 — Euler angle around the x-axis in degrees, or a vector3 containing all three angles.
  • y: number — Euler angle around the y-axis in degrees. Ignored if x is a vector3.
  • z: number — Euler angle around the z-axis in degrees. Ignored if x is a vector3.

xmath.lerp(t_or_out: number | vector3 | vector4 | quaternion, n1_or_t: number | vector3 | vector4 | quaternion, n2_or_v1: number | vector3 | vector4 | quaternion, v2: vector3 | vector4 | quaternion): number

Linearly interpolate between two numbers, vectors, or quaternions. For numbers, pass (t, n1, n2) and returns the interpolated number. For vectors/quaternions, pass (v_in_place, t, v1, v2) to modify v_in_place.

Parameters

  • t_or_out: number | vector3 | vector4 | quaternion — For numbers, the interpolation factor. For vectors/quaternions, the output value to store the result.
  • n1_or_t: number | vector3 | vector4 | quaternion — For numbers, the start value. For vectors/quaternions, the interpolation factor.
  • n2_or_v1: number | vector3 | vector4 | quaternion — For numbers, the end value. For vectors/quaternions, the start value.
  • v2: vector3 | vector4 | quaternion — For vectors/quaternions only, the end value.

Returns

  • result: number — For number inputs, returns the interpolated number. For vector/quaternion inputs, modifies v_in_place and returns nothing.

xmath.slerp(v_in_place: vector3 | vector4 | quaternion, t: number, v1: vector3 | vector4 | quaternion, v2: vector3 | vector4 | quaternion)

Spherically interpolate between two vectors or quaternions.

Parameters

  • v_in_place: vector3 | vector4 | quaternion
  • t: number
  • v1: vector3 | vector4 | quaternion
  • v2: vector3 | vector4 | quaternion

xmath.matrix(m_in_place: matrix4, m1: matrix4)

Set the value of a matrix to the identity matrix or copy another matrix.

Parameters

  • m_in_place: matrix4
  • m1: matrix4

xmath.matrix_axis_angle(m_in_place: matrix4, v: vector3, angle: number)

Set the value of a matrix for rotation around an axis by an angle.

Parameters

  • m_in_place: matrix4
  • v: vector3
  • angle: number

xmath.matrix_from_quat(m_in_place: matrix4, q: quaternion)

Set the value of a matrix from a quaternion.

Parameters

  • m_in_place: matrix4
  • q: quaternion

xmath.matrix_frustum(m_in_place: matrix4, left: number, right: number, bottom: number, top: number, near: number, far: number)

Set the value of a frustum matrix from given values.

Parameters

  • m_in_place: matrix4
  • left: number
  • right: number
  • bottom: number
  • top: number
  • near: number
  • far: number

xmath.matrix_inv(m_in_place: matrix4, m1: matrix4)

Calculate the inverse of a matrix.

Parameters

  • m_in_place: matrix4
  • m1: matrix4

xmath.matrix_look_at(m_in_place: matrix4, eye: vector3, look_at: vector3, up: vector3)

Set the value of a matrix from supplied look-at parameters.

Parameters

  • m_in_place: matrix4
  • eye: vector3
  • look_at: vector3
  • up: vector3

xmath.matrix4_orthographic(m_in_place: matrix4, left: number, right: number, bottom: number, top: number, near: number, far: number)

Set the value of an orthographic projection matrix.

Parameters

  • m_in_place: matrix4
  • left: number
  • right: number
  • bottom: number
  • top: number
  • near: number
  • far: number

xmath.matrix_ortho_inv(m_in_place: matrix4, m1: matrix4)

The resulting matrix is the inverse of the supplied matrix.

Parameters

  • m_in_place: matrix4
  • m1: matrix4

xmath.matrix4_perspective(m_in_place: matrix4, fov: number, aspect: number, near: number, far: number)

Set the value of a perspective projection matrix.

Parameters

  • m_in_place: matrix4
  • fov: number
  • aspect: number
  • near: number
  • far: number

xmath.matrix_rotation_x(m_in_place: matrix4, angle: number)

Set the value of a matrix for rotation around the x-axis.

Parameters

  • m_in_place: matrix4
  • angle: number

xmath.matrix_rotation_y(m_in_place: matrix4, angle: number)

Set the value of a matrix for rotation around the y-axis.

Parameters

  • m_in_place: matrix4
  • angle: number

xmath.matrix_rotation_z(m_in_place: matrix4, angle: number)

Set the value of a matrix for rotation around the z-axis.

Parameters

  • m_in_place: matrix4
  • angle: number

xmath.matrix_translation(m_in_place: matrix4, position: vector3 | vector4)

Set the value of a matrix for translation.

Parameters

  • m_in_place: matrix4
  • position: vector3 | vector4

xmath.quat_matrix4(q_in_place: quaternion, m: matrix4)

Set the value of a quaternion from a matrix4.

Parameters

  • q_in_place: quaternion
  • m: matrix4

xmath.matrix4_compose(m_in_place: matrix4, translation: vector3 | vector4, rotation: quaternion, scale: vector3)

Set the value of a matrix from translation, rotation and scale.

Parameters

  • m_in_place: matrix4
  • translation: vector3 | vector4
  • rotation: quaternion
  • scale: vector3

xmath.matrix4_scale(m_in_place: matrix4, scale: vector3 | number)

Set the value of a matrix from scale. Can take a vector3, a single number for uniform scale, or 3 numbers for x, y, z scale.

Parameters

  • m_in_place: matrix4
  • scale: vector3 | number

xmath.clamp(value_or_out: number | vector3 | vector4, value_or_min: number | vector3 | vector4, min_or_max: number | vector3 | vector4, max: number | vector3 | vector4): number

Clamp input value in range [min, max]. For numbers, pass (value, min, max) and returns the clamped number. For vectors, pass (v_in_place, value, min, max) to modify v_in_place. min and max can be numbers or matching vector types.

Parameters

  • value_or_out: number | vector3 | vector4 — For numbers, the value to clamp. For vectors, the output vector to store the result.
  • value_or_min: number | vector3 | vector4 — For numbers, the minimum value. For vectors, the value to clamp.
  • min_or_max: number | vector3 | vector4 — For numbers, the maximum value. For vectors, the minimum value.
  • max: number | vector3 | vector4 — For vectors only, the maximum value.

Returns

  • result: number — For number inputs, returns the clamped number. For vector inputs, modifies v_in_place and returns nothing.

On this page

Functionsxmath.add(v_in_place: vector3 | vector4, v1: vector3 | vector4, v2: vector3 | vector4)xmath.sub(v_in_place: vector3 | vector4, v1: vector3 | vector4, v2: vector3 | vector4)xmath.mul(v_in_place: vector3 | vector4, v: vector3 | vector4, n: number)xmath.div(v_in_place: vector3 | vector4, v: vector3 | vector4, n: number)xmath.cross(v_in_place: vector3, v1: vector3, v2: vector3)xmath.mul_per_elem(v_in_place: vector3 | vector4, v1: vector3 | vector4, v2: vector3 | vector4)xmath.normalize(v_in_place: vector3 | vector4, v1: vector3 | vector4)xmath.rotate(v_in_place: vector3, q: quaternion, v1: vector3)xmath.vector(v_in_place: vector3 | vector4)xmath.conj(q_in_place: quaternion, q1: quaternion)xmath.quat_axis_angle(q_in_place: quaternion, v: vector3, angle: number)xmath.quat_basis(q_in_place: quaternion, x: vector3, y: vector3, z: vector3)xmath.quat_from_to(q_in_place: quaternion, v1: vector3, v2: vector3)xmath.quat_rotation_x(q_in_place: quaternion, angle: number)xmath.quat_rotation_y(q_in_place: quaternion, angle: number)xmath.quat_rotation_z(q_in_place: quaternion, angle: number)xmath.quat(q_in_place: quaternion)xmath.euler_to_quat(q_in_place: quaternion, x: number | vector3, y: number, z: number)xmath.lerp(t_or_out: number | vector3 | vector4 | quaternion, n1_or_t: number | vector3 | vector4 | quaternion, n2_or_v1: number | vector3 | vector4 | quaternion, v2: vector3 | vector4 | quaternion): numberxmath.slerp(v_in_place: vector3 | vector4 | quaternion, t: number, v1: vector3 | vector4 | quaternion, v2: vector3 | vector4 | quaternion)xmath.matrix(m_in_place: matrix4, m1: matrix4)xmath.matrix_axis_angle(m_in_place: matrix4, v: vector3, angle: number)xmath.matrix_from_quat(m_in_place: matrix4, q: quaternion)xmath.matrix_frustum(m_in_place: matrix4, left: number, right: number, bottom: number, top: number, near: number, far: number)xmath.matrix_inv(m_in_place: matrix4, m1: matrix4)xmath.matrix_look_at(m_in_place: matrix4, eye: vector3, look_at: vector3, up: vector3)xmath.matrix4_orthographic(m_in_place: matrix4, left: number, right: number, bottom: number, top: number, near: number, far: number)xmath.matrix_ortho_inv(m_in_place: matrix4, m1: matrix4)xmath.matrix4_perspective(m_in_place: matrix4, fov: number, aspect: number, near: number, far: number)xmath.matrix_rotation_x(m_in_place: matrix4, angle: number)xmath.matrix_rotation_y(m_in_place: matrix4, angle: number)xmath.matrix_rotation_z(m_in_place: matrix4, angle: number)xmath.matrix_translation(m_in_place: matrix4, position: vector3 | vector4)xmath.quat_matrix4(q_in_place: quaternion, m: matrix4)xmath.matrix4_compose(m_in_place: matrix4, translation: vector3 | vector4, rotation: quaternion, scale: vector3)xmath.matrix4_scale(m_in_place: matrix4, scale: vector3 | number)xmath.clamp(value_or_out: number | vector3 | vector4, value_or_min: number | vector3 | vector4, min_or_max: number | vector3 | vector4, max: number | vector3 | vector4): number