@vpmedia/phaser 1.94.0 → 1.96.0

package/src/phaser/geom/line.js

@@ -5,25 +5,28 @@ import { GEOM_LINE } from '../core/const.js';
 
 export class Line {
   /**
-   * TBD.
-   * @param {number} x1 - TBD.
-   * @param {number} y1 - TBD.
-   * @param {number} x2 - TBD.
-   * @param {number} y2 - TBD.
+   * Creates a new Line instance.
+   * @param {number} x1 - The x coordinate of the start point (default: 0).
+   * @param {number} y1 - The y coordinate of the start point (default: 0).
+   * @param {number} x2 - The x coordinate of the end point (default: 0).
+   * @param {number} y2 - The y coordinate of the end point (default: 0).
    */
   constructor(x1 = 0, y1 = 0, x2 = 0, y2 = 0) {
+    /** @type {Point} */
     this.start = new Point(x1, y1);
+    /** @type {Point} */
     this.end = new Point(x2, y2);
+    /** @type {number} */
     this.type = GEOM_LINE;
   }
 
   /**
-   * TBD.
-   * @param {number} x1 - TBD.
-   * @param {number} y1 - TBD.
-   * @param {number} x2 - TBD.
-   * @param {number} y2 - TBD.
-   * @returns {Line} TBD.
+   * Sets the coordinates of this line to new values.
+   * @param {number} x1 - The new x coordinate of the start point.
+   * @param {number} y1 - The new y coordinate of the start point.
+   * @param {number} x2 - The new x coordinate of the end point.
+   * @param {number} y2 - The new y coordinate of the end point.
+   * @returns {Line} This line instance for chaining.
    */
   setTo(x1, y1, x2, y2) {
     this.start.setTo(x1, y1);
@@ -32,11 +35,11 @@ export class Line {
   }
 
   /**
-   * TBD.
-   * @param {object} startSprite - TBD.
-   * @param {object} endSprite - TBD.
-   * @param {boolean} useCenter - TBD.
-   * @returns {Line} TBD.
+   * Sets the coordinates of this line to match the positions of two sprites.
+   * @param {object} startSprite - The starting sprite to get the position from.
+   * @param {object} endSprite - The ending sprite to get the position from.
+   * @param {boolean} useCenter - Whether to use the center of the sprites (default: false).
+   * @returns {Line} This line instance for chaining.
    */
   fromSprite(startSprite, endSprite, useCenter = false) {
     if (useCenter) {
@@ -46,12 +49,12 @@ export class Line {
   }
 
   /**
-   * TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @param {number} angle - TBD.
-   * @param {number} length - TBD.
-   * @returns {Line} TBD.
+   * Sets the coordinates of this line to a point at a specific angle and distance.
+   * @param {number} x - The x coordinate of the starting point.
+   * @param {number} y - The y coordinate of the starting point.
+   * @param {number} angle - The angle in radians to set the line at.
+   * @param {number} length - The length of the line.
+   * @returns {Line} This line instance for chaining.
    */
   fromAngle(x, y, angle, length) {
     this.start.setTo(x, y);
@@ -60,10 +63,10 @@ export class Line {
   }
 
   /**
-   * TBD.
-   * @param {number} angle - TBD.
-   * @param {boolean} asDegrees - TBD.
-   * @returns {Line} TBD.
+   * Rotates this line around its center point by the specified angle.
+   * @param {number} angle - The angle in radians (or degrees if asDegrees is true) to rotate by.
+   * @param {boolean} asDegrees - Whether the angle is provided in degrees (default: false).
+   * @returns {Line} This line instance for chaining.
    */
   rotate(angle, asDegrees = false) {
     const cx = (this.start.x + this.end.x) / 2;
@@ -74,12 +77,12 @@ export class Line {
   }
 
   /**
-   * TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @param {number} angle - TBD.
-   * @param {boolean} asDegrees - TBD.
-   * @returns {Line} TBD.
+   * Rotates this line around a specific point by the specified 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 (or degrees if asDegrees is true) to rotate by.
+   * @param {boolean} asDegrees - Whether the angle is provided in degrees (default: false).
+   * @returns {Line} This line instance for chaining.
    */
   rotateAround(x, y, angle, asDegrees = false) {
     this.start.rotate(x, y, angle, asDegrees);
@@ -88,29 +91,29 @@ export class Line {
   }
 
   /**
-   * TBD.
-   * @param {Line} line - TBD.
-   * @param {boolean} asSegment - TBD.
-   * @param {Point} result - TBD.
-   * @returns {Point} TBD.
+   * Checks if this line intersects with another line.
+   * @param {Line} line - The other line to check for intersection with.
+   * @param {boolean} asSegment - Whether to treat the lines as segments (default: false).
+   * @param {Point} result - The point to store the intersection in (optional).
+   * @returns {Point} The intersection point, or null if no intersection occurs.
    */
   intersects(line, asSegment, result) {
     return intersectsPoints(this.start, this.end, line.start, line.end, asSegment, result);
   }
 
   /**
-   * TBD.
-   * @param {Line} line - TBD.
-   * @returns {number} TBD.
+   * Calculates the reflection of this line off another line.
+   * @param {Line} line - The line to reflect off.
+   * @returns {number} The angle of reflection in radians.
    */
   reflect(line) {
     return reflect(this, line);
   }
 
   /**
-   * TBD.
-   * @param {Point} output - TBD.
-   * @returns {Point} TBD.
+   * Returns the midpoint of this line.
+   * @param {Point} output - The point to store the result in (optional).
+   * @returns {Point} The midpoint of this line.
    */
   midPoint(output = null) {
     const result = output || new Point();
@@ -120,9 +123,9 @@ export class Line {
   }
 
   /**
-   * TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
+   * Centers this line on the specified point.
+   * @param {number} x - The x coordinate to center the line on.
+   * @param {number} y - The y coordinate to center the line on.
    */
   centerOn(x, y) {
     const cx = (this.start.x + this.end.x) / 2;
@@ -134,20 +137,20 @@ export class Line {
   }
 
   /**
-   * TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @returns {boolean} TBD.
+   * Checks if the specified point lies on this line (not necessarily on the segment).
+   * @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 lies on this line, false otherwise.
    */
   pointOnLine(x, y) {
     return (x - this.start.x) * (this.end.y - this.start.y) === (this.end.x - this.start.x) * (y - this.start.y);
   }
 
   /**
-   * TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @returns {boolean} TBD.
+   * Checks if the specified point lies on this line segment.
+   * @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 lies on this line segment, false otherwise.
    */
   pointOnSegment(x, y) {
     const xMin = Math.min(this.start.x, this.end.x);
@@ -158,9 +161,9 @@ export class Line {
   }
 
   /**
-   * TBD.
-   * @param {Point} output - TBD.
-   * @returns {Point} TBD.
+   * Returns a random point on this line.
+   * @param {Point} output - The point to store the result in (optional).
+   * @returns {Point} A random point on this line.
    */
   random(output = null) {
     const result = output || new Point();
@@ -171,10 +174,10 @@ export class Line {
   }
 
   /**
-   * TBD.
-   * @param {number} stepRate - TBD.
-   * @param {number[][]} results - TBD.
-   * @returns {number[][]} TBD.
+   * Gets coordinates of points along this line at regular intervals.
+   * @param {number} stepRate - The interval between points (default: 1).
+   * @param {number[][]} results - The array to store the results in (optional).
+   * @returns {number[][]} An array of coordinate pairs representing points along this line.
    */
   coordinatesOnLine(stepRate = 1, results = []) {
     let x1 = Math.round(this.start.x);
@@ -207,16 +210,16 @@ export class Line {
   }
 
   /**
-   * TBD.
-   * @returns {Line} TBD.
+   * Creates a clone of this line.
+   * @returns {Line} A new line with the same values as this one.
    */
   clone() {
     return clone(this);
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the length of this line.
+   * @returns {number} The length of this line.
    */
   get length() {
     return Math.sqrt(
@@ -226,112 +229,112 @@ export class Line {
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the angle of this line in radians.
+   * @returns {number} The angle of this line in radians.
    */
   get angle() {
     return Math.atan2(this.end.y - this.start.y, this.end.x - this.start.x);
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the slope of this line.
+   * @returns {number} The slope of this line.
    */
   get slope() {
     return (this.end.y - this.start.y) / (this.end.x - this.start.x);
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the perpendicular slope of this line.
+   * @returns {number} The perpendicular slope of this line.
    */
   get perpSlope() {
     return -((this.end.x - this.start.x) / (this.end.y - this.start.y));
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the x coordinate of the leftmost point on this line.
+   * @returns {number} The x coordinate of the leftmost point on this line.
    */
   get x() {
     return Math.min(this.start.x, this.end.x);
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the y coordinate of the topmost point on this line.
+   * @returns {number} The y coordinate of the topmost point on this line.
    */
   get y() {
     return Math.min(this.start.y, this.end.y);
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the x coordinate of the leftmost point on this line.
+   * @returns {number} The x coordinate of the leftmost point on this line.
    */
   get left() {
     return Math.min(this.start.x, this.end.x);
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the x coordinate of the rightmost point on this line.
+   * @returns {number} The x coordinate of the rightmost point on this line.
    */
   get right() {
     return Math.max(this.start.x, this.end.x);
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the y coordinate of the topmost point on this line.
+   * @returns {number} The y coordinate of the topmost point on this line.
    */
   get top() {
     return Math.min(this.start.y, this.end.y);
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the y coordinate of the bottommost point on this line.
+   * @returns {number} The y coordinate of the bottommost point on this line.
    */
   get bottom() {
     return Math.max(this.start.y, this.end.y);
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the width of this line (absolute difference between x coordinates).
+   * @returns {number} The width of this line.
    */
   get width() {
     return Math.abs(this.start.x - this.end.x);
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the height of this line (absolute difference between y coordinates).
+   * @returns {number} The height of this line.
    */
   get height() {
     return Math.abs(this.start.y - this.end.y);
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the normal vector x component of this line (perpendicular to the line).
+   * @returns {number} The normal vector x component of this line.
    */
   get normalX() {
     return Math.cos(this.angle - 1.5707963267948966);
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the normal vector y component of this line (perpendicular to the line).
+   * @returns {number} The normal vector y component of this line.
    */
   get normalY() {
     return Math.sin(this.angle - 1.5707963267948966);
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the angle of the normal vector of this line in radians.
+   * @returns {number} The angle of the normal vector of this line in radians.
    */
   get normalAngle() {
     return wrap(this.angle - 1.5707963267948966, -Math.PI, Math.PI);

package/src/phaser/geom/matrix.js

@@ -4,42 +4,49 @@ import { GEOM_MATRIX } from '../core/const.js';
 
 export class Matrix {
   /**
-   * TBD.
-   * @param {number} a - TBD.
-   * @param {number} b - TBD.
-   * @param {number} c - TBD.
-   * @param {number} d - TBD.
-   * @param {number} tx - TBD.
-   * @param {number} ty - TBD.
+   * Creates a new Matrix instance.
+   * @param {number} a - The a component of the matrix (default: 1).
+   * @param {number} b - The b component of the matrix (default: 0).
+   * @param {number} c - The c component of the matrix (default: 0).
+   * @param {number} d - The d component of the matrix (default: 1).
+   * @param {number} tx - The tx component of the matrix (default: 0).
+   * @param {number} ty - The ty component of the matrix (default: 0).
    */
   constructor(a = 1, b = 0, c = 0, d = 1, tx = 0, ty = 0) {
+    /** @type {number} */
     this.a = a;
+    /** @type {number} */
     this.b = b;
+    /** @type {number} */
     this.c = c;
+    /** @type {number} */
     this.d = d;
+    /** @type {number} */
     this.tx = tx;
+    /** @type {number} */
     this.ty = ty;
+    /** @type {number} */
     this.type = GEOM_MATRIX;
   }
 
   /**
-   * TBD.
-   * @param {number[]} array - TBD.
-   * @returns {Matrix} TBD.
+   * Sets the matrix components from an array.
+   * @param {number[]} array - The array to read the matrix components from (should have 6 elements).
+   * @returns {Matrix} This matrix instance for chaining.
    */
   fromArray(array) {
     return this.setTo(array[0], array[1], array[3], array[4], array[2], array[5]);
   }
 
   /**
-   * TBD.
-   * @param {number} a - TBD.
-   * @param {number} b - TBD.
-   * @param {number} c - TBD.
-   * @param {number} d - TBD.
-   * @param {number} tx - TBD.
-   * @param {number} ty - TBD.
-   * @returns {Matrix} TBD.
+   * Sets the matrix components to new values.
+   * @param {number} a - The new a component of the matrix.
+   * @param {number} b - The new b component of the matrix.
+   * @param {number} c - The new c component of the matrix.
+   * @param {number} d - The new d component of the matrix.
+   * @param {number} tx - The new tx component of the matrix.
+   * @param {number} ty - The new ty component of the matrix.
+   * @returns {Matrix} This matrix instance for chaining.
    */
   setTo(a, b, c, d, tx, ty) {
     this.a = a;
@@ -52,17 +59,17 @@ export class Matrix {
   }
 
   /**
-   * TBD.
-   * @returns {Matrix} TBD.
+   * Creates a clone of this matrix.
+   * @returns {Matrix} A new matrix with the same values as this one.
    */
   clone() {
     return clone(this);
   }
 
   /**
-   * TBD.
-   * @param {Matrix} matrix - TBD.
-   * @returns {Matrix} TBD.
+   * Copies the values of this matrix to another matrix.
+   * @param {Matrix} matrix - The matrix to copy values to.
+   * @returns {Matrix} The destination matrix.
    */
   copyTo(matrix) {
     matrix.copyFrom(this);
@@ -70,9 +77,9 @@ export class Matrix {
   }
 
   /**
-   * TBD.
-   * @param {Matrix} matrix - TBD.
-   * @returns {Matrix} TBD.
+   * Copies the values from another matrix to this matrix.
+   * @param {Matrix} matrix - The matrix to copy values from.
+   * @returns {Matrix} This matrix instance for chaining.
    */
   copyFrom(matrix) {
     this.a = matrix.a;
@@ -85,10 +92,10 @@ export class Matrix {
   }
 
   /**
-   * TBD.
-   * @param {boolean} transpose - TBD.
-   * @param {Float32Array} output - TBD.
-   * @returns {Float32Array} TBD.
+   * Converts this matrix to a Float32Array.
+   * @param {boolean} transpose - Whether to transpose the matrix (default: false).
+   * @param {Float32Array} output - The array to store the result in (optional).
+   * @returns {Float32Array} A Float32Array containing the matrix elements.
    */
   toArray(transpose = false, output = null) {
     const result = output || new Float32Array(9);
@@ -117,10 +124,10 @@ export class Matrix {
   }
 
   /**
-   * TBD.
-   * @param {Point} pos - TBD.
-   * @param {Point} output - TBD.
-   * @returns {Point} TBD.
+   * Applies this matrix to a point.
+   * @param {Point} pos - The point to apply the matrix to.
+   * @param {Point} output - The point to store the result in (optional).
+   * @returns {Point} The transformed point.
    */
   apply(pos, output = null) {
     const result = output || new Point();
@@ -130,10 +137,10 @@ export class Matrix {
   }
 
   /**
-   * TBD.
-   * @param {Point} pos - TBD.
-   * @param {Point} output - TBD.
-   * @returns {Point} TBD.
+   * Applies the inverse of this matrix to a point.
+   * @param {Point} pos - The point to apply the inverse matrix to.
+   * @param {Point} output - The point to store the result in (optional).
+   * @returns {Point} The transformed point.
    */
   applyInverse(pos, output = null) {
     const result = output || new Point();
@@ -146,10 +153,10 @@ export class Matrix {
   }
 
   /**
-   * TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @returns {Matrix} TBD.
+   * Translates this matrix by the specified amounts.
+   * @param {number} x - The amount to translate in the x direction.
+   * @param {number} y - The amount to translate in the y direction.
+   * @returns {Matrix} This matrix instance for chaining.
    */
   translate(x, y) {
     this.tx += x;
@@ -158,10 +165,10 @@ export class Matrix {
   }
 
   /**
-   * TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @returns {Matrix} TBD.
+   * Scales this matrix by the specified amounts.
+   * @param {number} x - The amount to scale in the x direction.
+   * @param {number} y - The amount to scale in the y direction.
+   * @returns {Matrix} This matrix instance for chaining.
    */
   scale(x, y) {
     this.a *= x;
@@ -174,9 +181,9 @@ export class Matrix {
   }
 
   /**
-   * TBD.
-   * @param {number} angle - TBD.
-   * @returns {Matrix} TBD.
+   * Rotates this matrix by the specified angle.
+   * @param {number} angle - The angle in radians to rotate by.
+   * @returns {Matrix} This matrix instance for chaining.
    */
   rotate(angle) {
     const cos = Math.cos(angle);
@@ -194,9 +201,9 @@ export class Matrix {
   }
 
   /**
-   * TBD.
-   * @param {Matrix} matrix - TBD.
-   * @returns {Matrix} TBD.
+   * Appends another matrix to this matrix (multiplying matrices).
+   * @param {Matrix} matrix - The matrix to append.
+   * @returns {Matrix} This matrix instance for chaining.
    */
   append(matrix) {
     const a1 = this.a;
@@ -213,8 +220,8 @@ export class Matrix {
   }
 
   /**
-   * TBD.
-   * @returns {Matrix} TBD.
+   * Sets this matrix to an identity matrix (no transformation).
+   * @returns {Matrix} This matrix instance for chaining.
    */
   identity() {
     return this.setTo(1, 0, 0, 1, 0, 0);