@vpmedia/phaser 1.94.0 → 1.96.0

package/src/phaser/geom/point.js

@@ -3,38 +3,41 @@ import { clone, distance, rotate } from './util/point.js';
 
 export class Point {
   /**
-   * TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
+   * Creates a new Point instance.
+   * @param {number} x - The x coordinate of the point (default: 0).
+   * @param {number} y - The y coordinate of the point (default: 0).
    */
   constructor(x = 0, y = 0) {
+    /** @type {number} */
     this.x = x;
+    /** @type {number} */
     this.y = y;
+    /** @type {number} */
     this.type = GEOM_POINT;
   }
 
   /**
-   * TBD.
-   * @param {Point} source - TBD.
-   * @returns {Point} TBD.
+   * Copies the coordinates from another point to this point.
+   * @param {Point} source - The point to copy coordinates from.
+   * @returns {Point} This point instance for chaining.
    */
   copyFrom(source) {
     return this.setTo(source.x, source.y);
   }
 
   /**
-   * TBD.
-   * @returns {Point} TBD.
+   * Returns a new point with the x and y coordinates swapped.
+   * @returns {Point} A new point instance with swapped coordinates.
    */
   invert() {
     return this.setTo(this.y, this.x);
   }
 
   /**
-   * TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @returns {Point} TBD.
+   * Sets the coordinates of this point to new values.
+   * @param {number} x - The new x coordinate for the point.
+   * @param {number} y - The new y coordinate for the point.
+   * @returns {Point} This point instance for chaining.
    */
   setTo(x, y) {
     this.x = x || 0;
@@ -43,11 +46,11 @@ export class Point {
   }
 
   /**
-   * TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @returns {Point} TBD.
-   * @deprecated
+   * Sets the coordinates of this point to new values.
+   * @param {number} x - The new x coordinate for the point.
+   * @param {number} y - The new y coordinate for the point.
+   * @returns {Point} This point instance for chaining.
+   * @deprecated Use setTo instead.
    */
   set(x, y) {
     this.x = x || 0;
@@ -56,10 +59,10 @@ export class Point {
   }
 
   /**
-   * TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @returns {Point} TBD.
+   * Adds the given x and y values to the point's coordinates.
+   * @param {number} x - The amount to add to the x coordinate.
+   * @param {number} y - The amount to add to the y coordinate.
+   * @returns {Point} This point instance for chaining.
    */
   add(x, y) {
     this.x += x;
@@ -68,10 +71,10 @@ export class Point {
   }
 
   /**
-   * TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @returns {Point} TBD.
+   * Subtracts the given x and y values from the point's coordinates.
+   * @param {number} x - The amount to subtract from the x coordinate.
+   * @param {number} y - The amount to subtract from the y coordinate.
+   * @returns {Point} This point instance for chaining.
    */
   subtract(x, y) {
     this.x -= x;
@@ -80,10 +83,10 @@ export class Point {
   }
 
   /**
-   * TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @returns {Point} TBD.
+   * Multiplies the point's coordinates by the given x and y values.
+   * @param {number} x - The amount to multiply the x coordinate by.
+   * @param {number} y - The amount to multiply the y coordinate by.
+   * @returns {Point} This point instance for chaining.
    */
   multiply(x, y) {
     this.x *= x;
@@ -92,10 +95,10 @@ export class Point {
   }
 
   /**
-   * TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @returns {Point} TBD.
+   * Divides the point's coordinates by the given x and y values.
+   * @param {number} x - The amount to divide the x coordinate by.
+   * @param {number} y - The amount to divide the y coordinate by.
+   * @returns {Point} This point instance for chaining.
    */
   divide(x, y) {
     this.x /= x;
@@ -104,10 +107,10 @@ export class Point {
   }
 
   /**
-   * TBD.
-   * @param {number} min - TBD.
-   * @param {number} max - TBD.
-   * @returns {Point} TBD.
+   * Constrains the x coordinate of this point to the given range.
+   * @param {number} min - The minimum value for the x coordinate.
+   * @param {number} max - The maximum value for the x coordinate.
+   * @returns {Point} This point instance for chaining.
    */
   clampX(min, max) {
     this.x = Math.max(min, Math.min(max, this.x));
@@ -115,10 +118,10 @@ export class Point {
   }
 
   /**
-   * TBD.
-   * @param {number} min - TBD.
-   * @param {number} max - TBD.
-   * @returns {Point} TBD.
+   * Constrains the y coordinate of this point to the given range.
+   * @param {number} min - The minimum value for the y coordinate.
+   * @param {number} max - The maximum value for the y coordinate.
+   * @returns {Point} This point instance for chaining.
    */
   clampY(min, max) {
     this.y = Math.max(min, Math.min(max, this.y));
@@ -126,10 +129,10 @@ export class Point {
   }
 
   /**
-   * TBD.
-   * @param {number} min - TBD.
-   * @param {number} max - TBD.
-   * @returns {Point} TBD.
+   * Constrains both coordinates of this point to the given range.
+   * @param {number} min - The minimum value for both coordinates.
+   * @param {number} max - The maximum value for both coordinates.
+   * @returns {Point} This point instance for chaining.
    */
   clamp(min, max) {
     this.x = Math.max(min, Math.min(max, this.x));
@@ -138,17 +141,17 @@ export class Point {
   }
 
   /**
-   * TBD.
-   * @returns {Point} TBD.
+   * Creates a clone of this point.
+   * @returns {Point} A new point with the same coordinates as this one.
    */
   clone() {
     return clone(this);
   }
 
   /**
-   * TBD.
-   * @param {Point} dest - TBD.
-   * @returns {Point} TBD.
+   * Copies the coordinates of this point to another point.
+   * @param {Point} dest - The point to copy coordinates to.
+   * @returns {Point} The destination point.
    */
   copyTo(dest) {
     dest.x = this.x;
@@ -157,28 +160,28 @@ export class Point {
   }
 
   /**
-   * TBD.
-   * @param {Point} b - TBD.
-   * @returns {number} TBD.
+   * Calculates the distance between this point and another point.
+   * @param {Point} b - The other point to calculate the distance to.
+   * @returns {number} The distance between the two points.
    */
   distance(b) {
     return distance(this, b);
   }
 
   /**
-   * TBD.
-   * @param {Point} a - TBD.
-   * @returns {boolean} TBD.
+   * Checks if this point is equal to another point.
+   * @param {Point} a - The other point to compare with.
+   * @returns {boolean} True if the points have the same coordinates, false otherwise.
    */
   equals(a) {
     return a.x === this.x && a.y === this.y;
   }
 
   /**
-   * TBD.
-   * @param {Point} a - TBD.
-   * @param {boolean} asDegrees - TBD.
-   * @returns {number} TBD.
+   * Calculates the angle between this point and another point.
+   * @param {Point} a - The other point to calculate the angle to.
+   * @param {boolean} asDegrees - Whether to return the result in degrees (default: false).
+   * @returns {number} The angle between the two points in radians or degrees.
    */
   angle(a, asDegrees = false) {
     if (asDegrees) {
@@ -188,46 +191,46 @@ export class Point {
   }
 
   /**
-   * TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @param {number} angle - TBD.
-   * @param {boolean} asDegrees - TBD.
-   * @param {number | null | undefined} dist - TBD.
-   * @returns {Point} TBD.
+   * Rotates this point around another point by a given angle.
+   * @param {number} x - The x coordinate of the center point to rotate around.
+   * @param {number} y - The y coordinate of the center point to rotate around.
+   * @param {number} angle - The angle in radians to rotate by.
+   * @param {boolean} asDegrees - Whether the angle is provided in degrees (default: false).
+   * @param {number | null | undefined} dist - The distance to rotate from (default: null).
+   * @returns {Point} This point instance for chaining.
    */
   rotate(x, y, angle, asDegrees, dist = null) {
     return rotate(this, x, y, angle, asDegrees, dist);
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Calculates the magnitude (length) of this point from the origin.
+   * @returns {number} The magnitude of the point.
    */
   getMagnitude() {
     return Math.sqrt(this.x * this.x + this.y * this.y);
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Calculates the square of the magnitude (length) of this point from the origin.
+   * @returns {number} The square of the magnitude of the point.
    */
   getMagnitudeSq() {
     return this.x * this.x + this.y * this.y;
   }
 
   /**
-   * TBD.
-   * @param {number} magnitude - TBD.
-   * @returns {Point} TBD.
+   * Sets the magnitude (length) of this point while preserving its direction.
+   * @param {number} magnitude - The new magnitude for the point.
+   * @returns {Point} This point instance for chaining.
    */
   setMagnitude(magnitude) {
     return this.normalize().multiply(magnitude, magnitude);
   }
 
   /**
-   * TBD.
-   * @returns {Point} TBD.
+   * Normalizes this point to have a magnitude of 1 while preserving its direction.
+   * @returns {Point} This point instance for chaining.
    */
   normalize() {
     if (!this.isZero()) {
@@ -239,74 +242,74 @@ export class Point {
   }
 
   /**
-   * TBD.
-   * @returns {boolean} TBD.
+   * Checks if this point has zero magnitude (is at the origin).
+   * @returns {boolean} True if both x and y coordinates are zero, false otherwise.
    */
   isZero() {
     return this.x === 0 && this.y === 0;
   }
 
   /**
-   * TBD.
-   * @param {Point} a - TBD.
-   * @returns {number} TBD.
+   * Calculates the dot product of this point and another point.
+   * @param {Point} a - The other point to calculate the dot product with.
+   * @returns {number} The dot product of the two points.
    */
   dot(a) {
     return this.x * a.x + this.y * a.y;
   }
 
   /**
-   * TBD.
-   * @param {Point} a - TBD.
-   * @returns {number} TBD.
+   * Calculates the cross product of this point and another point.
+   * @param {Point} a - The other point to calculate the cross product with.
+   * @returns {number} The cross product of the two points.
    */
   cross(a) {
     return this.x * a.y - this.y * a.x;
   }
 
   /**
-   * TBD.
-   * @returns {Point} TBD.
+   * Returns a perpendicular point (rotated 90 degrees counter-clockwise).
+   * @returns {Point} A new point that is perpendicular to this one.
    */
   perp() {
     return this.setTo(-this.y, this.x);
   }
 
   /**
-   * TBD.
-   * @returns {Point} TBD.
+   * Returns a perpendicular point (rotated 90 degrees clockwise).
+   * @returns {Point} A new point that is perpendicular to this one (rotated clockwise).
    */
   rperp() {
     return this.setTo(this.y, -this.x);
   }
 
   /**
-   * TBD.
-   * @returns {Point} TBD.
+   * Returns a point with the same direction as this one but with y coordinate negated.
+   * @returns {Point} A new point with the same x coordinate but negated y coordinate.
    */
   normalRightHand() {
     return this.setTo(this.y * -1, this.x);
   }
 
   /**
-   * TBD.
-   * @returns {Point} TBD.
+   * Returns a new point with the x and y coordinates rounded down to the nearest integer.
+   * @returns {Point} A new point with floored coordinates.
    */
   floor() {
     return this.setTo(Math.floor(this.x), Math.floor(this.y));
   }
 
   /**
-   * TBD.
-   * @returns {Point} TBD.
+   * Returns a new point with the x and y coordinates rounded up to the nearest integer.
+   * @returns {Point} A new point with ceiled coordinates.
    */
   ceil() {
     return this.setTo(Math.ceil(this.x), Math.ceil(this.y));
   }
 
   /**
-   * TBD.
-   * @returns {string} TBD.
+   * Returns a string representation of this point.
+   * @returns {string} A string representation of the point in the format "[Point (x=value y=value)]".
    */
   toString() {
     return `[{Point (x=${this.x} y=${this.y})}]`;

package/src/phaser/geom/polygon.js

@@ -4,14 +4,19 @@ import { GEOM_POLYGON } from '../core/const.js';
 
 export class Polygon {
   /**
-   * TBD.
-   * @param {object[]} points - TBD.
+   * Creates a new Polygon instance.
+   * @param {object[]} points - The array of points to define the polygon (optional).
    */
   constructor(points = null) {
+    /** @type {number} */
     this.area = 0;
+    /** @type {Point[]} */
     this._points = [];
+    /** @type {boolean} */
     this.closed = true;
+    /** @type {boolean} */
     this.flattened = false;
+    /** @type {number} */
     this.type = GEOM_POLYGON;
     if (points) {
       this.setTo(points);
@@ -19,9 +24,9 @@ export class Polygon {
   }
 
   /**
-   * TBD.
-   * @param {number[]} output - TBD.
-   * @returns {number[]} TBD.
+   * Converts the polygon's points to a number array.
+   * @param {number[]} output - The array to store the result in (optional).
+   * @returns {number[]} An array of numbers representing the polygon's points.
    */
   toNumberArray(output = []) {
     for (let i = 0; i < this._points.length; i += 1) {
@@ -38,8 +43,8 @@ export class Polygon {
   }
 
   /**
-   * TBD.
-   * @returns {Polygon} TBD.
+   * Flattens the polygon's point array to a simple numeric array.
+   * @returns {Polygon} This polygon instance for chaining.
    */
   flatten() {
     this._points = this.toNumberArray();
@@ -48,18 +53,18 @@ export class Polygon {
   }
 
   /**
-   * TBD.
-   * @returns {Polygon} TBD.
+   * Creates a clone of this polygon.
+   * @returns {Polygon} A new polygon with the same values as this one.
    */
   clone() {
     return clone(this);
   }
 
   /**
-   * TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @returns {boolean} TBD.
+   * Checks if the specified point is contained within this polygon.
+   * @param {number} x - The x coordinate of the point to check.
+   * @param {number} y - The y coordinate of the point to check.
+   * @returns {boolean} True if the point is contained within this polygon, false otherwise.
    */
   contains(x, y) {
     //  Adapted from http://www.ecse.rpi.edu/Homepages/wrf/Research/Short_Notes/pnpoly.html by Jonas Raoni Soares Silva
@@ -89,9 +94,9 @@ export class Polygon {
   }
 
   /**
-   * TBD.
-   * @param {object[]} points - TBD.
-   * @returns {Polygon} TBD.
+   * Sets the polygon's points to new values.
+   * @param {object[]} points - The array of points to define the polygon.
+   * @returns {Polygon} This polygon instance for chaining.
    */
   setTo(points) {
     this.area = 0;
@@ -128,9 +133,9 @@ export class Polygon {
   }
 
   /**
-   * TBD.
-   * @param {number} y0 - TBD.
-   * @returns {number} TBD.
+   * Calculates the area of this polygon.
+   * @param {number} y0 - The y coordinate of the lowest boundary (internal use).
+   * @returns {number} The area of this polygon.
    */
   calculateArea(y0) {
     let p1;
@@ -152,15 +157,15 @@ export class Polygon {
   }
 
   /**
-   * TBD.
-   * @returns {object[]} TBD.
+   * Gets the points of this polygon.
+   * @returns {object[]} The array of points that define this polygon.
    */
   get points() {
     return this._points;
   }
 
   /**
-   * TBD.
+   * Sets the points of this polygon.
    */
   set points(value) {
     if (value !== null) {