feat: Updated Vector3 add and subtract to support partial right hand values (#59)

* Change files

* feat: Updated Vector3 add and subtract to support partial right hand values

Author: JakeShirley

change/@minecraft-math-e40e46c9-fad2-4d58-b5c5-988ab81b099e.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Updated Vector3 add and subtract to support partial right hand values",
+  "packageName": "@minecraft/math",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

libraries/math/api-report/math.api.md

@@ -79,7 +79,7 @@ export const VECTOR3_ZERO: Vector3;
 export class Vector3Builder implements Vector3 {
     constructor(vec: Vector3, arg?: never, arg2?: never);
     constructor(x: number, y: number, z: number);
-    add(v: Vector3): this;
+    add(v: Partial<Vector3>): this;
     assign(vec: Vector3): this;
     clamp(limits: {
         min?: Partial<Vector3>;
@@ -99,7 +99,7 @@ export class Vector3Builder implements Vector3 {
     rotateZ(a: number): this;
     scale(val: number): this;
     slerp(vec: Vector3, t: number): this;
-    subtract(v: Vector3): this;
+    subtract(v: Partial<Vector3>): this;
     toString(options?: {
         decimals?: number;
         delimiter?: string;
@@ -114,7 +114,7 @@ export class Vector3Builder implements Vector3 {
 
 // @public
 export class Vector3Utils {
-    static add(v1: Vector3, v2: Vector3): Vector3;
+    static add(v1: Vector3, v2: Partial<Vector3>): Vector3;
     static clamp(v: Vector3, limits?: {
         min?: Partial<Vector3>;
         max?: Partial<Vector3>;
@@ -133,7 +133,7 @@ export class Vector3Utils {
     static rotateZ(v: Vector3, a: number): Vector3;
     static scale(v1: Vector3, scale: number): Vector3;
     static slerp(a: Vector3, b: Vector3, t: number): Vector3;
-    static subtract(v1: Vector3, v2: Vector3): Vector3;
+    static subtract(v1: Vector3, v2: Partial<Vector3>): Vector3;
     static toString(v: Vector3, options?: {
         decimals?: number;
         delimiter?: string;

libraries/math/src/vector3/coreHelpers.test.ts

@@ -217,4 +217,50 @@ describe('Vector3 operations', () => {
             expect(result.z).toBeCloseTo(0);
         });
     });
+
+    describe('Vector3 add partial', () => {
+        it(`add a single axis`, () => {
+            const result = Vector3Utils.add(VECTOR3_UP, { z: 4 });
+            expect(result.x).toBeCloseTo(0);
+            expect(result.y).toBeCloseTo(1);
+            expect(result.z).toBeCloseTo(4);
+        });
+
+        it(`add two axis`, () => {
+            const result = Vector3Utils.add(VECTOR3_UP, { z: 7, x: 2 });
+            expect(result.x).toBeCloseTo(2);
+            expect(result.y).toBeCloseTo(1);
+            expect(result.z).toBeCloseTo(7);
+        });
+
+        it(`add all three axis`, () => {
+            const result = Vector3Utils.add(VECTOR3_UP, { x: 8, y: 2, z: 3 });
+            expect(result.x).toBeCloseTo(8);
+            expect(result.y).toBeCloseTo(3);
+            expect(result.z).toBeCloseTo(3);
+        });
+    });
+
+    describe('Vector3 subtract partial', () => {
+        it(`subtract a single axis`, () => {
+            const result = Vector3Utils.subtract(VECTOR3_UP, { z: 4 });
+            expect(result.x).toBeCloseTo(0);
+            expect(result.y).toBeCloseTo(1);
+            expect(result.z).toBeCloseTo(-4);
+        });
+
+        it(`subtract two axis`, () => {
+            const result = Vector3Utils.subtract(VECTOR3_UP, { z: 7, x: 2 });
+            expect(result.x).toBeCloseTo(-2);
+            expect(result.y).toBeCloseTo(1);
+            expect(result.z).toBeCloseTo(-7);
+        });
+
+        it(`subtract all three axis`, () => {
+            const result = Vector3Utils.subtract(VECTOR3_UP, { x: 8, y: 2, z: 3 });
+            expect(result.x).toBeCloseTo(-8);
+            expect(result.y).toBeCloseTo(-1);
+            expect(result.z).toBeCloseTo(-3);
+        });
+    });
 });

libraries/math/src/vector3/coreHelpers.ts

@@ -24,17 +24,17 @@ export class Vector3Utils {
      *
      * Add two vectors to produce a new vector
      */
-    static add(v1: Vector3, v2: Vector3): Vector3 {
-        return { x: v1.x + v2.x, y: v1.y + v2.y, z: v1.z + v2.z };
+    static add(v1: Vector3, v2: Partial<Vector3>): Vector3 {
+        return { x: v1.x + (v2.x ?? 0), y: v1.y + (v2.y ?? 0), z: v1.z + (v2.z ?? 0) };
     }
 
     /**
      * subtract
      *
      * Subtract two vectors to produce a new vector (v1-v2)
      */
-    static subtract(v1: Vector3, v2: Vector3): Vector3 {
-        return { x: v1.x - v2.x, y: v1.y - v2.y, z: v1.z - v2.z };
+    static subtract(v1: Vector3, v2: Partial<Vector3>): Vector3 {
+        return { x: v1.x - (v2.x ?? 0), y: v1.y - (v2.y ?? 0), z: v1.z - (v2.z ?? 0) };
     }
 
     /** scale

libraries/math/src/vector3/vectorWrapper.test.ts

@@ -54,6 +54,16 @@ describe('Vector3Builder', () => {
         expect(resultTwo).toBe(vectorA); // Referential equality must be preserved
     });
 
+    it('should be able to add a partial vector3 with the same result as the coreHelpers function', () => {
+        const vectorA = new Vector3Builder(1, 2, 3);
+        const vectorB: Partial<Vector3> = { x: 4, z: 6 };
+        const vectorC = Vector3Utils.add(vectorA, vectorB);
+
+        const result = vectorA.add(vectorB);
+        expect(result).toEqual(vectorC);
+        expect(vectorA).toBe(result); // Referential equality must be preserved
+    });
+
     it('should be able to subtract a vector3 with the same result as the coreHelpers function', () => {
         const vectorA = new Vector3Builder(5, 7, 9);
         const vectorB = new Vector3Builder(4, 5, 6);
@@ -70,6 +80,16 @@ describe('Vector3Builder', () => {
         expect(resultTwo).toBe(vectorA); // Referential equality must be preserved
     });
 
+    it('should be able to subtract a partial vector3 with the same result as the coreHelpers function', () => {
+        const vectorA = new Vector3Builder(1, 2, 3);
+        const vectorB: Partial<Vector3> = { x: 4, z: 6 };
+        const vectorC = Vector3Utils.subtract(vectorA, vectorB);
+
+        const result = vectorA.subtract(vectorB);
+        expect(result).toEqual(vectorC);
+        expect(vectorA).toBe(result); // Referential equality must be preserved
+    });
+
     it('should be able to scale a vector3 with the same result as the coreHelpers function', () => {
         const vectorA = new Vector3Builder(1, 2, 3);
         const vectorB = Vector3Utils.scale(vectorA, 3);

libraries/math/src/vector3/vectorWrapper.ts

@@ -57,7 +57,7 @@ export class Vector3Builder implements Vector3 {
      *
      * Adds the vector v to this, returning itself.
      */
-    add(v: Vector3): this {
+    add(v: Partial<Vector3>): this {
         return this.assign(Vector3Utils.add(this, v));
     }
 
@@ -66,7 +66,7 @@ export class Vector3Builder implements Vector3 {
      *
      * Subtracts the vector v from this, returning itself.
      */
-    subtract(v: Vector3): this {
+    subtract(v: Partial<Vector3>): this {
         return this.assign(Vector3Utils.subtract(this, v));
     }