# 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. When passing in 3D vectors, the result will always be 2D. All these functions 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 (all but `v_be*d`

) 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]