Improve lua vector helper class doumentation (#12090)

This commit is contained in:
DS 2022-03-19 12:06:55 +01:00 committed by GitHub
parent e54f5e544f
commit 8d55702d13
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -1544,15 +1544,12 @@ Displays a minimap on the HUD.
Representations of simple things
================================
Position/vector
---------------
Vector (ie. a position)
-----------------------
{x=num, y=num, z=num}
vector.new(x, y, z)
Note: it is highly recommended to construct a vector using the helper function:
vector.new(num, num, num)
For helper functions see [Spatial Vectors].
See [Spatial Vectors] for details.
`pointed_thing`
---------------
@ -1573,8 +1570,7 @@ Exact pointing location (currently only `Raycast` supports these fields):
from 1).
* `pointed_thing.intersection_normal`: Unit vector, points outwards of the
selected selection box. This specifies which face is pointed at.
Is a null vector `{x = 0, y = 0, z = 0}` when the pointer is inside the
selection box.
Is a null vector `vector.zero()` when the pointer is inside the selection box.
@ -3303,33 +3299,76 @@ The following functions provide escape sequences:
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}`.
However, one should *never* create a vector manually as above, such misbehavior
is deprecated. The vector helpers set a metatable for the created vectors which
allows indexing with numbers, calling functions directly on vectors and using
operators (like `+`). Furthermore, the internal implementation might change in
Minetest 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 vectors is, please refer to Wikipedia:
https://en.wikipedia.org/wiki/Euclidean_vector.
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.)
Note that they are *not* used for:
* n-dimensional vectors where n is not 3 (ie. n=2)
* arrays of the form `{num, num, num}`
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 Minetest 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 Minetest 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.
Old code might still use vectors without metatables, be aware of this!
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
-------------------------------
Vectors can be indexed with numbers and allow method and operator syntax.
All these forms of addressing a vector `v` are valid:
`v[1]`, `v[3]`, `v.x`, `v[1] = 42`, `v.y = 13`
Note: Prefer letter over number indexing for performance and compatibility reasons.
Where `v` is a vector and `foo` stands for any function name, `v:foo(...)` does
the same as `vector.foo(v, ...)`, apart from deprecated functionality.
`tostring` is defined for vectors, see `vector.to_string`.
The metatable that is used for vectors can be accessed via `vector.metatable`.
Do not modify it!
All `vector.*` functions allow vectors `{x = X, y = Y, z = Z}` without metatables.
Returned vectors always have a metatable set.
For the following functions, `v`, `v1`, `v2` are vectors,
`p1`, `p2` are positions,
Common functions and methods
----------------------------
For the following functions (and subchapters),
`v`, `v1`, `v2` are vectors,
`p1`, `p2` are position vectors,
`s` is a scalar (a number),
vectors are written like this: `(x, y, z)`:
@ -3351,6 +3390,7 @@ vectors are written like this: `(x, y, z)`:
* `init`: If given starts looking for the vector at this string index.
* `vector.to_string(v)`:
* Returns a string of the form `"(x, y, z)"`.
* `tostring(v)` does the same.
* `vector.direction(p1, p2)`:
* Returns a vector of length 1 with direction `p1` to `p2`.
* If `p1` and `p2` are identical, returns `(0, 0, 0)`.
@ -3403,6 +3443,9 @@ For the following functions `x` can be either a vector or a number:
* Returns a scaled vector.
* Deprecated: If `s` is a vector: Returns the Schur quotient.
Operators
---------
Operators can be used if all of the involved vectors have metatables:
* `v1 == v2`:
* Returns whether `v1` and `v2` are identical.
@ -3419,8 +3462,11 @@ Operators can be used if all of the involved vectors have metatables:
* `v / s`:
* Returns `v` scaled by `1 / s`.
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
vector (`{x = <pitch>, y = <yaw>, z = <roll>}`) where pitch, yaw and roll are
angles in radians.
* `vector.rotate(v, r)`:
@ -3437,6 +3483,18 @@ angles in radians.
* 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:
* `minetest.hash_node_position` (Only works on node positions.)
* `minetest.dir_to_wallmounted` (Involves wallmounted param2 values.)