CFrame: Difference between revisions

Latest revision as of 21:30, 11 March 2024

CFrame stands for Coordinate Frame. All objects inherited from BasePart have CFrame properties. These define where an object is, and its orientation (how it is rotated). The Position is part of a CFrame, along with a rotation matrix that defines how the object is oriented.

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 be different if you place the brick in a different location:

print(Workspace.Part.CFrame)

0, 3, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1

The first 3 numbers from all that is the 3D position of an object, in this case

0

3

0

. The last 9 numbers make up a Rotation Matrix which describes which way the object is rotated, in this case

1	0	0
0	1	0
0	0	1

.

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. Let's take a look at how to use CFrames to your advantage.

Moving bricks around

Open up a new place with a part.

In the Command Line, type in this bit here and hit enter:

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 absolute beginner's guide to scripting, 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.

Radians

The numbers returned by CFrame.Angles() are radians (one radian is equal to the radius of the circle).

math.pi/2 (A quarter turn, or 90 degrees)
math.pi (A half turn, or 180 degrees)
math.pi*2 (A full turn, or 360 degrees)
math.pi + math.pi/2 (Three-quarters turn, or 270 degrees)

For more information on radians, see Radians.

CFraming more than one object

To CFrame more than one object we use the Get_(Method) to create a table of all selected objects, then we use a foor loop to CFrame all of the selected objects.

Used in the command bar:

for _,v in pairs(game.Selection:Get()) do v.CFrame = v.CFrame * CFrame.new(0, 0, 0) end

Constructors

These Constructors are used for creating CFrame values.

Constructor

Description

CFrame.new()

Creates a blank identity CFrame

CFrame.new(Vector3 position)

Creates CFrame from position.

CFrame.new(Vector3 position, Vector3 point)

Creates CFrame from position, and looking at point.

CFrame.new(number x, number y, number z)

Creates CFrame from position (x, y, z).

CFrame.new(number x, number y, number z, number qx, number qy, number qz, number 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 a CFrame at (x, y, z) with an orientation specified by the rotation matrix

R₀₀	R₀₁	R₀₂
R₁₀	R₁₁	R₁₂
R₂₀	R₂₁	R₂₂

.

CFrame.fromEulerAnglesXYZ(number rx, number ry, number rz)

Creates a rotated CFrame using angles (rx, ry, rz) in radians.

CFrame.Angles(number rx, number ry, number rz)

Same function as fromEulerAnglesXYZ, shorter (preferred) name. Equivalent to:

CFrame.Angles(rx, 0, 0) * CFrame.Angles(0, ry, 0) * CFrame.Angles(0, 0, rz)

This is only available in 2010+ clients. For older clients, use the equivalent fromEulerAnglesXYZ function.

CFrame.fromAxisAngle(v, r)

Creates a rotated CFrame from a Unit Vector3 and a rotation in radians

Properties

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 (unit vector)

Methods

Member Function	Description
CFrame:inverse()	returns the inverse of this CFrame
CFrame:toWorldSpace(CFrame)	returns a CFrame transformed from Object to World coordinates.
CFrame:toObjectSpace(CFrame)	returns a CFrame transformed from World to Object coordinates.
CFrame:pointToWorldSpace(Vector3)	returns a Vector3 transformed from Object to World coordinates.
CFrame:pointToObjectSpace(Vector3)	returns a Vector3 transformed from World to Object coordinates.
CFrame:vectorToWorldSpace(Vector3)	returns a Vector3 rotated from Object to World coordinates.
CFrame:vectorToObjectSpace(Vector3)	returns a Vector3 rotated from World to Object coordinates.
CFrame:components()	returns the CFrame values: x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22
CFrame:toEulerAnglesXYZ()	returns "best guess" angles that could be used to generate CFrame

Operators

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 + Vector3	returns CFrame translated (slid) by Vector3
CFrame - Vector3	returns CFrame translated (slid) by -Vector3

index.php?title=Category:Data types

@@ Line 1: / Line 1: @@
-{{Map|[[Scripting]]|[[Data Types]]}}
+{{Map|Scripting|Data Types}}
 CFrame stands for Coordinate Frame. All objects inherited from [[BasePart]] have [[CFrame (Property)|CFrame properties]]. These define where an object is, and its orientation (how it is rotated). The [[Position (Property)|Position]] is part of a CFrame, along with a rotation matrix that defines how the object is oriented.
 <!--
@@ Line 5: / Line 5: @@
 All that really means is that a CFrame is where an object is, and how it's rotated. It uses a [[Vector3]] to specify the position, and a grid of numbers to specify its orientation.}}-->
-For example, in a place with a few bricks scattered about, put this in the [[command line]]:
+For example, in a place with a few bricks scattered about, put this in the [[Command Bar|command line]]:
 The [[output]] will show something like this, though your numbers will be different if you place the brick in a different location:
@@ Line 14: / Line 14: @@
 }}
-The first 3 numbers from all that is the 3D position of an object, in this case {{Vector3|9|7|5}}. The last 9 numbers make up a Rotation Matrix which describes which way the object is rotated, in this case {{RotationMatrix/small|0|0|1|0|1|0|-1|0|0}}.
+The first 3 numbers from all that is the 3D position of an object, in this case {{Vector3|0|3|0}}. The last 9 numbers make up a Rotation Matrix which describes which way the object is rotated, in this case {{RotationMatrix/small|1|0|0|0|1|0|0|0|1}}.
 ==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.
+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. Let's take a look at how to use CFrames to your advantage.
 ===Moving bricks around===
 Open up a new place with a part. <!--[[Basic Test Map|Click here for a quick guide on how to set up a script testing Place]]-->
@@ Line 24: / Line 24: @@
 In the Command Line, type in this bit here and hit enter:
-<code lua>Workspace.Part.CFrame = CFrame.new(0, 50, 0)</code>
+<syntaxhighlight lang="lua">Workspace.Part.CFrame = CFrame.new(0, 50, 0)</syntaxhighlight>
-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 [[Absolute beginner's guide to scripting]], 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 {{Vector3|0|50|0}}, making the brick move to that position.
+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 [[absolute beginner's guide to scripting]], 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 {{Vector3|0|50|0}}, making the brick move to that position.
 {|style="text-align:center; {{border-radius|4px}}; background-color: #ffdddd; border: 2px solid; border-color: #ff0000 #aa0000 #aa0000 #ff0000; margin: 6px 10px; padding: 2px;"
@@ Line 44: / Line 44: @@
 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 [[Operator]]s instead of a Constructor.
+In the case of rotating bricks the popular option is to actually use one of the [[operator]]s instead of a Constructor.
 {|style="text-align:center; {{border-radius|4px}}; background-color: #ffdddd; border: 2px solid; border-color: #ff0000 #aa0000 #aa0000 #ff0000; margin: 6px 10px; padding: 2px;"
@@ Line 50: / Line 50: @@
 |    CFrame you're changing               ||      Set To    || Position of where you want the brick ||With||      Rotation of Brick
 |-style=" margin:0; background:#EEEEEE; padding:0.2em 0.4em;"
-|game.Workspace.Part.CFrame|| = ||CFrame.new(0, 50, 0)    ||*||CFrame.Angles(0, [[Function_Dump/Mathematical_Functions#math.pi|math.pi]], 0)
+|game.Workspace.Part.CFrame|| = ||CFrame.new(0, 50, 0)    ||*||CFrame.Angles(0, [[Function Dump/Mathematical Functions#math.pi|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 <tt>*</tt> [[Operator]] to compose the rotation CFrame, which you created with <tt>CFrame.Angles</tt>
+What this does is take the object you want to rotate; creates a CFrame from it's current location; and uses the <tt>*</tt> [[operator]] to compose the rotation CFrame, which you created with <tt>CFrame.Angles</tt>
 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.
@@ Line 66: / Line 66: @@
 *math.pi + math.pi/2 (Three-quarters turn, or 270 degrees)
 For more information on radians, see [[Radians]].
+===CFraming more than one object===
+To CFrame more than one object we use the [[Get_(Method)]] to create a table of all selected objects, then we use a foor loop to CFrame all of the selected objects.
+Used in the command bar:
+ for _,v in pairs(game.Selection:Get()) do v.CFrame = v.CFrame * CFrame.new(0, 0, 0) end
 ==[[Constructors]]==
@@ Line 77: / Line 84: @@
 | CFrame.new() || Creates a blank identity CFrame
 |-
-| CFrame.new('''v''') || Creates CFrame from position '''Vector3 v'''
+| CFrame.new({{type|Vector3}} <var>position</var>) || Creates {{type|CFrame}} from <var>position</var>.
 |-
-| CFrame.new('''v, l''') || Creates CFrame from position '''Vector3 v''' looking at point '''Vector3 l'''
+| CFrame.new({{type|Vector3}} <var>position</var>, {{type|Vector3}} <var>point</var>) || Creates {{type|CFrame}} from <var>position</var>, and looking at <var>point</var>.
 |-
-| CFrame.new('''x, y, z''') || Creates CFrame from position '''(x, y, z)'''
+| CFrame.new({{type|number}} <var>x</var>, {{type|number}} <var>y</var>, {{type|number}} <var>z</var>) || Creates {{type|CFrame}} from position (<var>x</var>, <var>y</var>, <var>z</var>).
 |-
-| CFrame.new('''x, y, z, qx, qy, qz, qw''') || Creates CFrame from position '''(x, y, z)''' and quaternion '''(qx, qy, qz, qw)'''
+| CFrame.new({{type|number}} <var>x</var>, {{type|number}} <var>y</var>, {{type|number}} <var>z</var>, {{type|number}} <var>qx</var>, {{type|number}} <var>qy</var>, {{type|number}} <var>qz</var>, {{type|number}} <var>qw</var>) || Creates {{type|CFrame}} from position (<var>x</var>, <var>y</var>, <var>z</var>) and quaternion (<var>qx</var>, <var>qy</var>, <var>qz</var>, <var>qw</var>).
 |-
-| CFrame.new('''x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22''') || Creates a CFrame at '''(x, y, z)''' with an orientation specified by the rotation matrix {{RotationMatrix}}
+| CFrame.new(<var>x</var>, <var>y</var>, <var>z</var>, <var>R00</var>, <var>R01</var>, <var>R02</var>, <var>R10</var>, <var>R11</var>, <var>R12</var>, <var>R20</var>, <var>R21</var>, <var>R22</var>) || Creates a {{type|CFrame}} at (<var>x</var>, <var>y</var>, <var>z</var>) with an orientation specified by the rotation matrix {{RotationMatrix}}.
 |-
-| CFrame.fromEulerAnglesXYZ('''rx, ry, rz''') || Creates a rotated CFrame using angles '''(rx, ry, rz)''' in radians
+| CFrame.fromEulerAnglesXYZ({{type|number}} <var>rx</var>, {{type|number}} <var>ry</var>, {{type|number}} <var>rz</var>) || Creates a rotated {{type|CFrame}} using angles (<var>rx</var>, <var>ry</var>, <var>rz</var>) in radians.
 |-
-| CFrame.Angles('''rx, ry, rz''') || Same function as fromEulerAnglesXYZ, shorter (preferred) name
+| CFrame.Angles({{type|number}} <var>rx</var>, {{type|number}} <var>ry</var>, {{type|number}} <var>rz</var>) || Same function as fromEulerAnglesXYZ, shorter (preferred) name. Equivalent to:
+{{`|CFrame.Angles(rx, 0, 0) * CFrame.Angles(0, ry, 0) * CFrame.Angles(0, 0, rz)}}
+'''This is only available in 2010+ clients. For older clients, use the equivalent fromEulerAnglesXYZ function.'''
 |-
-| CFrame.fromAxisAngle('''v, r''') || Creates a rotated CFrame from a '''Unit Vector3''' and a '''rotation''' in  radians
+| CFrame.fromAxisAngle(<var>v</var>, <var>r</var>) || Creates a rotated {{type|CFrame}} from a '''Unit Vector3''' and a '''rotation''' in  radians
 |}
@@ Line 100: / Line 110: @@
 !Property !! Type !! Description
 |-
-| CFrame.p || [[Vector3]] || The 3D position of the CFrame
+| CFrame.p || {{type|Vector3}} || The 3D position of the CFrame
 |-
-| CFrame.x || [[Number]] || the x-component of the Vector3 position
+| CFrame.x || {{type|number}} || the x-component of the Vector3 position
 |-
-| CFrame.y || [[Number]] || the y-component of the Vector3 position
+| CFrame.y || {{type|number}} || the y-component of the Vector3 position
 |-
-| CFrame.z || [[Number]] || the z-component of the Vector3 position
+| CFrame.z || {{type|number}} || the z-component of the Vector3 position
 |-
-| CFrame.lookVector || [[Vector3]] || returns the facing direction (unit vector)
+| CFrame.lookVector || {{type|Vector3}} || returns the facing direction (unit vector)
 |}
@@ Line 136: / Line 146: @@
 == Operators ==
-These [[Operators]] are used for combining CFrames and Vector3s.
+These [[operators]] are used for combining CFrames and Vector3s.
 {| class="wikitable"
@@ Line 150: / Line 160: @@
 |}
-[[Category:Data Types]]
+[[index.php?title=Category:Data types]]

CFrame: Difference between revisions

Latest revision as of 21:30, 11 March 2024

Contents

Using CFrames

Moving bricks around

Rotating bricks

Radians

CFraming more than one object

Constructors

Properties

Methods

Operators

Navigation menu

Page actions

Page actions

Personal tools

Navigation

Search

Scripting Help

Legacy Client Help

Tools