Log In  

Cart #vector_p8-3 | 2023-03-11 | Code ▽ | Embed ▽ | License: CC4-BY-NC-SA


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.


  • 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

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.


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.


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


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
P#121553 2022-11-29 14:31 ( Edited 2023-07-24 14:49)

i got an error loading it up

P#121622 2022-11-30 15:03

oh yeah, right, the cart here has a demo, you gotta remove that code and then you can use the lib. I gotta put that in the post...

P#121629 2022-11-30 18:23

[Please log in to post a comment]

Follow Lexaloffle:          
Generated 2023-09-30 06:26:36 | 0.018s | Q:16