---
name: vector
last_updated: 2026-06-24T18:42:20Z
type: library
summary: "A library of vector functions."
---

# vector

A library of vector functions.

**Type:** library

## Description

This library implements functionality for the vector type in addition to the
built-in primitive operator support. It uses vectors with three components
(`x`, `y`, and `z`).

Individual vector components can be accessed using the fields `x` or `X`, `y`
or `Y`, `z` or `Z`. Since vector values are immutable, writing to individual
components is not supported.

## Properties

### vector.zero

**Type:** `vector`

Constant vector with all components set to `0`.

### vector.one

**Type:** `vector`

Constant vector with all components set to `1`.

## Functions

### vector.create

**Signature:** `vector.create(x: number, y: number, z: number): vector`

Creates a new vector with the given component values.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |
| `y` | `number` |  |  |
| `z` | `number` |  |  |

**Returns:** `vector`

### vector.magnitude

**Signature:** `vector.magnitude(vec: vector): number`

Calculates the magnitude of a given vector.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `vec` | `vector` |  |  |

**Returns:** `number`

### vector.normalize

**Signature:** `vector.normalize(vec: vector): vector`

Computes the normalized version (unit vector) of a given vector.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `vec` | `vector` |  |  |

**Returns:** `vector`

### vector.cross

**Signature:** `vector.cross(vec1: vector, vec2: vector): vector`

Computes the cross product of two vectors.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `vec1` | `vector` |  |  |
| `vec2` | `vector` |  |  |

**Returns:** `vector`

### vector.dot

**Signature:** `vector.dot(vec1: vector, vec2: vector): number`

Computes the dot product of two vectors.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `vec1` | `vector` |  |  |
| `vec2` | `vector` |  |  |

**Returns:** `number`

### vector.angle

**Signature:** `vector.angle(vec1: vector, vec2: vector, axis: vector?): number`

Computes the angle between two vectors in radians. The axis, if specified,
is used to determine the sign of the angle.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `vec1` | `vector` |  |  |
| `vec2` | `vector` |  |  |
| `axis` | `vector?` |  |  |

**Returns:** `number`

### vector.floor

**Signature:** `vector.floor(vec: vector): vector`

Applies [math.floor()](/docs/reference/engine/globals/math.md) to every component of the input vector.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `vec` | `vector` |  |  |

**Returns:** `vector`

### vector.ceil

**Signature:** `vector.ceil(vec: vector): vector`

Applies [math.ceil()](/docs/reference/engine/globals/math.md) to every component of the input vector.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `vec` | `vector` |  |  |

**Returns:** `vector`

### vector.abs

**Signature:** `vector.abs(vec: vector): vector`

Applies [math.abs()](/docs/reference/engine/globals/math.md) to every component of the input vector.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `vec` | `vector` |  |  |

**Returns:** `vector`

### vector.sign

**Signature:** `vector.sign(vec: vector): vector`

Applies [math.sign()](/docs/reference/engine/globals/math.md) to every component of the input vector.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `vec` | `vector` |  |  |

**Returns:** `vector`

### vector.clamp

**Signature:** `vector.clamp(vec: vector, min: vector, max: vector): vector`

Applies [math.clamp()](/docs/reference/engine/globals/math.md) to every component of the input vector.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `vec` | `vector` |  |  |
| `min` | `vector` |  |  |
| `max` | `vector` |  |  |

**Returns:** `vector`

### vector.lerp

**Signature:** `vector.lerp(vec1: vector, vec2: vector, alpha: number): vector`

Returns a vector linearly interpolated between two vectors (`vec1`,
`vec2`) by the fraction `alpha`. Note that `alpha` is **not** limited to
the range `[0, 1]`.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `vec1` | `vector` |  |  |
| `vec2` | `vector` |  |  |
| `alpha` | `number` |  |  |

**Returns:** `vector`

### vector.max

**Signature:** `vector.max(...: vector): vector`

Applies [math.max()](/docs/reference/engine/globals/math.md) to the corresponding components of the input
vectors.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `...` | `vector` |  |  |

**Returns:** `vector`

### vector.min

**Signature:** `vector.min(...: vector): vector`

Applies [math.min()](/docs/reference/engine/globals/math.md) to the corresponding components of the input
vectors.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `...` | `vector` |  |  |

**Returns:** `vector`