What Vector Math Functions Does Planck.js Provide?

Planck.js, a 2D physics engine rewritten in JavaScript for cross-platform games, provides a dedicated Vec2 class equipped with utility functions for essential 2D vector math manipulations. This article outlines the core methods available in Planck.js for managing vector operations—such as addition, subtraction, scaling, dot products, and cross products—which are crucial for calculating forces, velocities, and positions within a physics simulation.

Core Vector Creation and Manipulation

At the heart of motion and geometry in Planck.js is the Vec2 object. Rather than forcing developers to manage raw coordinate objects, the engine includes built-in methods to create, clone, and modify 2D vectors efficiently.

• Vec2(x, y): The constructor used to initialize a new vector with specific \(x\) and \(y\) coordinates.
• Vec2.clone(): Creates a duplicate copy of an existing vector instance, preventing accidental mutations to the original coordinates during calculations.
• Vec2.set(x, y): Dynamically updates the coordinates of an existing vector in place, reducing garbage collection overhead by reusing objects.
• Vec2.setZero(): Resets both the \(x\) and \(y\) components of the vector to zero.

Basic Geometric Operations

Planck.js simplifies standard algebraic operations on vectors, offering both static methods (which return a new vector) and instance methods (which often mutate the vector to optimize performance).

Addition and Subtraction

• Vec2.add(v1, v2): Adds two vectors together to compute a combined resultant vector.
• Vec2.sub(v1, v2): Subtracts one vector from another, frequently used to determine the distance or direction between two bodies.

Scaling and Inversion

• Vec2.mul(v, s): Multiplies a vector \(v\) by a scalar value \(s\), effectively scaling its magnitude without altering its direction.
• Vec2.neg(): Negates the vector, reversing its direction along both axes.

Advanced Vector Mathematics

For physics calculations like collision response, angular momentum, and directional alignment, Planck.js exposes standard geometric products.

Dot and Cross Products

• Vec2.dot(v1, v2): Calculates the scalar dot product of two vectors, which is vital for determining the projection of one vector onto another or finding the angle between them.
• Vec2.cross(v1, v2): Computes the cross product. In 2D physics, the cross product of two vectors returns a scalar representing the magnitude of the perpendicular vector, used extensively for torque and angular velocity calculations.

Length and Normalization

• Vec2.length(): Returns the straight-line magnitude (Euclidean length) of the vector.
• Vec2.lengthSquared(): Returns the squared length of the vector (\(x^2 + y^2\)). This is computationally cheaper than length() because it skips the square-root operation, making it ideal for distance comparisons.
• Vec2.normalize(): Redefines the vector to have a length of 1 while maintaining its original direction, turning it into a unit vector.

Distance and Utility Methods

Planck.js also includes helper functions to evaluate the spatial relationships between different points in the simulation environment.

• Vec2.distance(v1, v2): Computes the precise distance between two vector points.
• Vec2.distanceSquared(v1, v2): Computes the squared distance between two points, maximizing performance during proximity checks.
• Vec2.isValid(): A debugging utility that verifies if the vector components are valid numbers (i.e., not NaN or Infinity), ensuring the stability of the physics simulation loop.