vector_extras/doc.md

# 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