p5 2.2.3 → 2.3.0-rc.1

package/dist/math/p5.Vector.js

@@ -1,90 +1,93 @@
-import { q as TWO_PI } from '../constants-BdTiYOQI.js';
+import { o as TWO_PI } from '../constants-0wkVUfqa.js';
 
 /**
  * @module Math
- * @requires constants
  */
 
 
-/// HELPERS FOR REMAINDER METHOD
-const calculateRemainder2D = function (xComponent, yComponent) {
-  if (xComponent !== 0) {
-    this.x = this.x % xComponent;
-  }
-  if (yComponent !== 0) {
-    this.y = this.y % yComponent;
-  }
-  return this;
+/**
+ * This function is used by binary vector operations to prioritize shorter vectors,
+ * and to emit a warning when lengths do not match.
+ */
+const prioritizeSmallerDimension = function(currentVectorDimension, args) {
+  return Math.min(currentVectorDimension, args.length);
 };
 
-const calculateRemainder3D = function (xComponent, yComponent, zComponent) {
-  if (xComponent !== 0) {
-    this.x = this.x % xComponent;
-  }
-  if (yComponent !== 0) {
-    this.y = this.y % yComponent;
-  }
-  if (zComponent !== 0) {
-    this.z = this.z % zComponent;
-  }
-  return this;
-};
 
 class Vector {
+  /**
+   * The values of an N-dimensional vector.
+   *
+   * This array of numbers that represents the vector.
+   * Each number in the array corresponds to a different component of the vector,
+   * like its position in different directions (e.g., x, y, z).
+   *
+   * You can update the values of the entire vector to a new set of values.
+   * You need to provide an array of numbers, where each number represents a component
+   * of the vector (e.g., x, y, z). The length of the array will become the number of
+   * dimensions of the vector.
+   *
+   * You can add (`add()`), multiply (`mult()`), divide (`div()`), and subtract (`sub()`)
+   * vectors from each other, and calculate remainder (`rem()`). Only use these functions
+   * on vectors when they are the same size: both 2-dimensional, or both 3-dimensional.
+   * When an operation uses two vectors of different sizes, the smaller dimension will be
+   * used, any additional values of the longer vector will be ignored.
+   *
+   * You can multiply, divide, or calculate remainder of a vector with a single number. Then,
+   * the same operation will be done on each element of the vector.
+   *
+   * @type {Array<number>} The array of values representing the vector.
+   * @throws Will throw an error if provided no arguments, or if the arguments
+   *         are not all finity numbers
+   */
+  values = [];
+
   // This is how it comes in with createVector()
   // This check if the first argument is a function
   constructor(...args) {
-    let values = args; // .map(arg => arg || 0);
+
+    if (args.length === 0) {
+      this._friendlyError(
+        'Requires valid arguments.', 'p5.Vector'
+      );
+    }
+
     if (typeof args[0] === 'function') {
       this.isPInst = true;
       this._fromRadians = args[0];
       this._toRadians = args[1];
-      values = args.slice(2); // .map(arg => arg || 0);
+      args = args.slice(2);
     }
-    let dimensions = values.length; // TODO: make default 3 if no arguments
-    if (dimensions === 0) {
-      this.dimensions = 2;
-      this._values = [0, 0, 0];
+
+    this.values = [];
+    if(Array.isArray(args) && !args.every(v => typeof v === 'number' && Number.isFinite(v))){
+      this._friendlyError(
+        'Arguments contain non-finite numbers',
+        'p5.Vector'
+      );
     } else {
-      this.dimensions = dimensions;
-      this._values = values;
+      this.values = args;
     }
-  }
 
-  /**
-   * Gets the values of the N-dimensional vector.
-   *
-   * This method returns an array of numbers that represent the vector.
-   * Each number in the array corresponds to a different component of the vector,
-   * like its position in different directions (e.g., x, y, z).
-   *
-   * @returns {Array<number>} The array of values representing the vector.
-   */
-  get values() {
-    return this._values;
+    // This property is here where duck typing (checking if obj.isVector) needs
+    // to be used over more standard type checking (obj instanceof Vector). This
+    // needs to happen where we are building multiple files, such as in p5.webgpu.js,
+    // where if we `import { Vector }` directly, it will be a separate copy of the
+    // Vector class from the one imported in the main p5.js bundle.
+    this.isVector = true;
   }
 
+  // This will get overwritten when exported as part of p5.
+  _friendlyError(_e) {}
+
+
   /**
-   * Sets the values of the vector.
-   *
-   * This method allows you to update the entire vector with a new set of values.
-   * You need to provide an array of numbers, where each number represents a component
-   * of the vector (e.g., x, y, z). The length of the array should match the number of
-   * dimensions of the vector. If the array is shorter, the missing components will be
-   * set to 0. If the array is longer, the extra values will be ignored.
-   *
-   * @param {Array<number>} newValues - An array of numbers representing the new values for the vector.
+   * Gets how many dimensions the vector has.
    *
+   * @returns {Number} The number of dimensions. Can be 1, 2, or 3.
    */
-  set values(newValues) {
-    let dimensions = newValues.length;
-    if (dimensions === 0) {
-      this.dimensions = 2;
-      this._values = [0, 0, 0];
-    } else {
-      this.dimensions = dimensions;
-      this._values = newValues.slice();
-    }
+  get dimensions(){
+    return this.values.length;
   }
 
   /**
@@ -97,7 +100,7 @@ class Vector {
    * @returns {Number} The x component of the vector. Returns 0 if the value is not defined.
    */
   get x() {
-    return this._values[0] || 0;
+    return this.values[0] || 0;
   }
 
   /**
@@ -118,10 +121,10 @@ class Vector {
    *          get a value from a position that doesn't exist in the vector.
    */
   getValue(index) {
-    if (index < this._values.length) {
-      return this._values[index];
+    if (index < this.values.length) {
+      return this.values[index];
     } else {
-      p5._friendlyError(
+      this._friendlyError(
         'The index parameter is trying to set a value outside the bounds of the vector',
         'p5.Vector.setValue'
       );
@@ -143,10 +146,10 @@ class Vector {
    * @throws Will throw an error if the index is outside the bounds of the vector, meaning if you try to set a value at a position that doesn't exist in the vector.
    */
   setValue(index, value) {
-    if (index < this._values.length) {
-      this._values[index] = value;
+    if (index < this.values.length) {
+      this.values[index] = value;
     } else {
-      p5._friendlyError(
+      this._friendlyError(
         'The index parameter is trying to set a value outside the bounds of the vector',
         'p5.Vector.setValue'
       );
@@ -163,7 +166,7 @@ class Vector {
    * @returns {Number} The y component of the vector. Returns 0 if the value is not defined.
    */
   get y() {
-    return this._values[1] || 0;
+    return this.values[1] || 0;
   }
 
   /**
@@ -176,7 +179,7 @@ class Vector {
    * @returns {Number} The z component of the vector. Returns 0 if the value is not defined.
    */
   get z() {
-    return this._values[2] || 0;
+    return this.values[2] || 0;
   }
 
   /**
@@ -189,7 +192,7 @@ class Vector {
    * @returns {Number} The w component of the vector. Returns 0 if the value is not defined.
    */
   get w() {
-    return this._values[3] || 0;
+    return this.values[3] || 0;
   }
 
   /**
@@ -202,8 +205,8 @@ class Vector {
    * @param {Number} xVal - The new value for the x component.
    */
   set x(xVal) {
-    if (this._values.length > 1) {
-      this._values[0] = xVal;
+    if (this.values.length > 1) {
+      this.values[0] = xVal;
     }
   }
 
@@ -217,8 +220,8 @@ class Vector {
    * @param {Number} yVal - The new value for the y component.
    */
   set y(yVal) {
-    if (this._values.length > 1) {
-      this._values[1] = yVal;
+    if (this.values.length > 1) {
+      this.values[1] = yVal;
     }
   }
 
@@ -232,8 +235,8 @@ class Vector {
    * @param {Number} zVal - The new value for the z component.
    */
   set z(zVal) {
-    if (this._values.length > 2) {
-      this._values[2] = zVal;
+    if (this.values.length > 2) {
+      this.values[2] = zVal;
     }
   }
 
@@ -247,8 +250,8 @@ class Vector {
    * @param {Number} wVal - The new value for the w component.
    */
   set w(wVal) {
-    if (this._values.length > 3) {
-      this._values[3] = wVal;
+    if (this.values.length > 3) {
+      this.values[3] = wVal;
     }
   }
 
@@ -270,7 +273,7 @@ class Vector {
    * }
    */
   toString() {
-    return `vector[${this._values.join(', ')}]`;
+    return `vector[${this.values.join(', ')}]`;
   }
 
   /**
@@ -328,13 +331,12 @@ class Vector {
    */
   set(...args) {
     if (args[0] instanceof Vector) {
-      this._values = args[0].values.slice();
+      this.values = args[0].values.slice();
     } else if (Array.isArray(args[0])) {
-      this._values = args[0].map(arg => arg || 0);
+      this.values = args[0].map(arg => arg || 0);
     } else {
-      this._values = args.map(arg => arg || 0);
+      this.values = args.map(arg => arg || 0);
     }
-    this.dimensions = this._values.length;
     return this;
   }
 
@@ -364,12 +366,14 @@ class Vector {
    */
   copy() {
     if (this.isPInst) {
-      return new Vector(this._fromRadians, this._toRadians, ...this._values);
+      return new Vector(this._fromRadians, this._toRadians, ...this.values);
     } else {
-      return new Vector(...this._values);
+      return new Vector(...this.values);
     }
   }
 
+
+
   /**
    * Adds to a vector's components.
    *
@@ -377,8 +381,12 @@ class Vector {
    * another <a href="#/p5.Vector">p5.Vector</a> object, as in `v.add(v2)`, or
    * an array of numbers, as in `v.add([1, 2, 3])`.
    *
-   * If a value isn't provided for a component, it won't change. For
-   * example, `v.add(4, 5)` adds 4 to `v.x`, 5 to `v.y`, and 0 to `v.z`.
+   * Add vectors only when they are the same size: both 2-dimensional, or
+   * both 3-dimensional. When two vectors of different sizes are added, the
+   * smaller dimension will be used, any additional values of the longer
+   * vector will be ignored.
+   * For example, adding `[1, 2, 3]` and `[4, 5]` will result in `[5, 7]`.
+   *
    * Calling `add()` with no arguments, as in `v.add()`, has no effect.
    *
    * This method supports N-dimensional vectors.
@@ -495,17 +503,18 @@ class Vector {
    * @chainable
    */
   add(...args) {
-    if (args[0] instanceof Vector) {
-      args = args[0].values;
-    } else if (Array.isArray(args[0])) {
-      args = args[0];
-    }
-    args.forEach((value, index) => {
-      this._values[index] = (this._values[index] || 0) + (value || 0);
-    });
+    const minDimension = prioritizeSmallerDimension(this.dimensions, args);
+
+    this.values = this.values.reduce((acc, v, i) => {
+      if(i < minDimension) acc[i] = this.values[i] + Number(args[i]);
+      return acc;
+    }, new Array(minDimension));
+
     return this;
   }
 
+
+
   /**
    * Performs modulo (remainder) division with a vector's `x`, `y`, and `z`
    * components.
@@ -515,10 +524,14 @@ class Vector {
    * an array of numbers, as in `v.rem([1, 2, 3])`.
    *
    * If only one value is provided, as in `v.rem(2)`, then all the components
-   * will be set to their values modulo 2. If two values are provided, as in
-   * `v.rem(2, 3)`, then `v.z` won't change. Calling `rem()` with no
+   * will be set to their values modulo 2. Calling `rem()` with no
    * arguments, as in `v.rem()`, has no effect.
    *
+   * Modulo vectors only when they are the same size: both 2D, or both 3D.
+   * When two vectors of different sizes are used, the smaller dimension will be
+   * used, any additional values of the longer vector will be ignored.
+   * For example, taking `[3, 6, 9]` modulo `[2, 4]` will result in `[1, 2]`.
+   *
    * The static version of `rem()`, as in `p5.Vector.rem(v2, v1)`, returns a
    * new <a href="#/p5.Vector">p5.Vector</a> object and doesn't change the
    * originals.
@@ -613,59 +626,14 @@ class Vector {
    * @param {p5.Vector | Number[]}  value  divisor vector.
    * @chainable
    */
-  rem(x, y, z) {
-    if (x instanceof Vector) {
-      if ([x.x, x.y, x.z].every(Number.isFinite)) {
-        const xComponent = parseFloat(x.x);
-        const yComponent = parseFloat(x.y);
-        const zComponent = parseFloat(x.z);
-        return calculateRemainder3D.call(
-          this,
-          xComponent,
-          yComponent,
-          zComponent
-        );
-      }
-    } else if (Array.isArray(x)) {
-      if (x.every(element => Number.isFinite(element))) {
-        if (x.length === 2) {
-          return calculateRemainder2D.call(this, x[0], x[1]);
-        }
-        if (x.length === 3) {
-          return calculateRemainder3D.call(this, x[0], x[1], x[2]);
-        }
-      }
-    } else if (arguments.length === 1) {
-      if (Number.isFinite(arguments[0]) && arguments[0] !== 0) {
-        this.x = this.x % arguments[0];
-        this.y = this.y % arguments[0];
-        this.z = this.z % arguments[0];
-        return this;
-      }
-    } else if (arguments.length === 2) {
-      const vectorComponents = [...arguments];
-      if (vectorComponents.every(element => Number.isFinite(element))) {
-        if (vectorComponents.length === 2) {
-          return calculateRemainder2D.call(
-            this,
-            vectorComponents[0],
-            vectorComponents[1]
-          );
-        }
-      }
-    } else if (arguments.length === 3) {
-      const vectorComponents = [...arguments];
-      if (vectorComponents.every(element => Number.isFinite(element))) {
-        if (vectorComponents.length === 3) {
-          return calculateRemainder3D.call(
-            this,
-            vectorComponents[0],
-            vectorComponents[1],
-            vectorComponents[2]
-          );
-        }
-      }
-    }
+  rem(...args) {
+    const minDimension = prioritizeSmallerDimension(this.dimensions, args);
+
+    this.values = Array.from({ length: minDimension }, (_, i) => {
+      return (args[i] > 0) ? this.values[i] % args[i] : this.values[i];
+    });
+
+    return this;
   }
 
   /**
@@ -675,10 +643,13 @@ class Vector {
    * <a href="#/p5.Vector">p5.Vector</a> object, as in `v.sub(v2)`, or an array
    * of numbers, as in `v.sub([1, 2, 3])`.
    *
-   * If a value isn't provided for a component, it won't change. For
-   * example, `v.sub(4, 5)` subtracts 4 from `v.x`, 5 from `v.y`, and 0 from `v.z`.
    * Calling `sub()` with no arguments, as in `v.sub()`, has no effect.
    *
+   * Subtract vectors only when they are the same size: both 2D, or both 3D.
+   * When two vectors of different sizes are used, the smaller dimension will be
+   * used, any additional values of the longer vector will be ignored.
+   * For example, subtracting `[1, 2]` from `[3, 5, 7]` will result in `[2, 3]`.
+   *
    * The static version of `sub()`, as in `p5.Vector.sub(v2, v1)`, returns a new
    * <a href="#/p5.Vector">p5.Vector</a> object and doesn't change the
    * originals.
@@ -788,19 +759,13 @@ class Vector {
    * @chainable
    */
   sub(...args) {
-    if (args[0] instanceof Vector) {
-      args[0].values.forEach((value, index) => {
-        this._values[index] -= value || 0;
-      });
-    } else if (Array.isArray(args[0])) {
-      args[0].forEach((value, index) => {
-        this._values[index] -= value || 0;
-      });
-    } else {
-      args.forEach((value, index) => {
-        this._values[index] -= value || 0;
-      });
-    }
+    const minDimension = prioritizeSmallerDimension(this.dimensions, args);
+
+    this.values = this.values.reduce((acc, v, i) => {
+      if(i < minDimension) acc[i] = this.values[i] - args[i];
+      return acc;
+    }, new Array(minDimension));
+
     return this;
   }
 
@@ -812,11 +777,14 @@ class Vector {
    * of numbers, as in `v.mult([1, 2, 3])`.
    *
    * If only one value is provided, as in `v.mult(2)`, then all the components
-   * will be multiplied by 2. If a value isn't provided for a component, it
-   * won't change. For example, `v.mult(4, 5)` multiplies `v.x` by, `v.y` by 5,
-   * and `v.z` by 1. Calling `mult()` with no arguments, as in `v.mult()`, has
+   * will be multiplied by 2. Calling `mult()` with no arguments, as in `v.mult()`, has
    * no effect.
    *
+   * Multiply vectors only when they are the same size: both 2D, or both 3D.
+   * When two vectors of different sizes are multiplied, the smaller dimension will be
+   * used, any additional values of the longer vector will be ignored.
+   * For example, multiplying `[1, 2, 3]` by `[4, 5]` will result in `[4, 10]`.
+   *
    * The static version of `mult()`, as in `p5.Vector.mult(v, 2)`, returns a new
    * <a href="#/p5.Vector">p5.Vector</a> object and doesn't change the
    * originals.
@@ -979,43 +947,51 @@ class Vector {
    * @chainable
    */
   mult(...args) {
-    if (args.length === 1 && args[0] instanceof Vector) {
-      const v = args[0];
-      const maxLen = Math.min(this._values.length, v.values.length);
-      for (let i = 0; i < maxLen; i++) {
-        if (Number.isFinite(v.values[i]) && typeof v.values[i] === 'number') {
-          this._values[i] *= v.values[i];
-        } else {
-          console.warn(
-            'p5.Vector.prototype.mult:',
-            'v contains components that are either undefined or not finite numbers'
-          );
-          return this;
-        }
-      }
-    } else if (args.length === 1 && Array.isArray(args[0])) {
-      const arr = args[0];
-      const maxLen = Math.min(this._values.length, arr.length);
-      for (let i = 0; i < maxLen; i++) {
-        if (Number.isFinite(arr[i]) && typeof arr[i] === 'number') {
-          this._values[i] *= arr[i];
-        } else {
-          console.warn(
-            'p5.Vector.prototype.mult:',
-            'arr contains elements that are either undefined or not finite numbers'
-          );
-          return this;
-        }
-      }
-    } else if (
-      args.length === 1 &&
-      typeof args[0] === 'number' &&
-      Number.isFinite(args[0])
-    ) {
-      for (let i = 0; i < this._values.length; i++) {
-        this._values[i] *= args[0];
-      }
-    }
+    const minDimension = prioritizeSmallerDimension(this.dimensions, args);
+
+    this.values = this.values.reduce((acc, v, i) => {
+      if(i < minDimension) acc[i] = this.values[i] * args[i];
+      return acc;
+    }, new Array(minDimension));
+
+    // if (args.length === 1 && args[0] instanceof Vector) {
+    //   const v = args[0];
+    //   const maxLen = Math.min(this.values.length, v.values.length);
+    //   for (let i = 0; i < maxLen; i++) {
+    //     if (Number.isFinite(v.values[i]) && typeof v.values[i] === 'number') {
+    //       if(!this.values[i]) this.values[i] = 0;
+    //       this.values[i] *= v.values[i];
+    //     } else {
+    //       console.warn(
+    //         'p5.Vector.prototype.mult:',
+    //         'v contains components that are either undefined or not finite numbers'
+    //       );
+    //       return this;
+    //     }
+    //   }
+    // } else if (args.length === 1 && Array.isArray(args[0])) {
+    //   const arr = args[0];
+    //   const maxLen = Math.min(this.values.length, arr.length);
+    //   for (let i = 0; i < maxLen; i++) {
+    //     if (Number.isFinite(arr[i]) && typeof arr[i] === 'number') {
+    //       this.values[i] *= arr[i];
+    //     } else {
+    //       console.warn(
+    //         'p5.Vector.prototype.mult:',
+    //         'arr contains elements that are either undefined or not finite numbers'
+    //       );
+    //       return this;
+    //     }
+    //   }
+    // } else if (
+    //   args.length === 1 &&
+    //   typeof args[0] === 'number' &&
+    //   Number.isFinite(args[0])
+    // ) {
+    //   for (let i = 0; i < this.values.length; i++) {
+    //     this.values[i] *= args[0];
+    //   }
+    // }
     return this;
   }
 
@@ -1027,11 +1003,14 @@ class Vector {
    * of numbers, as in `v.div([1, 2, 3])`.
    *
    * If only one value is provided, as in `v.div(2)`, then all the components
-   * will be divided by 2. If a value isn't provided for a component, it
-   * won't change. For example, `v.div(4, 5)` divides `v.x` by, `v.y` by 5,
-   * and `v.z` by 1. Calling `div()` with no arguments, as in `v.div()`, has
+   * will be divided by 2. Calling `div()` with no arguments, as in `v.div()`, has
    * no effect.
    *
+   * Divide vectors only when they are the same size: both 2D, or both 3D.
+   * When two vectors of different sizes are divided, the smaller dimension will be
+   * used, any additional values of the longer vector will be ignored.
+   * For example, dividing `[8, 12, 21]` by `[2, 3]` will result in `[4, 4]`.
+   *
    * The static version of `div()`, as in `p5.Vector.div(v, 2)`, returns a new
    * <a href="#/p5.Vector">p5.Vector</a> object and doesn't change the
    * originals.
@@ -1195,57 +1174,19 @@ class Vector {
    * @chainable
    */
   div(...args) {
-    if (args.length === 0) return this;
-    if (args.length === 1 && args[0] instanceof Vector) {
-      const v = args[0];
-      if (
-        v._values.every(
-          val => Number.isFinite(val) && typeof val === 'number'
-        )
-      ) {
-        if (v._values.some(val => val === 0)) {
-          console.warn('p5.Vector.prototype.div:', 'divide by 0');
-          return this;
-        }
-        this._values = this._values.map((val, i) => val / v._values[i]);
-      } else {
-        console.warn(
-          'p5.Vector.prototype.div:',
-          'vector contains components that are either undefined or not finite numbers'
-        );
-      }
-      return this;
-    }
-
-    if (args.length === 1 && Array.isArray(args[0])) {
-      const arr = args[0];
-      if (arr.every(val => Number.isFinite(val) && typeof val === 'number')) {
-        if (arr.some(val => val === 0)) {
-          console.warn('p5.Vector.prototype.div:', 'divide by 0');
-          return this;
-        }
-        this._values = this._values.map((val, i) => val / arr[i]);
-      } else {
-        console.warn(
-          'p5.Vector.prototype.div:',
-          'array contains components that are either undefined or not finite numbers'
-        );
-      }
-      return this;
-    }
+    const minDimension = prioritizeSmallerDimension(this.dimensions, args);
 
-    if (args.every(val => Number.isFinite(val) && typeof val === 'number')) {
-      if (args.some(val => val === 0)) {
-        console.warn('p5.Vector.prototype.div:', 'divide by 0');
-        return this;
-      }
-      this._values = this._values.map((val, i) => val / args[0]);
-    } else {
+    if(!args.every(v => typeof v === 'number' && v !== 0)){
       console.warn(
-        'p5.Vector.prototype.div:',
-        'arguments contain components that are either undefined or not finite numbers'
+        'p5.Vector.prototype.div',
+        'Arguments contain components that are 0'
       );
+      return this;
     }
+    this.values = this.values.reduce((acc, v, i) => {
+      if(i < minDimension) acc[i] = this.values[i] / args[i];
+      return acc;
+    }, new Array(minDimension));
 
     return this;
   }
@@ -1298,7 +1239,8 @@ class Vector {
    *   // Create a p5.Vector object.
    *   let p = createVector(30, 40);
    *
-   *   // Draw a line from the origin.
+   *   // Draw a line from th
+   * e origin.
    *   line(0, 0, p.x, p.y);
    *
    *   // Style the text.
@@ -1313,7 +1255,7 @@ class Vector {
    * }
    */
   magSq() {
-    return this._values.reduce(
+    return this.values.reduce(
       (sum, component) => sum + component * component,
       0
     );
@@ -1417,9 +1359,9 @@ class Vector {
    */
   dot(...args) {
     if (args[0] instanceof Vector) {
-      return this.dot(...args[0]._values);
+      return this.dot(...args[0].values);
     }
-    return this._values.reduce((sum, component, index) => {
+    return this.values.reduce((sum, component, index) => {
       return sum + component * (args[index] || 0);
     }, 0);
   }
@@ -1430,6 +1372,9 @@ class Vector {
    * The cross product is a vector that points straight out of the plane created
    * by two vectors. The cross product's magnitude is the area of the parallelogram
    * formed by the original two vectors.
+   * 
+   * The cross product is defined on 3-dimensional vectors, and will use the `x`, `y`,
+   * and `z` components. This method should only be used with 3D vectors.
    *
    * The static version of `cross()`, as in `p5.Vector.cross(v1, v2)`, is the same
    * as calling `v1.cross(v2)`.
@@ -2038,8 +1983,18 @@ class Vector {
    * }
    */
   setHeading(a) {
-    if (this.isPInst) a = this._toRadians(a);
-    let m = this.mag();
+    if (this.dimensions < 2 || (
+      this._values instanceof Array && this._values.slice(2).some(v => v !== 0))
+    ) {
+      p5._friendlyError(  
+        'p5.Vector.setHeading() only supports 2D vectors (z === 0). ' +
+        'For 3D or higher-dimensional vectors, use rotate() or another ' +
+        'appropriate method instead.',
+        'p5.Vector.setHeading'
+      );
+      return this;
+    }
+    const m = this.mag();
     this.x = m * Math.cos(a);
     this.y = m * Math.sin(a);
     return this;
@@ -2738,6 +2693,7 @@ class Vector {
    * Returns the vector's components as an array of numbers.
    *
    * @return {Number[]} array with the vector's components.
+   * @deprecated To retrieve vector components, use `v.values`
    * @example
    * // META:norender
    * function setup() {
@@ -2824,15 +2780,15 @@ class Vector {
   equals(...args) {
     let values;
     if (args[0] instanceof Vector) {
-      values = args[0]._values;
+      values = args[0].values;
     } else if (Array.isArray(args[0])) {
       values = args[0];
     } else {
       values = args;
     }
 
-    for (let i = 0; i < this._values.length; i++) {
-      if (this._values[i] !== (values[i] || 0)) {
+    for (let i = 0; i < this.values.length; i++) {
+      if (this.values[i] !== (values[i] || 0)) {
         return false;
       }
     }
@@ -2852,8 +2808,8 @@ class Vector {
    * @chainable
    */
   clampToZero() {
-    for (let i = 0; i < this._values.length; i++) {
-      this._values[i] = this._clampToZero(this._values[i]);
+    for (let i = 0; i < this.values.length; i++) {
+      this.values[i] = this._clampToZero(this.values[i]);
     }
     return this;
   }
@@ -3110,7 +3066,7 @@ class Vector {
     if (!target) {
       target = v1.copy();
       if (arguments.length === 3) {
-        p5._friendlyError(
+        this._friendlyError(
           'The target parameter is undefined, it should be of type p5.Vector',
           'p5.Vector.add'
         );
@@ -3157,7 +3113,7 @@ class Vector {
     if (!target) {
       target = v1.copy();
       if (arguments.length === 3) {
-        p5._friendlyError(
+        this._friendlyError(
           'The target parameter is undefined, it should be of type p5.Vector',
           'p5.Vector.sub'
         );
@@ -3201,7 +3157,7 @@ class Vector {
     if (!target) {
       target = v.copy();
       if (arguments.length === 3) {
-        p5._friendlyError(
+        this._friendlyError(
           'The target parameter is undefined, it should be of type p5.Vector',
           'p5.Vector.mult'
         );
@@ -3227,7 +3183,7 @@ class Vector {
       target = v.copy();
     } else {
       if (!(target instanceof Vector)) {
-        p5._friendlyError(
+        this._friendlyError(
           'The target parameter should be of type p5.Vector',
           'p5.Vector.rotate'
         );
@@ -3271,7 +3227,7 @@ class Vector {
       target = v.copy();
 
       if (arguments.length === 3) {
-        p5._friendlyError(
+        this._friendlyError(
           'The target parameter is undefined, it should be of type p5.Vector',
           'p5.Vector.div'
         );
@@ -3339,7 +3295,7 @@ class Vector {
     if (!target) {
       target = v1.copy();
       if (arguments.length === 4) {
-        p5._friendlyError(
+        this._friendlyError(
           'The target parameter is undefined, it should be of type p5.Vector',
           'p5.Vector.lerp'
         );
@@ -3369,7 +3325,7 @@ class Vector {
     if (!target) {
       target = v1.copy();
       if (arguments.length === 4) {
-        p5._friendlyError(
+        this._friendlyError(
           'The target parameter is undefined, it should be of type p5.Vector',
           'p5.Vector.slerp'
         );
@@ -3423,7 +3379,7 @@ class Vector {
       target = v.copy();
     } else {
       if (!(target instanceof Vector)) {
-        p5._friendlyError(
+        this._friendlyError(
           'The target parameter should be of type p5.Vector',
           'p5.Vector.normalize'
         );
@@ -3449,7 +3405,7 @@ class Vector {
       target = v.copy();
     } else {
       if (!(target instanceof Vector)) {
-        p5._friendlyError(
+        this._friendlyError(
           'The target parameter should be of type p5.Vector',
           'p5.Vector.limit'
         );
@@ -3475,7 +3431,7 @@ class Vector {
       target = v.copy();
     } else {
       if (!(target instanceof Vector)) {
-        p5._friendlyError(
+        this._friendlyError(
           'The target parameter should be of type p5.Vector',
           'p5.Vector.setMag'
         );
@@ -3531,7 +3487,7 @@ class Vector {
       target = incidentVector.copy();
     } else {
       if (!(target instanceof Vector)) {
-        p5._friendlyError(
+        this._friendlyError(
           'The target parameter should be of type p5.Vector',
           'p5.Vector.reflect'
         );
@@ -3572,7 +3528,7 @@ class Vector {
     } else if (v1 instanceof Array) {
       v = new Vector().set(v1);
     } else {
-      p5._friendlyError(
+      this._friendlyError(
         'The v1 parameter should be of type Array or p5.Vector',
         'p5.Vector.equals'
       );
@@ -3660,6 +3616,8 @@ function vector(p5, fn) {
    */
   p5.Vector = Vector;
 
+  Vector.prototype._friendlyError = p5._friendlyError;
+
   /**
    * The x component of the vector
    * @type {Number}