# Vector3

## Overview

Vector3 is a data type used to express vector in a three-dimensional space using X, Y, and Z axes. It is used to handle a variety of 3D data such as position, direction, speed, and strength. It is also one of the key elements used by many systems to calculate coordinates and vector within a space or simulating 3D physics.

## Constructors

### new

Creates and returns a new vector using the passed X, Y, and Z values.

#### Parameters

| Parameter  | Description                |
| ---------- | -------------------------- |
| `number` x | The value of X coordinate. |
| `number` y | The value of Y coordinate. |
| `number` z | The value of Z coordinate. |

#### Return

| Return    | Description          |
| --------- | -------------------- |
| `Vector3` | The created Vector3. |

#### Code Samples

```lua
local Vector = Vector3.new(1, 2, 3)
print(Vector)
```

## Properties

### X

`number` 

The value of X coordinate.

#### Code Samples

```lua
local Vector = Vector3.new(10, 5, 8)
print(Vector.X)
```

### Y

`number` 

The value of Y coordinate.

#### Code Samples

```lua
local Vector = Vector3.new(10, 5, 8)
print(Vector.Y)
```

### Z

`number` 

The value of Z coordinate.

#### Code Samples

```lua
local Vector = Vector3.new(10, 5, 8)
print(Vector.Z)
```

### zero

`Vector3`

A vector of which axis values are zeroes (0, 0, 0).

#### Code Samples

```lua
local ZeroVector = Vector3.zero
print(ZeroVector)
```

### one

`Vector3` 

A vector of which axis values are ones (1, 1, 1).

#### Code Samples

```lua
local OneVector = Vector3.one
print(OneVector)
```

### xAxis

`Vector3` 

A Vector3 set to have the value of 1 for X axis and 0 for other axes (1, 0, 0).

#### Code Samples

```lua
local XAxis = Vector3.xAxis
print(XAxis)
```

### yAxis

`Vector3` 

A Vector3 set to have the value of 1 for Y axis and 0 for other axes (0, 1, 0).

#### Code Samples

```lua
local YAxis = Vector3.yAxis
print(YAxis)
```

### zAxis

`Vector3` 

A Vector3 set to have the value of 1 for Z axis and 0 for other axes (0, 0, 1).

#### Code Samples

```lua
local ZAxis = Vector3.zAxis
print(ZAxis)
```

### Unit

`Vector3`

A Vector3 of which size is removed and length is 1 while maintaining the original direction.

#### Code Samples

```lua
local Vector = Vector3.new(100, 50, 200)
print(Vector.Unit)
```

### Magnitude

`number`

The value representing the size of a Vector3.

#### Code Samples

```lua
local Vector = Vector3.new(100, 50, 200)
print(Vector.Magnitude)
```

## Methods

### Abs

Makes each coordinate of a vector positive, even if some of them were negative, and returns a new vector.

#### Parameters

#### Return

| `Vector3` | The created Vector3. |
| --------- | -------------------- |

#### Code Samples

```lua
local v = Vector3.new(-2, 4, -6)
print("Abs:", v:Abs()) --> Output: 2, 4, 6
```

### Angle

Calculates the angle between two vectors in radian and returns it. If there is a reference axis, the direction of the angle is also considered in the return value.

#### Parameters

| `Vector3` otherVector | The Vector3 to calculate its angle.                                                                                                                                   |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Vector3` axis        | The Vector3 to be used as a reference axis to determine the direction of an angle. If no axis is provided, only the absolute angle between two vectors is calculated. |

#### Return

| `number` | Returns the angle between two vectors in radian. |
| -------- | ------------------------------------------------ |

#### Code Samples

```lua
local a = Vector3.new(1, 0, 0)
local b = Vector3.new(0, 1, 0)
print("Angle:", a:Angle(b) -- Output: 1.570796
```

### Ceil

Rounds up each coordinate of the vectors and returns a new vector.

#### Parameters

#### Return

| `Vector3` | The created Vector3. |
| --------- | -------------------- |

#### Code Samples

```lua
local v = Vector3.new(-2.6, 5.1, 8.8)
print("Ceil:", v:Ceil()) --> Output: -2, 6, 9
```

### ClampMagnitude

Returns a new vector of which length is restricted not to exceed maxLength.

#### Parameters

| `number` maxLength | The maximum value used to restrict vector length. |
| ------------------ | ------------------------------------------------- |

#### Return

| `Vector3` | The created Vector3. |
| --------- | -------------------- |

#### Code Samples

```lua
local v = Vector3.new(10, 0, 0)
print("ClampMagnitude", v:ClampMagnitude(3)) --> Output: 3, 0, 0
```

### Cross

Returns the cross product between two vectors as a new vector.

#### Parameters

| `Vector3` Parameter for cross product. | The Vector3 to calculate its cross product. |
| -------------------------------------- | ------------------------------------------- |

#### Return

| `Vector3` | The created Vector3. |
| --------- | -------------------- |

#### Code Samples

```lua
local a = Vector3.new(1, 0, 0)
local b = Vector3.new(0, 1, 0)
print("Cross:", a:Cross(b)) --> Output: 0, 0, 1
```

### Distance

Returns the distance between two vectors.

#### Parameters

| `Vector3` otherVector | The Vector3 to calculate distance. |
| --------------------- | ---------------------------------- |

#### Return

| `number` | Returns the linear distance between two vectors in a numeric value. |
| -------- | ------------------------------------------------------------------- |

#### Code Samples

```lua
local a = Vector3.new(0, 0, 0)
local b = Vector3.new(3, 4, 0)
print("Distance:", a:Distance(b)) --> Output: 5
```

### Dot

Returns the dot value between two vectors as a scalar.

#### Parameters

| `Vector3` vector | The Vector3 to calculate its dot product. |
| ---------------- | ----------------------------------------- |

#### Return

| `number` | Returns the dot product between two vectors as a scalar. |
| -------- | -------------------------------------------------------- |

#### Code Samples

```lua
local a = Vector3.new(1, 2, 3)
local b = Vector3.new(4, 5, 6)
print("Dot:", a:Dot(b)) --> Output: 32
```

### Floor

Rounds down each coordinate of the exiting vectors and returns a new vector.

#### Parameters

#### Return

| `Vector3` | The created Vector3. |
| --------- | -------------------- |

#### Code Samples

```lua
local v = Vector3.new(-2.6, 5.1, 8.8)
print("Floor:", v:Floor()) --> Output: -3, 5, 8
```

### FuzzyEq

Compares the squared size of both vectors and returns true if both values are within the epsilon range calculated according to vector size. In this case, both vectors are treated as the same vector.

#### Parameters

| `Vector3` otherVector | The Vector3 to compare.                                                                                                                                                      |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `number` epsilon      | A value indicates tolerance. This value is applied in proportion to vector size. It is used to determine whether the difference of two squared vectors is within this range. |

#### Return

\| `bool` | <p>Returns true if the difference of two squared vectors is within the epsilon tolerance according to vector size. <br>Returns false otherwise.</p> |
\| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |

#### Code Samples

```lua
local a = Vector3.new(1.0001, 2.0001, 3.0001)
local b = Vector3.new(1.0002, 2.0002, 3.0002)
print("FuzzyEq:", a:FuzzyEq(b)) --> Output: false
```

### Lerp

Calculates the linear interpolation between the current vector and the target vector according to alpha ratio and returns it as a new vector.

#### Parameters

| `Vector3` goal | The target Vector3 to be interpolated.  |
| -------------- | --------------------------------------- |
| `number` alpha | A value indicating interpolation ratio. |

#### Return

| `Vector3` | The created Vector3. |
| --------- | -------------------- |

#### Code Samples

```lua
local a = Vector3.new(0, 0, 0)
local b = Vector3.new(10, 10, 10)
print("Lerp:", a:Lerp(b, 0.3)) --> Output: 3, 3, 3
```

### Max

Compares the X, Y, and Z value of two vectors, selects the higher value for each axis, and returns a new vector with the selected values.

#### Parameters

| `Vector3` otherVector | The other Vector3 to compare. |
| --------------------- | ----------------------------- |

#### Return

| `Vector3` | The created Vector3. |
| --------- | -------------------- |

#### Code Samples

```lua
local a = Vector3.new(1, 5, 3)
local b = Vector3.new(4, 2, 6)
print("Max:", a:Max(b)) --> Output: 4, 5, 6
```

### Min

Compares the X, Y, and Z value of two vectors, selects the lower value for each axis, and returns a new vector with the selected values.

#### Parameters

| `Vector3` otherVector | The other Vector3 to compare. |
| --------------------- | ----------------------------- |

#### Return

| `Vector3` | The created Vector3. |
| --------- | -------------------- |

#### Code Samples

```lua
local a = Vector3.new(1, 5, 3)
local b = Vector3.new(4, 2, 6)
print("Min:", a:Min(b)) --> Output: 1, 2, 3
```

### MoveTowards

Returns a new vector, which is moved from the current vector toward the target vector in the distance of maxDelta.

#### Parameters

| `Vector3` target  | The Vector3 to be the movement target.                |
| ----------------- | ----------------------------------------------------- |
| `number` maxDelta | The maximum distance movable in a single calculation. |

#### Return

| `Vector3` | The created Vector3. |
| --------- | -------------------- |

#### Code Samples

```lua
local a = Vector3.new(0, 0, 0)
local b = Vector3.new(10, 0, 0)
print("MoveTowards:", a:MoveTowards(b, 3)) --> Output: 3, 0, 0
```

### Reflect

Returns a new vector, which is reflected by a given normal vector.

#### Parameters

| `Vector3` inNormal | The normal vector (Vector3) to be the reference point of reflection. |
| ------------------ | -------------------------------------------------------------------- |

#### Return

| `Vector3` | The created Vector3. |
| --------- | -------------------- |

#### Code Samples

```lua
local v = Vector3.new(1, -1, 0)
local n = Vector3.new(0, 1, 0)
print("Reflect", v:Reflect(n)) --> Output: 1, 1, 0
```

### Rotate

Returns a new vector, which is rotated by radians along the provided axis.

#### Parameters

| `Vector3` axis   | The Vector3 to be the rotation axis.                                           |
| ---------------- | ------------------------------------------------------------------------------ |
| `number` radians | A value specifying the angle by which a vector is rotated, measured in radian. |

#### Return

| `Vector3` | The created Vector3. |
| --------- | -------------------- |

#### Code Samples

```lua
local v = Vector3.new(1, 0, 0)
local axis = Vector3.new(0, 1, 0)
print("Rotate:", v:Rotate(axis, math.rad(90))) --> Output: 0, 0, -1
```

### Sign

Converts the each coordinate of an existing vector and returns the result as a new vector. Any negative number is converted to -1; any positive value is converted to 1; and 0 is not converted.

#### Parameters

#### Return

| `Vector3` | The created Vector3. |
| --------- | -------------------- |

#### Code Samples

```lua
local v = Vector3.new(-2.6, 5.1, 0)
print("Sign:", v:Sign()) --> Output: -1, 1, 0
```

### Slerp

Calculates the spherical linear interpolation between the current vector and the target vector according to alpha ratio and returns it as a new vector.

While Lerp interpolates along a linear path, Slerp interpolates along a curve on a unit sphere, making its rotation axis movement smoother and more constant.

#### Parameters

| `Vector3` goal | The target Vector3 to be interpolated.  |
| -------------- | --------------------------------------- |
| `number` alpha | A value indicating interpolation ratio. |

#### Return

| `Vector3` | The created Vector3. |
| --------- | -------------------- |

#### Code Samples

```lua
local a = Vector3.new(1, 0, 0)
local b = Vector3.new(0, 1, 0)
print("Slerp:", a:Slerp(b, 0.5)) --> Output: 0.707107, 0.707107, 0 
```

## See also

{% content-ref url="../../../manual/studio-manual/get-started/coordinate-system" %}
[coordinate-system](https://docs.overdare.com/manual/studio-manual/get-started/coordinate-system)
{% endcontent-ref %}