mirror of
https://github.com/minetest/minetest.git
synced 2024-08-18 20:44:16 +02:00
Improve lua vector helper class doumentation (#12090)
This commit is contained in:
parent
e54f5e544f
commit
8d55702d13
102
doc/lua_api.txt
102
doc/lua_api.txt
@ -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.)
|
||||
|
||||
|
||||
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user