Skip to content

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.

37.6 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, it, expect } from 'vitest';
import {
    intersectRects,
    invertMatrix4,
    screenToWorld,
    pointInWorldRect,
    quaternionToAngle2D,
    projectWorldPoint,
    projectDirectionAt,
    nearPlaneSide,
    isProjectable,
    createInvVPCache,
    pointInOBB,
    screenRay,
    rayPlaneHit,
} from '../src/ui/util/math';
import type { ScreenRect, ProjectedPoint } from '../src/ui/util/math';

// =============================================================================
// Helpers
// =============================================================================

function identity4(): Float32Array {
    const m = new Float32Array(16);
    m[0] = 1; m[5] = 1; m[10] = 1; m[15] = 1;
    return m;
}

function translation4(tx: number, ty: number, tz: number): Float32Array {
    const m = identity4();
    m[12] = tx; m[13] = ty; m[14] = tz;
    return m;
}

function scale4(sx: number, sy: number, sz: number): Float32Array {
    const m = new Float32Array(16);
    m[0] = sx; m[5] = sy; m[10] = sz; m[15] = 1;
    return m;
}

function rotationZ4(radians: number): Float32Array {
    const c = Math.cos(radians);
    const s = Math.sin(radians);
    const m = identity4();
    m[0] = c; m[1] = s;
    m[4] = -s; m[5] = c;
    return m;
}

function mulMat4(a: Float32Array, b: Float32Array): Float32Array {
    const out = new Float32Array(16);
    for (let i = 0; i < 4; i++) {
        for (let j = 0; j < 4; j++) {
            let sum = 0;
            for (let k = 0; k < 4; k++) {
                sum += a[i + k * 4] * b[k + j * 4];
            }
            out[i + j * 4] = sum;
        }
    }
    return out;
}

function expectMatClose(a: Float32Array, b: Float32Array, precision = 5) {
    expect(a.length).toBe(b.length);
    for (let i = 0; i < a.length; i++) {
        expect(a[i]).toBeCloseTo(b[i], precision);
    }
}

function quaternionFromAngle(angle: number): { rz: number; rw: number } {
    return { rz: Math.sin(angle / 2), rw: Math.cos(angle / 2) };
}

// =============================================================================
// Tests
// =============================================================================

describe('uiMath', () => {

    // =========================================================================
    // intersectRects
    // =========================================================================

    describe('intersectRects', () => {
        it('should return correct intersection for two overlapping rects', () => {
            const a: ScreenRect = { x: 0, y: 0, w: 10, h: 10 };
            const b: ScreenRect = { x: 5, y: 5, w: 10, h: 10 };
            const r = intersectRects(a, b);
            expect(r).toEqual({ x: 5, y: 5, w: 5, h: 5 });
        });

        it('should return zero-sized rect for non-overlapping rects', () => {
            const a: ScreenRect = { x: 0, y: 0, w: 5, h: 5 };
            const b: ScreenRect = { x: 10, y: 10, w: 5, h: 5 };
            const r = intersectRects(a, b);
            expect(r.w).toBe(0);
            expect(r.h).toBe(0);
        });

        it('should return inner rect when one is fully inside another', () => {
            const outer: ScreenRect = { x: 0, y: 0, w: 20, h: 20 };
            const inner: ScreenRect = { x: 5, y: 5, w: 5, h: 5 };
            const r = intersectRects(outer, inner);
            expect(r).toEqual({ x: 5, y: 5, w: 5, h: 5 });
        });

        it('should return same rect for identical rects', () => {
            const a: ScreenRect = { x: 3, y: 4, w: 10, h: 8 };
            const r = intersectRects(a, a);
            expect(r).toEqual(a);
        });

        it('should return zero width/height for edge-touching rects', () => {
            const a: ScreenRect = { x: 0, y: 0, w: 5, h: 5 };
            const b: ScreenRect = { x: 5, y: 0, w: 5, h: 5 };
            const r = intersectRects(a, b);
            expect(r.w).toBe(0);
        });

        it('should handle partial overlap on one axis only', () => {
            const a: ScreenRect = { x: 0, y: 0, w: 10, h: 5 };
            const b: ScreenRect = { x: 5, y: 10, w: 10, h: 5 };
            const r = intersectRects(a, b);
            expect(r.h).toBe(0);
        });
    });

    // =========================================================================
    // invertMatrix4
    // =========================================================================

    describe('invertMatrix4', () => {
        it('should invert identity to identity', () => {
            const id = identity4();
            const inv = invertMatrix4(id);
            expectMatClose(inv, id);
        });

        it('should invert translation to negative translation', () => {
            const t = translation4(3, -7, 5);
            const inv = invertMatrix4(t);
            expect(inv[12]).toBeCloseTo(-3);
            expect(inv[13]).toBeCloseTo(7);
            expect(inv[14]).toBeCloseTo(-5);
        });

        it('should invert scale to reciprocal scale', () => {
            const s = scale4(2, 4, 0.5);
            const inv = invertMatrix4(s);
            expect(inv[0]).toBeCloseTo(0.5);
            expect(inv[5]).toBeCloseTo(0.25);
            expect(inv[10]).toBeCloseTo(2);
        });

        it('should satisfy M * M^-1 = Identity', () => {
            const m = translation4(5, -3, 1);
            m[0] = 2; m[5] = 3;
            const inv = invertMatrix4(m);
            const product = mulMat4(m, inv);
            expectMatClose(product, identity4());
        });

        it('should return zero-filled output for singular matrix', () => {
            const singular = new Float32Array(16);
            const inv = invertMatrix4(singular);
            for (let i = 0; i < 16; i++) {
                expect(inv[i]).toBe(0);
            }
        });

        it('should write to custom result buffer', () => {
            const id = identity4();
            const buf = new Float32Array(16);
            const result = invertMatrix4(id, buf);
            expect(result).toBe(buf);
            expectMatClose(buf, id);
        });

        it('should correctly invert a 2D rotation matrix', () => {
            const angle = Math.PI / 3;
            const rot = rotationZ4(angle);
            const inv = invertMatrix4(rot);
            const product = mulMat4(rot, inv);
            expectMatClose(product, identity4());
        });

        it('should invert an orthographic projection matrix', () => {
            const ortho = new Float32Array(16);
            const l = -10, r = 10, b = -5, t = 5, n = -1, f = 1;
            ortho[0] = 2 / (r - l);
            ortho[5] = 2 / (t - b);
            ortho[10] = -2 / (f - n);
            ortho[12] = -(r + l) / (r - l);
            ortho[13] = -(t + b) / (t - b);
            ortho[14] = -(f + n) / (f - n);
            ortho[15] = 1;
            const inv = invertMatrix4(ortho);
            const product = mulMat4(ortho, inv);
            expectMatClose(product, identity4());
        });
    });

    // =========================================================================
    // screenToWorld
    // =========================================================================

    describe('screenToWorld', () => {
        it('should map viewport center to world origin with identity VP', () => {
            const invVP = identity4();
            const result = screenToWorld(400, 300, invVP, 0, 0, 800, 600);
            expect(result.x).toBeCloseTo(0);
            expect(result.y).toBeCloseTo(0);
        });

        it('should map viewport corners to NDC corners with identity VP', () => {
            const invVP = identity4();
            const topLeft = screenToWorld(0, 0, invVP, 0, 0, 800, 600);
            expect(topLeft.x).toBeCloseTo(-1);
            expect(topLeft.y).toBeCloseTo(-1);

            const bottomRight = screenToWorld(800, 600, invVP, 0, 0, 800, 600);
            expect(bottomRight.x).toBeCloseTo(1);
            expect(bottomRight.y).toBeCloseTo(1);
        });

        it('should apply translation from VP inverse', () => {
            const invVP = translation4(10, 20, 0);
            const result = screenToWorld(400, 300, invVP, 0, 0, 800, 600);
            expect(result.x).toBeCloseTo(10);
            expect(result.y).toBeCloseTo(20);
        });

        it('should handle viewport offset (vpX, vpY non-zero)', () => {
            const invVP = identity4();
            const result = screenToWorld(200, 200, invVP, 100, 100, 200, 200);
            expect(result.x).toBeCloseTo(0);
            expect(result.y).toBeCloseTo(0);
        });

        it('should roundtrip with projectWorldPoint for identity VP', () => {
            const vp = identity4();
            const invVP = invertMatrix4(vp);
            const sx = 250, sy = 180;
            const vpX = 0, vpY = 0, vpW = 800, vpH = 600;
            const world = screenToWorld(sx, sy, invVP, vpX, vpY, vpW, vpH);
            const { x: backX, y: backY } = projectWorldPoint(world.x, world.y, 0, vp, vpX, vpY, vpW, vpH);
            expect(backX).toBeCloseTo(sx);
            expect(backY).toBeCloseTo(sy);
        });

        it('should roundtrip with projectWorldPoint for scaled VP', () => {
            const vp = scale4(0.5, 0.5, 1);
            vp[15] = 1;
            const invVP = invertMatrix4(vp);
            const sx = 300, sy = 400;
            const vpX = 0, vpY = 0, vpW = 800, vpH = 600;
            const world = screenToWorld(sx, sy, invVP, vpX, vpY, vpW, vpH);
            const { x: backX, y: backY } = projectWorldPoint(world.x, world.y, 0, vp, vpX, vpY, vpW, vpH);
            expect(backX).toBeCloseTo(sx);
            expect(backY).toBeCloseTo(sy);
        });
    });

    // =========================================================================
    // projectWorldPoint
    // =========================================================================

    describe('projectWorldPoint', () => {
        it('should map world origin to viewport center with identity VP', () => {
            const vp = identity4();
            const { x: sx, y: sy } = projectWorldPoint(0, 0, 0, vp, 0, 0, 800, 600);
            expect(sx).toBeCloseTo(400);
            expect(sy).toBeCloseTo(300);
        });

        it('should map world (-1,-1) to viewport origin with identity VP', () => {
            const vp = identity4();
            const { x: sx, y: sy } = projectWorldPoint(-1, -1, 0, vp, 0, 0, 800, 600);
            expect(sx).toBeCloseTo(0);
            expect(sy).toBeCloseTo(0);
        });

        it('should handle scaled VP matrix', () => {
            const vp = scale4(2, 2, 1);
            vp[15] = 1;
            const { x: sx, y: sy } = projectWorldPoint(0.5, 0.5, 0, vp, 0, 0, 800, 600);
            expect(sx).toBeCloseTo(800);
            expect(sy).toBeCloseTo(600);
        });

        it('should apply viewport offset', () => {
            const vp = identity4();
            const { x: sx, y: sy } = projectWorldPoint(0, 0, 0, vp, 50, 100, 800, 600);
            expect(sx).toBeCloseTo(450);
            expect(sy).toBeCloseTo(400);
        });

        it('should be consistent with screenToWorld roundtrip', () => {
            const vp = translation4(0.5, -0.3, 0);
            const invVP = invertMatrix4(vp);
            const vpX = 10, vpY = 20, vpW = 640, vpH = 480;
            const wx = 3.5, wy = -2.1;
            const { x: sx, y: sy } = projectWorldPoint(wx, wy, 0, vp, vpX, vpY, vpW, vpH);
            const back = screenToWorld(sx, sy, invVP, vpX, vpY, vpW, vpH);
            expect(back.x).toBeCloseTo(wx);
            expect(back.y).toBeCloseTo(wy);
        });
    });

    // =========================================================================
    // pointInWorldRect
    // =========================================================================

    describe('pointInWorldRect', () => {
        it('should return true for point at center', () => {
            expect(pointInWorldRect(5, 5, 5, 5, 10, 10, 0.5, 0.5)).toBe(true);
        });

        it('should return false for point outside', () => {
            expect(pointInWorldRect(20, 20, 5, 5, 10, 10, 0.5, 0.5)).toBe(false);
        });

        it('should return true for point on edge (boundary inclusive)', () => {
            expect(pointInWorldRect(0, 0, 5, 5, 10, 10, 0.5, 0.5)).toBe(true);
            expect(pointInWorldRect(10, 10, 5, 5, 10, 10, 0.5, 0.5)).toBe(true);
        });

        it('should handle default pivot (0.5, 0.5) with symmetric bounds', () => {
            expect(pointInWorldRect(-5, 0, 0, 0, 10, 10, 0.5, 0.5)).toBe(true);
            expect(pointInWorldRect(5, 0, 0, 0, 10, 10, 0.5, 0.5)).toBe(true);
            expect(pointInWorldRect(-5.01, 0, 0, 0, 10, 10, 0.5, 0.5)).toBe(false);
        });

        it('should handle pivot (0, 0) extending right and up', () => {
            expect(pointInWorldRect(5, 5, 0, 0, 10, 10, 0, 0)).toBe(true);
            expect(pointInWorldRect(-1, -1, 0, 0, 10, 10, 0, 0)).toBe(false);
        });

        it('should handle pivot (1, 1) extending left and down', () => {
            expect(pointInWorldRect(-5, -5, 0, 0, 10, 10, 1, 1)).toBe(true);
            expect(pointInWorldRect(1, 1, 0, 0, 10, 10, 1, 1)).toBe(false);
        });

        it('should handle zero-size rect (only exact center matches)', () => {
            expect(pointInWorldRect(5, 5, 5, 5, 0, 0, 0.5, 0.5)).toBe(true);
            expect(pointInWorldRect(5.001, 5, 5, 5, 0, 0, 0.5, 0.5)).toBe(false);
        });
    });

    // =========================================================================
    // quaternionToAngle2D
    // =========================================================================

    describe('quaternionToAngle2D', () => {
        it('should return 0 for identity quaternion', () => {
            expect(quaternionToAngle2D(0, 1)).toBeCloseTo(0);
        });

        it('should return PI/2 for 90 degree rotation', () => {
            const q = quaternionFromAngle(Math.PI / 2);
            expect(quaternionToAngle2D(q.rz, q.rw)).toBeCloseTo(Math.PI / 2);
        });

        it('should return PI for 180 degree rotation', () => {
            const q = quaternionFromAngle(Math.PI);
            expect(quaternionToAngle2D(q.rz, q.rw)).toBeCloseTo(Math.PI);
        });

        it('should return -PI/2 for -90 degree rotation', () => {
            const q = quaternionFromAngle(-Math.PI / 2);
            expect(quaternionToAngle2D(q.rz, q.rw)).toBeCloseTo(-Math.PI / 2);
        });

        it('should return 2*PI for 360 degree rotation (atan2 does not wrap)', () => {
            const q = quaternionFromAngle(2 * Math.PI);
            const angle = quaternionToAngle2D(q.rz, q.rw);
            expect(angle).toBeCloseTo(2 * Math.PI, 4);
        });
    });

    // =========================================================================
    // pointInOBB
    // =========================================================================

    describe('pointInOBB', () => {
        it('should behave like pointInWorldRect with no rotation', () => {
            const q = quaternionFromAngle(0);
            expect(pointInOBB(5, 5, 5, 5, 10, 10, 0.5, 0.5, q.rz, q.rw)).toBe(true);
            expect(pointInOBB(20, 20, 5, 5, 10, 10, 0.5, 0.5, q.rz, q.rw)).toBe(false);
        });

        it('should detect point inside 45-degree rotated rect', () => {
            const q = quaternionFromAngle(Math.PI / 4);
            expect(pointInOBB(5, 5, 5, 5, 10, 10, 0.5, 0.5, q.rz, q.rw)).toBe(true);
        });

        it('should reject point outside rotated rect but inside AABB', () => {
            const q = quaternionFromAngle(Math.PI / 4);
            expect(pointInOBB(10, 5, 5, 5, 6, 6, 0.5, 0.5, q.rz, q.rw)).toBe(false);
        });

        it('should handle 90-degree rotation (swapped axes)', () => {
            const q = quaternionFromAngle(Math.PI / 2);
            expect(pointInOBB(5, 9, 5, 5, 10, 2, 0.5, 0.5, q.rz, q.rw)).toBe(true);
            expect(pointInOBB(9, 5, 5, 5, 10, 2, 0.5, 0.5, q.rz, q.rw)).toBe(false);
        });

        it('should always contain center point at any rotation', () => {
            for (const angle of [0, Math.PI / 6, Math.PI / 3, Math.PI / 2, Math.PI]) {
                const q = quaternionFromAngle(angle);
                expect(pointInOBB(5, 5, 5, 5, 10, 10, 0.5, 0.5, q.rz, q.rw)).toBe(true);
            }
        });

        it('should handle custom pivot with rotation', () => {
            const q = quaternionFromAngle(0);
            expect(pointInOBB(5, 5, 0, 0, 10, 10, 0, 0, q.rz, q.rw)).toBe(true);
            expect(pointInOBB(-1, -1, 0, 0, 10, 10, 0, 0, q.rz, q.rw)).toBe(false);
        });

        it('should handle zero-size OBB', () => {
            const q = quaternionFromAngle(Math.PI / 4);
            expect(pointInOBB(5, 5, 5, 5, 0, 0, 0.5, 0.5, q.rz, q.rw)).toBe(true);
            expect(pointInOBB(5.1, 5, 5, 5, 0, 0, 0.5, 0.5, q.rz, q.rw)).toBe(false);
        });
    });

    // =========================================================================
    // createInvVPCache
    // =========================================================================

    describe('createInvVPCache', () => {
        it('should compute inverse on first call', () => {
            const cache = createInvVPCache();
            const vp = identity4();
            cache.update(vp);
            const inv = cache.getInverse(vp);
            expectMatClose(inv, identity4());
        });

        it('should return cached result for same VP', () => {
            const cache = createInvVPCache();
            const vp = translation4(3, 4, 0);
            cache.update(vp);
            const inv1 = cache.getInverse(vp);
            const inv2 = cache.getInverse(vp);
            expect(inv1).toBe(inv2);
        });

        it('should recompute when VP changes', () => {
            const cache = createInvVPCache();
            const vp1 = translation4(1, 0, 0);
            cache.update(vp1);
            const inv1Snapshot = new Float32Array(cache.getInverse(vp1));

            const vp2 = translation4(2, 0, 0);
            cache.update(vp2);
            const inv2 = cache.getInverse(vp2);

            expect(inv2[12]).toBeCloseTo(-2);
            expect(inv1Snapshot[12]).toBeCloseTo(-1);
        });

        it('should return valid inverse (multiply original gives identity)', () => {
            const cache = createInvVPCache();
            const vp = scale4(3, 2, 1);
            vp[15] = 1;
            cache.update(vp);
            const inv = cache.getInverse(vp);
            const product = mulMat4(vp, inv);
            expectMatClose(product, identity4());
        });

        it('should work with update then getInverse sequence', () => {
            const cache = createInvVPCache();
            const vp = translation4(5, -3, 0);
            cache.update(vp);
            const inv = cache.getInverse(vp);
            expect(inv[12]).toBeCloseTo(-5);
            expect(inv[13]).toBeCloseTo(3);
        });
    });
});

// =============================================================================
// screenToWorld under a perspective projection
// =============================================================================

/** Right-handed perspective, matching the engine's `perspective()` in mat4. */
function perspective4(fovY: number, aspect: number, near: number, far: number): Float32Array {
    const m = new Float32Array(16);
    const f = 1 / Math.tan(fovY / 2);
    m[0] = f / aspect;
    m[5] = f;
    m[10] = (far + near) / (near - far);
    m[11] = -1;
    m[14] = (2 * far * near) / (near - far);
    return m;
}

/** Right-handed orthographic, the symmetric [-far, far] the 2D camera builds. */
function ortho4(halfW: number, halfH: number, far: number): Float32Array {
    const m = new Float32Array(16);
    m[0] = 1 / halfW;
    m[5] = 1 / halfH;
    m[10] = -1 / far;
    m[15] = 1;
    return m;
}

describe('screenToWorld across projections', () => {
    // The claim every 2D caller depends on: intersecting the ray costs nothing
    // under an orthographic camera, because x/y do not vary along it.
    it('is unchanged orthographically, whatever plane is asked for', () => {
        const vp = ortho4(160, 120, 1000);
        const inv = invertMatrix4(vp)!;
        const atZero = screenToWorld(480, 180, inv, 0, 0, 640, 480);
        const atFar = screenToWorld(480, 180, inv, 0, 0, 640, 480, -300);

        expect(atZero.x).toBeCloseTo(80, 5);
        expect(atZero.y).toBeCloseTo(-30, 5);
        expect(atFar.x).toBeCloseTo(atZero.x, 5);
        expect(atFar.y).toBeCloseTo(atZero.y, 5);
    });

    // And the claim that makes it necessary: under perspective the same screen
    // point names different world points depending on the depth asked for, so a
    // single answer would have been wrong for every plane but one.
    it('follows the ray under perspective, so the plane decides the answer', () => {
        // Camera at the origin looking down -z; the plane sits at z = -d.
        const vp = perspective4(Math.PI / 2, 1, 0.1, 1000);
        const inv = invertMatrix4(vp)!;

        // Half a viewport to the right ⇒ the ray leaves at 45° with fov 90°,
        // so it crosses z = -d at x = d exactly.
        const near = screenToWorld(640, 240, inv, 0, 0, 640, 480, -10);
        const far = screenToWorld(640, 240, inv, 0, 0, 640, 480, -100);

        expect(near.x).toBeCloseTo(10, 3);
        expect(far.x).toBeCloseTo(100, 3);
        expect(near.y).toBeCloseTo(0, 3);
    });

    it('does not answer with the near plane when a depth is given', () => {
        const vp = perspective4(Math.PI / 2, 1, 0.1, 1000);
        const inv = invertMatrix4(vp)!;
        // The pre-ray implementation ignored ndcZ, which under perspective is the
        // near plane's answer — two orders of magnitude off at this depth.
        const onPlane = screenToWorld(640, 240, inv, 0, 0, 640, 480, -100);
        expect(Math.abs(onPlane.x)).toBeGreaterThan(50);
    });
});

describe('screenToWorld picking planes', () => {
    // What the editor relies on when it tests each candidate on its own plane:
    // under an orthographic view that costs an unproject and changes no answer,
    // so 2D picking cannot regress.
    it('gives one answer per screen point orthographically, at any entity depth', () => {
        const vp = ortho4(160, 120, 1000);
        const inv = invertMatrix4(vp)!;
        const depths = [0, -5, 1, -400, 900];
        const answers = depths.map((z) => screenToWorld(500, 200, inv, 0, 0, 640, 480, z));
        for (const a of answers) {
            expect(a.x).toBeCloseTo(answers[0].x, 6);
            expect(a.y).toBeCloseTo(answers[0].y, 6);
        }
    });

    // And why it is needed: perspective spreads those same depths apart, so a
    // sprite off the 2D plane would be unclickable where it is drawn.
    it('spreads them apart under perspective', () => {
        const vp = perspective4(Math.PI / 2, 4 / 3, 0.1, 1000);
        const inv = invertMatrix4(vp)!;
        const near = screenToWorld(500, 200, inv, 0, 0, 640, 480, -10);
        const far = screenToWorld(500, 200, inv, 0, 0, 640, 480, -400);
        expect(Math.abs(far.x - near.x)).toBeGreaterThan(1);
    });
});

describe('projectWorldPoint carries the same third dimension', () => {
    // The unproject took a plane; the project has to take the point's depth, or
    // an overlay drawn ON an entity (outline, gizmo, screen rect) lands on the
    // entity's shadow at z = 0 instead of on the entity.
    it('is unchanged orthographically, whatever depth the point is at', () => {
        const vp = ortho4(160, 120, 1000);
        const flat = projectWorldPoint(80, -30, 0, vp, 0, 0, 640, 480);
        const deep = projectWorldPoint(80, -30, -400, vp, 0, 0, 640, 480);
        expect(deep.x).toBeCloseTo(flat.x, 6);
        expect(deep.y).toBeCloseTo(flat.y, 6);
    });

    it('projects nearer content further from the centre under perspective', () => {
        const vp = perspective4(Math.PI / 2, 1, 0.1, 1000);
        const near = projectWorldPoint(50, 0, -100, vp, 0, 0, 640, 480);
        const far = projectWorldPoint(50, 0, -400, vp, 0, 0, 640, 480);
        const centre = 320;
        expect(Math.abs(near.x - centre)).toBeGreaterThan(Math.abs(far.x - centre) * 2);
    });

    // The round trip is the whole contract: project a point at its depth, ask the
    // ray for that same plane, and get the point back. Dropping wz breaks this by
    // a factor that grows with depth — which is exactly how a selection outline
    // ends up the wrong size around a sprite it is supposed to trace.
    it('round-trips with screenToWorld on the point own plane, under perspective', () => {
        const vp = perspective4(Math.PI / 2, 4 / 3, 0.1, 1000);
        const inv = invertMatrix4(vp)!;
        // In front of the camera (which sits at the origin looking down -z); z = 0
        // is the eye itself, where a projection divides by zero for anyone.
        for (const z of [-1, -100, -400, -900]) {
            const { x: sx, y: sy } = projectWorldPoint(37, -21, z, vp, 0, 0, 640, 480);
            const back = screenToWorld(sx, sy, inv, 0, 0, 640, 480, z);
            expect(back.x).toBeCloseTo(37, 3);
            expect(back.y).toBeCloseTo(-21, 3);
        }
    });
});

describe('projectWorldPoint says whether a point has a screen position at all', () => {
    // Behind the eye the divide flips x, y AND w, so the point comes back mirrored
    // through the centre of the view — inside the viewport, on the wrong side, and
    // indistinguishable from a real position once w is dropped.
    it('rejects a point behind a perspective eye, which the mirror hides', () => {
        const vp = perspective4(Math.PI / 2, 4 / 3, 0.1, 1000);
        const centre = 320;
        const front = projectWorldPoint(50, 0, -200, vp, 0, 0, 640, 480);
        const behind = projectWorldPoint(50, 0, 200, vp, 0, 0, 640, 480);
        expect(isProjectable(front)).toBe(true);
        expect(isProjectable(behind)).toBe(false);
        expect(front.x).toBeGreaterThan(centre);
        // The mirror: same world x, opposite side, and on screen the whole time.
        expect(behind.x).toBeLessThan(centre);
        expect(behind.x).toBeGreaterThan(0);
    });

    // Off-screen is not the same fact. A collider or a frustum reaching past the
    // edge still HAS coordinates there, and an overlay clipped to the canvas needs
    // them to know which way it left.
    it('keeps a point that is merely outside the viewport', () => {
        const vp = perspective4(Math.PI / 2, 4 / 3, 0.1, 1000);
        const off = projectWorldPoint(5000, 0, -200, vp, 0, 0, 640, 480);
        expect(isProjectable(off)).toBe(true);
        expect(off.x).toBeGreaterThan(640);
    });

    // An orthographic projection has no eye to stand behind: w is 1 everywhere,
    // and the 2D editor — whose content sits at and below z = 0 — depends on that.
    it('accepts every depth orthographically', () => {
        const vp = ortho4(160, 120, 1000);
        for (const z of [-400, 0, 400]) {
            expect(isProjectable(projectWorldPoint(80, -30, z, vp, 0, 0, 640, 480))).toBe(true);
        }
    });

    // What a segment cut at the near plane interpolates on; see the editor's
    // near-plane clipping of collider and frustum wireframes.
    it('reports the clip depth the near plane is expressed in', () => {
        const vp = perspective4(Math.PI / 2, 4 / 3, 0.1, 1000);
        const atNear = projectWorldPoint(0, 0, -0.1, vp, 0, 0, 640, 480);
        expect(atNear.clipZ / atNear.clipW).toBeCloseTo(-1, 5);
        const atFar = projectWorldPoint(0, 0, -1000, vp, 0, 0, 640, 480);
        expect(atFar.clipZ / atFar.clipW).toBeCloseTo(1, 5);
    });
});

describe('nearPlaneSide is what a segment is cut on', () => {
    const vp = perspective4(Math.PI / 2, 4 / 3, 10, 1000);
    const side = (x: number, y: number, z: number) =>
        nearPlaneSide(projectWorldPoint(x, y, z, vp, 0, 0, 640, 480));

    it('is zero on the near plane and signed either side of it', () => {
        expect(side(0, 0, -10)).toBeCloseTo(0, 6);
        expect(side(0, 0, -200)).toBeGreaterThan(0);
        expect(side(0, 0, -1)).toBeLessThan(0);   // between the eye and the near plane
        expect(side(0, 0, 200)).toBeLessThan(0);  // behind the eye
    });

    // The whole cut rests on this: one crossing, solved for one t, and the world
    // point at that t is where the drawable part ends.
    it('is affine along a world segment', () => {
        const a = { x: -300, y: 120, z: -400 };
        const b = { x: 500, y: -80, z: 300 };
        const sa = side(a.x, a.y, a.z);
        const sb = side(b.x, b.y, b.z);
        for (const t of [0.1, 0.37, 0.5, 0.9]) {
            const mid = side(a.x + (b.x - a.x) * t, a.y + (b.y - a.y) * t, a.z + (b.z - a.z) * t);
            expect(mid).toBeCloseTo(sa + (sb - sa) * t, 6);
        }
        // And it does cross, or the case above is never exercised.
        expect(sa * sb).toBeLessThan(0);
    });

    // Orthographically w does not vary and the volume the editor builds is vast, so
    // nothing a 2D scene contains is ever on the wrong side of this.
    it('keeps every depth a 2D scene uses under an orthographic projection', () => {
        const flat = ortho4(160, 120, 100000);
        for (const z of [-4000, -400, 0, 400]) {
            expect(nearPlaneSide(projectWorldPoint(80, -30, z, flat, 0, 0, 640, 480)))
                .toBeGreaterThan(0);
        }
    });
});

describe('projectDirectionAt answers for the point, not just for the camera', () => {
    const VP_W = 830;
    const VP_H = 494;
    const ASPECT = VP_W / VP_H;
    const project = (vp: Float32Array, x: number, y: number, z: number): ProjectedPoint =>
        projectWorldPoint(x, y, z, vp, 0, 0, VP_W, VP_H);
    const direction = (vp: Float32Array, at: ProjectedPoint, d: readonly number[]) =>
        projectDirectionAt(at, d[0], d[1], d[2], vp, 0, 0, VP_W, VP_H);

    // The derivative and the projector have to be the same function, or an arm is
    // drawn along one and dragged along the other.
    it('is the projection own slope, to the digit a difference can measure', () => {
        const vp = perspective4(Math.PI / 3, ASPECT, 1, 5000);
        const h = 1e-4;
        for (const [x, y, z] of [[0, 0, -600], [500, 200, -600], [-320, -90, -1800]]) {
            for (const d of [[1, 0, 0], [0, 1, 0], [0, 0, 1]]) {
                const here = project(vp, x, y, z);
                const step = project(vp, x + d[0] * h, y + d[1] * h, z + d[2] * h);
                const slope = direction(vp, here, d);
                expect(slope.x).toBeCloseTo((step.x - here.x) / h, 4);
                expect(slope.y).toBeCloseTo((step.y - here.y) / h, 4);
            }
        }
    });

    // Orthographically there is no divide to vary, so the camera alone DOES answer
    // — which is why a basis read off it was right until the eye gained a fov.
    it('is the same everywhere under an orthographic projection', () => {
        const vp = ortho4(160 * ASPECT, 160, 4000);
        for (const d of [[1, 0, 0], [0, 1, 0], [0, 0, 1]]) {
            const centre = direction(vp, project(vp, 0, 0, 0), d);
            const corner = direction(vp, project(vp, 150 * ASPECT, 140, -900), d);
            expect(corner.x).toBeCloseTo(centre.x, 9);
            expect(corner.y).toBeCloseTo(centre.y, 9);
        }
    });

    // Head-on, world Z runs straight at the eye and projects to nothing — AT THE
    // CENTRE. Off to the side the same axis leans outward, and by a length worth
    // grabbing: the arm a camera-only basis draws as zero everywhere.
    it('turns the axis that runs at the eye into a real arm off-centre', () => {
        const vp = perspective4(Math.PI / 3, ASPECT, 1, 5000);
        const centre = direction(vp, project(vp, 0, 0, -600), [0, 0, 1]);
        expect(Math.hypot(centre.x, centre.y)).toBeLessThan(1e-9);

        const at = project(vp, 500, 0, -600);
        const alongZ = direction(vp, at, [0, 0, 1]);
        const alongX = direction(vp, at, [1, 0, 0]);
        expect(alongZ.x).toBeGreaterThan(0); // outward, toward the edge it sits near
        expect(Math.hypot(alongZ.x, alongZ.y)).toBeGreaterThan(Math.hypot(alongX.x, alongX.y) * 0.5);
    });
});

/**
 * The property a game reads a click through, spelled out.
 *
 * A 2D camera fits by HEIGHT: orthoSize is the half-height, and the half-WIDTH
 * follows from the viewport's aspect. So the visible world is `centre ± orthoSize`
 * vertically but `centre ± orthoSize * aspect` horizontally, and only at the
 * design aspect do those coincide with the design box.
 *
 * A game that assumes the design box instead — `worldX = px * (designW / rectW)`
 * — is exact at the centre and wrong by more the further out the click is. On a
 * chessboard in a maximised browser window that is a whole file: click the a-file,
 * select the b-file. Hence CameraView.screenToWorld rather than arithmetic.
 */
describe('an orthographic 2D camera fits by height', () => {
    const ORTHO = 360, CX = 640, CY = 360;
    // What the camera builds: translate to the centre, then the ortho box.
    const camera = (vpW: number, vpH: number) => {
        const halfW = ORTHO * (vpW / vpH);
        const vp = ortho4(halfW, ORTHO, 1000);
        // Fold the centre in: world → view is a translation by -centre.
        const m = new Float32Array(vp);
        m[12] = -CX / halfW;
        m[13] = -CY / ORTHO;
        return { vp: m, inv: invertMatrix4(m)!, halfW };
    };

    it('shows centre ± orthoSize*aspect across, whatever the viewport shape', () => {
        for (const [w, h] of [[1280, 720], [1600, 800], [1920, 950]]) {
            const { inv, halfW } = camera(w, h);
            const left = screenToWorld(0, h / 2, inv, 0, 0, w, h);
            const right = screenToWorld(w, h / 2, inv, 0, 0, w, h);
            expect(left.x).toBeCloseTo(CX - halfW, 3);
            expect(right.x).toBeCloseTo(CX + halfW, 3);
            // Vertically it is always the design height — that is what "fit by
            // height" means, and why only the horizontal answer moves.
            // screenY here is GL's (up from the BOTTOM), not the DOM's: a caller
            // holding a MouseEvent has to flip it first, and one that forgets
            // gets a board mirrored about its middle rank.
            const atBottom = screenToWorld(w / 2, 0, inv, 0, 0, w, h);
            const atTop = screenToWorld(w / 2, h, inv, 0, 0, w, h);
            expect(atBottom.y).toBeCloseTo(CY - ORTHO, 3);
            expect(atTop.y).toBeCloseTo(CY + ORTHO, 3);
        }
    });

    it('disagrees with design-box arithmetic away from the centre', () => {
        const [w, h] = [1600, 800];
        const { inv } = camera(w, h);
        const designX = (px: number) => px * (1280 / w); // what a hand-rolled game does
        // Dead centre: the two agree, which is why the bug looks intermittent.
        expect(screenToWorld(w / 2, h / 2, inv, 0, 0, w, h).x).toBeCloseTo(designX(w / 2), 3);
        // A tenth of the way in: off by more than half a 80-unit board square.
        const near = screenToWorld(w * 0.1, h / 2, inv, 0, 0, w, h).x;
        expect(Math.abs(near - designX(w * 0.1))).toBeGreaterThan(40);
    });
});

// =============================================================================
// The ray itself, and screenToWorld as its z-plane case
// =============================================================================

describe('screenRay', () => {
    // What a screen point actually names. `screenToWorld` answers for ONE plane —
    // the one 2D content sits on — and a caller that needs a different one (an
    // editor dragging along an axis) could not ask before this existed.
    it('is a unit ray leaving the near plane', () => {
        const inv = invertMatrix4(perspective4(Math.PI / 2, 1, 0.1, 1000))!;
        const ray = screenRay(320, 240, inv, 0, 0, 640, 480);
        const len = Math.hypot(ray.dir.x, ray.dir.y, ray.dir.z);
        expect(len).toBeCloseTo(1, 6);
        // Down the centre of a camera at the origin looking along -z.
        expect(ray.dir.z).toBeCloseTo(-1, 6);
        expect(ray.origin.z).toBeCloseTo(-0.1, 3);
    });

    // The plane no z-keyed call can express: the GROUND, which is where 3D content
    // stands. A 45° ray meets y = -10 at z = -10 — that is the whole point of
    // handing the plane in rather than assuming it.
    it('meets a tilted plane where the geometry says', () => {
        const inv = invertMatrix4(perspective4(Math.PI / 2, 1, 0.1, 1000))!;
        const ray = screenRay(320, 0, inv, 0, 0, 640, 480);
        const hit = rayPlaneHit(ray, { x: 0, y: -10, z: 0 }, { x: 0, y: 1, z: 0 })!;
        expect(hit).not.toBeNull();
        expect(hit.y).toBeCloseTo(-10, 3);
        expect(hit.z).toBeCloseTo(-10, 3);
        expect(hit.x).toBeCloseTo(0, 3);
    });

    it('has no answer for a plane it runs along', () => {
        const inv = invertMatrix4(perspective4(Math.PI / 2, 1, 0.1, 1000))!;
        const ray = screenRay(320, 240, inv, 0, 0, 640, 480);
        expect(rayPlaneHit(ray, { x: 0, y: 0, z: -5 }, { x: 1, y: 0, z: 0 })).toBeNull();
    });

    // The refactor's contract: the old entry point is the new one with the plane
    // 2D content lives on, so no 2D caller can drift from the ray.
    it('is what screenToWorld intersects, for every plane and projection', () => {
        for (const vp of [ortho4(160, 120, 1000), perspective4(Math.PI / 2, 4 / 3, 0.1, 1000)]) {
            const inv = invertMatrix4(vp)!;
            for (const [sx, sy] of [[0, 0], [320, 240], [637, 11], [500, 200]]) {
                for (const planeZ of [0, -10, 37, -400]) {
                    const viaPlane = screenToWorld(sx, sy, inv, 0, 0, 640, 480, planeZ);
                    const ray = screenRay(sx, sy, inv, 0, 0, 640, 480);
                    const hit = rayPlaneHit(ray, { x: 0, y: 0, z: planeZ }, { x: 0, y: 0, z: 1 });
                    expect(hit).not.toBeNull();
                    expect(viaPlane.x).toBeCloseTo(hit!.x, 4);
                    expect(viaPlane.y).toBeCloseTo(hit!.y, 4);
                    expect(hit!.z).toBeCloseTo(planeZ, 4);
                }
            }
        }
    });
});