@flare-engine/math 0.3.0 → 0.4.0

package/dist/index.js

@@ -271,6 +271,141 @@ const Color = {
 	}
 };
 //#endregion
+//#region src/curves.ts
+/**
+* Parametric curves — quadratic/cubic Bézier and Catmull-Rom — plus approximate
+* arc length for each.
+*
+* Every sampler comes in two forms, per the repo's hot-path convention: an
+* allocating one returning a fresh `Vec2`, and an `…Into` one writing to a
+* caller-owned buffer. Sampling a path each frame is exactly the case the
+* `…Into` forms exist for.
+*
+* Control points are passed as loose numbers rather than `Vec2` objects so a
+* caller holding coordinates in a `Float32Array` — the documented storage for
+* bulk numeric data — can sample without building temporaries first.
+*/
+/** Quadratic Bézier at `t`, writing into `out`. `t` is clamped to [0, 1]. */
+function bezier2Into(p0x, p0y, p1x, p1y, p2x, p2y, t, out) {
+	const u = t < 0 ? 0 : t > 1 ? 1 : t;
+	const v = 1 - u;
+	const a = v * v;
+	const b = 2 * v * u;
+	const c = u * u;
+	out.x = a * p0x + b * p1x + c * p2x;
+	out.y = a * p0y + b * p1y + c * p2y;
+	return out;
+}
+/** Quadratic Bézier at `t`. Allocates — see `bezier2Into` for the hot path. */
+function bezier2(p0x, p0y, p1x, p1y, p2x, p2y, t) {
+	return bezier2Into(p0x, p0y, p1x, p1y, p2x, p2y, t, {
+		x: 0,
+		y: 0
+	});
+}
+/** Cubic Bézier at `t`, writing into `out`. `t` is clamped to [0, 1]. */
+function bezier3Into(p0x, p0y, p1x, p1y, p2x, p2y, p3x, p3y, t, out) {
+	const u = t < 0 ? 0 : t > 1 ? 1 : t;
+	const v = 1 - u;
+	const vv = v * v;
+	const uu = u * u;
+	const a = vv * v;
+	const b = 3 * vv * u;
+	const c = 3 * v * uu;
+	const d = uu * u;
+	out.x = a * p0x + b * p1x + c * p2x + d * p3x;
+	out.y = a * p0y + b * p1y + c * p2y + d * p3y;
+	return out;
+}
+/** Cubic Bézier at `t`. Allocates — see `bezier3Into` for the hot path. */
+function bezier3(p0x, p0y, p1x, p1y, p2x, p2y, p3x, p3y, t) {
+	return bezier3Into(p0x, p0y, p1x, p1y, p2x, p2y, p3x, p3y, t, {
+		x: 0,
+		y: 0
+	});
+}
+/**
+* Centripetal-free (uniform) Catmull-Rom spline at `t`, writing into `out`.
+*
+* The curve passes **through** `p1` and `p2`; `p0` and `p3` are the neighbouring
+* control points that set the tangents, and `t` runs from `p1` (0) to `p2` (1).
+* That interpolating property is the reason to reach for this over a Bézier when
+* a path must hit its waypoints exactly.
+*/
+function catmullRomInto(p0x, p0y, p1x, p1y, p2x, p2y, p3x, p3y, t, out) {
+	const u = t < 0 ? 0 : t > 1 ? 1 : t;
+	const uu = u * u;
+	const uuu = uu * u;
+	out.x = .5 * (2 * p1x + (-p0x + p2x) * u + (2 * p0x - 5 * p1x + 4 * p2x - p3x) * uu + (-p0x + 3 * p1x - 3 * p2x + p3x) * uuu);
+	out.y = .5 * (2 * p1y + (-p0y + p2y) * u + (2 * p0y - 5 * p1y + 4 * p2y - p3y) * uu + (-p0y + 3 * p1y - 3 * p2y + p3y) * uuu);
+	return out;
+}
+/** Catmull-Rom at `t`. Allocates — see `catmullRomInto` for the hot path. */
+function catmullRom(p0x, p0y, p1x, p1y, p2x, p2y, p3x, p3y, t) {
+	return catmullRomInto(p0x, p0y, p1x, p1y, p2x, p2y, p3x, p3y, t, {
+		x: 0,
+		y: 0
+	});
+}
+/** Scratch buffer for the length helpers — they are not reentrant, which is
+*  fine because they do not call user code. */
+const _scratch = {
+	x: 0,
+	y: 0
+};
+/**
+* Approximate arc length by sampling `segments` chords.
+*
+* Always an **underestimate**: a chord is the shortest path between its
+* endpoints, so a polyline through the curve is never longer than the curve.
+* Error falls roughly with the square of `segments`; 16 is a reasonable default
+* for UI paths, more for anything a camera follows closely.
+*/
+function bezier2Length(p0x, p0y, p1x, p1y, p2x, p2y, segments = 16) {
+	const n = segments < 1 ? 1 : segments | 0;
+	let total = 0;
+	let px = p0x;
+	let py = p0y;
+	for (let i = 1; i <= n; i++) {
+		bezier2Into(p0x, p0y, p1x, p1y, p2x, p2y, i / n, _scratch);
+		total += Math.hypot(_scratch.x - px, _scratch.y - py);
+		px = _scratch.x;
+		py = _scratch.y;
+	}
+	return total;
+}
+/** Approximate arc length of a cubic Bézier. See `bezier2Length`. */
+function bezier3Length(p0x, p0y, p1x, p1y, p2x, p2y, p3x, p3y, segments = 16) {
+	const n = segments < 1 ? 1 : segments | 0;
+	let total = 0;
+	let px = p0x;
+	let py = p0y;
+	for (let i = 1; i <= n; i++) {
+		bezier3Into(p0x, p0y, p1x, p1y, p2x, p2y, p3x, p3y, i / n, _scratch);
+		total += Math.hypot(_scratch.x - px, _scratch.y - py);
+		px = _scratch.x;
+		py = _scratch.y;
+	}
+	return total;
+}
+/**
+* Approximate arc length of the Catmull-Rom span between `p1` and `p2`.
+* See `bezier2Length` for the accuracy note.
+*/
+function catmullRomLength(p0x, p0y, p1x, p1y, p2x, p2y, p3x, p3y, segments = 16) {
+	const n = segments < 1 ? 1 : segments | 0;
+	let total = 0;
+	let px = p1x;
+	let py = p1y;
+	for (let i = 1; i <= n; i++) {
+		catmullRomInto(p0x, p0y, p1x, p1y, p2x, p2y, p3x, p3y, i / n, _scratch);
+		total += Math.hypot(_scratch.x - px, _scratch.y - py);
+		px = _scratch.x;
+		py = _scratch.y;
+	}
+	return total;
+}
+//#endregion
 //#region src/easings.ts
 const PI = Math.PI;
 const HALF_PI = PI / 2;
@@ -518,6 +653,102 @@ function rayVsRect(originX, originY, dirX, dirY, r) {
 	if (tMax < 0 || tMin > tMax) return null;
 	return tMin >= 0 ? tMin : tMax;
 }
+/**
+* Is `p` on the segment `a`→`b`? Assumes neither is degenerate.
+*/
+function pointOnSegment(px, py, ax, ay, bx, by) {
+	if ((px - ax) * (by - ay) - (py - ay) * (bx - ax) !== 0) return false;
+	const dot = (px - ax) * (bx - ax) + (py - ay) * (by - ay);
+	if (dot < 0) return false;
+	return dot <= (bx - ax) * (bx - ax) + (by - ay) * (by - ay);
+}
+/**
+* Do two segments intersect, including collinear overlap?
+*
+* The companion to `segmentIntersection`: that returns *where* two segments
+* cross and is `null` when there is no single crossing point, which includes
+* collinear segments lying on top of each other. Those genuinely do intersect,
+* so a caller who only needs the yes/no answer asks here instead.
+*/
+function segmentsIntersect(x1, y1, x2, y2, x3, y3, x4, y4) {
+	const d1x = x2 - x1;
+	const d1y = y2 - y1;
+	const d2x = x4 - x3;
+	const d2y = y4 - y3;
+	const denom = d1x * d2y - d1y * d2x;
+	const ex = x3 - x1;
+	const ey = y3 - y1;
+	if (denom === 0) {
+		const aPoint = d1x === 0 && d1y === 0;
+		const bPoint = d2x === 0 && d2y === 0;
+		if (aPoint && bPoint) return x1 === x3 && y1 === y3;
+		if (aPoint) return pointOnSegment(x1, y1, x3, y3, x4, y4);
+		if (bPoint) return pointOnSegment(x3, y3, x1, y1, x2, y2);
+		if (ex * d1y - ey * d1x !== 0) return false;
+		const useX = Math.abs(d1x) >= Math.abs(d1y);
+		return (useX ? Math.min(x1, x2) : Math.min(y1, y2)) <= (useX ? Math.max(x3, x4) : Math.max(y3, y4)) && (useX ? Math.min(x3, x4) : Math.min(y3, y4)) <= (useX ? Math.max(x1, x2) : Math.max(y1, y2));
+	}
+	const t = (ex * d2y - ey * d2x) / denom;
+	const u = (ex * d1y - ey * d1x) / denom;
+	return t >= 0 && t <= 1 && u >= 0 && u <= 1;
+}
+/**
+* Where two segments cross, written into `out`.
+*
+* Returns `null` when there is no **single** crossing point — segments that miss
+* each other, are parallel, or are collinear. Collinear overlap is the case
+* worth knowing about: the segments do intersect, at infinitely many points, so
+* there is no one answer to write into `out`. Use `segmentsIntersect` when the
+* yes/no answer is what you need.
+*
+* `out` is left untouched when the result is `null`.
+*/
+function segmentIntersectionInto(x1, y1, x2, y2, x3, y3, x4, y4, out) {
+	const d1x = x2 - x1;
+	const d1y = y2 - y1;
+	const d2x = x4 - x3;
+	const d2y = y4 - y3;
+	const denom = d1x * d2y - d1y * d2x;
+	if (denom === 0) {
+		const aPoint = d1x === 0 && d1y === 0;
+		const bPoint = d2x === 0 && d2y === 0;
+		if (aPoint && !bPoint && pointOnSegment(x1, y1, x3, y3, x4, y4)) {
+			out.x = x1;
+			out.y = y1;
+			return out;
+		}
+		if (bPoint && !aPoint && pointOnSegment(x3, y3, x1, y1, x2, y2)) {
+			out.x = x3;
+			out.y = y3;
+			return out;
+		}
+		if (aPoint && bPoint && x1 === x3 && y1 === y3) {
+			out.x = x1;
+			out.y = y1;
+			return out;
+		}
+		return null;
+	}
+	const ex = x3 - x1;
+	const ey = y3 - y1;
+	const t = (ex * d2y - ey * d2x) / denom;
+	if (t < 0 || t > 1) return null;
+	const u = (ex * d1y - ey * d1x) / denom;
+	if (u < 0 || u > 1) return null;
+	out.x = x1 + t * d1x;
+	out.y = y1 + t * d1y;
+	return out;
+}
+/**
+* Where two segments cross. Allocates — see `segmentIntersectionInto` for the
+* hot path.
+*/
+function segmentIntersection(x1, y1, x2, y2, x3, y3, x4, y4) {
+	return segmentIntersectionInto(x1, y1, x2, y2, x3, y3, x4, y4, {
+		x: 0,
+		y: 0
+	});
+}
 //#endregion
 //#region src/mat3.ts
 const Mat3 = {
@@ -668,6 +899,25 @@ var SeededRNG = class {
 	int(min, max) {
 		return Math.floor(this.float(min, max + 1));
 	}
+	/**
+	* The generator's entire internal state, as a single int32.
+	*
+	* Enough to resume the exact sequence later, which is what makes a save file
+	* or a replay reproducible: store this alongside the save, hand it back to
+	* `setState`, and the next `next()` returns what it would have returned.
+	*/
+	getState() {
+		return this.state;
+	}
+	/**
+	* Restore a state previously read from `getState`.
+	*
+	* Coerced to int32 exactly as the constructor coerces a seed, so any number
+	* is accepted and a round-trip through JSON is safe.
+	*/
+	setState(state) {
+		this.state = state | 0;
+	}
 };
 /** Returns a random float in [min, max). */
 function randomFloat(min, max) {
@@ -1073,15 +1323,16 @@ const Vec2 = {
 			y: v.y * inv
 		};
 	},
-	/** Zero-alloc; writes into `out`. Mandatory `out` so callers avoid temporaries in hot paths. */
-	normalizeOut(dx, dy, speed, out) {
+	/** The direction of `(dx, dy)` scaled to `length`; writes zeros when `(dx, dy)` is shorter than
+	* 1e-6. Zero-alloc, mandatory `out`; scalar components so hot paths need no temporary Vec2. */
+	scaleToLengthInto(dx, dy, length, out) {
 		const len = Math.sqrt(dx * dx + dy * dy);
 		if (len <= 1e-6) {
 			out.x = 0;
 			out.y = 0;
 			return out;
 		}
-		const inv = speed / len;
+		const inv = length / len;
 		out.x = dx * inv;
 		out.y = dy * inv;
 		return out;
@@ -1238,7 +1489,7 @@ const Vec2 = {
 	/** Zero-alloc homing steer: rotate velocity (vx,vy) toward direction (dx,dy) by at most maxStep
 	* radians, preserving speed; writes into out. Mandatory out. Byte-identical to hand-rolled
 	* homing-bullet steering (Math.hypot speed + atan2 + branch-form turn + cos/sin * speed). */
-	turnVelocityToward(vx, vy, dx, dy, maxStep, out) {
+	turnVelocityTowardInto(vx, vy, dx, dy, maxStep, out) {
 		const speed = Math.hypot(vx, vy);
 		const newAng = rotateTowards(Math.atan2(vy, vx), Math.atan2(dy, dx), maxStep);
 		out.x = Math.cos(newAng) * speed;
@@ -1257,7 +1508,16 @@ exports.Vec2 = Vec2;
 exports.advanceWindowedStreak = advanceWindowedStreak;
 exports.angleDelta = angleDelta;
 exports.approxEquals = approxEquals;
+exports.bezier2 = bezier2;
+exports.bezier2Into = bezier2Into;
+exports.bezier2Length = bezier2Length;
+exports.bezier3 = bezier3;
+exports.bezier3Into = bezier3Into;
+exports.bezier3Length = bezier3Length;
 exports.cappedBonus = cappedBonus;
+exports.catmullRom = catmullRom;
+exports.catmullRomInto = catmullRomInto;
+exports.catmullRomLength = catmullRomLength;
 exports.choose = choose;
 exports.circleVsCircle = circleVsCircle;
 exports.clamp = clamp;
@@ -1313,6 +1573,9 @@ exports.rectVsRect = rectVsRect;
 exports.remainingInWindow = remainingInWindow;
 exports.rotateTowards = rotateTowards;
 exports.seededIndex = seededIndex;
+exports.segmentIntersection = segmentIntersection;
+exports.segmentIntersectionInto = segmentIntersectionInto;
+exports.segmentsIntersect = segmentsIntersect;
 exports.shuffle = shuffle;
 exports.sign = sign;
 exports.smoothStep = smoothStep;