# vector.p8

a simple and lightweight (in tokens) vector math library for PICO-8. this library contains no error handling *at all*. it's a side effect of keeping it low in tokens, so you're gonna have to be responsible of whatever goes in.

usage:

`load #vector_p8`

- save as such: vector.p8.
- remove all the demo code; it's in the second tab.
`#include`

in any cart you want.

## functions within:

### creation and management

`vector(x,y,z)`

- *the* function. vectors are just normal Lua tables with `x`

, `y`

and `z`

fields, so you can pass any table that contains x, y and z to any of the functions and it'll work just fine.

`v_polar(length,angle)`

- makes a vector using polar coordinates.

`v_rnd()`

- gives a normalized vector with a random direction.

`v_cpy(v)`

- copies a vector.

`v_unpck(v)`

- unpacks a vector.

`v_arr(v)`

- returns a vector as an array of the 3 components that comprise it. Ignore the third value (Z) if your vector is a 2D one.

`v_tostr(v,d)`

- turns a vector into a string. The `d`

parameter is used to know if it should be printed as a 3D vector or not.

`v_isvec(v)`

- checks if a certain value is a vector.

### actual math

`v_add(a,b)`

- adds two vectors of any dimension.

`v_sub(a,b)`

- subtracts two vectors of any dimension.

`v_scl(v,n)`

- scales a vector by a scalar (normal number).

`v_mul(v,n)`

- alias for `v_scl`

.

`v_div(v,n)`

- scales a vector by the inverse of a scalar ("divides" the vector).

`v_dot(a,b)`

- computes the dot product of two vectors.

`v_cross(a,b)`

- computes the cross product of two 3D vectors.

`v_magsq(v)`

- computes the magnitude squared of a vector.

`v_mag(v)`

- computes the magnitude of a vector.

`v_dstsq(a,b)`

- computes the distance squared between two vectors.

`v_dst(a,b)`

- computes the distance between two vectors.

`v_norm(v)`

- normalizes a vector.

`v_perp(v)`

- gets a 2D vector perpendicular to the passed one.

`v_sprj(a,b)`

- returns the scalar projection of one 2D vector in another.

`v_proj(a,b)`

- returns the actual projection of one 2D vector in another.

### rotation related functions

**WARNING!**

none of these functions work with 3D vectors. all of them work with revolutions according to PICO-8's convention.

`v_rot(v,t)`

- Rotates a vector by an angle `t`

.

`v_ang(v)`

- Gets the direction a vector is pointing towards.

`v_atwds(a,b)`

- Gets the angle needed to point towards another vector.

### miscellaneous

`v_lerp(a,b,t)`

- linearly interpolates two vectors.

`v_flr(v)`

- floors a vector.

`v_eq(a,b)`

- checks if two vectors are equal.

## constants

**WARNING!**

because of the way Lua tables work, do **NOT** use compound assignments to alter a variable if you directly assign one of these constants to it. either copy the constant using `v_cpy`

and then assign that to the variable or use one of the functions within the library to manipulate it.

`v_right`

- rightwards pointing vector.

`v_left`

- leftwards pointing vector.

`v_up`

- upwards pointing vector. Y points downward in 2D so this vector points towards -Y.

`v_down`

- downwards pointing vector. Y points downward in 2D so this vector points towards +Y.

`v_above`

- 3D vector pointing upwards. unlike 2D, Y in 3D points upwards, so this vector points towards +Y.

`v_below`

- 3D vector pointing downwards. unlike 2D, Y in 3D points upwards, so this vector points towards -Y.

`v_front`

- 3D vector pointing forwards.

`v_back`

- 3D vector pointing backwards.

`v_zero`

- zero vector. all components are set to 0.

`v_one`

- identity vector. all components are set to 1.

`v_cntr`

- utility vector pointing towards the center of the screen, i.e. [64,64].

## changelog

v1.2.1 (11-03-2023):

- thought I had fixed all functions that used
`v_getd`

, but turns out one function I hadn't added to the docs,`v_flr`

, still used it. - documented
`v_flr`

. - improved explanation for
`v_atwds`

.

v1.2 (06-12-2022):

- fixed the math functions
`v_add`

,`v_sub`

,`v_scl`

,`v_div`

and`v_neg`

using the now-defunct`v_getd`

function.

v1.1 (09-11-2022):

- removed all dimension related functions.

Consequently, a parameter was added to v_tostr for it to know how to format the output. - added
`v_sprj`

and`v_proj`

. - renamed
`v_center`

to`v_cntr`

.

v1.0 (09-11-2022):

- initial release

[Please log in to post a comment]