vector_extras/doc.md

155 lines
6.8 KiB
Markdown
Raw Normal View History

2020-04-07 20:47:07 +02:00
# Vector helpers added by this mod
## Helpers which return many positions for a shape, e.g. a line
### Line functions
These may be deprecated since raycasting has been added to minetest.
See e.g. `minetest.line_of_sight`.
* `vector.line([pos, dir[, range][, alt]])`: returns a table of vectors
* `dir` is either a direction (when range is a number) or
the start position (when range is the end position).
* If alt is true, an old path calculation is used.
* `vector.twoline(x, y)`: can return e.g. `{{0,0}, {0,1}}`
* This is a lower-level function than `vector.line`; it can be used for
a 2D line.
* `vector.threeline(x, y, z)`: can return e.g. `{{0,0,0}, {0,1,0}}`
* Similar to `vector.twoline`; this one is for the 3D case.
* The parameters should be integers.
* `vector.rayIter(pos, dir)`: returns an iterator for a for loop
* `pos` can have non-integer values
* `vector.fine_line([pos, dir[, range], scale])`: returns a table of vectors
* Like `vector.line` but allows non-integer positions
* It uses `vector.rayIter`.
### Flood Fill
* `vector.search_2d(go_test, x0, y0, allow_revisit, give_map)`: returns e.g.
`{{0,0}, {0,1}}`
* This function uses a Flood Fill algorithm, so it can be used to detect
positions connected to each other in 2D.
* `go_test(x, y)` should be a function which returns true iff the algorithm
can "fill" at the position `(x, y)`.
* `(x0, y0)` defines the start position.
* If `allow_revisit` is false (the default), the function
invokes `go_test` only once at every potential position.
* If `give_map` is true (default is false), the function returns the
marked table, whose indices are 2D vector indices, instead of a list of
2D positions.
* `vector.search_3d(can_go, startpos, apply_move, moves)`: returns FIXME
* FIXME
### Other Shapes
* `vector.explosion_table(r)`: returns e.g. `{{pos1}, {pos2, true}}`
* The returned list of positions and boolean represents a sphere;
if the boolean is true, the position is on the outer side of the sphere.
* It might be used for explosion calculations; but `vector.explosion_perlin`
should make more realistic holes.
* `vector.explosion_perlin(rmin, rmax[, nparams])`: returns e.g.
`{{pos1}, {pos2, true}}`
* This function is similar to `vector.explosion_table`; the positions
do not represent a sphere but a more complex hole which is calculated
with the help of perlin noise.
* `rmin` and `rmax` represent the minimum and maximum radius,
and `nparams` (which has a default value) are parameters for the perlin
noise.
* `vector.circle(r)`: returns a table of vectors
* The returned positions represent a circle of radius `r` along the x and z
directions; the y coordinates are all zero.
* `vector.ring(r)`: returns a table of vectors
* This function is similar to `vector.circle`; the positions are all
touching each other (i.e. they are connected on whole surfaces and not
only infinitely thin edges), so it is called `ring` instead of `circle`
* `r` can be a non-integer number.
* `vector.throw_parabola(pos, vel, gravity, point_count, time)`
* FIXME: should return positions along a parabola so that moving objects
collisions can be calculated
* `vector.triangle(pos1, pos2, pos3)`: returns a table of positions, a number
and a table with barycentric coordinates
* This function calculates integer positions for a triangle defined by
`pos1`, `pos2` and `pos3`, so it can be used to place polygons in
minetest.
* The returned number is the number of positions.
* The barycentric coordinates are specified in a table with three elements;
the first one corresponds to `pos1`, etc.
## Helpers for various vector calculations
* `vector.sort_positions(ps[, preferred_coords])`
* Sorts a table of vectors `ps` along the coordinates specified in the
table `preferred_coords` in-place.
* If `preferred_coords` is omitted, it sorts along z, y and x in this order,
where z has the highest priority.
* `vector.maxnorm(v)`: returns the Tschebyshew norm of `v`
* `vector.sumnorm(v)`: returns the Manhattan norm of `v`
* `vector.pnorm(v, p)`: returns the `p` norm of `v`
* `vector.inside(pos, minp, maxp)`: returns a boolean
* Returns true iff `pos` is within the closed AABB defined by `minp`
and `maxp`.
* `vector.minmax(pos1, pos2)`: returns two vectors
* This does the same as `worldedit.sort_pos`.
* The components of the second returned vector are all bigger or equal to
those of the first one.
* `vector.move(pos1, pos2, length)`: returns a vector
* Go from `pos1` `length` metres to `pos2` and then round to the nearest
integer position.
* Made for rubenwardy
* `vector.from_number(i)`: returns `{x=i, y=i, z=i}`
* `vector.chunkcorner(pos)`: returns a vector
* Returns the mapblock position of the mapblock which contains
the integer position `pos`
* `vector.point_distance_minmax(p1, p2)`: returns two numbers
* Returns the minimum and maximum of the absolute component-wise distances
* `vector.collision(p1, p2)` FIXME
* `vector.update_minp_maxp(minp, maxp, pos)`
* Can change `minp` and `maxp` so that `pos` is within the AABB defined by
`minp` and `maxp`
* `vector.unpack(v)`: returns three numbers
* Returns `v.z, v.y, v.x`
* `vector.get_max_coord(v)`: returns a string
* Returns `"x"`, `"y"` or `"z"`, depending on which component has the
biggest value
* `vector.get_max_coords(v)`: returns three strings
* Similar to `vector.get_max_coord`; it returns the coordinates in the order
of their component values
* Example: `vector.get_max_coords{x=1, y=5, z=3}` returns `"y", "z", "x"`
* `vector.serialize(v)`: returns a string
* In comparison to `minetest.serialize`, this function uses a more compact
string for the serialization.
## Minetest-specific helper functions
* `vector.straightdelay([length, vel[, acc]])`: returns a number
* Returns the time an object takes to move `length` if it has velocity `vel`
and acceleration `acc`
* `vector.sun_dir([time])`: returns a vector or nil
* Returns the vector which points to the sun
* If `time` is omitted, it uses the current time.
* This function does not yet support the moon;
at night it simply returns `nil`.
## Helpers which I don't recommend to use now
* `vector.pos_to_string(pos)`: returns a string
* It is similar to `minetest.pos_to_string`; it uses a different format:
`"("..pos.x.."|"..pos.y.."|"..pos.z..")"`
* `vector.zero`
* The zero vector `{x=0, y=0, z=0}`
* `vector.quickadd(pos, [z],[y],[x])`
* Adds values to the vector components in-place
## Deprecated helpers
* `vector.plane`
* should be removed soon; it should have done the same as vector.triangle