Vec3

3D vector operations for positions, directions, and displacements. Vectors are opaque Vec3Handles; every operation is a host call returning a new handle (vectors are immutable — no operation ever mutates its inputs). Read primitive components back with components. Accessed via snaptrude.core.math.vec3.

Types

Vec3Handle

An opaque, kind-tagged string handle referencing an immutable 3D vector held by the host. Obtained from new (or any vec3 operation) and passed back into other API methods. Passing an invalid or foreign handle rejects with HandleInvalidError (code HANDLE_INVALID).

Vec3Components

The primitive read-back record for a vector, returned by components.

Property	Type	Description
x	number	The X component
y	number	The Y component
z	number	The Z component

Functions

new(x, y, z)

Create a vector from primitive components.

• Parameters:
  • x: number — The X component
  • y: number — The Y component
  • z: number — The Z component
• Returns: Vec3Handle — Handle to the new vector

const position = await snaptrude.core.math.vec3.new(1, 2, 3);

---

add(a, b)

Component-wise sum a + b.

• Parameters:
  • a: Vec3Handle — First vector
  • b: Vec3Handle — Second vector
• Returns: Vec3Handle — Handle to a new vector a + b

const a = await snaptrude.core.math.vec3.new(1, 0, 0);
const b = await snaptrude.core.math.vec3.new(0, 2, 0);
const sum = await snaptrude.core.math.vec3.add(a, b);

---

subtract(a, b)

Component-wise difference a - b.

• Parameters:
  • a: Vec3Handle — Vector to subtract from
  • b: Vec3Handle — Vector to subtract
• Returns: Vec3Handle — Handle to a new vector a - b

---

scale(v, scalar)

Scale v by a scalar.

• Parameters:
  • v: Vec3Handle — The vector to scale
  • scalar: number — The scalar multiplier
• Returns: Vec3Handle — Handle to a new scaled vector

---

dot(a, b)

Dot product.

• Parameters:
  • a: Vec3Handle — First vector
  • b: Vec3Handle — Second vector
• Returns: number — The scalar dot product

---

cross(a, b)

Cross product a × b.

• Parameters:
  • a: Vec3Handle — First vector
  • b: Vec3Handle — Second vector
• Returns: Vec3Handle — Handle to a new vector perpendicular to both a and b

---

length(v)

Euclidean length.

• Parameters:
  • v: Vec3Handle — The vector
• Returns: number — The Euclidean length

---

lengthSquared(v)

Squared length (avoids the sqrt).

• Parameters:
  • v: Vec3Handle — The vector
• Returns: number — The squared length

---

normalize(v)

Unit vector in the same direction (zero vector if length 0).

• Parameters:
  • v: Vec3Handle — The vector to normalize
• Returns: Vec3Handle — Handle to a new unit-length vector, or a zero vector if the input has length 0

---

distance(a, b)

Euclidean distance between two points.

• Parameters:
  • a: Vec3Handle — First point
  • b: Vec3Handle — Second point
• Returns: number — The distance between a and b

---

lerp(a, b, t)

Linear interpolation a + (b - a) * t.

• Parameters:
  • a: Vec3Handle — Start vector (returned when t = 0)
  • b: Vec3Handle — End vector (returned when t = 1)
  • t: number — Interpolation factor
• Returns: Vec3Handle — Handle to a new interpolated vector

---

negate(v)

Negate (reverse direction).

• Parameters:
  • v: Vec3Handle — The vector to negate
• Returns: Vec3Handle — Handle to a new vector with all components negated

---

equals(a, b)

Exact component equality.

• Parameters:
  • a: Vec3Handle — First vector
  • b: Vec3Handle — Second vector
• Returns: boolean — true if all components match exactly

For floating-point comparisons, prefer equalsApprox.

---

equalsApprox(a, b, epsilon?)

Approximate equality within epsilon.

• Parameters:
  • a: Vec3Handle — First vector
  • b: Vec3Handle — Second vector
  • epsilon: number (optional, default 1e-6) — Tolerance for the comparison
• Returns: boolean — true if the vectors are equal within epsilon

---

components(v)

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

• Parameters:
  • v: Vec3Handle — The vector to read
• Returns: Vec3Components — The { x, y, z } primitive record

const v = await snaptrude.core.math.vec3.new(1, 2, 3);
const { x, y, z } = await snaptrude.core.math.vec3.components(v);
// x === 1, y === 2, z === 3

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 Vec3Handle	The handle cannot be resolved — unknown, released, another plugin's, or the wrong kind (deliberately one code for all resolution failures)	kind: "vec3"
RESOURCE_QUOTA_EXCEEDED	every operation returning a Vec3Handle	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.