Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 37 ยท Parts, Physics and Building

Vectors and CFrames

Learn Vector3 math (add, scale, Magnitude, Unit, Dot, Lerp) and CFrame (position plus rotation, Angles, lookAt, LookVector, multiplication, PivotTo) for placing and moving Roblox parts.

Where is something, which way does it face, how far is it from the player? Roblox answers all three with two types: Vector3 (a point or a direction in 3D) and CFrame (a position and a rotation together). Almost every script that moves or aims something uses them.

Vector3

A Vector3 is three numbers: X, Y, Z. In Roblox, Y is up; X and Z lie on the ground. The unit is the stud.

LUA
local a = Vector3.new(1, 2, 3)
print(a.X, a.Y, a.Z)    --> 1 2 3

A Vector3 can mean two different things, and it helps to keep them apart:

  • a point: a location, like part.Position.
  • a direction or offset: an arrow, such as "10 studs up".

Vector math

Vectors support operators directly:

LUA
local a = Vector3.new(1, 2, 3)
local b = Vector3.new(4, 5, 6)

print(a + b)    --> 5, 7, 9
print(b - a)    --> 3, 3, 3    (the arrow from a to b)
print(a * 2)    --> 2, 4, 6    (scale)
print(a / 2)    --> 0.5, 1, 1.5
print(-a)       --> -1, -2, -3

Useful members:

Member Meaning
v.Magnitude Length of the vector
v.Unit Same direction, length 1
a:Dot(b) Dot product: how much two directions agree (1 same, 0 perpendicular, -1 opposite for unit vectors)
a:Cross(b) Vector perpendicular to both
a:Lerp(b, t) Blend: t = 0 gives a, t = 1 gives b
(a - b).Magnitude Distance between two points
LUA
local player = workspace.Player.HumanoidRootPart
local door = workspace.Door

local distance = (door.Position - player.Position).Magnitude
if distance < 10 then
	print("The player is near the door")
end

Subtracting two positions gives the arrow between them; its Magnitude is the distance. This is the most common vector trick in Roblox.

Constants: Vector3.zero (0,0,0), Vector3.one (1,1,1), Vector3.xAxis, Vector3.yAxis, Vector3.zAxis.

Direction toward a target

LUA
local direction = (target.Position - start.Position).Unit   -- length 1
local nextPoint = start.Position + direction * 5            -- 5 studs toward the target

Taking .Unit removes the distance and keeps just the direction. Multiply it by a speed to make something chase a target. Beware: .Unit of a zero vector gives NaN; check the distance first.

CFrame

A CFrame (coordinate frame) stores a position and a rotation. Every part has part.CFrame. Setting CFrame moves and rotates it in one step. part.Position is shorthand for part.CFrame.Position.

LUA
local cf1 = CFrame.new(0, 10, 0)                    -- position only
local cf2 = CFrame.new(Vector3.new(5, 0, 5))        -- from a Vector3
local cf3 = CFrame.Angles(0, math.rad(90), 0)       -- rotation only (radians!)
local cf4 = CFrame.lookAt(Vector3.new(0, 5, 0), Vector3.new(10, 5, 0))  -- at (0,5,0), facing (10,5,0)

CFrame.Angles(rx, ry, rz) takes radians; convert degrees with math.rad. A turn left or right (spin around the up axis) is the Y angle.

Reading a CFrame

LUA
local cf = part.CFrame
print(cf.Position)      -- the point
print(cf.LookVector)    -- where the front faces (the -Z direction)
print(cf.RightVector)   -- the right side
print(cf.UpVector)      -- the top

LookVector is how you shoot a bullet forward: bullet.Position = muzzle.Position + muzzle.CFrame.LookVector * 5.

Combining CFrames

Multiplying CFrames applies one relative to the other. The right-hand side is interpreted in the space of the left:

LUA
local base = CFrame.new(10, 0, 0) * CFrame.Angles(0, math.rad(90), 0)
-- "stand at (10, 0, 0), turn 90 degrees"

local placed = base * CFrame.new(0, 0, -5)
-- "now walk 5 studs forward in that turned direction"

The order matters: A * B is not the same as B * A. A handy mental model is "start at A, then do B from there."

Moving things with CFrames

LUA
part.CFrame = part.CFrame * CFrame.new(0, 0, -2)               -- 2 studs forward (relative)
part.CFrame = part.CFrame * CFrame.Angles(0, math.rad(15), 0)  -- turn 15 degrees
part.CFrame = CFrame.new(0, 10, 0)                              -- jump to an absolute place

For a Model, use model:PivotTo(cframe) and model:GetPivot(). A single part also supports PivotTo.

Moving an unanchored part by setting its CFrame fights the physics engine. Anchor parts you move by script, or use constraints and forces for physical movement (see the next lesson).

Stand-in: Vector3 math

The following JavaScript stand-ins implement the same math. First vectors: add, scale, distance, direction and Lerp.

JS Stand-in: Vector3 operations (JavaScript)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: a CFrame that turns around Y

A real CFrame holds a full rotation. To keep this small, the stand-in handles position plus a turn around the vertical Y axis (a yaw), which is the most common case. Multiplication works the same way: the right side is applied in the left side's space.

JS Stand-in: CFrame position, yaw and multiplication (JavaScript)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

With the 90 degree turn applied first, "5 studs forward" goes sideways along the X axis from (10, 0, 0); in the other order it goes forward along Z before the turn. This is why CFrame order matters.

Common mistakes

  • Giving CFrame.Angles degrees; it needs radians (math.rad).
  • Treating Position as a direction: positions are points; subtract two to get a direction.
  • Calling .Unit on a zero-length vector (when two points coincide), which yields NaN.
  • Multiplying CFrames in the wrong order.
  • Moving unanchored parts by CFrame every frame and wondering why physics glitches.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How do you get the distance between two parts' positions?

    Subtracting positions gives the arrow between them; its Magnitude is the distance.
  2. 2. What unit does CFrame.Angles expect?

    Angles takes radians; use math.rad(degrees) to convert.
  3. 3. What does CFrame.LookVector give you?

    LookVector points the way the CFrame faces, which is useful for shooting or walking forward.
  4. 4. Does CFrame multiplication commute (A * B equals B * A)?

    A * B means 'start at A, then apply B from there', so the order matters.

Summary

  • Vector3 is a point or an arrow; Y is up; subtract points for a direction and use .Magnitude for distance, .Unit for pure direction.
  • Lerp, Dot and Cross blend, compare and combine vectors.
  • A CFrame is position plus rotation; build with CFrame.new, CFrame.Angles (radians) and CFrame.lookAt.
  • Multiply CFrames to apply movement relative to a frame; order matters; use PivotTo for models.

Next: Anchoring, Collisions and Physics