Add utility to get/set ex.Vector size

[eonarheim]

Context

It would be useful to set the magnitude of a vector, this allows easy scaling or capping at a maximum value. This is especially useful in physics simulations.

Proposal

I propose something like the following (there is probably a more efficient method of changing the size of the vector)

  /**
   * The magnitude (size) of the Vector
   * @obsolete magnitude will be removed in favor `.size` in version v0.24.0
   */
  public magnitude(): number {
    return this.distance();
  }
  
 /**
  * The size (aka magnitude) of the Vector
  */
  public get size(): number {
    return this.distance();
  }

  public set size(newLength: number) {
    this.normalize().scale(newLength);
  }

Usage:

const vel = new ex.Vector(3, 4);

console.log(vel.size); // 5
vel.size = 13;

// Automatically calculates to correct scale
console.log(vel.x); // 5
console.log(vel.y); // 12

[saahilk]

Hi, I'd like to work on this issue.

[eonarheim]

@saahilk All yours! I've added the community in-progress label for you

[saahilk]

@eonarheim Alright let me get started then!

[saahilk]

@eonarheim Is there a doc where I can find how to setup the environment? I only found this. Also could you point me to the files I should look through to get started on this issue specifically?

[eonarheim]

@saahilk Let me know if this doesn't cover everything https://github.com/excaliburjs/Excalibur#environment-setup, please let me know if there are any gaps in the readme 👍

[eonarheim]

We'll want to fix the readme if any steps are ambiguous, missing, wrong, or poorly written

[saahilk]

@eonarheim Alright. Thanks!

[saahilk]

@eonarheim Hi which files do I look at to start with?

[eonarheim]

Hi @saahilk Check out Algebra.ts

[saahilk]

@eonarheim Do I keep the existing magnitude function marking it as obsolete or just remove it adding the size() function?

[eonarheim]

Good question, lets keep the existing magnitude function with an @obsolete in the JSDoc comment. We'll remove it in the future v0.25.0 release.

[saahilk]

Hi @eonarheim I've submitted an initial pull request with some changes. Let me know if there's anything else that needs to be changed.

[saahilk]

Hi @eonarheim the comments in the usage you have mentioned in the above issue is incorrect. When you set vel.size=13 the unit vector is (0.6, 0.8) and the scaled vector will be (7.8, 10.4) and not (5, 12).

[eonarheim]

@saahilk Good find! I was trying to do math in my head when writing the issue and failed oops!

[saahilk]

@eonarheim Could you check the modified pull request here.