Skip to main content

Vectors

Excalibur uses the Vector structure to represent points. The Vector class has many different static methods available for doing vector math as well as instance methods to combine vectors together in different ways.

Creating vectors​

To quickly create a vector, use the vec global:

ts
import { vec } from 'excalibur'
 
const point = vec(0, 10)
ts
import { vec } from 'excalibur'
 
const point = vec(0, 10)

Alternatively, you may see examples of using the more verbose new Vector(x, y) format:

ts
import { Vector } from 'excalibur'
 
const point = new Vector(0, 10)
ts
import { Vector } from 'excalibur'
 
const point = new Vector(0, 10)

To set the value of an existing vector, use Vector.setTo:

ts
import { vec } from 'excalibur'
 
const point = vec(0, 10).setTo(10, 10)
ts
import { vec } from 'excalibur'
 
const point = vec(0, 10).setTo(10, 10)

There are some built-in vector constants you can use:

Cloning vectors​

Vectors are objects, so mutating them will change the state for all references. Use the Vector.clone method to clone a vector to mutate it:

ts
import { vec } from 'excalibur'
 
const point = vec(0, 10)
point.setTo(8, 8)
       
(method) Vector.setTo(x: number, y: number): void
const samePoint = point
const anotherPoint = point.clone()
anotherPoint.setTo(50, 50)
 
console.log(point.toString()) // "(8, 8)"
console.log(samePoint.toString()) // "(8, 8)"
console.log(anotherPoint.toString()) // "(50, 50)"
ts
import { vec } from 'excalibur'
 
const point = vec(0, 10)
point.setTo(8, 8)
       
(method) Vector.setTo(x: number, y: number): void
const samePoint = point
const anotherPoint = point.clone()
anotherPoint.setTo(50, 50)
 
console.log(point.toString()) // "(8, 8)"
console.log(samePoint.toString()) // "(8, 8)"
console.log(anotherPoint.toString()) // "(50, 50)"
tip

Notice how both point and samePoint share the same vector reference, so using setTo mutates the vector. Use clone to ensure you are not changing vectors unexpectedly!

setTo returns void so that it "feels awkward" to chain it. This is intentional to avoid confusion about whether you are mutating the vector or creating a new one.

Linear interpolation (lerp) between vectors​

Lerp returns a new vector that represents a point along the line between two vectors. Given a number between 0 and 1 (representing the percentage of progress) and a target vector, it produces the intermediate vector at that fraction of the distance.

The standard formula for linear interpolation is:

lerp(a, b, t) = a + (b - a) * t
lerp(a, b, t) = a + (b - a) * t
  • a = starting vector
  • b = target vector
  • t = interpolation factor (0 ≤ t ≤ 1)

When t = 0, the result is a.

When t = 1, the result is b.

When t = 0.5, the result is exactly halfway between a and b.