Spatial Vectors¶

Luanti stores 3-dimensional spatial vectors in Lua as tables of 3 coordinates, and has a class to represent them (vector.*), which this chapter is about. For details on what a spatial vector is, please refer to Wikipedia.

Spatial vectors are used for various things, including, but not limited to:

• any 3D spatial vector (x/y/z-directions)
• Euler angles (pitch/yaw/roll in radians) (Spatial vectors have no real semantic meaning here. Therefore, most vector operations make no sense in this use case.)

The API documentation may refer to spatial vectors, as produced by vector.new, by any of the following notations:

• (x, y, z) (Used rarely, and only if it's clear that it's a vector.)
• vector.new(x, y, z)
• {x=num, y=num, z=num} (Even here you are still supposed to use vector.new.)

Compatibility notes¶

Vectors used to be defined as tables of the form {x = num, y = num, z = num}. Since version 5.5.0, vectors additionally have a metatable to enable easier use. Note: Those old-style vectors can still be found in old mod code. Hence, mod and engine APIs still need to be able to cope with them in many places.

Manually constructed tables are deprecated and highly discouraged. This interface should be used to ensure seamless compatibility between mods and the Luanti API. This is especially important to callback function parameters and functions overwritten by mods. Also, though not likely, the internal implementation of a vector might change in the future. In your own code, or if you define your own API, you can, of course, still use other representations of vectors.

Vectors provided by API functions will provide an instance of this class if not stated otherwise. Mods should adapt this for convenience reasons.

Special properties of the class¶

For special properties common to all vector types (indexing, method syntax, operators, etc.), see Common to all vector types.

Functions¶

For common functions available to both vector and vector2, see Common functions.

The following functions are specific to vector (3D vectors).

For the following functions, v, v1, v2 are vectors, p1, p2 are position vectors, s is a scalar (a number), vectors are written like this: (x, y, z):

• vector.new([a[, b, c]]):
  • Returns a new vector (a, b, c).
  • Deprecated: vector.new() does the same as vector.zero() and vector.new(v) does the same as vector.copy(v)
• 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.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, y, z).
• vector.random_in_area(min, max):
  • Returns a random integer position in area formed by min and max
  • min and max are inclusive.
  • You can use vector.sort if you have two vectors and don't know which are the minimum and the maximum.

Operators¶

For vector operators (+, -, *, /, ==, unary -), see Common to all vector types.

Rotation-related functions¶

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

• vector.rotate(v, r):
  • Applies the rotation r to v and returns the result.
  • Uses (extrinsic) Z-X-Y rotation order and is right-handed, consistent with ObjectRef:set_rotation.
  • vector.rotate(vector.new(0, 0, 1), r) and vector.rotate(vector.new(0, 1, 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.

Further helpers¶

There are more helper functions involving vectors, but they are listed elsewhere because they only work on specific sorts of vectors or involve things that are not vectors.

For example:

• core.hash_node_position (Only works on node positions.)
• core.dir_to_wallmounted (Involves wallmounted param2 values.)