CFrame
From Roblox Wiki
|
| Up one category: Scripting |
|
| Up one category: Data Types |
Contents |
CFrame
CFrame stands for Coordinate Frame. All Parts and many other 3D items have CFrames. These define where an object is, and how it is rotated. The Position (Property) is part of a CFrame, along with a rotation matrix that defines how the object is rotated.
|
All that really means is that a CFrame is where an object is, and how it's rotated. It uses two Vector3s to not just tell where a part is, but which way it is facing as well. For example, in a Place with a few bricks scattered about, put this in the Command Line:
The Output will show something like this, though your numbers will probably be different:
|
>>>>TODO: Image breaking down the CFrame values
Using CFrames
CFrames are, since they tell you exactly where an object is and how it's rotated, very useful for making things move exactly where you want them. Lets take a look at how to use CFrames to your advantage.
Moving bricks around
Open up a new place with a part. Click here for a quick guide on how to set up a script testing Place
In the Command Line, type in this bit here and hit enter:
| game.Workspace.Part.CFrame = CFrame.new(0, 50, 0) |
You should see that the brick moved up a good distance, you may need to move the camera to see it. What you just did is change where the brick is, by changing it's CFrame. As you should know from the basic scripting guide, you changed the Part's CFrame property, or value by using the equal sign. You set Part.CFrame to a new CFrame, by using the CFrame.new constructor. You constructed a new CFrame using 3 different values. This told the Lua engine to set the brick's CFrame to 0, 50, 0, which set it's position to 0, 50, 0, making the brick move to that position.
| CFrame you're changing | Set To | Position of where you want the brick |
| game.Workspace.Part.CFrame | = | CFrame.new(0, 50, 0) |
| The object named "Part" in Workspace | Move to here |
|
But wait! CFrames are not just useful for moving bricks around. When you change the CFrame property directly with a command, you can place bricks inside of other bricks. This is something that the Position property cannot do. You can also rotate bricks, but this is a little more complex. |
Rotating bricks
At the bottom of this page you'll see a few tables that give you the different constructors for CFrame. You can see a bunch of new() commands, which all have different Arguments inside of the Function. This is because there are several different ways to create a CFrame. You can use just a position, like in the above example, or you can use the more complex ones.
In the case of rotating bricks the popular option is to actually use one of the Operators instead of a Constructor.
| CFrame you're changing | Set To | Position of where you want the brick | With | Rotation of Brick |
| game.Workspace.Part.CFrame | = | CFrame.new(0, 50, 0) | * | CFrame.Angles(0, math.pi, 0) |
| The object named "Part" in Workspace | The same spot we just put the brick | Rotate this much |
What this does is take the object you want to rotate; creates a CFrame from it's current location; and uses the * Operator to compose the rotation CFrame, which you created with CFrame.Angles
The CFrame.Angles constructor creates a CFrame that is just rotations. In the Moving Bricks part we created one that was just a position. Bricks use the CFrame for both rotation and position, which is what you create when you use the * operator. It takes the position CFrame and the Rotation CFrame, and combines them.
RadiansThe numbers used in CFrame.Angles() are called Radians. These are not your normal Degrees, and in fact are fractions of Pi. Most of the time you will use
You can also use parts of these, such as
For more information on Radians, Check out this page |
Constructors
These Constructors are used for creating CFrame values.
| Constructor | Description |
|---|---|
| CFrame.new() | Creates a blank identity CFrame |
| CFrame.new(v) | Creates CFrame from position Vector3 v |
| CFrame.new(v, l) | Creates CFrame from position Vector3 v looking at point l |
| CFrame.new(x, y, z) | Creates CFrame from position (x, y, z) |
| CFrame.new(x, y, z, qx, qy, qz, qw) | Creates CFrame from position (x, y, z) and quaternion (qx, qy, qz, qw) |
| CFrame.new(x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22) | Creates CFrame from position (x, y, z) and rotation matrix (R00, R01, R02, R10, R11, R12, R20, R21, R22) |
| CFrame.fromEulerAnglesXYZ(x, y, z) | Creates a rotated CFrame (x, y, z) in radians |
| CFrame.Angles(x, y, z) | Same function as fromEulerAnglexXYZ, shorter (preferred) name |
| CFrame.fromAxisAngle(v, r) | Creates a rotated CFrame from a Unit Vector3 and a Vector3 rotation in radians |
When you want to use just the position data from a CFrame you can use these properties of CFrames. Note that they are read only, meaning that you can use them, but you cannot change them. (ie: CFrame.x = 5 will not work, but a = CFrame.x will work)
| Property | Type | Description |
|---|---|---|
| CFrame.p | Vector3 | The 3D position of the CFrame |
| CFrame.x | number | the x-component of the Vector3 position |
| CFrame.y | number | the y-component of the Vector3 position |
| CFrame.z | number | the z-component of the Vector3 position |
| CFrame.lookVector | Vector3 | returns the facing direction along each axis |
These functions are used for changing Vector3s and CFrames.
| Member Function | Description |
|---|---|
| CFrame:inverse() | returns the inverse of this CFrame |
| CFrame:toWorldSpace(CFrame) | returns a CFrame transformed from Object to World coordinates. Also works with tuples |
| CFrame:toObjectSpace(CFrame) | returns a CFrame transformed from World to Object coordinates. Also works with tuples |
| Vector3:pointToWorldSpace(Vector3) | returns a Vector3 transformed from Object to World coordinates. Also works with tuples |
| Vector3:pointToObjectSpace(Vector3) | returns a Vector3 transformed from World to Object coordinates. Also works with tuples |
| Vector3:vectorToWorldSpace(Vector3) | returns a Vector3 rotated from Object to World coordinates. Also works with tuples |
| Vector3:vectorToObjectSpace(Vector3) | returns a Vector3 rotated from World to Object coordinates. Also works with tuples |
These Operators are used for combining CFrames and Vector3s.
| Operator | Description |
|---|---|
| CFrame * CFrame | returns composition of two CFrames |
| CFrame * Vector3 | returns Vector3 transformed from Object to World coordinates |
| CFrame + CFrame | returns sum of both CFrames |
| CFrame + Vector3 | returns CFrame translated (slid) by Vector3 |
| CFrame - Vector3 | returns CFrame translated (slid) by -Vector3 |
