Special Types

Learn what special types exist, including Vector, Quaternions, and more.

Vector3

Decentraland uses vector3 data to represent paths, points in space, and directions. Vectors can also be used to define rotation orientations, as a friendlier alternative to quaternions. A Vector3 object contains numerical values for each of the x, y, and z axis.

const myVector: Vector3 = { x: 8, y: 1, z: 8 }

The Vector3 namespace contains a series of handy methods that you can call to avoid having to deal with most vector math operations. Write Vector3., and VS Studio will display a dropdown with all of the available functions.

Below are a few lines showing the syntax for some basic operations with vectors.

// Create a vector object
let myVector = Vector3.create(3, 1, 5)

// Alternative syntax to create a vector object
let myOtherVector: Vector3 = { x: 8, y: 1, z: 8 }

// Edit one of its values
myVector.x = 5

// Call functions from the Vector3 namespace,
// All these functions require passing Vector3 objects in their parameters

let normalizedVector = Vector3.normalize(myVector)

let distance = Vector3.distance(myVector, myOtherVector)

let midPoint = Vector3.lerp(myVector, myOtherVector, 0.5)

Vector3 objects are often required in the fields of several components. For example, the Transform component contains Vector3 values for the position and scale of the entity.

To create a custom component with parameters that require Vector3 values, set the type of these parameters as Schema.Vector3.

📔 Note: Vector3 must be imported via

import { Vector3 } from "@dcl/sdk/math"

See Imports for how to handle these easily.

Shortcuts for writing direction vectors

The following shortcuts exist for defining generic vectors:

• Vector3.Zero() returns (0, 0, 0)

• Vector3.Up() returns (0, 1, 0)

• Vector3.Down() returns (0, -1, 0)

• Vector3.Left() returns (-1, 0, 0)

• Vector3.Right() returns (1, 0, 0)

• Vector3.Forward() returns (0, 0, 1)

• Vector3.Backward() returns (0, 0, -1)

Quaternions

Quaternions are used to store rotation information for the Transform component. A Quaternion is composed of four numerical values between -1 and 1: x, y, z, w.

const myQuaternion: Vector3 = { x: 0, y: 0, z: 0, w: 1 }

Quaternions are different from Euler angles, the more common x, y and z notation with numbers that go from 0 to 360 that most people are familiar with. The engine expresses all rotations as Quaternions, so it makes sense to avoid computations to convert to and from euler whenever possible.

The Quaternion namespace contains a series of handy methods that you can call to avoid having to deal with many math operations. Write Quaternion., and VS Studio will display a dropdown with all of the available functions.

Below are a few lines showing the syntax for some basic operations with Quaternions.

// Create a quaternion object
let myQuaternion = Quaternion.crate(0, 0, 0, 1)

// Edit one of its values
myQuaternion.x = 1

// Call functions from the quaternion namespace
let midPoint = Quaternion.slerp(myQuaternion1, myQuaternion2, 0.5)

let rotationDifference = Quaternion.fromToRotation(
  myQuaternion1,
  myQuaternion2,
  Quaternion.Zero()
)

Since it's a lot easier to think in terms of Euler degrees, the SDK includes a couple of functions to convert to and from Quaternions and Euler.

💡 Tip: Avoid running these conversions as part of recurrent logic inside a system, that run on every tick, as that can get expensive. These conversions are mostly useful for one-time operations, like setting the rotation of a new entity.

// From euler to Quaternion
let myQuaternion = Quaternion.fromEulerDegrees(90, 0, 0)

// From quaternion to Euler
let myEuler = Quaternion.toEulerAngles(myQuaternion)

Quaternion objects are often required in the fields of components. For example, the Transform component contains Quaternion values for rotation of the entity.

To create a custom component with parameters that require Quaternion values, set the type of these parameters as Schema.Quaternion.

📔 Note: Quaternion must be imported via

import { Quaternion } from "@dcl/sdk/math"

See Imports for how to handle these easily.

Scalars

A scalar is nothing more than a number. For that reason, it doesn't make much sense to instantiate a Scalar object to store data, as you can do the same with a number. The functions in the Scalar namespace however expose several handy functions (similar to those in the Vector3 namespace), that can be used on numbers.

// Call functions from the Scalar class
let random = Scalar.randomRange(1, 100)

let midPoint = Scalar.lerp(number1, number2, 0.5)

let clampedValue = Scalar.clamp(myInput, 0, 100)

📔 Note: Scalar must be imported via

import { Scalar } from "@dcl/sdk/math"

See Imports for how to handle these easily.