Quat

Quaternion operations for 3D rotations. Accessed via snaptrude.core.math.quat.

Quaternions are opaque QuatHandles; every operation is a host call returning a new handle — inputs are never mutated. Read primitive components back with components. Quaternions avoid gimbal lock and provide smooth interpolation compared to Euler angles.

Types

QuatHandle

An opaque, immutable value handle referencing a quaternion on the host (runtime form "quat_<token>"). See Handles.

QuatComponents

Primitive record returned by reads — plain numbers, not a handle.

Property	Type	Description
x	number	The X component
y	number	The Y component
z	number	The Z component
w	number	The W (scalar) component

Functions

new(x, y, z, w)

Create a quaternion from primitive components.

• Parameters:
  • x: number — The X component
  • y: number — The Y component
  • z: number — The Z component
  • w: number — The W (scalar) component
• Returns: QuatHandle

const { quat } = snaptrude.core.math;
const q = await quat.new(0, 0, 0, 1);

---

identity()

The identity rotation.

• Returns: QuatHandle

---

fromAxisAngle(axis, angle)

Build from a rotation axis and angle (radians).

• Parameters:
  • axis: Vec3Handle — The rotation axis
  • angle: number — The rotation angle in radians
• Returns: QuatHandle
• Throws: HandleInvalidError (code HANDLE_INVALID) if axis is not a valid handle

const { vec3, quat } = snaptrude.core.math;
// 90° rotation around the Y axis
const up = await vec3.new(0, 1, 0);
const rot = await quat.fromAxisAngle(up, Math.PI / 2);

---

fromEuler(x, y, z)

Build from Euler angles (radians).

• Parameters:
  • x: number — Rotation around the X axis in radians
  • y: number — Rotation around the Y axis in radians
  • z: number — Rotation around the Z axis in radians
• Returns: QuatHandle

---

multiply(a, b)

Hamilton product a * b (apply b then a).

Quaternion multiplication is not commutative: a * b ≠ b * a.

• Parameters:
  • a: QuatHandle — First quaternion (applied second)
  • b: QuatHandle — Second quaternion (applied first)
• Returns: QuatHandle — The combined rotation
• Throws: HandleInvalidError (code HANDLE_INVALID) if a or b is not a valid handle

---

conjugate(q)

Conjugate.

• Parameters:
  • q: QuatHandle — The quaternion
• Returns: QuatHandle
• Throws: HandleInvalidError (code HANDLE_INVALID) if q is not a valid handle

---

length(q)

Magnitude.

• Parameters:
  • q: QuatHandle — The quaternion
• Returns: number
• Throws: HandleInvalidError (code HANDLE_INVALID) if q is not a valid handle

---

normalize(q)

Unit quaternion.

• Parameters:
  • q: QuatHandle — The quaternion to normalize
• Returns: QuatHandle — A unit-length quaternion
• Throws: HandleInvalidError (code HANDLE_INVALID) if q is not a valid handle

---

inverse(q)

Inverse rotation.

• Parameters:
  • q: QuatHandle — The quaternion to invert
• Returns: QuatHandle
• Throws: HandleInvalidError (code HANDLE_INVALID) if q is not a valid handle

---

toAxisAngle(q)

Decompose into axis + angle.

• Parameters:
  • q: QuatHandle — The quaternion to decompose
• Returns: { axis: Vec3Handle, angle: number } — The rotation axis and angle in radians
• Throws: HandleInvalidError (code HANDLE_INVALID) if q is not a valid handle

---

slerp(a, b, t)

Spherical linear interpolation.

• Parameters:
  • a: QuatHandle — Start quaternion
  • b: QuatHandle — End quaternion
  • t: number — Interpolation factor
• Returns: QuatHandle — The interpolated quaternion
• Throws: HandleInvalidError (code HANDLE_INVALID) if a or b is not a valid handle

---

dot(a, b)

Dot product.

• Parameters:
  • a: QuatHandle — First quaternion
  • b: QuatHandle — Second quaternion
• Returns: number
• Throws: HandleInvalidError (code HANDLE_INVALID) if a or b is not a valid handle

---

equals(a, b)

Exact component equality.

For floating-point comparisons, prefer equalsApprox.

• Parameters:
  • a: QuatHandle — First quaternion
  • b: QuatHandle — Second quaternion
• Returns: boolean
• Throws: HandleInvalidError (code HANDLE_INVALID) if a or b is not a valid handle

---

equalsApprox(a, b, epsilon?)

Approximate equality within epsilon (default 1e-6).

• Parameters:
  • a: QuatHandle — First quaternion
  • b: QuatHandle — Second quaternion
  • epsilon: number (optional, default 1e-6) — Comparison tolerance
• Returns: boolean
• Throws: HandleInvalidError (code HANDLE_INVALID) if a or b is not a valid handle

---

components(q)

Read the primitive { x, y, z, w } components of a quaternion handle.

• Parameters:
  • q: QuatHandle — The quaternion to read
• Returns: QuatComponents — { x, y, z, w } as plain numbers
• Throws: HandleInvalidError (code HANDLE_INVALID) if q is not a valid handle

const { quat } = snaptrude.core.math;
const q = await quat.fromEuler(0, Math.PI / 2, 0);
const { x, y, z, w } = await quat.components(q);

Errors

Failed calls reject with a typed PluginError — see Error Handling. Both conditions come from the handle registry:

Code	Thrown by	When	details
HANDLE_INVALID	every operation taking a QuatHandle (or the Vec3Handle in fromAxisAngle)	The handle cannot be resolved — unknown, released, another plugin's, or the wrong kind (deliberately one code for all resolution failures)	kind: "quat" (or "vec3")
RESOURCE_QUOTA_EXCEEDED	every operation returning a handle	The plugin's value-handle arena is full	kind, limit, current

On RESOURCE_QUOTA_EXCEEDED, release handles you no longer need (see Handles) and retry.