fix: [#3165] Deprecate Vector.size in favor of Vector.magnitude

Closes: #3165

CHANGELOG.md

@@ -47,6 +47,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Deprecated
 
+- `Vector.size` is deprecated, use `Vector.magnitude` instead
 - `ScreenShader` v_texcoord is deprecated, use v_uv. This is changed to match the materials shader API
 - `actor.getGlobalPos()` - use `actor.globalPos` instead
 - `actor.getGlobalRotation()` - use `actor.globalRotation` instead

src/engine/Actions/Action/MoveBy.ts

@@ -39,7 +39,7 @@ export class MoveBy implements Action {
       this._started = true;
       this._start = new Vector(this._tx.pos.x, this._tx.pos.y);
       this._end = this._start.add(this._offset);
-      this._distance = this._offset.size;
+      this._distance = this._offset.magnitude;
       this._dir = this._end.sub(this._start).normalize();
     }
 

src/engine/Camera.ts

@@ -183,7 +183,7 @@ export class RadiusAroundActorStrategy implements CameraStrategy<Actor> {
     const focus = cam.getFocus();
 
     const direction = position.sub(focus);
-    const distance = direction.size;
+    const distance = direction.magnitude;
     if (distance >= this.radius) {
       const offset = distance - this.radius;
       return focus.add(direction.normalize().scale(offset));

src/engine/Collision/BodyComponent.ts

@@ -173,7 +173,7 @@ export class BodyComponent extends Component implements Clonable<BodyComponent>
     if (this._sleeping) {
       this.setSleeping(true);
     }
-    const currentMotion = this.vel.size * this.vel.size + Math.abs(this.angularVelocity * this.angularVelocity);
+    const currentMotion = this.vel.magnitude * this.vel.magnitude + Math.abs(this.angularVelocity * this.angularVelocity);
     const bias = this._bodyConfig.sleepBias;
     this.sleepMotion = bias * this.sleepMotion + (1 - bias) * currentMotion;
     this.sleepMotion = clamp(this.sleepMotion, 0, 10 * this._bodyConfig.sleepEpsilon);

src/engine/Collision/Colliders/CircleCollider.ts

@@ -126,7 +126,7 @@ export class CircleCollider extends Collider {
     const u1 = dir.scale(u.dot(dir));
     const u2 = u.sub(u1);
 
-    const d = u2.size;
+    const d = u2.magnitude;
 
     if (d > this.radius) {
       return null;

src/engine/Collision/Colliders/CollisionJumpTable.ts

@@ -61,7 +61,7 @@ export const CollisionJumpTable = {
 
     const info: SeparationInfo = {
       collider: circle,
-      separation: -minAxis.size,
+      separation: -minAxis.magnitude,
       axis: normal,
       point: point,
       localPoint: local,

src/engine/Collision/Detection/DynamicTreeCollisionProcessor.ts

@@ -217,8 +217,8 @@ export class DynamicTreeCollisionProcessor implements CollisionProcessor {
 
         // Maximum travel distance next frame
         const updateDistance =
-          body.vel.size * seconds + // velocity term
-          body.acc.size * 0.5 * seconds * seconds; // acc term
+          body.vel.magnitude * seconds + // velocity term
+          body.acc.magnitude * 0.5 * seconds * seconds; // acc term
 
         // Find the minimum dimension
         const minDimension = Math.min(collider.bounds.height, collider.bounds.width);
@@ -245,7 +245,7 @@ export class DynamicTreeCollisionProcessor implements CollisionProcessor {
               const hit = other.rayCast(ray, updateDistance + this._config.continuous.surfaceEpsilon * 10);
               if (hit) {
                 const translate = hit.point.sub(origin);
-                if (translate.size < minTranslate.size) {
+                if (translate.magnitude < minTranslate.magnitude) {
                   minTranslate = translate;
                   minCollider = other;
                 }

src/engine/Graphics/Context/rectangle-renderer/rectangle-renderer.ts

@@ -99,7 +99,7 @@ export class RectangleRenderer implements RendererPlugin {
     const snapToPixel = this._context.snapToPixel;
 
     const dir = end.sub(start);
-    const length = dir.size;
+    const length = dir.magnitude;
     const normal = dir.normalize().perpendicular();
     const halfThick = thickness / 2;
 

src/engine/Math/matrix.ts

@@ -415,13 +415,13 @@ export class Matrix {
 
   public getScaleX(): number {
     // absolute scale of the matrix (we lose sign so need to add it back)
-    const xscale = vec(this.data[0], this.data[4]).size;
+    const xscale = vec(this.data[0], this.data[4]).magnitude;
     return this._scaleSignX * xscale;
   }
 
   public getScaleY(): number {
     // absolute scale of the matrix (we lose sign so need to add it back)
-    const yscale = vec(this.data[1], this.data[5]).size;
+    const yscale = vec(this.data[1], this.data[5]).magnitude;
     return this._scaleSignY * yscale;
   }
 

src/engine/Math/vector.ts

@@ -187,14 +187,15 @@ export class Vector implements Clonable<Vector> {
    * @param magnitude
    */
   public clampMagnitude(magnitude: number): Vector {
-    const size = this.size;
+    const size = this.magnitude;
     const newSize = clamp(size, 0, magnitude);
-    this.size = newSize;
+    this.magnitude = newSize;
     return this;
   }
 
   /**
    * The size (magnitude) of the Vector
+   * @deprecated Will be removed in v1, use Vector.magnitude
    */
   public get size(): number {
     return this.distance();
@@ -203,12 +204,28 @@ export class Vector implements Clonable<Vector> {
   /**
    * Setting the size mutates the current vector
    * @warning Can be used to set the size of the vector, **be very careful using this, mutating vectors can cause hard to find bugs**
+   * @deprecated Will be removed in v1, use Vector.magnitude
    */
   public set size(newLength: number) {
     const v = this.normalize().scale(newLength);
     this.setTo(v.x, v.y);
   }
 
+  /**
+   * The magnitude (length) of the Vector
+   */
+  public get magnitude(): number {
+    return this.distance();
+  }
+
+  /**
+   * Setting the size mutates the current vector
+   * @warning Can be used to set the size of the vector, **be very careful using this, mutating vectors can cause hard to find bugs**
+   */
+  public set magnitude(newMagnitude: number) {
+    this.normalize().scale(newMagnitude, this);
+  }
+
   /**
    * Normalizes a vector to have a magnitude of 1.
    */

src/spec/AlgebraSpec.ts

@@ -94,20 +94,20 @@ describe('Vectors', () => {
     expect(v2.distance()).toBe(20);
   });
 
-  it('can have a size', () => {
+  it('can have a magnitude', () => {
     const v = new ex.Vector(20, 0);
     const v2 = new ex.Vector(0, -20);
 
-    expect(v.size).toBe(20);
-    expect(v2.size).toBe(20);
+    expect(v.magnitude).toBe(20);
+    expect(v2.magnitude).toBe(20);
   });
 
-  it('can have size set', () => {
+  it('can have magnitude set', () => {
     const v = new ex.Vector(20, 0);
     const v2 = new ex.Vector(3, 4);
 
-    v.size = 10;
-    v2.size = 13;
+    v.magnitude = 10;
+    v2.magnitude = 13;
 
     expect(v.equals(new ex.Vector(10, 0))).toBeTruthy();
     expect(v2.equals(new ex.Vector(7.8, 10.4))).toBeTruthy();
@@ -296,7 +296,7 @@ describe('Vectors', () => {
     const after = sut.normalize();
     expect(before.x).toBeCloseTo(after.x, 4);
     expect(before.y).toBeCloseTo(after.y, 4);
-    expect(sut.size).toBe(5);
+    expect(sut.magnitude).toBe(5);
   });
 });