Data types

Rally’s value types are immutable classes: every operation returns a new value, and a property only changes when you assign it a new one.

import { Part, Vector3, getChild, workspace } from '@rally/sdk';

const platform = getChild(workspace, 'Platform', Part);
platform.position = platform.position.add(new Vector3(0, 5, 0)); // not position.y += 5

They don’t work with operators such as + or *: use methods like add, sub and mul. To compare two values, use equals; === only tells you whether two variables hold the same object. Import the classes from @rally/sdk. Positions and sizes are in studs, rotations in degrees.

Vector3

A 3D vector: positions, sizes, velocities and directions (in studs), and rotations (in degrees around X, Y and Z).

Constructors

Constructor	Description
new Vector3(x = 0, y = 0, z = 0)	A vector; each component defaults to 0.
Vector3.from(v: Vector3Like): Vector3	Converts [x, y, z] or { x, y, z } (missing components are 0). A Vector3 is returned as it is.

Constants

Constant	Value
Vector3.zero	new Vector3(0, 0, 0)
Vector3.one	new Vector3(1, 1, 1)
Vector3.up	new Vector3(0, 1, 0)
Vector3.xAxis	new Vector3(1, 0, 0)
Vector3.yAxis	new Vector3(0, 1, 0)
Vector3.zAxis	new Vector3(0, 0, 1)

Properties (read-only)

Property	Type	Description
x	number	X component.
y	number	Y component (up).
z	number	Z component.
magnitude	number	Length.
unit	Vector3	Same direction, length 1 (the zero vector stays zero).

Methods

Method	Description
add(o: Vector3): Vector3	Component-wise sum.
sub(o: Vector3): Vector3	Component-wise difference.
mul(s: number | Vector3): Vector3	Scales by a number, or multiplies component by component with another Vector3.
div(s: number): Vector3	Divides each component by a number.
neg(): Vector3	The opposite vector.
dot(o: Vector3): number	Dot product.
cross(o: Vector3): Vector3	Cross product.
distanceTo(o: Vector3): number	Distance to another point.
lerp(o: Vector3, t: number): Vector3	Linear interpolation: t 0 is this vector, 1 is o.
withX(x: number): Vector3	A copy with x replaced.
withY(y: number): Vector3	A copy with y replaced.
withZ(z: number): Vector3	A copy with z replaced.
equals(o: Vector3, epsilon = 1e-6): boolean	True when every component differs by at most epsilon.
toArray(): [number, number, number]	[x, y, z].
toString(): string	Text like Vector3(1, 2.5, 0), rounded to 3 decimals.

Vector2

A 2D vector: positions and sizes on screen (in pixels, or as fractions of the parent), and 2D math.

Constructors

Constructor	Description
new Vector2(x = 0, y = 0)	A vector; each component defaults to 0.
Vector2.from(v: Vector2Like): Vector2	Converts [x, y] or { x, y } (missing components are 0). A Vector2 is returned as it is.

Constants

Constant	Value
Vector2.zero	new Vector2(0, 0)
Vector2.one	new Vector2(1, 1)

Properties (read-only)

Property	Type	Description
x	number	X component (to the right on screen).
y	number	Y component (on screen, it points down).
magnitude	number	Length.
unit	Vector2	Same direction, length 1 (the zero vector stays zero).

Methods

Method	Description
add(o: Vector2): Vector2	Component-wise sum.
sub(o: Vector2): Vector2	Component-wise difference.
mul(s: number): Vector2	Scales by a number.
lerp(o: Vector2, t: number): Vector2	Linear interpolation: t 0 is this vector, 1 is o.
equals(o: Vector2, epsilon = 1e-6): boolean	True when both components differ by at most epsilon.
toArray(): [number, number]	[x, y].
toString(): string	Text like Vector2(100, 40), rounded to 3 decimals.

Color3

An RGB color. Each channel (r, g and b) goes from 0 to 1.

Constructors

Constructor	Description
new Color3(r = 1, g = 1, b = 1)	A color from channels between 0 and 1; each defaults to 1 (white).
Color3.fromRGB(r: number, g: number, b: number): Color3	From channels between 0 and 255.
Color3.fromHex(hex: string): Color3	From '#2c7afd', '2c7afd' or '#fff'. Text that isn’t a color gives white.
Color3.fromInt(n: number): Color3	From a number like 0x2c7afd.
Color3.fromHSV(h: number, s: number, v: number): Color3	From hue, saturation and value, each from 0 to 1.
Color3.from(value: Color3Like): Color3	Converts a hex string, a 0xRRGGBB number, an [r, g, b] array or an { r, g, b } object (channels 0 to 1). A Color3 is returned as it is.

Constants

Constant	Value
Color3.white	Color3.fromHex('#ffffff')
Color3.black	Color3.fromHex('#000000')

Properties (read-only)

Property	Type	Description
r	number	Red, 0 to 1.
g	number	Green, 0 to 1.
b	number	Blue, 0 to 1.

Methods

Method	Description
lerp(o: Color3, t: number): Color3	Blends toward o: t 0 is this color, 1 is o.
toInt(): number	The color as a 0xRRGGBB number.
toHex(): string	The color as '#rrggbb'.
equals(o: Color3): boolean	True when both colors have the same '#rrggbb'.
toString(): string	Text like Color3(#2c7afd).

Quaternion

A rotation as a unit quaternion, for rotation math such as turning a direction or blending two rotations. Parts store rotation as Euler angles in degrees: convert with fromEulerDegrees and toEulerDegrees.

Constructors

Constructor	Description
new Quaternion(x = 0, y = 0, z = 0, w = 1)	A quaternion from its components; the default, (0, 0, 0, 1), is no rotation.
Quaternion.fromEulerDegrees(e: Vector3): Quaternion	From Euler angles in degrees, applied in X, then Y, then Z order: the way a part’s rotation works.

Properties (read-only)

Property	Type	Description
x	number	X component.
y	number	Y component.
z	number	Z component.
w	number	W component.

Methods

Method	Description
toEulerDegrees(): Vector3	Back to Euler angles in degrees, in the form a part’s rotation takes.
rotate(v: Vector3): Vector3	Rotates a vector by this rotation.
slerp(o: Quaternion, t: number): Quaternion	Smoothly interpolates toward o: t 0 is this rotation, 1 is o.
normalized(): Quaternion	The same rotation scaled to length 1.

import { Part, Quaternion, Vector3, getChild, print, workspace } from '@rally/sdk';

// Which way does the part's own X axis point in the world?
const arrow = getChild(workspace, 'Arrow', Part);
const turn = Quaternion.fromEulerDegrees(arrow.rotation);
print(turn.rotate(Vector3.xAxis));

// Halfway between two rotations, as a rotation a part can use.
const a = Quaternion.fromEulerDegrees(new Vector3(0, 0, 0));
const b = Quaternion.fromEulerDegrees(new Vector3(0, 90, 0));
arrow.rotation = a.slerp(b, 0.5).toEulerDegrees();

Assigning values to properties

Properties check what you assign:

• Numbers can’t be NaN, and numbers outside a property’s range are clamped into it.
• Vectors must be finite: Infinity or NaN in a component throws.
• Enum properties take one of their allowed strings; anything else throws a TypeError that lists them (see Enums).
• Instance properties (such as Model.primaryPart) take an instance of the right class, or null.

In scripts, assign values of the property’s type: new Vector3(0, 5, 0), Color3.fromHex('#ff3b30'). Project files store the same values as JSON: vectors as [x, y, z] arrays and colors as "#rrggbb" strings (see Project format).

Types Rally doesn’t have

If you’re used to other engines, these types have no direct equivalent in Rally:

Type	In Rally
CFrame	A part’s position and rotation (both Vector3; rotation in degrees). Use Quaternion for rotation math.
UDim2, UDim	A GUI object’s positionScale + position and sizeScale + size (each a Vector2).
BrickColor	Color3.
Enum.* values	Strings, such as part.material = 'neon' (Enums).
Ray	workspace.raycast(origin, direction) takes the ray’s origin and direction.
NumberRange, NumberSequence, ColorSequence, Rect, Region3	None.

Structures

Plain objects the API takes or returns. Each is a type you can import for annotations, such as import type { TweenInfo } from '@rally/sdk'.

TweenInfo

Field	Type	Description
time	number	Duration in seconds.
easing?	Easing	The curve to follow. The default is 'quadInOut'.
repeatCount?	number	Extra plays after the first (-1 repeats forever).
reverses?	boolean	Play backwards after each forward play (a moving platform).
delay?	number	Seconds to wait before starting.

RaycastOptions

Field	Type	Description
ignore?	Instance[]	Instances (and their descendants) the ray passes through.
hitCharacters?	boolean	Include characters (default true).

RaycastResult

Field	Type	Description
instance	BasePart | Character | Terrain	What was hit: a part, a character, or Terrain.
position	Vector3	Where the ray hit, in world coordinates.
normal	Vector3	The direction the hit surface faces, with length 1.
distance	number	How far the hit is from the ray’s origin, in studs.

InputObject

Field	Type	Description
kind	'key' | 'mouse' | 'touch'	'key' for keyboard keys, 'mouse' for mouse buttons (see Input kind).
key	string	Keyboard keys by their KeyboardEvent.code name ('KeyE', 'Space', 'ArrowUp'); mouse buttons as 'MouseLeft', 'MouseMiddle' or 'MouseRight'.
position	Vector2	The pointer position, in pixels, when the input happened.

AnimationTrack

One animated property of one object.

Field	Type	Description
path?	string	Path of names from the target to the animated object ('Lid', 'Arm/Hand'); ‘’ = target.
property	string	The property, e.g. ‘position’, ‘rotation’, ‘color’, ‘transparency’, ‘size’.
keys	AnimationKey[]	The keyframes: at least one. Keys are sorted by time when the tracks are assigned.
relative?	boolean	Values are offsets added to the property’s value when play() starts. Works for number, Vector3 and Vector2 properties.

AnimationKey

One keyframe: at t seconds the property is value; easing shapes the way to the next key.

Field	Type	Description
t	number	Time of the key, in seconds from the start of the animation (negative times count as 0).
value	unknown	A number, [x, y, z], "#rrggbb", … — whatever the property takes.
easing?	Easing	Curve from this key to the next (default ‘linear’).

TerrainStroke

Field	Type	Description
x	number	Center of the brush in world coordinates (x).
z	number	Center of the brush in world coordinates (z).
radius	number	Brush radius in studs.
strength	number	raise/lower: studs added at the center. smooth/flatten: how far to blend, 0–1 (1 = fully). The effect fades smoothly to nothing at the brush edge.
mode	SculptMode	What the brush does.
target?	number	flatten: the world height to level to (default: the height at the brush center).

TerrainPaintStroke

Field	Type	Description
x	number	Center of the brush in world coordinates (x).
z	number	Center of the brush in world coordinates (z).
radius	number	Brush radius in studs.
material	TerrainMaterial	The material to paint.

DataValue

type DataValue = string | number | boolean | null | DataValue[] | { [key: string]: DataValue };

What a data store can hold: JSON values.

AttributeValue

type AttributeValue = string | number | boolean | Vector3 | Vector2 | Color3 | null;

What an attribute can hold. Setting an attribute to null (or undefined) removes it.