Vector Maths

What it does

Every function takes plain { x, y } data and returns a new vector. Nothing mutates its arguments, which matters more than it sounds: a helper that quietly writes back into the vector you passed is the classic source of a body that applies one frame's velocity twice, and the bug stays invisible until something moves at the wrong speed. Reached as game.vecMath, generic names such as add, scale and dot cannot collide with anything in your own code.

The squared forms are there for comparisons. len2 and dist2 skip the square root, and a comparison never needs one: dist2(a, b) < r * r is the same test as dist(a, b) < r and costs less, so reach for it in anything that runs per pair per frame.

Features

• Arithmetic — add, sub, scale and dot.
• Magnitudes and distances — len, len2, dist and dist2, with and without the root.
• Safe normalising — normalize leaves a zero vector at zero rather than turning it into NaN.
• Speed limits — clampLen caps a magnitude without changing the direction.
• Angles and turns — fromAngle and angleOf between angles and vectors, and rotate about the origin.
• Blends and steps — lerp between two vectors, and stepToward, which moves toward a target by at most a step and never overshoots.
• Steering angles — signedAngle and turnToward, the angle helpers of maths, available under the same names.

Good for

• Thrust-and-coast ships — thrust along a heading with fromAngle and a top speed with clampLen.
• Homing and chasing — a missile that turns toward its target, an enemy that steps toward the player.
• Range checks — dist2 against a squared radius for every pair of rocks and shots.
• Any 2D game logic — positions and velocities in a line-art game or any other 2D game.

Make it yours

There is nothing to configure: these are functions, used from game.vecMath or imported from the package. Two everyday uses: a ship that adds fromAngle(heading, thrust * dt) to its velocity each frame and caps it with clampLen; and a turret that turns its barrel with turnToward and checks its range with dist2 before it fires.

Works with

• maths — the source of signedAngle and turnToward, bundled with this pack; compose it too for easing, ranges and the rest of its game maths.
• core-vector — includes this pack with the rest of the vector kit.
• vector-motion — integration, gravity and screen wrap over the same plain data.
• vector-hit — collision tests over the same points.

Good to know

• 2D only.
• Plain objects rather than typed arrays: this is for game logic, not for a tight inner loop over ten thousand particles, where you work on the arrays directly.
• Every call returns a new object, the price of never mutating; vector-motion's integrator writes in place for that reason.