A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file Correctness of the camera/projection matrix math. These functions are
* exercised indirectly whenever CameraPlugin builds a view/projection,
* but nothing asserted the numbers were right — a sign flip in ortho or a
* transposed multiply would render "fine" and be silently wrong. Column
* major throughout: element (row r, col c) lives at m[c * 4 + r], and a
* point transforms as out[r] = Σ_c m[c*4+r] · v[c].
*/
import { describe, it, expect } from 'vitest';
import {
ortho, perspective, invertTranslation, invertViewZ, multiply, frustumCornersWorld, IDENTITY,
} from '../src/math/mat4';
const close = (a: number, b: number, eps = 1e-6) => expect(Math.abs(a - b)).toBeLessThanOrEqual(eps);
/** Column-major matrix · (x,y,z,w) → [x',y',z',w']. */
function apply(m: Float32Array, x: number, y: number, z: number, w = 1): [number, number, number, number] {
const out: [number, number, number, number] = [0, 0, 0, 0];
for (let r = 0; r < 4; r++) {
out[r] = m[0 * 4 + r] * x + m[1 * 4 + r] * y + m[2 * 4 + r] * z + m[3 * 4 + r] * w;
}
return out;
}
// Every builder returns a shared module-level scratch array, so a second call
// clobbers the first. Snapshot before comparing — this mirrors how callers must
// treat the results and guards the shared-buffer contract itself.
const snap = (m: Float32Array): Float32Array => Float32Array.from(m);
describe('mat4.ortho', () => {
it('maps the box corners to the NDC cube and the center to the origin', () => {
const m = snap(ortho(-10, 10, -5, 5, 1, 100));
// x: [-10,10] → [-1,1]; y: [-5,5] → [-1,1] (z picked in-range, does not affect x/y).
expect(apply(m, 10, 5, -1)[0]).toBeCloseTo(1, 6);
expect(apply(m, -10, -5, -1)[0]).toBeCloseTo(-1, 6);
expect(apply(m, 10, 5, -1)[1]).toBeCloseTo(1, 6);
expect(apply(m, -10, -5, -1)[1]).toBeCloseTo(-1, 6);
const c = apply(m, 0, 0, -50.5); // (center x, center y, mid eye-depth)
close(c[0], 0); close(c[1], 0); close(c[2], 0);
});
it('uses the OpenGL depth convention: near plane → -1, far plane → +1', () => {
const m = snap(ortho(-1, 1, -1, 1, 1, 100));
// Eye space looks down -Z, so the near plane sits at z = -near, far at z = -far.
close(apply(m, 0, 0, -1)[2], -1);
close(apply(m, 0, 0, -100)[2], 1);
});
it('is affine in w and leaves the perspective row untouched (w stays 1)', () => {
const m = snap(ortho(-3, 7, -2, 8, 0.5, 20));
expect(apply(m, 4, 4, -4)[3]).toBe(1);
});
});
describe('mat4.perspective', () => {
it('emits w = -z (the perspective divide) and keeps the optical axis centered', () => {
const m = snap(perspective(Math.PI / 2, 16 / 9, 0.1, 1000));
const p = apply(m, 0, 0, -5);
close(p[0], 0);
close(p[1], 0);
close(p[3], 5); // w = -z = -(-5)
});
it('scales x by 1/aspect and y by the focal length at fov=90°', () => {
// fov = 90° → f = 1/tan(45°) = 1, so m[0] = 1/aspect, m[5] = 1.
const aspect = 2;
const m = snap(perspective(Math.PI / 2, aspect, 1, 100));
close(m[0], 1 / aspect);
close(m[5], 1);
close(m[11], -1);
});
});
describe('mat4.invertTranslation', () => {
it('sends the camera position to the origin', () => {
const m = snap(invertTranslation(3, -4, 5));
const o = apply(m, 3, -4, 5);
close(o[0], 0); close(o[1], 0); close(o[2], 0); close(o[3], 1);
});
});
describe('mat4.invertViewZ', () => {
it('equals invertTranslation when the camera is unrotated (θ=0)', () => {
const t = snap(invertTranslation(7, -2, 3));
const v = snap(invertViewZ(7, -2, 3, 1, 0)); // cosθ=1, sinθ=0
for (let i = 0; i < 16; i++) close(v[i], t[i]);
});
it('sends the camera position to the origin under rotation', () => {
const th = Math.PI / 3;
const m = snap(invertViewZ(5, 8, -2, Math.cos(th), Math.sin(th)));
const o = apply(m, 5, 8, -2);
close(o[0], 0); close(o[1], 0); close(o[2], 0);
});
it('rotates world into view space: a +90° camera turns +X into -Y', () => {
// Camera at origin rotated +90° (cos=0, sin=1). A world point on +X should
// land on the view-space -Y axis (the world rotates by -θ into the view).
const m = snap(invertViewZ(0, 0, 0, 0, 1));
const o = apply(m, 1, 0, 0);
close(o[0], 0); close(o[1], -1);
});
});
describe('mat4.multiply', () => {
it('IDENTITY is the two-sided identity', () => {
const a = snap(invertTranslation(2, 3, 4));
const left = snap(multiply(IDENTITY, a));
const right = snap(multiply(a, IDENTITY));
for (let i = 0; i < 16; i++) { close(left[i], a[i]); close(right[i], a[i]); }
});
it('composes transforms in column-major order (M·v applies the right operand first)', () => {
// ortho ∘ view: projecting the camera-space origin of a translated camera
// must equal projecting (0,0,0) directly — the camera sits at its own origin.
const proj = snap(ortho(-10, 10, -10, 10, 1, 100));
const view = snap(invertTranslation(4, -6, -50));
const vp = snap(multiply(proj, view));
const throughCombined = apply(vp, 4, -6, -50);
const throughSeparate = apply(proj, ...(apply(view, 4, -6, -50).slice(0, 3) as [number, number, number]));
for (let i = 0; i < 4; i++) close(throughCombined[i], throughSeparate[i]);
});
it('matches a hand-computed product on a non-symmetric pair', () => {
// Two distinct translations compose additively: T(a)·T(b) = T(a+b).
const A = snap(invertTranslation(-1, -2, -3)); // translate(+1,+2,+3)
const B = snap(invertTranslation(-4, -5, -6)); // translate(+4,+5,+6)
const AB = snap(multiply(A, B));
// Combined translation column (m[12..14]) must be the sum (+5,+7,+9).
close(AB[12], 5); close(AB[13], 7); close(AB[14], 9); close(AB[15], 1);
});
});
describe('mat4 shared scratch buffers (footgun contract)', () => {
it('reuses one array per builder — callers must snapshot before the next call', () => {
const first = ortho(-1, 1, -1, 1, 1, 10);
const second = ortho(-2, 2, -2, 2, 1, 20);
expect(first).toBe(second); // same reference: the first result was overwritten
expect(first[0]).toBeCloseTo(2 / 4, 6); // now holds the SECOND box's 2/(r-l)
});
it('IDENTITY is a genuine identity matrix and is not a scratch target', () => {
expect(Array.from(IDENTITY)).toEqual([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
multiply(IDENTITY, IDENTITY); // multiply writes its own buffer, never IDENTITY
expect(IDENTITY[0]).toBe(1);
expect(IDENTITY[5]).toBe(1);
});
});
describe('mat4.frustumCornersWorld', () => {
// Corner i: near face bl, br, tr, tl (i = 0..3), then the far face.
const corner = (c: Float32Array, i: number): [number, number, number] =>
[c[i * 3]!, c[i * 3 + 1]!, c[i * 3 + 2]!];
it('undoes an orthographic view-projection back to its own box', () => {
// The camera sits at z = 10 looking down -Z; the symmetric ortho depth range
// puts the near face BEHIND it, which is what the box really is.
const vp = snap(multiply(snap(ortho(-400, 400, -300, 300, -1000, 1000)),
snap(invertViewZ(0, 0, 10, 1, 0))));
const c = frustumCornersWorld(vp);
expect(corner(c, 0).map((v) => Math.round(v))).toEqual([-400, -300, 1010]);
expect(corner(c, 2).map((v) => Math.round(v))).toEqual([400, 300, 1010]);
expect(corner(c, 4).map((v) => Math.round(v))).toEqual([-400, -300, -990]);
expect(corner(c, 6).map((v) => Math.round(v))).toEqual([400, 300, -990]);
});
it('opens out with distance under a perspective projection', () => {
// 90° vertical fov, aspect 2: the near face is 2x1 half-extents at z = -1,
// and the far face ten times that at z = -10.
const vp = snap(perspective(Math.PI / 2, 2, 1, 10));
const c = frustumCornersWorld(vp);
const [nx, ny, nz] = corner(c, 2);
close(nx, 2, 1e-4); close(ny, 1, 1e-4); close(nz, -1, 1e-4);
const [fx, fy, fz] = corner(c, 6);
close(fx, 20, 1e-3); close(fy, 10, 1e-3); close(fz, -10, 1e-3);
});
it('collapses to the origin for a matrix with no inverse', () => {
// Not "whatever the scratch held": a singular matrix has no frustum, and the
// previous camera's corners would be indistinguishable from this one's.
frustumCornersWorld(snap(perspective(Math.PI / 2, 2, 1, 10)));
expect(Array.from(frustumCornersWorld(new Float32Array(16)))).toEqual(new Array(24).fill(0));
});
});