Spatial Vectors¶

A spatial vector is similar to a position, but instead using absolute world coordinates, it uses relative coordinates, relative to no particular point.

Internally, it is implemented as a table with the 3 fields x, y and z. Example: {x = 0, y = 1, z = 0}.

For the following functions, v, v1, v2 are vectors, p1, p2 are positions, s is a scalar (a number):

• vector.new(a[, b, c]):
  • Returns a vector.
  • A copy of a if a is a vector.
  • {x = a, y = b, z = c}, if all of a, b, c are defined numbers.
• vector.zero():
  • Returns a new vector (0, 0, 0).
• vector.copy(v):
  • Returns a copy of the vector v.
• vector.direction(p1, p2):
  • Returns a vector of length 1 with direction p1 to p2.
  • If p1 and p2 are identical, returns {x = 0, y = 0, z = 0}.
• vector.distance(p1, p2):
  • Returns zero or a positive number, the distance between p1 and p2.
• vector.length(v):
  • Returns zero or a positive number, the length of vector v.
• vector.normalize(v):
  • Returns a vector of length 1 with direction of vector v.
  • If v has zero length, returns {x = 0, y = 0, z = 0}.
• vector.floor(v):
  • Returns a vector, each dimension rounded down.
• vector.round(v):
  • Returns a vector, each dimension rounded to nearest integer.
  • At a multiple of 0.5, rounds away from zero.
• vector.apply(v, func):
  • Returns a vector where the function func has been applied to each component.
• vector.equals(v1, v2):
  • Returns a boolean, true if the vectors are identical.
• vector.sort(v1, v2):
  • Returns in order minp, maxp vectors of the cuboid defined by v1, v2.
• vector.angle(v1, v2):
  • Returns the angle between v1 and v2 in radians.
• vector.dot(v1, v2):
  • Returns the dot product of v1 and v2.
• vector.cross(v1, v2):
  • Returns the cross product of v1 and v2.
• vector.offset(v, x, y, z):
  • Returns the sum of the vectors v and {x = x, y = y, z = z}.

For the following functions x can be either a vector or a number:

• vector.add(v, x):
  • Returns a vector.
  • If x is a vector: Returns the sum of v and x.
  • If x is a number: Adds x to each component of v.
• vector.subtract(v, x):
  • Returns a vector.
  • If x is a vector: Returns the difference of v subtracted by x.
  • If x is a number: Subtracts x from each component of v.
• vector.multiply(v, s):
  • Returns a scaled vector.
  • Deprecated: If s is a vector: Returns the Schur product.
• vector.divide(v, s):
  • Returns a scaled vector.
  • Deprecated: If s is a vector: Returns the Schur quotient.

For the following functions a is an angle in radians and r is a rotation vector ({x = , y = , z = }) where pitch, yaw and roll are angles in radians.

• vector.rotate(v, r):
  • Applies the rotation r to v and returns the result.
  • vector.rotate({x = 0, y = 0, z = 1}, r) and vector.rotate({x = 0, y = 1, z = 0}, r) return vectors pointing forward and up relative to an entity's rotation r.
• vector.rotate_around_axis(v1, v2, a):
  • Returns v1 rotated around axis v2 by a radians according to the right hand rule.
• vector.dir_to_rotation(direction[, up]):
  • Returns a rotation vector for direction pointing forward using up as the up vector.
  • If up is omitted, the roll of the returned vector defaults to zero.
  • Otherwise direction and up need to be vectors in a 90 degree angle to each other.