forgeax-engine-math

Pure functions, out-parameter-first, SoA-friendly math. Functions that write output storage require an explicit out to reuse caller-owned buffers. Returning the same out is allowed; optional/default output allocation is forbidden. Covers @forgeax/engine-math.

Mental model

Namespaces (vec3 / mat4 / quat / color ...) group pure functions with out first: vec3.add(out, a, b) writes and returns out, allowing buffer reuse without GC. A common task is reading an entity's world pose: GlobalTransform.world is a derived column-major mat4 of 16 floats, updated every frame. Author local TRS; let the engine derive world transforms. Read position and basis vectors with mat4.getTranslation/getForward/getUp/getRight instead of unpacking matrices. Conversely, screenToRay constructs a world ray from screen coordinates and view/projection matrices.

Core API quick reference

[!NOTE] Transform stores authored local TRS only; transient GlobalTransform.world stores the resolved world matrix, written each frame by propagateTransforms. Raw world.spawn must attach both components; SceneAsset/mount helpers supply the pair automatically.

Sample a path by distance

Use curve3.catmullRom(out, controls, t, { parameterization: 'centripetal' }) (default) or explicit uniform / chordal. closed: true wraps controls without a duplicate endpoint. curve3.catmullRomTangent supplies the analytic direction. Build curve3.arcLengths(new Float32Array(subdivisions + 1), sample) once, then sample at curve3.parameterAtDistance(lengths, travelledDistance). Rebuild after control edits; increase subdivisions until the application's error budget converges. The caller owns the table; no Scene/animation cache is introduced.

Read an entity pose

flowchart LR
  T["world.get(e, GlobalTransform).unwrap().world<br/>16 floats, column-major mat4"] --> G["mat4.getTranslation / getForward / getUp / getRight"]
  G --> P["Use position and basis vectors in game logic"]
  S["screenX, screenY + view/proj"] --> R["screenToRay -> Ray"]
  R --> H["rayAabbIntersects -> hit test"]

Usage skeleton

import { mat4, vec3 } from '@forgeax/engine-math';
import { GlobalTransform } from '@forgeax/engine-scene';

// read world-space pose off GlobalTransform.world (a live 16-float column-major Float32Array)
const worldMat = world.get(entity, GlobalTransform).unwrap().world;
const pos = mat4.getTranslation(vec3.create(), worldMat); // m[12..14]
const fwd = mat4.getForward(vec3.create(), worldMat);     // -Z basis
const up = mat4.getUp(vec3.create(), worldMat);           // +Y basis

// out-param idiom: allocate once, reuse across frames
const tmp = vec3.create();
vec3.scale(tmp, fwd, 5);          // tmp = fwd * 5
vec3.add(pos, pos, tmp);          // pos = pos + tmp (writes into pos, returns it)

import { screenToRay, rayAabbIntersects, ray as rayNs } from '@forgeax/engine-math';

const r = screenToRay(rayNs.create(new Float32Array(6)), mouseX, mouseY, vpW, vpH, viewMat, projMat);
const hit = rayAabbIntersects(r, entityAabb); // hit.hit -> boolean

import { ray, mat4, vec2 } from '@forgeax/engine-math';

// world -> screen: project a 3D point to pixels, y-down from top-left.
const vp = mat4.computeViewProj(mat4.create(), eye, target, up, fovY, aspect, 0.1, 100);
const out = vec2.create();
const r = ray.worldToScreen(out, worldPos, vp, canvasW, canvasH);
if (r.onScreen && !r.behind) {
  // out[0], out[1] are valid pixels for DOM overlays or HUD anchors.
}

import { pickVertexOnEntity, pickVertex } from '@forgeax/engine-picking';

// propagateTransforms must have run for this frame (D-9 precondition).
propagateTransforms(world);

// Nearest vertex on one entity; omitted limit -> VertexHit|undefined.
const hit = pickVertexOnEntity(world, cameraEntity, sx, sy, w, h, entity);
if (hit) {
  // hit.worldPos / vertexIndex / screenDist / worldDist / deformed
}

// Whole-scene query with limit -> VertexHit[], ascending screenDist.
const candidates = pickVertex(world, cameraEntity, sx, sy, w, h, { limit: 5 });

worldToScreen: world coordinates to screen pixels

ray.worldToScreen is the dual of screenToRay: project a world-space 3D point back to screen pixels. It computes mat4 * vec4 internally to preserve pre-division w; projectPoint discards w and cannot be reused.

import { ray, mat4 } from '@forgeax/engine-math';

const vp = mat4.computeViewProj(mat4.create(), eye, target, up, fovY, aspect, near, far);
const out = vec2.create();
const result = ray.worldToScreen(out, worldPos, vp, canvas.width, canvas.height);
// result.onScreen -- NDC xyz are all inside clip space.
// result.behind -- behind the camera (w < 0); out is meaningless.
// !onScreen && !behind: outside the frustum but in front; out remains valid for screen-edge clamping.

• Out parameter: the first argument is Vec2, written with y-down, top-left pixel coordinates: px = (ndc.x * 0.5 + 0.5) * w, py = (1 - (ndc.y * 0.5 + 0.5)) * h.
• Plain-data flags: returns { onScreen: boolean, behind: boolean }.
• Degenerate canvas: canvasW <= 0 || canvasH <= 0 returns { onScreen: false, behind: false }, leaving out unchanged.
• Barrel import: import { ray } from '@forgeax/engine-math'; ray.worldToScreen(...); symmetric with the screenToRay namespace.

computeViewProj: perspective and view composition

mat4.computeViewProj composes mat4.perspective * mat4.lookAt using plain numbers and Vec3Like arguments. It has no runtime POD dependency and follows the abstraction of lookAt / perspective (charter P4).

const vp = mat4.computeViewProj(mat4.create(), eye, target, up, fovY, aspect, near, far);
// Equivalent to:
// const view = mat4.lookAt(mat4.create(), eye, target, up);
// const proj = mat4.perspective(mat4.create(), fovY, aspect, near, far);
// const vp = mat4.multiply(mat4.create(), proj, view);

• Signature: computeViewProj(out, eye, target, up, fovYRadians, aspect, near, far): Mat4.
• Out-parameter style: writes and returns the first argument.
• Composition: a convenience operation, identified in JSDoc; internally lookAt + perspective, then multiply.
• Typical use: supply worldToScreen for 3D-to-2D projection, without coupling to engine components.

Screen picking: vertex queries (pickVertex / pickVertexOnEntity)

Vertex picking queries without editing. Import from @forgeax/engine-runtime; it composes rayTriangleIntersects and screenToRay.

Return contract: omitted limit returns VertexHit | undefined, supporting safe if-hit narrowing and direct hit.worldPos access without casts. With limit, returns VertexHit[]: empty means miss; a limit above the hit count returns all candidates. TypeScript distinguishes these forms; do not access hit[0] or .length when limit is omitted.

Ordering: ascending screenDist puts the nearest screen projection first. Use worldDist for world-space ordering or weighting. Behind-camera vertices (behind=true) are excluded; off-screen vertices in front remain candidates for edge snapping.

Degenerate input: skip triangle-strip, line, and point submeshes; only triangle-list participates. Without indices, use successive triples. Skip Uint16Array positions, matching computeAABB; exclude NaN/Inf vertices. Empty meshes return undefined / [].

Errors: reuse PickError; the only thrown error is camera-component-missing. Missing/empty/degraded vertices return undefined / [] as recoverable misses without interrupting batch queries.

import { pickVertexOnEntity, pickVertex, type VertexHit } from '@forgeax/engine-picking';

const hit = pickVertexOnEntity(world, cameraEntity, sx, sy, w, h, entity);
if (hit) {
  const { entity, vertexIndex, worldPos, screenDist, worldDist, deformed } = hit;
  // worldPos: Vec3Like (Float32Array-like), world-space coords
  // deformed: true when mesh is Morph/Skin evaluated -> worldPos is current pose
}

Pitfalls

• Out parameters overwrite buffers: vec3.add(out, a, b) writes and returns out. const c = vec3.add(a, a, b) overwrites a; use a separate buffer to preserve it.
• Column-major layout: GlobalTransform.world matches GPU/WGSL mat4x4<f32>; translation is column 3 (world[12..14]). A newly spawned GlobalTransform with data: {} is identity before its first propagation, not uninitialized data.
• Silent degenerate fallback: invalid math input (zero-length normalization, perspective division with w'=0) falls back to safe values such as (0,0,0) without throwing. Callers own guards; this thin math layer prioritizes performance over charter P3. See the README's degenerate-input table.
• Check worldToScreen.behind before screen-edge clamping: when true, out is meaningless and can project behind-camera points into an opposite quadrant.
• Run propagateTransforms before vertex picking, as with pick(). Queries read GlobalTransform.world directly without propagation; newly spawned entities otherwise retain identity and yield incorrect worldPos without crashing.
• Current CPU pose only: vertex and triangle queries share Morph-then-Skin projection. Unavailable vertex poses yield no candidates; use pickTriangle for a structured unavailable result. Propagate joints first. Custom shaders, displacement and alpha coverage are not reconstructed.
• For higher-level rendering/picking symptoms, see forgeax-engine-debug.

Further reading

• Namespace/function quick reference, naming, degenerate-input policy, and three NDC projection modes: packages/math/README.md; README and count-math-exports.mjs own export counts.
• Pose helpers (getTranslation/getForward/getUp/getRight): packages/math/src/mat4.ts.
• Picking (screenToRay / rayAabbIntersects / rayTriangleIntersects / mat4.unproject / worldToScreen): packages/math/src/ray.ts and packages/math/src/mat4.ts; runtime pick(...): packages/runtime/README.md Picking; vertex helpers: Vertex Picking.
• Derived GlobalTransform.world contract: packages/runtime/README.md, Transform: local TRS + world mat4.