@pmndrs/klipp 0.0.0-stage → 0.14.0

package/dist/core/body/positionComposer.d.ts

@@ -0,0 +1,56 @@
+import { type Vec3 } from 'math';
+import type { CameraState } from '../CameraState.js';
+import type { TargetPose } from '../TargetPose.js';
+import type { DamperState, DampingConstant, Vector3DamperState } from '../damping/damping.js';
+import type { PredictorState } from '../damping/predictor.js';
+export type PositionComposerParams = {
+    /** Desired distance from the camera to the target. */
+    cameraDistance: number;
+    /** Where the target should land on screen: `[x, y]`, `0` = center, `±1` = edge. */
+    screenPosition: [number, number];
+    /** Viewport width divided by height. */
+    aspect: number;
+    /** Allowed target drift from `screenPosition` before the camera shifts laterally. */
+    deadZone: [number, number];
+    /** Response time for dolly and lateral composition. */
+    damping: DampingConstant;
+    /** Maximum allowed target drift, enforced immediately. */
+    hardLimit: [number, number];
+    /** Allowed target depth drift before the camera dollies. */
+    depthDeadZone: number;
+    /** Maximum damping speed for both stages, in world units/sec. */
+    maxSpeed: number;
+    /** Seconds to extrapolate the target's tracked position ahead by. */
+    lookaheadTime: number;
+    /** Smooth-time budget (seconds) for the velocity estimate driving `lookaheadTime`. */
+    lookaheadSmoothing: number;
+    /** Whether lookahead ignores vertical movement. */
+    lookaheadIgnoreY: boolean;
+};
+/** Every setting from `settings`, or its default. */
+export declare const createParams: (settings?: Partial<PositionComposerParams>) => PositionComposerParams;
+export type PositionComposerState = {
+    damper: Vector3DamperState;
+    depthDamper: DamperState;
+    predictor: PredictorState;
+    primed: boolean;
+    /** Activation seen while the target was unresolved, applied on the first frame that has one. */
+    activationPending: boolean;
+    /** Whether that pending activation was primed. */
+    activationPrimed: boolean;
+    /** Last desired lateral position, kept while the target stays inside the dead zone. */
+    lastActiveDesiredPosition: Vec3;
+    hasActiveDesiredPosition: boolean;
+};
+export declare const createState: () => PositionComposerState;
+/** Only extents with a dead zone or hard limit are read, so callers can skip resolving them otherwise. */
+export declare const needsExtent: (params: PositionComposerParams) => boolean;
+/**
+ * Positions `out` using depth and screen-space composition around the target and its `extent`. A `null`
+ * target leaves `out` as is.
+ */
+export declare function update(out: CameraState, state: PositionComposerState, params: PositionComposerParams, targetPose: TargetPose | null, dt: number, justActivated: boolean): void;
+/** Restart the lookahead history, for when the target switches to a different object. */
+export declare function retarget(state: PositionComposerState): void;
+/** Start the next activation from `position` instead of snapping to the target. */
+export declare function prime(state: PositionComposerState, params: PositionComposerParams, position: Vec3): void;

package/dist/core/body/positionComposer.js

@@ -0,0 +1,207 @@
+import { __exportAll } from "../../_virtual/_rolldown/runtime.js";
+import { createState as createState$1, createVector3State, damp, dampVector3, reset, resetVector3 } from "../damping/damping.js";
+import { project } from "../TargetExtent.js";
+import { withDefaults } from "../params.js";
+import { addPosition, create, predictDelta, reset as reset$1 } from "../damping/predictor.js";
+import { clamp, degreesToRadians, vec3 } from "math";
+//#region src/core/body/positionComposer.ts
+var positionComposer_exports = /* @__PURE__ */ __exportAll({
+	createParams: () => createParams,
+	createState: () => createState,
+	needsExtent: () => needsExtent,
+	prime: () => prime,
+	retarget: () => retarget,
+	update: () => update
+});
+/** Every setting from `settings`, or its default. */
+var createParams = (settings) => withDefaults({
+	cameraDistance: 10,
+	screenPosition: [0, 0],
+	aspect: 1,
+	deadZone: [0, 0],
+	damping: 0,
+	hardLimit: [0, 0],
+	depthDeadZone: 0,
+	maxSpeed: Infinity,
+	lookaheadTime: 0,
+	lookaheadSmoothing: 1,
+	lookaheadIgnoreY: false
+}, settings);
+var createState = () => ({
+	damper: createVector3State(),
+	depthDamper: createState$1(),
+	predictor: create(),
+	primed: false,
+	activationPending: false,
+	activationPrimed: false,
+	lastActiveDesiredPosition: [
+		0,
+		0,
+		0
+	],
+	hasActiveDesiredPosition: false
+});
+/** Only extents with a dead zone or hard limit are read, so callers can skip resolving them otherwise. */
+var needsExtent = (params) => params.deadZone[0] > 0 || params.deadZone[1] > 0 || params.hardLimit[0] > 0 || params.hardLimit[1] > 0;
+var scratchTarget = [
+	0,
+	0,
+	0
+];
+var scratchLookaheadDelta = [
+	0,
+	0,
+	0
+];
+var scratchForward = [
+	0,
+	0,
+	0
+];
+var scratchRight = [
+	0,
+	0,
+	0
+];
+var scratchUp = [
+	0,
+	0,
+	0
+];
+var scratchRelative = [
+	0,
+	0,
+	0
+];
+var scratchDesired = [
+	0,
+	0,
+	0
+];
+var scratchExtents = [0, 0];
+var forwardAxis = [
+	0,
+	0,
+	-1
+];
+var rightAxis = [
+	1,
+	0,
+	0
+];
+var upAxis = [
+	0,
+	1,
+	0
+];
+/**
+* Positions `out` using depth and screen-space composition around the target and its `extent`. A `null`
+* target leaves `out` as is.
+*/
+function update(out, state, params, targetPose, dt, justActivated) {
+	if (justActivated) {
+		state.activationPending = true;
+		state.activationPrimed = state.primed;
+		state.primed = false;
+	}
+	if (!targetPose) return;
+	const activating = state.activationPending;
+	const skipReset = activating && state.activationPrimed;
+	state.activationPending = false;
+	const { extent } = targetPose;
+	const target = vec3.copy(scratchTarget, targetPose.position);
+	if (activating) reset$1(state.predictor);
+	addPosition(state.predictor, target, dt, params.lookaheadSmoothing);
+	if (params.lookaheadTime > 0) {
+		predictDelta(scratchLookaheadDelta, state.predictor, params.lookaheadTime);
+		if (params.lookaheadIgnoreY) scratchLookaheadDelta[1] = 0;
+		vec3.add(target, target, scratchLookaheadDelta);
+	}
+	vec3.copy(out.target, target);
+	out.hasTarget = true;
+	const position = out.position;
+	vec3.transformQuat(scratchForward, forwardAxis, out.quaternion);
+	vec3.transformQuat(scratchRight, rightAxis, out.quaternion);
+	vec3.transformQuat(scratchUp, upAxis, out.quaternion);
+	vec3.subtract(scratchRelative, target, position);
+	const currentDepth = vec3.dot(scratchRelative, scratchForward);
+	let desiredDepth = params.cameraDistance;
+	let insideDepthDeadZone = false;
+	if (!activating && params.depthDeadZone > 0) {
+		const depthError = currentDepth - params.cameraDistance;
+		insideDepthDeadZone = Math.abs(depthError) <= params.depthDeadZone;
+		if (!insideDepthDeadZone) desiredDepth = params.cameraDistance + clamp(depthError, -params.depthDeadZone, params.depthDeadZone);
+	}
+	if (!insideDepthDeadZone) {
+		if (activating && !skipReset) reset(state.depthDamper);
+		const instant = typeof params.damping === "number" && params.damping <= 0;
+		state.depthDamper.value = currentDepth;
+		const dampedDepth = instant ? desiredDepth : damp(state.depthDamper, desiredDepth, params.damping, dt, params.maxSpeed).value;
+		vec3.scaleAndAdd(position, position, scratchForward, currentDepth - dampedDepth);
+	}
+	vec3.subtract(scratchRelative, target, position);
+	const halfHeight = params.cameraDistance * Math.tan(degreesToRadians(out.fov) / 2);
+	const halfWidth = halfHeight * params.aspect;
+	project(scratchExtents, extent, scratchRight, scratchUp);
+	const extentX = scratchExtents[0] / halfWidth;
+	const extentY = scratchExtents[1] / halfHeight;
+	const currentRight = vec3.dot(scratchRelative, scratchRight);
+	const currentUp = vec3.dot(scratchRelative, scratchUp);
+	let desiredScreenX = params.screenPosition[0];
+	let desiredScreenY = params.screenPosition[1];
+	let insideDeadZone = false;
+	if (!activating && (params.deadZone[0] > 0 || params.deadZone[1] > 0)) {
+		const halfDeadWidth = params.deadZone[0];
+		const halfDeadHeight = params.deadZone[1];
+		const deadExtentX = Math.min(extentX, halfDeadWidth);
+		const deadExtentY = Math.min(extentY, halfDeadHeight);
+		const errorX = currentRight / halfWidth - params.screenPosition[0];
+		const errorY = currentUp / halfHeight - params.screenPosition[1];
+		const edgeErrorX = errorX + Math.sign(errorX) * deadExtentX;
+		const edgeErrorY = errorY + Math.sign(errorY) * deadExtentY;
+		insideDeadZone = Math.abs(edgeErrorX) <= halfDeadWidth && Math.abs(edgeErrorY) <= halfDeadHeight;
+		if (!insideDeadZone) {
+			desiredScreenX = params.screenPosition[0] + clamp(edgeErrorX, -halfDeadWidth, halfDeadWidth) - Math.sign(errorX) * deadExtentX;
+			desiredScreenY = params.screenPosition[1] + clamp(edgeErrorY, -halfDeadHeight, halfDeadHeight) - Math.sign(errorY) * deadExtentY;
+		}
+	}
+	if (!insideDeadZone) {
+		vec3.scaleAndAdd(scratchDesired, position, scratchRight, currentRight - desiredScreenX * halfWidth);
+		vec3.scaleAndAdd(scratchDesired, scratchDesired, scratchUp, currentUp - desiredScreenY * halfHeight);
+		vec3.copy(state.lastActiveDesiredPosition, scratchDesired);
+		state.hasActiveDesiredPosition = true;
+	} else if (state.hasActiveDesiredPosition) vec3.copy(scratchDesired, state.lastActiveDesiredPosition);
+	else vec3.copy(scratchDesired, position);
+	if (activating && !skipReset) resetVector3(state.damper);
+	dampVector3(state.damper, position, scratchDesired, params.damping, dt, params.maxSpeed);
+	if (params.hardLimit[0] <= 0 && params.hardLimit[1] <= 0) return;
+	vec3.subtract(scratchRelative, target, position);
+	const afterRight = vec3.dot(scratchRelative, scratchRight);
+	const afterUp = vec3.dot(scratchRelative, scratchUp);
+	const halfLimitWidth = params.hardLimit[0];
+	const halfLimitHeight = params.hardLimit[1];
+	const limitExtentX = Math.min(extentX, halfLimitWidth);
+	const limitExtentY = Math.min(extentY, halfLimitHeight);
+	const limitErrorX = afterRight / halfWidth - params.screenPosition[0];
+	const limitErrorY = afterUp / halfHeight - params.screenPosition[1];
+	const limitEdgeErrorX = limitErrorX + Math.sign(limitErrorX) * limitExtentX;
+	const limitEdgeErrorY = limitErrorY + Math.sign(limitErrorY) * limitExtentY;
+	if (Math.abs(limitEdgeErrorX) <= halfLimitWidth && Math.abs(limitEdgeErrorY) <= halfLimitHeight) return;
+	const clampedX = params.screenPosition[0] + clamp(limitEdgeErrorX, -halfLimitWidth, halfLimitWidth) - Math.sign(limitErrorX) * limitExtentX;
+	const clampedY = params.screenPosition[1] + clamp(limitEdgeErrorY, -halfLimitHeight, halfLimitHeight) - Math.sign(limitErrorY) * limitExtentY;
+	vec3.scaleAndAdd(position, position, scratchRight, afterRight - clampedX * halfWidth);
+	vec3.scaleAndAdd(position, position, scratchUp, afterUp - clampedY * halfHeight);
+}
+/** Restart the lookahead history, for when the target switches to a different object. */
+function retarget(state) {
+	reset$1(state.predictor);
+}
+/** Start the next activation from `position` instead of snapping to the target. */
+function prime(state, params, position) {
+	dampVector3(state.damper, position, position, params.damping, 0);
+	state.depthDamper.value = 0;
+	damp(state.depthDamper, 0, params.damping, 0);
+	state.primed = true;
+}
+//#endregion
+export { createParams, createState, needsExtent, positionComposer_exports, prime, retarget, update };

package/dist/core/body/safeFromToRotation.d.ts

@@ -0,0 +1,3 @@
+import { type Quat, type Vec3 } from 'math';
+/** Rotation from `from` to `to` as a turn around `up` followed by a pitch, so it never adds roll. */
+export declare function safeFromToRotation(out: Quat, from: Vec3, to: Vec3, up: Vec3): Quat;

package/dist/core/body/safeFromToRotation.js

@@ -0,0 +1,39 @@
+import { quat, vec3 } from "math";
+//#region src/core/body/safeFromToRotation.ts
+var scratchProjectedFrom = [
+	0,
+	0,
+	0
+];
+var scratchProjectedTo = [
+	0,
+	0,
+	0
+];
+var scratchAxis = [
+	0,
+	0,
+	0
+];
+var scratchPitch = [
+	0,
+	0,
+	0,
+	1
+];
+/** Rotation from `from` to `to` as a turn around `up` followed by a pitch, so it never adds roll. */
+function safeFromToRotation(out, from, to, up) {
+	vec3.scaleAndAdd(scratchProjectedFrom, from, up, -vec3.dot(from, up));
+	vec3.scaleAndAdd(scratchProjectedTo, to, up, -vec3.dot(to, up));
+	if (vec3.squaredLength(scratchProjectedFrom) < 1e-10 || vec3.squaredLength(scratchProjectedTo) < 1e-10) {
+		vec3.cross(scratchAxis, from, to);
+		if (vec3.squaredLength(scratchAxis) < 1e-10) vec3.copy(scratchAxis, up);
+		return quat.setAxisAngle(out, vec3.normalize(scratchAxis, scratchAxis), vec3.angle(from, to));
+	}
+	vec3.normalize(scratchAxis, vec3.cross(scratchAxis, up, from));
+	quat.setAxisAngle(scratchPitch, scratchAxis, vec3.angle(to, up) - vec3.angle(from, up));
+	quat.setAxisAngle(out, up, vec3.signedAngle(scratchProjectedFrom, scratchProjectedTo, up));
+	return quat.multiply(out, out, scratchPitch);
+}
+//#endregion
+export { safeFromToRotation };

package/dist/core/body/threeRing.d.ts

@@ -0,0 +1,28 @@
+import { type Vec3 } from 'math';
+/** A horizontal ring around the target. */
+export type Orbit = {
+    /** Horizontal distance from the target. */
+    radius: number;
+    /** Height above the target. */
+    height: number;
+};
+export type Orbits = {
+    top: Orbit;
+    center: Orbit;
+    bottom: Orbit;
+};
+/** A smooth curve through the rings, as `[height, radius]` knots with Bezier control points between them. */
+export type ThreeRingState = {
+    /** An extrapolated end, bottom, center, top and another extrapolated end. */
+    knots: number[];
+    ctrl1: number[];
+    ctrl2: number[];
+    /** Settings the curve was built for. */
+    builtFor: number[];
+};
+export declare const createState: () => ThreeRingState;
+/**
+ * Writes the point of the curve at `t` to `out` as `[0, height, radius]`: `0` is the bottom ring, `0.5` the center
+ * ring and `1` the top ring. Rebuilds the curve only when the rings or the curvature changed.
+ */
+export declare function point(out: Vec3, state: ThreeRingState, orbits: Orbits, splineCurvature: number, t: number): Vec3;

package/dist/core/body/threeRing.js

@@ -0,0 +1,100 @@
+import { __exportAll } from "../../_virtual/_rolldown/runtime.js";
+import { clamp } from "math";
+//#region src/core/body/threeRing.ts
+var threeRing_exports = /* @__PURE__ */ __exportAll({
+	createState: () => createState,
+	point: () => point
+});
+var knotCount = 5;
+var createState = () => ({
+	knots: new Array(10).fill(0),
+	ctrl1: new Array(10).fill(0),
+	ctrl2: new Array(10).fill(0),
+	builtFor: new Array(7).fill(NaN)
+});
+function isBuiltFor(state, orbits, splineCurvature) {
+	const built = state.builtFor;
+	return built[0] === orbits.bottom.height && built[1] === orbits.bottom.radius && built[2] === orbits.center.height && built[3] === orbits.center.radius && built[4] === orbits.top.height && built[5] === orbits.top.radius && built[6] === splineCurvature;
+}
+function setKnot(knots, index, height, radius) {
+	knots[index * 2] = height;
+	knots[index * 2 + 1] = radius;
+}
+var a = new Array(knotCount).fill(0);
+var b = new Array(knotCount).fill(0);
+var c = new Array(knotCount).fill(0);
+var r = new Array(knotCount).fill(0);
+function computeControlPoints({ knots, ctrl1, ctrl2 }) {
+	const n = 4;
+	for (let axis = 0; axis < 2; axis++) {
+		const k = (i) => knots[i * 2 + axis];
+		a[0] = 0;
+		b[0] = 2;
+		c[0] = 1;
+		r[0] = k(0) + 2 * k(1);
+		for (let i = 1; i < 3; i++) {
+			a[i] = 1;
+			b[i] = 4;
+			c[i] = 1;
+			r[i] = 4 * k(i) + 2 * k(i + 1);
+		}
+		a[3] = 2;
+		b[3] = 7;
+		c[3] = 0;
+		r[3] = 8 * k(3) + k(n);
+		for (let i = 1; i < n; i++) {
+			const m = a[i] / b[i - 1];
+			b[i] -= m * c[i - 1];
+			r[i] -= m * r[i - 1];
+		}
+		ctrl1[6 + axis] = r[3] / b[3];
+		for (let i = 2; i >= 0; i--) ctrl1[i * 2 + axis] = (r[i] - c[i] * ctrl1[(i + 1) * 2 + axis]) / b[i];
+		for (let i = 0; i < 3; i++) ctrl2[i * 2 + axis] = 2 * k(i + 1) - ctrl1[(i + 1) * 2 + axis];
+		ctrl2[6 + axis] = .5 * (k(n) + ctrl1[6 + axis]);
+	}
+}
+function build(state, orbits, splineCurvature) {
+	const { bottom, center, top } = orbits;
+	const { knots, builtFor } = state;
+	setKnot(knots, 1, bottom.height, bottom.radius);
+	setKnot(knots, 2, center.height, center.radius);
+	setKnot(knots, 3, top.height, top.radius);
+	const keep = 1 - clamp(splineCurvature, 0, 1);
+	setKnot(knots, 0, keep * (1.5 * bottom.height - .5 * center.height), keep * (1.5 * bottom.radius - .5 * center.radius));
+	setKnot(knots, 4, keep * (1.5 * top.height - .5 * center.height), keep * (1.5 * top.radius - .5 * center.radius));
+	computeControlPoints(state);
+	builtFor[0] = bottom.height;
+	builtFor[1] = bottom.radius;
+	builtFor[2] = center.height;
+	builtFor[3] = center.radius;
+	builtFor[4] = top.height;
+	builtFor[5] = top.radius;
+	builtFor[6] = splineCurvature;
+}
+/**
+* Writes the point of the curve at `t` to `out` as `[0, height, radius]`: `0` is the bottom ring, `0.5` the center
+* ring and `1` the top ring. Rebuilds the curve only when the rings or the curvature changed.
+*/
+function point(out, state, orbits, splineCurvature, t) {
+	if (!isBuiltFor(state, orbits, splineCurvature)) build(state, orbits, splineCurvature);
+	const { knots, ctrl1, ctrl2 } = state;
+	let s = clamp(t, 0, 1) * 2;
+	let segment = 1;
+	if (s > 1) {
+		s -= 1;
+		segment = 2;
+	}
+	const d = 1 - s;
+	const w0 = d * d * d;
+	const w1 = 3 * d * d * s;
+	const w2 = 3 * d * s * s;
+	const w3 = s * s * s;
+	const i = segment * 2;
+	const j = (segment + 1) * 2;
+	out[0] = 0;
+	out[1] = w0 * knots[i] + w1 * ctrl1[i] + w2 * ctrl2[i] + w3 * knots[j];
+	out[2] = w0 * knots[i + 1] + w1 * ctrl1[i + 1] + w2 * ctrl2[i + 1] + w3 * knots[j + 1];
+	return out;
+}
+//#endregion
+export { createState, point, threeRing_exports };

package/dist/core/body/tracker.d.ts

@@ -0,0 +1,42 @@
+import { type Quat, type Vec3 } from 'math';
+import type { TargetPose } from '../TargetPose.js';
+import type { DamperState, DampingConstant, Vector3DamperState } from '../damping/damping.js';
+import { type BindingMode } from './BindingModes.js';
+export type TrackerParams = {
+    /** Rotation frame of the camera offset and the target offset. */
+    bindingMode: BindingMode;
+    /** Response time for following the target position. */
+    damping: DampingConstant;
+    /** Response time for turning with the target, for every `bindingMode` but `worldSpace`. */
+    rotationDamping: DampingConstant;
+    /** Maximum damping speed, in world units/sec. */
+    maxSpeed: number;
+};
+export type TrackerState = {
+    /** Damped target position, the point the camera offset is added to. */
+    trackedPoint: Vec3;
+    previousOffset: Vec3;
+    hasPrevious: boolean;
+    damper: Vector3DamperState;
+    /** Damped `bindingMode` rotation, the frame of the offsets. */
+    orientation: Quat;
+    rotationDamper: DamperState;
+    /** Target rotation captured on entering `lockToTargetOnAssign`, valid while `assigned`. */
+    assignedRotation: Quat;
+    assigned: boolean;
+};
+export declare const createState: () => TrackerState;
+/** Makes the next `trackTarget` snap to the target. */
+export declare function reset(state: TrackerState): void;
+/** Makes the next `trackTarget` ease from `point` and `orientation` instead of snapping to the target. */
+export declare function prime(state: TrackerState, point: Vec3, offset: Vec3, orientation: Quat): void;
+/** Whether `referenceOrientation` will read `target.rotation` this frame. */
+export declare const needsTargetRotation: (state: Pick<TrackerState, 'assigned'>, bindingMode: BindingMode) => boolean;
+/** The rotation `bindingMode` applies to offsets around `target`. Captures it on entering `lockToTargetOnAssign`. */
+export declare function referenceOrientation(out: Quat, state: Pick<TrackerState, 'assignedRotation' | 'assigned'>, bindingMode: BindingMode, target: TargetPose): Quat;
+/**
+ * Damps the tracked point toward the target position plus `targetOffset`, per axis of the camera `offset`'s frame.
+ * When `offset` changes, the tracked point turns with it around the target, so moving the camera is never damped.
+ * Writes the tracked point to `out` and the reference orientation to `outOrientation`.
+ */
+export declare function trackTarget(out: Vec3, outOrientation: Quat, state: TrackerState, params: TrackerParams, target: TargetPose, offset: Vec3, targetOffset: Vec3, dt: number): Vec3;

package/dist/core/body/tracker.js

@@ -0,0 +1,193 @@
+import { __exportAll } from "../../_virtual/_rolldown/runtime.js";
+import { createState as createState$1, createVector3State, damp, dampQuaternion, dampVector3, reset as reset$1, resetVector3 } from "../damping/damping.js";
+import { BindingModes } from "./BindingModes.js";
+import { safeFromToRotation } from "./safeFromToRotation.js";
+import { mat4, quat, vec3 } from "math";
+//#region src/core/body/tracker.ts
+var tracker_exports = /* @__PURE__ */ __exportAll({
+	createState: () => createState,
+	needsTargetRotation: () => needsTargetRotation,
+	prime: () => prime,
+	referenceOrientation: () => referenceOrientation,
+	reset: () => reset,
+	trackTarget: () => trackTarget
+});
+var createState = () => ({
+	trackedPoint: [
+		0,
+		0,
+		0
+	],
+	previousOffset: [
+		0,
+		0,
+		0
+	],
+	hasPrevious: false,
+	damper: createVector3State(),
+	orientation: [
+		0,
+		0,
+		0,
+		1
+	],
+	rotationDamper: createState$1(),
+	assignedRotation: [
+		0,
+		0,
+		0,
+		1
+	],
+	assigned: false
+});
+/** Makes the next `trackTarget` snap to the target. */
+function reset(state) {
+	state.hasPrevious = false;
+	resetVector3(state.damper);
+	reset$1(state.rotationDamper);
+}
+function start(damper) {
+	damp(damper, damper.value, 1, 0);
+}
+/** Makes the next `trackTarget` ease from `point` and `orientation` instead of snapping to the target. */
+function prime(state, point, offset, orientation) {
+	reset(state);
+	vec3.copy(state.trackedPoint, point);
+	vec3.copy(state.previousOffset, offset);
+	quat.copy(state.orientation, orientation);
+	state.hasPrevious = true;
+	start(state.damper.x);
+	start(state.damper.y);
+	start(state.damper.z);
+	start(state.rotationDamper);
+}
+/** Whether `referenceOrientation` will read `target.rotation` this frame. */
+var needsTargetRotation = (state, bindingMode) => bindingMode !== BindingModes.worldSpace && !(bindingMode === BindingModes.lockToTargetOnAssign && state.assigned);
+var worldUp = [
+	0,
+	1,
+	0
+];
+var forwardAxis = [
+	0,
+	0,
+	-1
+];
+var origin = [
+	0,
+	0,
+	0
+];
+var scratchForward = [
+	0,
+	0,
+	0
+];
+var scratchLookMatrix = mat4.create();
+/** The rotation `bindingMode` applies to offsets around `target`. Captures it on entering `lockToTargetOnAssign`. */
+function referenceOrientation(out, state, bindingMode, target) {
+	if (bindingMode !== BindingModes.lockToTargetOnAssign) state.assigned = false;
+	if (bindingMode === BindingModes.worldSpace) return quat.identity(out);
+	if (bindingMode === BindingModes.lockToTargetOnAssign) {
+		if (!state.assigned) {
+			state.assigned = true;
+			if (target.hasRotation) quat.copy(state.assignedRotation, target.rotation);
+			else quat.identity(state.assignedRotation);
+		}
+		return quat.copy(out, state.assignedRotation);
+	}
+	if (!target.hasRotation) return quat.identity(out);
+	quat.copy(out, target.rotation);
+	if (bindingMode === BindingModes.lockToTarget) return out;
+	vec3.transformQuat(scratchForward, forwardAxis, out);
+	if (bindingMode === BindingModes.lockToTargetWithWorldUp) scratchForward[1] = 0;
+	if (vec3.squaredLength(scratchForward) < 1e-10) return out;
+	vec3.normalize(scratchForward, scratchForward);
+	mat4.targetTo(scratchLookMatrix, origin, scratchForward, worldUp);
+	return quat.fromMat4(out, scratchLookMatrix);
+}
+var scratchGoal = [
+	0,
+	0,
+	0
+];
+var scratchReference = [
+	0,
+	0,
+	0,
+	1
+];
+var scratchWorldOffset = [
+	0,
+	0,
+	0
+];
+var scratchPreviousOffset = [
+	0,
+	0,
+	0
+];
+var scratchRotation = [
+	0,
+	0,
+	0,
+	1
+];
+var scratchDelta = [
+	0,
+	0,
+	0
+];
+var scratchStep = [
+	0,
+	0,
+	0
+];
+var scratchFrame = [
+	0,
+	0,
+	0,
+	1
+];
+var scratchFrameInverse = [
+	0,
+	0,
+	0,
+	1
+];
+/**
+* Damps the tracked point toward the target position plus `targetOffset`, per axis of the camera `offset`'s frame.
+* When `offset` changes, the tracked point turns with it around the target, so moving the camera is never damped.
+* Writes the tracked point to `out` and the reference orientation to `outOrientation`.
+*/
+function trackTarget(out, outOrientation, state, params, target, offset, targetOffset, dt) {
+	referenceOrientation(scratchReference, state, params.bindingMode, target);
+	if (state.hasPrevious) dampQuaternion(state.rotationDamper, state.orientation, scratchReference, params.rotationDamping, dt);
+	else {
+		quat.copy(state.orientation, scratchReference);
+		start(state.rotationDamper);
+	}
+	quat.copy(outOrientation, state.orientation);
+	vec3.add(scratchGoal, target.position, vec3.transformQuat(scratchGoal, targetOffset, outOrientation));
+	vec3.transformQuat(scratchWorldOffset, offset, outOrientation);
+	if (state.hasPrevious && !vec3.exactEquals(state.previousOffset, offset)) {
+		vec3.transformQuat(scratchPreviousOffset, state.previousOffset, outOrientation);
+		safeFromToRotation(scratchRotation, scratchPreviousOffset, scratchWorldOffset, worldUp);
+		vec3.subtract(scratchDelta, state.trackedPoint, scratchGoal);
+		vec3.add(state.trackedPoint, scratchGoal, vec3.transformQuat(scratchDelta, scratchDelta, scratchRotation));
+	}
+	vec3.copy(state.previousOffset, offset);
+	state.hasPrevious = true;
+	vec3.cross(scratchDelta, scratchWorldOffset, worldUp);
+	if (vec3.squaredLength(scratchDelta) < 1e-10) quat.copy(scratchFrame, outOrientation);
+	else quat.fromMat4(scratchFrame, mat4.targetTo(scratchLookMatrix, origin, scratchWorldOffset, worldUp));
+	quat.conjugate(scratchFrameInverse, scratchFrame);
+	vec3.subtract(scratchDelta, scratchGoal, state.trackedPoint);
+	vec3.transformQuat(scratchDelta, scratchDelta, scratchFrameInverse);
+	vec3.zero(scratchStep);
+	dampVector3(state.damper, scratchStep, scratchDelta, params.damping, dt, params.maxSpeed);
+	vec3.add(state.trackedPoint, state.trackedPoint, vec3.transformQuat(scratchStep, scratchStep, scratchFrame));
+	return vec3.copy(out, state.trackedPoint);
+}
+//#endregion
+export { createState, needsTargetRotation, prime, referenceOrientation, reset, trackTarget, tracker_exports };

package/dist/core/damping/Damper.d.ts

@@ -0,0 +1,11 @@
+import * as damping from './damping.js';
+import type { DampingConstant } from './damping.js';
+/** Stateful wrapper over `damp`. */
+export declare class Damper {
+    readonly state: damping.DamperState;
+    get velocity(): number;
+    set velocity(value: number);
+    update(current: number, target: number, dampingTime: DampingConstant, dt: number, maxSpeed?: number, epsilon?: number): number;
+    /** Reset the spring state so the next call snaps to the target again. */
+    reset(): void;
+}