feat(flame_3d): Add helpful extension functions to Vector (#3141)

Add helpful extension functions to Vector classes, including tests.

This was extracted directly from @wolfenrain 's [bigger
PR](#3085), making it easier
to merge later.

packages/flame_3d/lib/src/extensions/vector2.dart

@@ -7,3 +7,9 @@ extension Vector2Extension on Vector2 {
   /// Returns an immutable representation of the vector.
   ImmutableVector2 get immutable => (x: x, y: y);
 }
+
+extension Vector2Math on ImmutableVector2 {
+  List<double> get storage => [x, y];
+
+  Vector2 get mutable => Vector2(x, y);
+}

packages/flame_3d/lib/src/extensions/vector3.dart

@@ -7,3 +7,18 @@ extension Vector3Extension on Vector3 {
   /// Returns an immutable representation of the vector.
   ImmutableVector3 get immutable => (x: x, y: y, z: z);
 }
+
+extension Vector3Math on ImmutableVector3 {
+  List<double> get storage => [x, y, z];
+
+  ImmutableVector3 operator -(Object v) {
+    if (v is ImmutableVector3) {
+      return (x: x - v.x, y: y - v.y, z: z - v.z);
+    } else if (v is Vector3) {
+      return (x: x - v.x, y: y - v.y, z: z - v.z);
+    }
+    throw UnsupportedError('${v.runtimeType}');
+  }
+
+  Vector3 get mutable => Vector3(x, y, z);
+}

packages/flame_3d/lib/src/extensions/vector4.dart

@@ -7,3 +7,9 @@ extension Vector4Extension on Vector4 {
   /// Returns an immutable representation of the vector.
   ImmutableVector4 get immutable => (x: x, y: y, z: z, w: w);
 }
+
+extension Vector4Math on ImmutableVector4 {
+  List<double> get storage => [x, y, z, w];
+
+  Vector4 get mutable => Vector4(x, y, z, w);
+}

packages/flame_3d/test/vector2_extensions_test.dart

@@ -0,0 +1,20 @@
+import 'package:flame_3d/extensions.dart';
+import 'package:flame_3d/game.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  group('Vector2 extensions', () {
+    test('can convert back and forth to mutable', () {
+      final src = Vector2(1, 2);
+
+      final immutable = src.immutable;
+      expect(immutable.x, 1);
+      expect(immutable.y, 2);
+      expect(immutable.storage, [1, 2]);
+
+      final mutable = immutable.mutable;
+      expect(mutable.x, 1);
+      expect(mutable.y, 2);
+    });
+  });
+}

packages/flame_3d/test/vector3_extensions_test.dart

@@ -0,0 +1,30 @@
+import 'package:flame_3d/extensions.dart';
+import 'package:flame_3d/game.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  group('Vector3 extensions', () {
+    test('can convert back and forth to mutable', () {
+      final src = Vector3(1, 2, 3);
+
+      final immutable = src.immutable;
+      expect(immutable.x, 1);
+      expect(immutable.y, 2);
+      expect(immutable.z, 3);
+      expect(immutable.storage, [1, 2, 3]);
+
+      final mutable = immutable.mutable;
+      expect(mutable.x, 1);
+      expect(mutable.y, 2);
+      expect(mutable.z, 3);
+    });
+
+    test('can subtract immutable vector3', () {
+      final a = Vector3(0, 10, 0).immutable;
+      final b = Vector3(1, 2, 3);
+
+      expect((a - b).storage, [-1, 8, -3]);
+      expect((a - b.immutable).storage, [-1, 8, -3]);
+    });
+  });
+}

packages/flame_3d/test/vector4_extensions_test.dart

@@ -0,0 +1,24 @@
+import 'package:flame_3d/extensions.dart';
+import 'package:flame_3d/game.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  group('Vector4 extensions', () {
+    test('can convert back and forth to mutable', () {
+      final src = Vector4(1, 2, 3, 4);
+
+      final immutable = src.immutable;
+      expect(immutable.x, 1);
+      expect(immutable.y, 2);
+      expect(immutable.z, 3);
+      expect(immutable.w, 4);
+      expect(immutable.storage, [1, 2, 3, 4]);
+
+      final mutable = immutable.mutable;
+      expect(mutable.x, 1);
+      expect(mutable.y, 2);
+      expect(mutable.z, 3);
+      expect(mutable.w, 4);
+    });
+  });
+}