---
title: "mathx"
description: "The mathx namespace — the engine's Luau API reference for mathx."
section: "API Reference"
slug: "api-mathx"
canonical: "https://origozero.ai/docs/api-mathx"
updated: "2026-09-05T23:13:46.741712852+00:00"
tags: ["api", "reference"]
---

# mathx

The `mathx` namespace — 19 functions.

## globals/mathx/addScaledVec3 {#globals-mathx-addscaledvec3}

```lua
mathx.addScaledVec3(dstBuffer: Substrate.TypedBuffer, srcBuffer: Substrate.TypedBuffer, count: number, scale: number) -> boolean
```

`dst[i] += src[i] * scale` for `count` vec3 elements. Both
buffers must hold at least `count * 3` floats. Useful for
particle integration (position += velocity * dt) and accumulator
passes.

**Parameters**

- `dstBuffer` `Substrate.TypedBuffer` — The buffer written into.
- `srcBuffer` `Substrate.TypedBuffer` — The buffer read from.
- `count` `number` — Number of vec3 elements.
- `scale` `number` — Multiplier applied to every src element.

**Returns** `boolean` — True on success.

```lua
mathx.addScaledVec3(positions, velocities, n, dt)
```

## globals/mathx/dampScalar {#globals-mathx-dampscalar}

```lua
mathx.dampScalar(buffer: Substrate.TypedBuffer, offset: number, count: number, target: number, smoothTime: number, dt: number) -> boolean
```

Critically-damped exponential approach toward `target` for
`count` scalars at `buffer[offset .. offset+count]`. `smoothTime`
is the time constant (~ 0.16 ⇒ ~63% per frame at 60 Hz). Pass
`smoothTime <= 0` to snap to the target.

**Parameters**

- `buffer` `Substrate.TypedBuffer` — The buffer to operate on.
- `offset` `number` — Starting f32 index.
- `count` `number` — Number of scalars.
- `target` `number` — Target value all scalars approach.
- `smoothTime` `number` — Time constant (≤ 0 snaps to target).
- `dt` `number` — Frame time in seconds.

**Returns** `boolean` — True on success, false on a bad handle or out-of-range slice.

```lua
mathx.dampScalar(buf, 0, 16, 0.0, 0.16, dt)
```

## globals/mathx/lerpVec3 {#globals-mathx-lerpvec3}

```lua
mathx.lerpVec3(buffer: Substrate.TypedBuffer, offset: number, count: number, tx: number, ty: number, tz: number, t: number) -> boolean
```

Element-wise linear blend of `count` vec3s in
`buffer[offset .. offset+count*3]` toward `(tx, ty, tz)` by `t`.

**Parameters**

- `buffer` `Substrate.TypedBuffer` — The buffer to operate on.
- `offset` `number` — Starting f32 index.
- `count` `number` — Number of vec3 elements.
- `tx` `number` — Target X.
- `ty` `number` — Target Y.
- `tz` `number` — Target Z.
- `t` `number` — Blend amount (0..1).

**Returns** `boolean` — True on success.

```lua
mathx.lerpVec3(buf, 0, n, 0, 1, 0, 0.5)
```

## globals/mathx/normalizeQuat {#globals-mathx-normalizequat}

```lua
mathx.normalizeQuat(buffer: Substrate.TypedBuffer, offset: number, count: number) -> boolean
```

Re-normalise `count` quaternions in place. Zero-length quats
become identity (0, 0, 0, 1) so downstream code never sees NaN.

**Parameters**

- `buffer` `Substrate.TypedBuffer` — The buffer to operate on.
- `offset` `number` — Starting f32 index.
- `count` `number` — Number of quaternions.

**Returns** `boolean` — True on success.

```lua
mathx.normalizeQuat(buf, 0, n)
```

## globals/mathx/slerpQuat {#globals-mathx-slerpquat}

```lua
mathx.slerpQuat(buffer: Substrate.TypedBuffer, offset: number, count: number, tx: number, ty: number, tz: number, tw: number, t: number) -> boolean
```

Slerp `count` quaternions (xyzw) at `buffer[offset..]` toward
`(tx, ty, tz, tw)` by `t`. Falls back to nlerp+normalize for
very-close quats. Always picks the shortest-arc path.

**Parameters**

- `buffer` `Substrate.TypedBuffer` — The buffer to operate on.
- `offset` `number` — Starting f32 index.
- `count` `number` — Number of quaternions.
- `tx` `number` — Target quat X.
- `ty` `number` — Target quat Y.
- `tz` `number` — Target quat Z.
- `tw` `number` — Target quat W.
- `t` `number` — Slerp amount (0..1).

**Returns** `boolean` — True on success.

```lua
mathx.slerpQuat(buf, 0, n, 0, 0, 0, 1, 0.25)
```

## globals/mathx/transformVec3 {#globals-mathx-transformvec3}

```lua
mathx.transformVec3(buffer: Substrate.TypedBuffer, offset: number, count: number, mat16: { number }) -> boolean
```

Treat each vec3 in `buffer[offset..]` as a position (w = 1),
multiply by the 4x4 column-major matrix `mat16` (16-element
array), write `.xyz` of the result back. Layout matches glam,
wgpu, and GLSL conventions.

**Parameters**

- `buffer` `Substrate.TypedBuffer` — The buffer to operate on.
- `offset` `number` — Starting f32 index.
- `count` `number` — Number of vec3 elements.
- `mat16` `{ number }` — Column-major 4x4 matrix as a 16-element array.

**Returns** `boolean` — True on success.

```lua
mathx.transformVec3(positions, 0, n, worldMatrix)
```

## modules/mathx/README {#modules-mathx-readme}

```lua
require("@builtin/modules/api/engine/mathx") -- mathx (also available as global 'mathx')
```

Batch math kernels over buffer slices (damp, lerp/slerp, transform). Public Luau surface over the `__mathx` Internal FFI namespace.

Usage: local mathx = require("@builtin/modules/api/engine/mathx")
Also available as global: mathx

## modules/mathx/addScaledVec3 {#modules-mathx-addscaledvec3}

```lua
addScaledVec3(dstBuffer: Substrate.TypedBuffer, srcBuffer: Substrate.TypedBuffer,
```

`dst[i] += src[i] * scale` for `count` vec3 elements. Both
buffers must hold at least `count * 3` floats. Useful for
particle integration (position += velocity * dt) and accumulator
passes.

```lua
mathx.addScaledVec3(positions, velocities, n, dt)
```

## modules/mathx/dampScalar {#modules-mathx-dampscalar}

```lua
dampScalar(buffer: Substrate.TypedBuffer, offset: number, count: number,
```

Critically-damped exponential approach toward `target` for
`count` scalars at `buffer[offset .. offset+count]`. `smoothTime`
is the time constant (~ 0.16 ⇒ ~63% per frame at 60 Hz). Pass
`smoothTime <= 0` to snap to the target.

```lua
mathx.dampScalar(buf, 0, 16, 0.0, 0.16, dt)
```

## modules/mathx/lerpVec3 {#modules-mathx-lerpvec3}

```lua
lerpVec3(buffer: Substrate.TypedBuffer, offset: number, count: number,
```

Element-wise linear blend of `count` vec3s in
`buffer[offset .. offset+count*3]` toward `(tx, ty, tz)` by `t`.

```lua
mathx.lerpVec3(buf, 0, n, 0, 1, 0, 0.5)
```

## modules/mathx/normalizeQuat {#modules-mathx-normalizequat}

```lua
normalizeQuat(buffer: Substrate.TypedBuffer, offset: number, count: number): boolean
```

Re-normalise `count` quaternions in place. Zero-length quats
become identity (0, 0, 0, 1) so downstream code never sees NaN.

**Parameters**

- `buffer` `Substrate.TypedBuffer` — The buffer to operate on.
- `offset` `number` — Starting f32 index.
- `count` `number` — Number of quaternions.

```lua
mathx.normalizeQuat(buf, 0, n)
```

## modules/mathx/slerpQuat {#modules-mathx-slerpquat}

```lua
slerpQuat(buffer: Substrate.TypedBuffer, offset: number, count: number,
```

Slerp `count` quaternions (xyzw) at `buffer[offset..]` toward
`(tx, ty, tz, tw)` by `t`. Falls back to nlerp+normalize for
very-close quats. Always picks the shortest-arc path.

```lua
mathx.slerpQuat(buf, 0, n, 0, 0, 0, 1, 0.25)
```

## modules/mathx/transformVec3 {#modules-mathx-transformvec3}

```lua
transformVec3(buffer: Substrate.TypedBuffer, offset: number,
```

Treat each vec3 in `buffer[offset..]` as a position (w = 1),
multiply by the 4x4 column-major matrix `mat16` (16-element
array), write `.xyz` of the result back. Layout matches glam,
wgpu, and GLSL conventions.

```lua
mathx.transformVec3(positions, 0, n, worldMatrix)
```

## typed/builtin//modules/api/engine/mathx/mathx/addScaledVec3 {#typed-builtin-modules-api-engine-mathx-mathx-addscaledvec3}

```lua
mathx.addScaledVec3(dstBuffer: Substrate.TypedBuffer, srcBuffer: Substrate.TypedBuffer, count: number, scale: number) -> boolean
```

`dst[i] += src[i] * scale` for `count` vec3 elements. Both
buffers must hold at least `count * 3` floats. Useful for
particle integration (position += velocity * dt) and accumulator
passes.

**Parameters**

- `dstBuffer` `Substrate.TypedBuffer` — The buffer written into.
- `srcBuffer` `Substrate.TypedBuffer` — The buffer read from.
- `count` `number` — Number of vec3 elements.
- `scale` `number` — Multiplier applied to every src element.

**Returns** `boolean` — True on success.

```lua
mathx.addScaledVec3(positions, velocities, n, dt)
```

## typed/builtin//modules/api/engine/mathx/mathx/dampScalar {#typed-builtin-modules-api-engine-mathx-mathx-dampscalar}

```lua
mathx.dampScalar(buffer: Substrate.TypedBuffer, offset: number, count: number, target: number, smoothTime: number, dt: number) -> boolean
```

Critically-damped exponential approach toward `target` for
`count` scalars at `buffer[offset .. offset+count]`. `smoothTime`
is the time constant (~ 0.16 ⇒ ~63% per frame at 60 Hz). Pass
`smoothTime <= 0` to snap to the target.

**Parameters**

- `buffer` `Substrate.TypedBuffer` — The buffer to operate on.
- `offset` `number` — Starting f32 index.
- `count` `number` — Number of scalars.
- `target` `number` — Target value all scalars approach.
- `smoothTime` `number` — Time constant (≤ 0 snaps to target).
- `dt` `number` — Frame time in seconds.

**Returns** `boolean` — True on success, false on a bad handle or out-of-range slice.

```lua
mathx.dampScalar(buf, 0, 16, 0.0, 0.16, dt)
```

## typed/builtin//modules/api/engine/mathx/mathx/lerpVec3 {#typed-builtin-modules-api-engine-mathx-mathx-lerpvec3}

```lua
mathx.lerpVec3(buffer: Substrate.TypedBuffer, offset: number, count: number, tx: number, ty: number, tz: number, t: number) -> boolean
```

Element-wise linear blend of `count` vec3s in
`buffer[offset .. offset+count*3]` toward `(tx, ty, tz)` by `t`.

**Parameters**

- `buffer` `Substrate.TypedBuffer` — The buffer to operate on.
- `offset` `number` — Starting f32 index.
- `count` `number` — Number of vec3 elements.
- `tx` `number` — Target X.
- `ty` `number` — Target Y.
- `tz` `number` — Target Z.
- `t` `number` — Blend amount (0..1).

**Returns** `boolean` — True on success.

```lua
mathx.lerpVec3(buf, 0, n, 0, 1, 0, 0.5)
```

## typed/builtin//modules/api/engine/mathx/mathx/normalizeQuat {#typed-builtin-modules-api-engine-mathx-mathx-normalizequat}

```lua
mathx.normalizeQuat(buffer: Substrate.TypedBuffer, offset: number, count: number) -> boolean
```

Re-normalise `count` quaternions in place. Zero-length quats
become identity (0, 0, 0, 1) so downstream code never sees NaN.

**Parameters**

- `buffer` `Substrate.TypedBuffer` — The buffer to operate on.
- `offset` `number` — Starting f32 index.
- `count` `number` — Number of quaternions.

**Returns** `boolean` — True on success.

```lua
mathx.normalizeQuat(buf, 0, n)
```

## typed/builtin//modules/api/engine/mathx/mathx/slerpQuat {#typed-builtin-modules-api-engine-mathx-mathx-slerpquat}

```lua
mathx.slerpQuat(buffer: Substrate.TypedBuffer, offset: number, count: number, tx: number, ty: number, tz: number, tw: number, t: number) -> boolean
```

Slerp `count` quaternions (xyzw) at `buffer[offset..]` toward
`(tx, ty, tz, tw)` by `t`. Falls back to nlerp+normalize for
very-close quats. Always picks the shortest-arc path.

**Parameters**

- `buffer` `Substrate.TypedBuffer` — The buffer to operate on.
- `offset` `number` — Starting f32 index.
- `count` `number` — Number of quaternions.
- `tx` `number` — Target quat X.
- `ty` `number` — Target quat Y.
- `tz` `number` — Target quat Z.
- `tw` `number` — Target quat W.
- `t` `number` — Slerp amount (0..1).

**Returns** `boolean` — True on success.

```lua
mathx.slerpQuat(buf, 0, n, 0, 0, 0, 1, 0.25)
```

## typed/builtin//modules/api/engine/mathx/mathx/transformVec3 {#typed-builtin-modules-api-engine-mathx-mathx-transformvec3}

```lua
mathx.transformVec3(buffer: Substrate.TypedBuffer, offset: number, count: number, mat16: { number }) -> boolean
```

Treat each vec3 in `buffer[offset..]` as a position (w = 1),
multiply by the 4x4 column-major matrix `mat16` (16-element
array), write `.xyz` of the result back. Layout matches glam,
wgpu, and GLSL conventions.

**Parameters**

- `buffer` `Substrate.TypedBuffer` — The buffer to operate on.
- `offset` `number` — Starting f32 index.
- `count` `number` — Number of vec3 elements.
- `mat16` `{ number }` — Column-major 4x4 matrix as a 16-element array.

**Returns** `boolean` — True on success.

```lua
mathx.transformVec3(positions, 0, n, worldMatrix)
```