# CFrame

## Overview

CFrame is a data type that represents both position and rotation of an object in 3D space. Beyond simple coordinates, it includes directional information, making it useful for spatial placement and direction calculations.

Position data works like Vector3, allowing direct access to each X, Y, and Z values. Rotation is stored internally as a matrix, from which direction vectors like LookVector and RightVector are derived. These vectors are essential for tasks such as setting camera directions or aligning objects.

## Constructors

### Angles

Returns the same result as calling fromEulerAnglesXYZ() and uses the same rotation calculation method.

#### Parameters

| `number` rx | Rotation angle to apply around the X-axis, in radians. |
| ----------- | ------------------------------------------------------ |
| `number` ry | Rotation angle to apply around the Y-axis, in radians. |
| `number` rz | Rotation angle to apply around the Z-axis, in radians. |

#### Return

| `CFrame` | The created CFrame. |
| -------- | ------------------- |

#### Code Samples

```lua
local CF = CFrame.Angles(0, math.rad(40), 0)
```

### fromEulerAnglesXYZ

Receives rotation angles for the X, Y, and Z axes as radian values, then creates a CFrame with rotation applied in XYZ rotation order. The provided angles are applied sequentially in the specified axis order.

#### Parameters

| `number` rx | Rotation angle to apply around the X-axis, in radians. |
| ----------- | ------------------------------------------------------ |
| `number` ry | Rotation angle to apply around the Y-axis, in radians. |
| `number` rz | Rotation angle to apply around the Z-axis, in radians. |

#### Return

| `CFrame` | The created CFrame. |
| -------- | ------------------- |

#### Code Samples

```lua
local CF = CFrame.fromEulerAnglesXYZ(1, 0.5, 0.25)
```

### fromEulerAnglesYXZ

Receives rotation angles for the X, Y, and Z axes as radian values, then creates a CFrame with rotation applied in YXZ rotation order. The provided angles are applied sequentially in the specified axis order.

#### Parameters

| `number` rx | Rotation angle to apply around the X-axis, in radians. |
| ----------- | ------------------------------------------------------ |
| `number` ry | Rotation angle to apply around the Y-axis, in radians. |
| `number` rz | Rotation angle to apply around the Z-axis, in radians. |

#### Return

| `CFrame` | The created CFrame. |
| -------- | ------------------- |

#### Code Samples

```lua
local CF = CFrame.fromEulerAnglesYXZ(1, 0.5, 0.25)
```

### fromMatrix

Creates a CFrame based on the movement position and vectors forming the rotation matrix. If the Z value is omitted, the remaining rotation axis is automatically compensated by normalizing the cross product of X and Y. This completes the necessary rotation information to create the CFrame.

#### Parameters

| `Vector3` pos | The Vector3 value representing the position shift of the CFrame.                                                                                                                            |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Vector3` vX  | The Vector3 value corresponding to the first column of the rotation matrix, defining the local X-axis direction.                                                                            |
| `Vector3` vY  | The Vector3 value corresponding to the second column of the rotation matrix, defining the local Y-axis direction.                                                                           |
| `Vector3` vZ  | The Vector3 value corresponding to the third column of the rotation matrix, defining the local Z-axis direction. If omitted, the normalized cross product of X and Y is automatically used. |

#### Return

| `CFrame` | The created CFrame. |
| -------- | ------------------- |

#### Code Samples

```lua
local Position = Vector3.new(0, 50, 0)
local RightVector = Vector3.new(1, 0, 0)
local UpVector = Vector3.new(0, 1, 0)
local BackVector = Vector3.new(0, 0, 1)

local CF = CFrame.fromMatrix(Position, RightVector, UpVector, BackVector)
```

### fromOrientation

Returns the same result as calling fromEulerAnglesYXZ() and uses the same rotation calculation method.

#### Parameters

| `number` rx | Rotation angle to apply around the X-axis, in radians. |
| ----------- | ------------------------------------------------------ |
| `number` ry | Rotation angle to apply around the Y-axis, in radians. |
| `number` rz | Rotation angle to apply around the Z-axis, in radians. |

#### Return

| `CFrame` | The created CFrame. |
| -------- | ------------------- |

#### Code Samples

```lua
local CF = CFrame.fromOrientation(1, 0.5, 0.25)
```

### lookAt

Places the CFrame at the specified position (at), then applies rotation to look toward a specific point (lookAt). By default, the world space upward direction is calculated based on the Y-axis (0, 1, 0), and passing an up value allows direct setting of the reference upward direction.

#### Parameters

| `Vector3` at     | The Vector3 value representing the position to apply to the CFrame.                                                                                                   |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Vector3` lookAt | The Vector3 value representing the target position the CFrame should look toward. The created CFrame's direction is set to point toward this location.                |
| `Vector3` up     | The Vector3 value to be used as the upward direction. Specifies the reference upward direction when calculating direction; if omitted, the default (0, 1, 0) is used. |

#### Return

| `CFrame` | The created CFrame. |
| -------- | ------------------- |

#### Code Samples

```lua
local Part = script.Parent
local Workspace = game:GetService("Workspace")
local SpawnLocation = Workspace.SpawnLocation

local CF = CFrame.lookAt(Part.Position, SpawnLocation.Position)
```

### new

Creates and returns a new CFrame.

#### Parameters

#### Return

| `CFrame` | The created CFrame. |
| -------- | ------------------- |

#### Code Samples

```lua
local CF = CFrame.new()
```

### new

Creates a CFrame using the passed Vector3 value as position. No rotation information is included, and a coordinate system maintaining the default direction is returned.

#### Parameters

| `Vector3` Position | The Vector3 value representing the position to apply to the CFrame. |
| ------------------ | ------------------------------------------------------------------- |

#### Return

| `CFrame` | The created CFrame. |
| -------- | ------------------- |

#### Code Samples

```lua
local Position = Vector3.new(10, 50, 20)
local CF = CFrame.new(Position)
```

### new

Places the CFrame at the specified position, then sets the direction to point toward a specific location. By default, the world's upward direction is calculated based on the Y-axis (0, 1, 0).

#### Parameters

| `Vector3` Position | The Vector3 value representing the position to apply to the CFrame.                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Vector3` Look     | The Vector3 value representing the target position the CFrame should look toward. The created CFrame's direction is set to point toward this location. |

#### Return

| `CFrame` | The created CFrame. |
| -------- | ------------------- |

#### Code Samples

```lua
local Position = Vector3.new(10, 50, 20)
local LookAt = Vector3.new(0, 30, 0)
local CF = CFrame.new(Position, LookAt)
```

### new

Creates the CFrame's position based on the passed X, Y, Z coordinates. No rotation information is included, and a coordinate system maintaining the default direction is returned.

#### Parameters

| `number` x | The value of X coordinate. |
| ---------- | -------------------------- |
| `number` y | The value of Y coordinate. |
| `number` z | The value of Z coordinate. |

#### Return

| `CFrame` | The created CFrame. |
| -------- | ------------------- |

#### Code Samples

```lua
local CF = CFrame.new(10, 50, 20)
```

## Properties

### identity

`CFrame`

Represents the identity CFrame with no position or rotation. Provided as a fixed constant value, it does not belong to a specific CFrame instance and is used as a global reference value.

#### Code Samples

```lua
local CFZero = CFrame.identity
print(CFZero)
```

### LookVector

`Vector3`

LookVector is a vector representing the forward direction the CFrame is facing. Internally based on the inverted value of the Z-axis component of the rotation matrix, it is used to intuitively express the direction an object is facing.

#### Code Samples

```lua
local Part = script.Parent
local Workspace = game:GetService("Workspace")
local SpawnLocation = Workspace.SpawnLocation

local CF = CFrame.lookAt(Part.Position, SpawnLocation.Position)
print(CF.LookVector)
```

### Orientation

`Vector3`

Represents the rotational direction of the CFrame in 3D space. The direction is returned as Vector3 with the CFrame's rotation converted to Yaw, Pitch, and Roll.

This value must be configured in advance in the Workspace and cannot be modified at runtime while the game is running. Therefore, this property must be set during the Studio editing phase.

#### Code Samples

```lua
local CF = CFrame.fromOrientation(20, 90, 60)
print(CF.Orientation)
```

### Position

`Vector3`

The coordinates representing the position of the CFrame in 3D space.

#### Code Samples

```lua
local CF = CFrame.new(10, 50, 20)
print(CF.Position)
```

### RightVector

`Vector3`

The vector representing the right direction referenced by the CFrame. Internally corresponds to the first column of the rotation matrix, representing the local X-axis of an object.

#### Code Samples

```lua
local Part = script.Parent
local CF = Part.CFrame
print(CF.RightVector)
```

### Rotation

`CFrame`

Represents the rotational direction of the CFrame in 3D space. Internally, the direction information is expressed through a rotation matrix based on 3×3 rotation.

#### Code Samples

```lua
local CF = CFrame.Angles(0, math.rad(45), 0)
print(CF.Rotation)
```

### UpVector

`Vector3`

The vector representing the upward direction referenced by the CFrame. Internally corresponds to the second column of the rotation matrix, representing the local Y-axis of an object.

#### Code Samples

```lua
local Part = script.Parent
local CF = Part.CFrame
print(CF.UpVector)
```

### X

`number`

The X-axis coordinate value where the CFrame is positioned in 3D space.

#### Code Samples

```lua
local CF = CFrame.new(10, 50, 20)
print(CF.X)
```

### XVector

`Vector3`

Represents the vector corresponding to the X-axis in the CFrame's rotation direction. Internally, this is the same value as the first column of the rotation matrix and has the same direction as RightVector.

#### Code Samples

```lua
local CF = CFrame.new(10, 50, 20)
print(CF.XVector)
```

### Y

`number`

The Y-axis coordinate value where the CFrame is positioned in 3D space.

#### Code Samples

```lua
local CF = CFrame.new(10, 50, 20)
print(CF.Y)
```

### YVector

`Vector3`

Represents the vector for the Y-axis direction in the CFrame's rotation information. Internally, corresponds to the second column of the rotation matrix and has the same direction as UpVector.

#### Code Samples

```lua
local CF = CFrame.new(10, 50, 20)
print(CF.YVector)
```

### Z

`number`

The Z-axis coordinate value where the CFrame is positioned in 3D space.

#### Code Samples

```lua
local CF = CFrame.new(10, 50, 20)
print(CF.Z)
```

### ZVector

`Vector3`

Represents the vector corresponding to the Z-axis in the CFrame's rotation direction. Internally based on the third column of the rotation matrix, with a value opposite in direction to LookVector.

#### Code Samples

```lua
local CF = CFrame.new(10, 50, 20)
print(CF.ZVector)
```

## Methods

### FromEulerAnglesXYZ

Receives rotation angles for the X, Y, and Z axes as radian values, then creates a CFrame with rotation applied in XYZ rotation order.

#### Parameters

| `number` rx | Rotation angle to apply around the X-axis, in radians. |
| ----------- | ------------------------------------------------------ |
| `number` ry | Rotation angle to apply around the Y-axis, in radians. |
| `number` rz | Rotation angle to apply around the Z-axis, in radians. |

#### Return

| `CFrame` | The created CFrame. |
| -------- | ------------------- |

#### Code Samples

### FromEulerAnglesYXZ

Receives rotation angles for the X, Y, and Z axes as radian values, then creates a CFrame with rotation applied in YXZ rotation order.

#### Parameters

| `number` rx | Rotation angle to apply around the X-axis, in radians. |
| ----------- | ------------------------------------------------------ |
| `number` ry | Rotation angle to apply around the Y-axis, in radians. |
| `number` rz | Rotation angle to apply around the Z-axis, in radians. |

#### Return

| `CFrame` | The created CFrame. |
| -------- | ------------------- |

#### Code Samples

### Inverse

Returns a new CFrame with the conversion inversely applied. A coordinate system with both position and rotation inverted, which can be used to reverse conversions or calculate relative positions.

#### Parameters

#### Return

| `CFrame` | The created CFrame. |
| -------- | ------------------- |

#### Code Samples

```lua
local CF = CFrame.new(0, 50, 0)
local InverseCF = CF:Inverse()
```

### Lerp

Returns a new CFrame with position and rotation interpolated according to the alpha value between the current CFrame and the target CFrame. Alpha of 0 corresponds to the current CFrame, 1 corresponds to the goal CFrame.

#### Parameters

| `CFrame` goal  | The CFrame that is the target of interpolation. Position and rotation are interpolated from the current CFrame toward this CFrame.                                                                 |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `number` alpha | A numeric value representing the interpolation ratio. 0 corresponds to the current CFrame, 1 to the goal CFrame, and values between 0 and 1 represent intermediate states between the two CFrames. |

#### Return

| `CFrame` | Returns a new CFrame interpolated by the alpha ratio between the current CFrame and goal CFrame, with both position and rotation smoothly interpolated. |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |

#### Code Samples

```lua
local CF1 = CFrame.new(0, 0, 0)
local CF2 = CFrame.new(10, 10, 10)
local Alpha = 0.5

local Result = CF1:Lerp(CF2, Alpha)
```

### PointToObjectSpace

Converts world coordinates to the local coordinate system based on the CFrame. Reflects both the CFrame's position and rotation to return relative coordinates based on the object.

#### Parameters

| `Vector3` v3 | The Vector3 value representing a position in world space. The coordinate is converted to a local coordinate based on the CFrame. |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |

#### Return

| `Vector3` | Returns the coordinates in local space calculated by applying the CFrame's position and rotation to the input world coordinates. |
| --------- | -------------------------------------------------------------------------------------------------------------------------------- |

#### Code Samples

```lua
local CF = CFrame.new(25, 0, 0)
local WorldPoint = Vector3.new(35, 0, 0)
local LocalPoint = CF:PointToObjectSpace(WorldPoint)
```

### PointToWorldSpace

Converts local coordinates based on the CFrame to world coordinates. Reflects both the CFrame's position and rotation to return the actual coordinates in world space.

#### Parameters

| `Vector3` v3 | The Vector3 value representing the relative position calculated based on the CFrame. The coordinate is interpreted as a position based on the CFrame's origin. |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#### Return

| `Vector3` | Returns the coordinates in world space calculated by applying the CFrame's position and rotation to the provided relative coordinates. |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------- |

#### Code Samples

```lua
local CF = CFrame.new(10, 0, 0)
local LocalPoint = Vector3.new(15, 0, 0)
local WorldPoint = CF:PointToWorldSpace(LocalPoint)
```

### ToEulerAnglesXYZ

Approximates and returns the rotation applied to the CFrame as angle values based on XYZ rotation order.

#### Parameters

#### Return

| `Tuple` | Returns rotation angles for X-axis, Y-axis, and Z-axis in radians. |
| ------- | ------------------------------------------------------------------ |

#### Code Samples

```lua
local CF = CFrame.Angles(math.rad(30), math.rad(45), math.rad(60))
local X, Y, Z = CF:ToEulerAnglesXYZ()
```

### ToEulerAnglesYXZ

Approximates and returns the rotation applied to the CFrame as angle values based on YXZ rotation order.

#### Parameters

#### Return

| `Tuple` | Returns rotation angles for X-axis, Y-axis, and Z-axis in radians. |
| ------- | ------------------------------------------------------------------ |

#### Code Samples

```lua
local CF = CFrame.Angles(math.rad(30), math.rad(45), math.rad(60))
local X, Y, Z = CF:ToEulerAnglesYXZ()
```

### ToOrientation

Returns the same result as calling ToEulerAnglesYXZ() and uses the same rotation order and calculation method.

#### Parameters

#### Return

| `Tuple` | Returns rotation angles for X-axis, Y-axis, and Z-axis in radians. |
| ------- | ------------------------------------------------------------------ |

#### Code Samples

```lua
local CF = CFrame.Angles(math.rad(10), math.rad(20), math.rad(30))
local X, Y, Z = CF:ToOrientation()
```

### VectorToObjectSpace

Converts a direction vector in world space to a direction vector in local space based on the CFrame. Only rotation is applied in this process; position shift is not reflected.

#### Parameters

| `Vector3` v3 | The Vector3 value representing a direction in world space. The vector is converted to a local direction vector based on the CFrame. |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |

#### Return

| `Vector3` | Returns the direction vector in local space calculated by applying the CFrame's rotation to the provided direction vector. |
| --------- | -------------------------------------------------------------------------------------------------------------------------- |

#### Code Samples

```lua
local CF = CFrame.new()
local WorldDir = Vector3.new(1, 0, 0)
local LocalDir = CF:VectorToObjectSpace(WorldDir)
```

### VectorToWorldSpace

Converts a direction vector based on the CFrame to a direction vector in the world coordinate system. Only rotation is applied in this process; position shift is not reflected.

#### Parameters

| `Vector3` v3 | The Vector3 value representing the direction vector in local space based on the CFrame. |
| ------------ | --------------------------------------------------------------------------------------- |

#### Return

| `Vector3` | Returns the direction vector in world space calculated by applying the CFrame's rotation to the input direction vector. |
| --------- | ----------------------------------------------------------------------------------------------------------------------- |

#### Code Samples

```lua
local CF = CFrame.new()
local LocalDir = Vector3.new(1, 0, 0)
local WorldDir = CF:VectorToWorldSpace(LocalDir)
```

## Events

## See also

{% content-ref url="/pages/f7dY0KeRkFsA0mxkM6OB" %}
[Coordinate System](/manual/studio-manual/get-started/coordinate-system.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.overdare.com/development/api-reference/datatype/cframe.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.