diff options
| -rw-r--r-- | doc/lua_api.txt | 104 |
1 files changed, 81 insertions, 23 deletions
diff --git a/doc/lua_api.txt b/doc/lua_api.txt index 89bc7dc4b..52da17e9c 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -1544,15 +1544,12 @@ Displays a minimap on the HUD. Representations of simple things ================================ -Position/vector ---------------- - - {x=num, y=num, z=num} +Vector (ie. a position) +----------------------- - Note: it is highly recommended to construct a vector using the helper function: - vector.new(num, num, num) + vector.new(x, y, z) -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.) + |