Understanding CFrames
Understanding CFrames
A datatype/CFrame
, short for Coordinate Frame, is a data type used to rotate and position 3D objects. As either an object property or a standalone unit, a CFrame contains global X, Y, and Z coordinates as well as rotation data for each axis. In addition, CFrames contain helpful functions for working with objects in the 3D space.
Some examples of CFrame applications in a game might be:
- Finding a far-off target point for a projectile, like the position of an enemy targeted by a player’s laser blaster.
- Moving the camera so that it focuses on specific NPCs as a player interacts with them.
- Placing a status indicator directly above a player’s head to show if they are paralyzed, boosted, poisoned, etc.
CFrame Basics
Positioning a CFrame
An empty CFrame can be created with datatype/CFrame|CFrame.new()
at a default position of 0, 0, 0 in the game world. To position a CFrame at a specific point however, you should provide X, Y, and Z parameters to CFrame.new()
. In the following example, the redBlock
object is re-positioned at -2, 2, 4 by overwriting its CFrame property with the values stored in newCFrame
.


Alternatively, you can provide a new datatype/Vector3
position to CFrame.new()
and achieve the same result:
Rotating a CFrame
To create a rotated CFrame, use the datatype/CFrame|CFrame.Angles()
constructor, providing a rotation angle in radians for the desired axes:


CFrame.Angles()
must be specified in radians, not degrees. If you prefer degrees, simply use the math.rad()
converter as shown in this example.
Facing Toward a Point
One of the most powerful uses of CFrame.new()
is the ability to point the front surface of a CFrame at a specific point in the world. Consider the following example which places the redBlock
part at 0, 3, 0 and then points its front surface (marked by the white circle) at the blueCube
part:


Offsetting a CFrame
In some cases, you’ll need to offset an object by a specific number of studs from its current position. This can be done by simply adding or subtracting a Vector3 to/from a new CFrame created at the object’s position.


CFrame.new()
, as seen here, its Position property (redBlock.Position
) is a convenient shortcut.
The same technique can be used to offset an object from the position of another object. This time, a Vector3 is added to a new CFrame created at the blue cube’s position instead of the block’s position.


Dynamic CFrame Orientation
By themselves, the CFrame.new()
and CFrame.Angles()
constructors are powerful but they’re also very strict — they simply position/rotate an object at a specific orientation within the world. This is useful in some cases, but what if you can’t rely on a fixed world position and rotation angle? For instance:
- Placing a floating treasure directly in front of a player who may be standing anywhere in the world, facing any direction.
- Making a magical genie appear directly above a player’s right shoulder.
In these cases, CFrame functions are far more powerful than the strict constructors.
Relative Position
The datatype/CFrame|CFrame:ToWorldSpace()
function transforms an object’s CFrame — respecting its own local orientation — to a new world orientation. This makes it ideal for offsetting a part relative to itself or another object, regardless of how it’s currently positioned/rotated.
In the code/image below, notice that the red block gets offset 2 studs relative to the Y axis of the blue cube (the green arrow pointing through it) and not relative to the global Y axis pointing straight up.


Relative Rotation
CFrame:ToWorldSpace()
is also useful for rotating an object relative to itself, for instance rotating it 70 degrees counter-clockwise on its current Y axis and 20 degrees clockwise on its current Z axis.


Facing a Specific Surface Toward a Point
As illustrated earlier, you can make an object “look” at another object by supplying a Vector3 point as the second parameter of CFrame.new()
. This can be limiting, however, since the operation is associated with the object’s front face.
Fortunately, you can use relative rotation to make any face of the object point toward a Vector3 point. Consider this example which performs two consecutive CFrame operations:
- Point the front surface (marked by the white circle) at the target.
- Rotate the CFrame to make the top surface (marked by the black circle) point toward the target.


Finding a Point Between Points
Using a method known as linear interpolation, often referred to as lerp, you can position a CFrame between two points. For instance, the following code positions the redBlock
part directly between the greenCube
and cyanCube
parts, using a value of 0.7
to place it 70% of the distance away from the green cube.


These pointers should get you started on orienting objects in the game world via CFrame constructors and functions. Once you have a solid understanding of these concepts, consider exploring advanced CFrame manipulation in articles/CFrame Math Operations|CFrame Math Operations
.