Un CFrame, abréviation de Cadre de Coordonnées, est un type de donnée utilisé pour faire tourner et positionner des objets 3D. En tant que propriété d'objet ou unité autonome, un CFrame contient des coordonnées X, Y et Z globales ainsi que des données de rotation pour chaque axe. De plus, CFrames contient des fonctions utiles pour travailler avec des objets dans l'espace 3D.
Positionner un CFrame
Vous pouvez créer un CFrame vide à la position par défaut de (0, 0, 0) en utilisant CFrame.new(). Pour positionner un CFrame à un point spécifique, fournissez les coordonnées X, Y et Z en tant qu'arguments à CFrame.new(). Dans l'exemple suivant, la propriété CFrame de la pièce redBlock change pour newCFrame, la repositionnant à (-2, 2, 4).
Alternativement, vous pouvez fournir une nouvelle position Vector3 à CFrame.new() et obtenir le même résultat :
Faire tourner un CFrame
Pour créer un CFrame tourné, utilisez le constructeur CFrame.fromEulerAnglesXYZ(), en fournissant un angle de rotation en radians pour les axes souhaités. Les paramètres de CFrame.fromEulerAnglesXYZ() sont en radians, pas en degrés ; si vous préférez les degrés, utilisez math.rad() pour convertir les degrés en radians. Dans l'exemple suivant, la pièce redBlock tourne de 45 degrés dans le sens antihoraire sur son axe Y.
Orienter un CFrame vers un point
Vous pouvez utiliser CFrame.lookAt() pour pointer la surface avant d'un CFrame vers un point spécifique dans le monde. L'exemple suivant positionne redBlock à (0, 3, 0) et pointe sa surface avant, marquée par le cercle blanc, vers la pièce blueCube.
Décaler un CFrame
Pour décaler un objet d'un nombre spécifique de studs par rapport à sa position actuelle, ajoutez ou soustrayez un Vector3 à partir d'un nouveau CFrame à la position de l'objet. Pour obtenir une position Vector3 correctement formatée d'un objet à utiliser avec CFrame.new(), comme vu ici, sa propriété Position (redBlock.Position) est un raccourci pratique.
Vous pouvez utiliser la même technique pour décaler un objet par rapport à la position d'un autre objet. Dans l'exemple suivant, un Vector3 s'ajoute à un nouveau CFrame créé à la position du cube bleu au lieu de la position du bloc.
Orientation dynamique du CFrame
Les constructeurs CFrame.new() et CFrame.fromEulerAnglesXYZ() repositionnent ou font tourner un objet à une orientation spécifique dans le monde, mais vous ne pouvez parfois pas compter sur une position mondiale fixe et un angle de rotation. Par exemple :
- Placer un trésor flottant directement devant un joueur qui peut se tenir n'importe où dans le monde, faisant face à n'importe quelle direction.
- Faire apparaître un génie magique directement au-dessus de l'épaule droite d'un joueur.
Dans ces cas, utilisez les méthodes CFrame au lieu de leurs constructeurs.
Position relative
La fonction CFrame:ToWorldSpace() transforme le CFrame d'un objet — respectant sa propre orientation locale — à une nouvelle orientation mondiale. Cela le rend idéal pour décaler une pièce par rapport à elle-même ou à un autre objet, quelle que soit sa position/rotation actuelle.
Dans l'exemple suivant, la pièce redBlock se décale de 2 studs par rapport à l'axe Y du cube bleu (la flèche verte qui le traverse) et non par rapport à l'axe Y mondial pointant directement vers le haut.
Rotation relative
Vous pouvez également utiliser CFrame:ToWorldSpace() pour faire tourner un objet par rapport à lui-même. Dans l'exemple suivant, la pièce redBlock tourne de 70 degrés dans le sens antihoraire sur son axe Y et de 20 degrés dans le sens horaire sur son axe Z.
Faire face à une surface spécifique vers un point
Vous pouvez faire en sorte que l'avant d'un objet fasse face à un autre objet en fournissant un point Vector3 comme deuxième paramètre de CFrame.new(). Vous pouvez également utiliser la rotation relative pour faire en sorte que n'importe quelle face de l'objet pointe vers un point Vector3. L'exemple suivant effectue deux opérations CFrame consécutives :
- Pointer la surface avant, marquée par le cercle blanc, vers la cible.
- Faire tourner le CFrame pour que la surface supérieure, marquée par le cercle noir, pointe vers la cible.
Trouver un point entre des points
Vous pouvez utiliser l'interpolation linéaire, ou lerp, pour positionner un CFrame entre deux points. Dans l'exemple suivant, la pièce redBlock se repositionne entre les pièces greenCube et cyanCube. La valeur de 0.7 la place à 70% de la distance du cube vert.
