---
title: Vector
---

Represents a vector with up to three components. 2D APIs use only
`x`/`y`; 3D APIs (e.g. `Mat4:transformPoint`) also populate `z`.


## Fields

### `x`

The x component of the vector (read-only).
```lua
local v = Vector.xy(10, -5)
local xValue = v.x  -- 10
```


### `y`

The y component of the vector (read-only).
```lua
local v = Vector.xy(10, -5)
local yValue = v.y  -- -5
```


### `z`

The z component of the vector (read-only). Zero for vectors created
with `Vector.xy`; populated by 3D APIs that return a [Vector](/scripting/api-reference/vector/vector).
```lua
local v = m:transformPoint(1, 2, 3)
local zValue = v.z
```


## Constructors

### `xy`

{/* xy: (x:number, y:number) -> Vector */}
<div class="signature">
```lua
xy(x: number, y: number) -> Vector
```
</div>

Creates a vector with the specified x and y components.
```lua
local v = Vector.xy(5, -2)  -- 5 -2
```


### `origin`

{/* origin: () -> Vector */}
<div class="signature">
```lua
origin() -> Vector
```
</div>

Returns the zero vector (0, 0).
```lua
local origin = Vector.origin()  -- 0 0
```


### `scaleAndAdd`

{/* scaleAndAdd: (a: Vector, b: Vector, scale: number) -> Vector */}
<div class="signature">
```lua
scaleAndAdd(a: Vector, b: Vector, scale: number) -> Vector
```
</div>

Returns a + b * scale.
```lua
local r = Vector.scaleAndAdd(Vector.xy(1,2), Vector.xy(3,4), 2)  -- 7 10
```


### `scaleAndSub`

{/* scaleAndSub: (a: Vector, b: Vector, scale: number) -> Vector */}
<div class="signature">
```lua
scaleAndSub(a: Vector, b: Vector, scale: number) -> Vector
```
</div>

Returns a - b * scale.
```lua
local r = Vector.scaleAndSub(Vector.xy(7,10), Vector.xy(3,4), 2)  -- 1 2
```


### `lerp`

{/* lerp: (from: Vector, to: Vector, t: number) -> Vector */}
<div class="signature">
```lua
lerp(from: Vector, to: Vector, t: number) -> Vector
```
</div>

Returns the linear interpolation between the to and from
vector, using t where 0 returns the vector and 1 returns the other.
```lua
local p = Vector.lerp(Vector.xy(0,0), Vector.xy(8,0), 0.25)  -- 2 0
```


### `normalized`

{/* normalized: (v: Vector) -> Vector */}
<div class="signature">
```lua
normalized(v: Vector) -> Vector
```
</div>

Returns a normalized copy of the given vector.
```lua
local n = Vector.normalized(Vector.xy(10, 0))  -- Vector.xy(1, 0)
```


## Static Functions

### `distance`

{/* distance: (a: Vector, b: Vector) -> number */}
<div class="signature">
```lua
distance(a: Vector, b: Vector) -> number
```
</div>

Returns the distance between the two vectors.
```lua
local d = Vector.distance(Vector.xy(3, 4), Vector.xy(0, 0))  -- 5
```


### `distanceSquared`

{/* distanceSquared: (a: Vector, b: Vector) -> number */}
<div class="signature">
```lua
distanceSquared(a: Vector, b: Vector) -> number
```
</div>

Returns the squared distance between the two vectors.
```lua
local d2 = Vector.distanceSquared(Vector.xy(3,4), Vector.xy(0,0))  -- 25
```


### `dot`

{/* dot: (a: Vector, b: Vector) -> number */}
<div class="signature">
```lua
dot(a: Vector, b: Vector) -> number
```
</div>

Returns the dot product of the two vectors.
```lua
local dp = Vector.dot(Vector.xy(1,2), Vector.xy(3,4))  -- 11 (1*3 + 2*4)
```


### `cross`

{/* cross: (a: Vector, b: Vector) -> number */}
<div class="signature">
```lua
cross(a: Vector, b: Vector) -> number
```
</div>

Returns the cross product of two vectors (z-component of the 3D cross product).
```lua
local c = Vector.cross(Vector.xy(1, 0), Vector.xy(0, 1))  -- 1
```


### `length`

{/* length: (v: Vector) -> number */}
<div class="signature">
```lua
length(v: Vector) -> number
```
</div>

Returns the length of the given vector.
```lua
local len = Vector.length(Vector.xy(3, 4))  -- 5
```


### `lengthSquared`

{/* lengthSquared: (v: Vector) -> number */}
<div class="signature">
```lua
lengthSquared(v: Vector) -> number
```
</div>

Returns the squared length of the given vector.
```lua
local len2 = Vector.lengthSquared(Vector.xy(3, 4))  -- 25
```


## Methods

### `length`

{/* function length(self): number */}
<div class="signature">
```lua
length() -> number
```
</div>

<Warning>
  **Deprecated** - Use `Vector.length` instead.
</Warning>

Returns the length of the vector.


### `lengthSquared`

{/* function lengthSquared(self): number */}
<div class="signature">
```lua
lengthSquared() -> number
```
</div>

<Warning>
  **Deprecated** - Use `Vector.lengthSquared` instead.
</Warning>

Returns the squared length of the vector.
```lua
local v = Vector.xy(3, 4)
local len2 = v:lengthSquared()  -- 25
```


### `normalized`

{/* function normalized(self): Vector */}
<div class="signature">
```lua
normalized() -> Vector
```
</div>

<Warning>
  **Deprecated** - Use `Vector.normalized` instead.
</Warning>

Returns a normalized copy of the vector. If the length is zero,
the result is the zero vector.
```lua
local v = Vector.xy(10, 0)
local n = v:normalized()  -- 1 0
```


### `__eq`

{/* function __eq(self, rhs: Vector): boolean */}
<div class="signature">
```lua
__eq(rhs: Vector) -> boolean
```
</div>

Returns true if the two vectors have equal components.
```lua
local a = Vector.xy(1, 2)
local b = Vector.xy(1, 2)
local c = Vector.xy(2, 1)
print(a == b)  -- true
print(a == c)  -- false
```


### `__unm`

{/* function __unm(self): Vector */}
<div class="signature">
```lua
__unm() -> Vector
```
</div>

Returns the negated vector.
```lua
local v = Vector.xy(2, -3)
local neg = -v   -- -2 3
```


### `__add`

{/* function __add(self, rhs: Vector): Vector */}
<div class="signature">
```lua
__add(rhs: Vector) -> Vector
```
</div>

Returns the sum of two vectors.
```lua
local a = Vector.xy(2, 3)
local b = Vector.xy(-1, 5)
local c = a + b  -- 1 8
```


### `__sub`

{/* function __sub(self, rhs: Vector): Vector */}
<div class="signature">
```lua
__sub(rhs: Vector) -> Vector
```
</div>

Returns the difference between two vectors.
```lua
local a = Vector.xy(2, 3)
local b = Vector.xy(-1, 5)
local c = a - b  -- 3 -2
```


### `__mul`

{/* function __mul(self, rhs: number): Vector */}
<div class="signature">
```lua
__mul(rhs: number) -> Vector
```
</div>

Returns the vector scaled by the given number.
```lua
local v = Vector.xy(3, -2)
local doubled = v * 2    -- 6 -4
```


### `__div`

{/* function __div(self, rhs: number): Vector */}
<div class="signature">
```lua
__div(rhs: number) -> Vector
```
</div>

Returns the vector divided by the given number.
```lua
local v = Vector.xy(6, -4)
local half = v / 2    -- 3 -2
```


### `distance`

{/* function distance(self, other: Vector): number */}
<div class="signature">
```lua
distance(other: Vector) -> number
```
</div>

<Warning>
  **Deprecated** - Use `Vector.distance` instead.
</Warning>

Returns the distance to the other vector.
```lua
local a = Vector.xy(0, 0)
local b = Vector.xy(3, 4)
print(a:distance(b))  -- 5
```


### `distanceSquared`

{/* function distanceSquared(self, other: Vector): number */}
<div class="signature">
```lua
distanceSquared(other: Vector) -> number
```
</div>

<Warning>
  **Deprecated** - Use `Vector.distanceSquared` instead.
</Warning>

Returns the squared distance to the other vector.
```lua
local a = Vector.xy(0, 0)
local b = Vector.xy(3, 4)
print(a:distanceSquared(b))  -- 25
```


### `dot`

{/* function dot(self, other: Vector): number */}
<div class="signature">
```lua
dot(other: Vector) -> number
```
</div>

<Warning>
  **Deprecated** - Use `Vector.dot` instead.
</Warning>

Returns the dot product of the vector and the other vector.
```lua
local a = Vector.xy(1, 2)
local b = Vector.xy(3, 4)
print(a:dot(b))  -- 11  (1*3 + 2*4)
```


### `lerp`

{/* function lerp(self, other: Vector, t:number): Vector */}
<div class="signature">
```lua
lerp(other: Vector, t: number) -> Vector
```
</div>

<Warning>
  **Deprecated** - Use `Vector.lerp` instead.
</Warning>

Returns the linear interpolation between the vector and the other
vector, using t where 0 returns the vector and 1 returns the other.
```lua
local a = Vector.xy(0, 0)
local b = Vector.xy(10, 0)
local p = a:lerp(b, 0.5)  -- 5 0
```