Vectors, matrices and maths

The one rule that explains most surprises

Methods mutate this and return it. They do not return a new vector.

const a = new Vector3d(1, 0, 0);
const b = new Vector3d(0, 1, 0);

a.cross(b);        // a IS NOW the cross product; the original a is gone
a.add(b).normalize().scale(3, 3, 3);   // chains, all in place

That is what makes the API allocation-free, and it is the opposite of what a functional style expects. If you need to keep the original, copy into something you own first:

out.copy(a).cross(b);    // a untouched, nothing allocated

The exceptions are named. A handful of methods return a NEW vector, and each has a *Self sibling that does not:

allocates a new vector	mutates in place
negate()	negateSelf()
floor()	floorSelf()
ceil()	ceilSelf()
clamp(low, high)	clampSelf(low, high)
clone()	copy(v)

So v.negate() in a per-frame loop allocates every frame and v.negateSelf() does not. The names are the only clue; nothing in the call site shows it.

clone() comes from a pool, and only pays off if you give it back

clone() is vector3dPool.get(...). A pool is fast when instances come back: get() takes a free one and resets it. Nothing comes back on its own, so a clone that is simply dropped makes get() miss, construct, and write two registry entries.

Measured, 3M operations:

out.copy(a).cross(b)	39ms
new Vector3d(ax, ay, az).cross(b)	37ms
a.clone().cross(b)	2919ms

So:

• Transient value inside a function? Use a module-level scratch vector, or new Vector3d(). Not clone().
• Keeping it, then done with it? clone() and vector3dPool.release(v) when finished. Releasing is what makes the pool a pool.
• Writing a helper that returns a vector? Take an optional out:

const cross = (a, b, out = new Vector3d()) => out.copy(a).cross(b);

That is the engine's own convention, and it lets a hot caller supply scratch while a casual one ignores it.

A returned value can never be shared scratch. The next call overwrites something the caller is still holding, and nothing fails loudly:

const _t = new Vector3d();
const bad = (v) => _t.copy(v).normalize();   // WRONG: two calls alias

Argument defaults that drop a component

Three signatures quietly discard what you did not pass. All three are reachable by writing the obvious thing.

scale(x, y = x, z = 1) — z defaults to 1, not to x. A uniform scale has to say so three times:

v.scale(2);          // (1,2,3) -> (2,4,3)   z UNTOUCHED
v.scale(2, 2, 2);    // (1,2,3) -> (2,4,6)   what you meant

set(x, y, z = 0) — setting two components zeroes the third:

v.set(10, 20);       // z is now 0, whatever it was

Vector3d.pos on a renderable is typed Vector2d. Renderable.pos is an ObservableVector3d at run time but is declared through Polygon as a Vector2d, so .z, .setMuted and .setCallback need a cast from TypeScript. See issue #1510.

cross is two different functions

v3.cross(other);   // Vector3d: MUTATES v3, returns this
v2.cross(other);   // Vector2d: returns a NUMBER, mutates nothing

The 2D one is the z component of the 3D cross, which is the useful scalar for "which side is this on". Same name, different shape, different return.

Interpolation: four of them, and they are not interchangeable

a.lerp(b, t);            // straight line, t in 0..1
a.slerp(b, t);           // along the ARC, constant angular rate
a.damp(b, lambda, dt);   // frame-rate independent ease toward b
a.moveTowards(b, step);  // fixed distance per call, never overshoots

moveTowards is X/Y ONLY, on Vector3d as well as Vector2d. It is the one of the four that is not 3D: it measures the distance from dx and dy, steps along atan2(dy, dx), and leaves z exactly where it was. The source says so in a comment and the JSDoc says "on the x and y axis", but the name gives no hint, and in a list like the one above it reads as the sibling of the other three. Anything moving in three dimensions wants damp or an explicit step; reach for moveTowards only when the motion really is planar.

lerp between two directions is uneven: it slows at the ends, runs fast through the middle, and shortens the vector as it passes halfway. Anything whose direction matters more than its components wants slerp — a camera swinging to look somewhere, a turret tracking, a body moving over a sphere. slerp carries length linearly, so two unit vectors give a unit vector and nothing needs normalising afterwards.

damp is the one to use for "ease toward a target every frame", because lerp(current, target, 0.1) per frame is frame-rate dependent: it converges twice as fast at 120fps as at 60.

project scales THIS, and projectN is the one without the divide

a.project(b) does not return the component of a along b. It scales a by a.b / |b|^2 and returns a, so the result points along a, not along b. Worth knowing before you reach for it expecting the textbook projection.

projectN(v) is the same thing for a v that is already unit, so it skips the / v.length2():

a.project(b);   // a scaled by (a.b / |b|^2)
a.projectN(b);  // a scaled by (a.b)      -- only correct when |b| = 1

Handing projectN a target that is NOT unit does not normalise anything, it just scales by the raw dot product. That is the price of it being cheaper, and it is the caller's job to meet the contract.

Until 20.9 both 3D classes got this wrong: Vector3d.projectN and ObservableVector3d.projectN were copies of project, division and all, under projectN's name and its "slightly more efficient" doc comment. Nothing in the engine called either one and nothing tested them, which is how it survived. Both are fixed and all four classes are now pinned by tests.

length() is sqrt(x*x + y*y + z*z)

Fast and correct to 1 ULP for anything a game holds. It is NOT robust at extremes: components above ~1e154 overflow to Infinity and below ~1e-162 underflow to 0, because the squares are formed before the root. Math.hypot avoids that and costs 35 to 65% more. The engine takes the speed, which is the right trade for coordinates between 1e-3 and 1e6; nothing in a game is 148 orders of magnitude from unit scale.

length2() skips the square root. Use it for comparisons:

if (a.distance(b) < r) { }            // a square root you did not need
if (a.sub(b).length2() < r * r) { }   // same answer, cheaper

Observable vectors

ObservableVector2d / ObservableVector3d call a callback on every write, which is how a renderable knows its bounds went stale.

v.setCallback(() => { ... });
v.setMuted(true);     // write without firing it

setMuted is what you want when writing several components, so a half-updated vector does not fire a callback that reads the other half. set() already does this internally: it disables the callback, writes all three, fires once, and re-enables.

Note the observable set(x = 0, y = 0, z = 0) defaults EVERY argument, so set(10, 20) zeroes z exactly as the plain vector does.

Matrices

Matrix2d is 3x3 for 2D affine transforms; Matrix3d is 4x4. Both mutate and chain, same as vectors, and both come from pools.

m.identity().translate(x, y).rotate(angle).scale(sx, sy);

Order is the reverse of how it reads. These post-multiply, so the call made LAST reaches the vertex FIRST. To rotate a thing about its own centre, translate to the centre last.

Every renderable already HAS one

Renderable.currentTransform is a Matrix3d. If you are orienting something on screen, the matrix exists: write into it rather than building a parallel structure and copying.

// the whole transform of a renderable, written in place
mesh.currentTransform.identity().translate(x, y, z).rotate(angle, axis);

The sixteen numbers are val, column-major

Composing with translate/rotate/scale is one way to fill a matrix. The other is to write the numbers, which is what you want when the orientation comes from a basis you have already computed — three orthonormal vectors, a surface frame, a camera basis.

val is a Float32Array(16) in column-major order, the OpenGL convention: each basis vector occupies a stride-4 run, and the translation is the last column.

	X column	Y column	Z column	translation
indices	0,1,2	4,5,6	8,9,10	12,13,14

// an orientation from three axes, straight into the renderable's own matrix
const m = mesh.currentTransform.val;
m[0] = right.x;   m[1] = right.y;   m[2] = right.z;   m[3] = 0;
m[4] = up.x;      m[5] = up.y;      m[6] = up.z;      m[7] = 0;
m[8] = fwd.x;     m[9] = fwd.y;     m[10] = fwd.z;    m[11] = 0;
m[12] = 0;        m[13] = 0;        m[14] = 0;        m[15] = 1;

A helper that builds one should take the destination, the same way the engine takes an out, so it writes once into the matrix that will be used:

const orient = (frame, out) => { /* writes out.val */ return out; };
orient(frame, mesh.currentTransform);

Getting numbers IN from somewhere else

setTransform(...) takes the sixteen as arguments, and copy(m) takes another matrix:

m.setTransform(a, b, c, d, e, f, g, h, i, j, k, l, p, q, r, s);
m.copy(other);                 // Float32Array.set under the hood

Both are fine occasionally. In a per-frame loop, prefer writing val or copy() over spreading sixteen arguments, and note that one matrix built once and applied to many renderables is a copy() per renderable, not a rebuild per renderable.

val is Float32Array, so it holds float32. Numbers you put in are rounded to single precision. That is where they were always heading, since this is what reaches the GPU, but it means a value read back out is not bit-identical to the double you wrote.

Utilities

import { math } from "melonjs";

math.clamp(v, lo, hi);
math.lerp(a, b, t);              // scalars
math.damp(a, b, lambda, dt);     // frame-rate independent
math.degToRad(deg);  math.radToDeg(rad);
math.random(lo, hi);             // integer
math.randomFloat(lo, hi);
math.weightedRandom(lo, hi);     // integer, biased toward LO
math.round(n, decimals);
math.pow(n);                     // n squared
math.DEG_TO_RAD  math.RAD_TO_DEG  math.TAU  math.ETA  math.EPSILON

Values that wobble over time

Noise, the generator behind NoiseTexture2d, also samples directly. For a value that should drift without repeating (a torch's flicker, a sway, a camera wander), sample it with time:

import { Noise } from "melonjs";

const noise = new Noise({ seed: 7, frequency: 1.5, octaves: 3 });
// around 1; give each object its own offset so they do not move together
const flicker = 1 + 0.2 * noise.getNoise1d(seconds + offset);

getNoise1d returns [-1, 1] (with fractal octaves most values fall within about ±0.6), frequency is in changes per unit of the input, and the same seed gives the same field every run. A sum of sines repeats where people notice it, and Math.random() every frame jitters instead of drifting.

Symptoms

symptom	cause
z unchanged after scaling	scale(s) leaves z alone; pass scale(s, s, s)
z became 0 for no reason	set(x, y) defaults z to 0
the original vector changed	the method mutates; copy() into something first
memory climbs in a loop	clone() or negate()/floor()/ceil() per frame
two helper results are the same object	a shared scratch vector was returned
.z is a type error	Renderable.pos is declared Vector2d (#1510)
rotation eases oddly between directions	lerp on directions; use slerp
you built your own 16-number array	Renderable.currentTransform is already a Matrix3d; write its val
a value read back from a matrix differs	val is Float32Array; it holds float32
easing differs at 120fps	per-frame lerp; use damp
a flicker or sway looks mechanical, or visibly repeats	a sum of sines or a per-frame Math.random(): sample Noise#getNoise1d(time)

Related skills

• melonjs-3d — Camera3d, meshes, and where these vectors are used in 3D
• melonjs-physics — bodies, velocities and collision response
• melonjs-performance — pooling in general, and what release() is for