---
name: Vector3
last_updated: 2026-06-10T23:09:12Z
type: datatype
summary: "Represents a 3D value with a direction and magnitude."
---

# Vector3

Represents a 3D value with a direction and magnitude.

**Type:** datatype

## Description

The [Vector3](/docs/reference/engine/datatypes/Vector3.md) data type represents a vector in 3D space, typically
used as a point in 3D space or the dimensions of a rectangular prism.
[Vector3](/docs/reference/engine/datatypes/Vector3.md) supports basic component-based arithmetic operations (sum,
difference, product, and quotient) and these operations can be applied on the
left or right hand side to either another [Vector3](/docs/reference/engine/datatypes/Vector3.md) or a number. It
also features methods for common vector operations, such as
[Cross()](/docs/reference/engine/datatypes/Vector3.md) and [Dot()](/docs/reference/engine/datatypes/Vector3.md).

Alternatively to [Vector3](/docs/reference/engine/datatypes/Vector3.md), consider using the methods and properties
of the [vector](/docs/reference/engine/globals/vector.md) library.

Some example usages of [Vector3](/docs/reference/engine/datatypes/Vector3.md) are the
[Position](/docs/reference/engine/classes/BasePart.md), [Rotation](/docs/reference/engine/classes/BasePart.md), and
[Size](/docs/reference/engine/classes/BasePart.md) of parts, for example:

```lua
local Workspace = game:GetService("Workspace")

local part = Workspace.Part
part.Position = part.Position + Vector3.new(5, 2, 10) -- Move part by (5, 2, 10)
```

[Vector3](/docs/reference/engine/datatypes/Vector3.md) is also commonly used when constructing more complex 3D
data types such as [CFrame](/docs/reference/engine/datatypes/CFrame.md). Many of these data types' methods will
use a [Vector3](/docs/reference/engine/datatypes/Vector3.md) within their parameters, such as
[CFrame:PointToObjectSpace()](/docs/reference/engine/datatypes/CFrame.md).

## Constructors

### Vector3.new

**Signature:** `Vector3.new(x?: number, y?: number, z?: number)`

Returns a new [Vector3](/docs/reference/engine/datatypes/Vector3.md) using the given `x`, `y`, and `z` components.

**Parameters:**

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

### Vector3.FromNormalId

**Signature:** `Vector3.FromNormalId(normal: NormalId)`

Returns a new [Vector3](/docs/reference/engine/datatypes/Vector3.md) in the given direction.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `normal` | `NormalId` |  |  |

### Vector3.FromAxis

**Signature:** `Vector3.FromAxis(axis: Axis)`

Returns a new [Vector3](/docs/reference/engine/datatypes/Vector3.md) for the given axis.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `axis` | `Axis` |  |  |

## Constants

| Name | Type | Description |
|------|------|-------------|
| `Vector3.zero` | `Vector3` | A [Vector3](/docs/reference/engine/datatypes/Vector3.md) with a magnitude of `0`. |
| `Vector3.one` | `Vector3` | A [Vector3](/docs/reference/engine/datatypes/Vector3.md) with a value of `1` on every axis. |
| `Vector3.xAxis` | `Vector3` | A [Vector3](/docs/reference/engine/datatypes/Vector3.md) with a value of `1` on the **X** axis. |
| `Vector3.yAxis` | `Vector3` | A [Vector3](/docs/reference/engine/datatypes/Vector3.md) with a value of `1` on the **Y** axis. |
| `Vector3.zAxis` | `Vector3` | A [Vector3](/docs/reference/engine/datatypes/Vector3.md) with a value of `1` on the **Z** axis. |

## Properties

### Vector3.X

**Type:** `number`

The **X** coordinate of the [Vector3](/docs/reference/engine/datatypes/Vector3.md).

### Vector3.Y

**Type:** `number`

The **Y** coordinate of the [Vector3](/docs/reference/engine/datatypes/Vector3.md).

### Vector3.Z

**Type:** `number`

The **Z** coordinate of the [Vector3](/docs/reference/engine/datatypes/Vector3.md).

### Vector3.Magnitude

**Type:** `number`

The length of the [Vector3](/docs/reference/engine/datatypes/Vector3.md).

### Vector3.Unit

**Type:** `Vector3`

A normalized copy of the [Vector3](/docs/reference/engine/datatypes/Vector3.md) - one that has the same
direction as the original but a magnitude of `1`.

## Methods

### Vector3:Abs

**Signature:** `Vector3:Abs(): Vector3`

Returns a new vector from the absolute values of the original's
components. For example, a vector of `(-2, 4, -6)` returns a vector of
`(2, 4, 6)`.

**Returns:** `Vector3`

### Vector3:Ceil

**Signature:** `Vector3:Ceil(): Vector3`

Returns a new vector from the ceiling of the original's components. For
example, a vector of `(-2.6, 5.1, 8.8)` returns a vector of `(-2, 6, 9)`.

**Returns:** `Vector3`

### Vector3:Floor

**Signature:** `Vector3:Floor(): Vector3`

Returns a new vector from the floor of the original's components. For
example, a vector of `(-2.6, 5.1, 8.8)` returns a vector of `(-3, 5, 8)`.

**Returns:** `Vector3`

### Vector3:Sign

**Signature:** `Vector3:Sign(): Vector3`

Returns a new vector from the sign (-1, 0, or 1) of the original's
components. For example, a vector of `(-2.6, 5.1, 0)` returns a vector of
`(-1, 1, 0)`.

**Returns:** `Vector3`

### Vector3:Cross

**Signature:** `Vector3:Cross(other: Vector3): Vector3`

Returns the cross product of the two vectors.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `other` | `Vector3` |  |  |

**Returns:** `Vector3`

### Vector3:Angle

**Signature:** `Vector3:Angle(other: Vector3, axis?: Vector3): number`

Returns the angle in radians between the two vectors. If you provide an
axis, it determines the sign of the angle.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `other` | `Vector3` |  |  |
| `axis` | `Vector3` | `nil` |  |

**Returns:** `number`

### Vector3:Dot

**Signature:** `Vector3:Dot(other: Vector3): number`

Returns a scalar dot product of the two vectors.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `other` | `Vector3` |  |  |

**Returns:** `number`

### Vector3:FuzzyEq

**Signature:** `Vector3:FuzzyEq(other: Vector3, epsilon?: number): bool`

Returns `true` if the difference between the squared magnitude of the two
vectors is within `epsilon`. `epsilon` is scaled relative to the
magnitude, rather than an absolute epsilon.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `other` | `Vector3` |  |  |
| `epsilon` | `number` | `0.00001 aka 1e-5` |  |

**Returns:** `bool`

### Vector3:Lerp

**Signature:** `Vector3:Lerp(goal: Vector3, alpha: number): Vector3`

Returns a [Vector3](/docs/reference/engine/datatypes/Vector3.md) linearly interpolated between this
[Vector3](/docs/reference/engine/datatypes/Vector3.md) and the given `goal` [Vector3](/docs/reference/engine/datatypes/Vector3.md) by the fraction
`alpha`. Note that `alpha` is **not** limited to the range `[0, 1]`.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `goal` | `Vector3` |  |  |
| `alpha` | `number` |  |  |

**Returns:** `Vector3`

### Vector3:Max

**Signature:** `Vector3:Max(vector: Vector3): Vector3`

Returns a [Vector3](/docs/reference/engine/datatypes/Vector3.md) with each component as the highest among the
respective components of both provided [Vector3](/docs/reference/engine/datatypes/Vector3.md) objects.

```lua
local a = Vector3.new(1, 2, 1)
local b = Vector3.new(2, 1, 2)

print(a:Max(b))  --> Vector3.new(2, 2, 2)
```

**Parameters:**

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

**Returns:** `Vector3`

### Vector3:Min

**Signature:** `Vector3:Min(vector: Vector3): Vector3`

Returns a [Vector3](/docs/reference/engine/datatypes/Vector3.md) with each component as the lowest among the
respective components of both provided [Vector3](/docs/reference/engine/datatypes/Vector3.md) objects.

```lua
local a = Vector3.new(1, 2, 1)
local b = Vector3.new(2, 1, 2)

print(a:Min(b))  --> Vector3.new(1, 1, 1)
```

**Parameters:**

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

**Returns:** `Vector3`

## Math Operations

| Operation | Type A | Type B | Returns | Description |
|-----------|--------|--------|---------|-------------|
| `+` | `Vector3` | `Vector3` | `Vector3` | Produces a [Vector3](/docs/reference/engine/datatypes/Vector3.md) by adding each component of the first vector to the corresponding component of the second. |
| `-` | `Vector3` | `Vector3` | `Vector3` | Produces a [Vector3](/docs/reference/engine/datatypes/Vector3.md) by subtracting each component of the second vector from the corresponding component of the first. |
| `*` | `Vector3` | `Vector3` | `Vector3` | Produces a [Vector3](/docs/reference/engine/datatypes/Vector3.md) by multiplying each component of the first vector by the corresponding component of the second. |
| `/` | `Vector3` | `Vector3` | `Vector3` | Produces a [Vector3](/docs/reference/engine/datatypes/Vector3.md) by dividing each component of the first vector by the corresponding component of the second. |
| `//` | `Vector3` | `Vector3` | `Vector3` | Produces a [Vector3](/docs/reference/engine/datatypes/Vector3.md) by **floor dividing** each component of the first vector by the corresponding component of the second. |
| `*` | `Vector3` | `number` | `Vector3` | Produces a [Vector3](/docs/reference/engine/datatypes/Vector3.md) by multiplying each component of the provided vector by the number. |
| `/` | `Vector3` | `number` | `Vector3` | Produces a [Vector3](/docs/reference/engine/datatypes/Vector3.md) by dividing each component of the provided vector by the number. |
| `//` | `Vector3` | `number` | `Vector3` | Produces a [Vector3](/docs/reference/engine/datatypes/Vector3.md) by **floor dividing** each component of the provided vector by the number. |