CFrame

Afficher les obsolètes

*Ce contenu est traduit en utilisant l'IA (Beta) et peut contenir des erreurs. Pour consulter cette page en anglais, clique ici.

Le type de données CFrame , abrégé pour cadre de coordonnées 3D , décrit une position et une orientation 3D.Il se compose d'une composante positionnelle et d'une composante rotative et inclut des opérations arithmétiques essentielles pour travailler avec des données 3D sur Roblox.


-- Créer un cadre C à une certaine position et rotation d'Euler
local cf = CFrame.new(0, 5, 0) * CFrame.fromEulerAngles(math.rad(45), 0, 0)

Pour une introduction au type de données CFrame , voir CFrames .

Composant positionnel

La composante positionnelle est disponible en tant que Vector3.En outre, les composants de la position d'un objet CFrame sont également disponibles dans les propriétés X , Y et Z comme un Vector3 .

Composant rotatif

stocke les données de rotation 3D dans une matrice de rotation 3×3 .Ces valeurs sont retournées par la fonction CFrame:GetComponents() après les valeurs positionnelles x et y et z.Cette matrice est utilisée internement lorsque des calculs impliquant des rotations sont effectués, en utilisant radians comme unité (pour la conversion d'une à l'autre, utilisez math.rad() ou math.deg()).Pour plus d'informations sur la façon dont le moteur Roblox effectue des rotations, voir Enum.RotationOrder .

La table ci-dessous représente la matrice de rotation d'un objet CFrame et sa relation avec les propriétés vectorielles disponibles telles que LookVector et RightVector .Bien que les composants individuels de la matrice de rotation soient rarement utiles par eux-mêmes, les propriétés vectorielles qui en découlent sont beaucoup plus utiles.


<th>Vecteur Y, Vecteur supérieur</th>
<th>Vecteur Z, -LookVector <sup>†</sup></th>
</tr>
</thead>
<tbody>
<tr>
<td>R00</td>
<td>R01</td>
<td>R02</td>
</tr>
<tr>
<td>R10</td>
<td>R11</td>
<td>R12</td>
</tr>
<tr>
<td>R20</td>
<td>R21</td>
<td>R22</td>
</tr>
</tbody>
XVector, RightVector
À l'inverse des autres, LookVector représente les composants de colonne négés.Le LookVector est utile car beaucoup de Instances comme le Camera et Attachments traitent ce vecteur comme la direction vers laquelle l'instance pointe.

Résumé

Constructeurs

Propriétés

Méthodes

Opérations Maths

Constructeurs

new

Crée une identité vide CFrame.

new

Retourne un CFrame sans rotation avec la position du Vector3 fourni.

Paramètres

pos: Vector3

new

Retourne un nouveau CFrame situé à pos et tourné vers lookAt , en supposant que (0, 1, 0) est considéré comme "en haut" dans l'espace mondial.

Cet excès de constructeur a été remplacé par CFrame.lookAt(), qui atteint un objectif similaire. Il reste pour le souci de la compatibilité avec les versions précédentes.

À des angles de pente élevés (environ 82 degrés), vous pouvez expérimenter une instabilité numérique.Si c'est un problème, ou si vous avez besoin d'un vecteur "en haut" différent, utilisez CFrame.fromMatrix() pour construire plus précisément le CFrame.De plus, si lookAt est directement au-dessus de pos (angle de pente de 90 degrés), le vecteur «en haut» passe à l'axe X.

Paramètres

pos: Vector3
lookAt: Vector3

new

Retourne un CFrame avec une position composée des composants x, y et z fournis.

Paramètres

new

Retourne un CFrame à partir de la position ( x , y , z ) et un quaternion ( qX, qY, qZ, qW ).On s'attend à ce que le quaternion ait une longueur d'unité pour représenter une rotation valide.Si ce n'est pas le cas, le quaternion sera normalisé.

Paramètres

new

Crée un CFrame à partir de la position ( x , y , z ) avec une orientation spécifiée par la matrice de rotation.

[[R00 R01 R02] [R10 R11 R12] [R20 R21 R22]]

Paramètres

R00: number
R01: number
R02: number
R10: number
R11: number
R12: number
R20: number
R21: number
R22: number

lookAt

Retourne un nouveau CFrame avec la position de at et face à lookAt , optionnellement en spécifiant la direction vers le haut ( up ) avec une valeur par défaut de (0, 1, 0) .

Paramètres

lookAt: Vector3
Valeur par défaut : Vector3.yAxis

lookAlong

Retourne un nouveau CFrame avec la position de at et face le long de direction , optionnellement en spécifiant la direction vers le haut ( up ) avec une valeur par défaut de (0, 1, 0) .

Ce constructeur est équivalent à CFrame.lookAt(at, at + direction).

Paramètres

direction: Vector3
Valeur par défaut : Vector3.yAxis

fromRotationBetweenVectors

Retourne un CFrame représentant l'orientation nécessaire pour tourner du premier Vector3 au deuxième, avec la position réglée à zéro.

Paramètres

from: Vector3

Vecteur représentant la direction "de" .

Vecteur représentant la direction "vers".

fromEulerAngles

Retourne un rotatif CFrame à partir des angles rx , ry et rz en radians.Les rotations sont appliquées dans le facultatif Enum.RotationOrder avec un défaut de XYZ , équivalent à :


CFrame.fromEulerAngles(rx, 0, 0) * -- X
CFrame.fromEulerAngles(0, ry, 0) * -- Y
CFrame.fromEulerAngles(0, 0, rz) -- Z

Paramètres

rx: number
ry: number
rz: number
Valeur par défaut : Enum.RotationOrder.XYZ

fromEulerAnglesXYZ

Retourne un rotatif CFrame à partir des angles rx , ry et rz en radians en utilisant Enum.RotationOrder.XYZ , équivalent à :


CFrame.fromEulerAngles(rx, 0, 0) * -- X
CFrame.fromEulerAngles(0, ry, 0) * -- Y
CFrame.fromEulerAngles(0, 0, rz) -- Z

Paramètres

rx: number
ry: number
rz: number

fromEulerAnglesYXZ

Retourne un rotatif CFrame à partir des angles rx , ry et rz en radians en utilisant Enum.RotationOrder.YXZ , équivalent à :


CFrame.fromEulerAngles(0, ry, 0) * -- Y
CFrame.fromEulerAngles(rx, 0, 0) * -- X
CFrame.fromEulerAngles(0, 0, rz) -- Z

Paramètres

rx: number
ry: number
rz: number

Angles

Équivalent à fromEulerAnglesXYZ().

Paramètres

rx: number
ry: number
rz: number

fromOrientation

Équivalent à fromEulerAnglesYXZ().

Paramètres

rx: number
ry: number
rz: number

fromAxisAngle

Retourne une rotation CFrame de l'unité Vector3 et une rotation en radians.

Paramètres

fromMatrix

Renvoie un CFrame de traduction et les colonnes d'une matrice de rotation.Si vZ est exclu, la troisième colonne est calculée comme vX:Cross(vY).Unit .

Paramètres

pos: Vector3

La position 3D du CFrame .

Équivalent à RightVector.

Équivalent à UpVector.

Équivalent à - LookVector.

Propriétés

identity

Une identité CFrame sans traduction ou rotation.Cette propriété est une constante et doit être accessible globalement plutôt que par le biais d'un objet individuel CFrame.

Position

La position 3D du CFrame .

Rotation

Une copie de la CFrame sans traduction.

La coordonnée X de la position.

La coordonnée Y de la position.

La coordonnée Z de la position.

LookVector

La composante de direction vers l'avant de l'orientation de l'objet CFrame, équivalente à la colonne négative ZVector ou à la colonne négative de la matrice de rotation.


local cf = CFrame.new(0, 0, 0)
local x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22 = cf:GetComponents()
print(cf.LookVector) --> (-0, -0, -1)
print(-cf.ZVector) --> (-0, -0, -1)
print(-R02, -R12, -R22) --> (-0 -0 -1)

Ajouter un objet CFrame à soi-même LookVector produit un objet CFrame déplacé vers l'avant dans n'importe quelle direction vers laquelle il est tourné de 1 unité.

RightVector

La composante de direction à droite de l'orientation de l'objet CFrame. Équivalent à XVector ou à la première colonne de la matrice de rotation.


local cf = CFrame.new(0, 0, 0)
local x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22 = cf:GetComponents()
print(cf.RightVector) --> (1, 0, 0)
print(cf.XVector) --> (1, 0, 0)
print(R00, R10, R20) --> (1 0 0)

UpVector

La composante de direction vers le haut de l'orientation de l'objet CFrame. Équivalent à YVector ou à la deuxième colonne de la matrice de rotation.


local cf = CFrame.new(0, 0, 0)
local x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22 = cf:GetComponents()
print(cf.UpVector) --> (0, 1, 0)
print(cf.YVector) --> (0, 1, 0)
print(R01, R11, R21) --> (0 1 0)

XVector

La composante X de l'orientation de l'objet CFrame de la rotation. Équivalent à RightVector ou à la première colonne de la matrice de rotation.


local cf = CFrame.new(0, 0, 0)
local x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22 = cf:GetComponents()
print(cf.XVector) --> (1, 0, 0)
print(cf.RightVector) --> (1, 0, 0)
print(R00, R10, R20) --> (1 0 0)

YVector

La composante Y de l'orientation de l'objet CFrame de la rotation. Équivalent à UpVector ou à la deuxième colonne de la matrice de rotation.


local cf = CFrame.new(0, 0, 0)
local x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22 = cf:GetComponents()
print(cf.YVector) --> (0, 1, 0)
print(cf.UpVector) --> (0, 1, 0)
print(R01, R11, R21) --> (0 1 0)

ZVector

La composante Z de l'orientation de l'objet CFrame de la rotation de la matrice. Équivalent à la colonne négative LookVector ou à la troisième colonne de la matrice de rotation.


local cf = CFrame.new(0, 0, 0)
local x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22 = cf:GetComponents()
print(cf.ZVector) --> (0, 0, 1)
print(-cf.LookVector) --> (0, 0, 1)
print(R02, R12, R22) --> (0 0 1)

Méthodes

Inverse

Retourne l'inverse du CFrame .

Retours

Lerp

Retourne un CFrame interpolé entre lui-même et goal par la fraction alpha .

Paramètres

goal: CFrame
alpha: number

Retours

Orthonormalize

Retourne une copie orthonormale du CFrame .La propriété BasePart.CFrame applique automatiquement l'orthonormalisation, mais d'autres API qui prennent CFrames ne le font pas, donc cette méthode est parfois nécessaire lors de la mise à jour incrémentielle d'un CFrame et de son utilisation avec elles.

Retours

ToWorldSpace

Reçoit un ou plusieurs objets CFrame et les retourne transformés de l'objet au monde spatial. Équivalent à :

CFrame * cf

Paramètres

Retours

ToObjectSpace

Reçoit un ou plusieurs objets CFrame et les retourne transformés du monde vers l'espace d'objets. Équivalent à :

CFrame:Inverse() * cf

Paramètres

Retours

PointToWorldSpace

Reçoit un ou plusieurs objets Vector3 et les retourne transformés de l'objet au monde spatial. Équivalent à :

CFrame * v3

Paramètres

Retours

PointToObjectSpace

Reçoit un ou plusieurs objets Vector3 et les retourne transformés du monde vers l'espace d'objets. Équivalent à :

CFrame:Inverse() * v3

Paramètres

Retours

VectorToWorldSpace

Reçoit un ou plusieurs objets Vector3 et les retourne rotés de l'objet vers l'espace du monde. Équivalent à :

(CFrame - CFrame.Position) * v3

Paramètres

Retours

VectorToObjectSpace

Reçoit un ou plusieurs objets Vector3 et les retourne rotés du monde vers l'espace d'objets. Équivalent à :

(CFrame:Inverse() - CFrame:Inverse().Position) * v3

Paramètres

Retours

GetComponents

Retourne les valeurs x , y , z , R00 , R01 , R02 , R10 , R11 , R12 , R20 , R21 , et R22 , où x``yzCFrameR00 ‑ représentent la position de la matrice de rotation et R22 ‑ représentent sa matrice de rotation 3×3.

Retours

ToEulerAngles

Retourne des angles approximatifs qui pourraient être utilisés pour générer le CFrame en utilisant l'optionnel Enum.RotationOrder.Si vous ne fournissez pas order, la méthode utilise Enum.RotationOrder.XYZ.

Paramètres

Valeur par défaut : Enum.RotationOrder.XYZ

ToEulerAnglesXYZ

Retourne des angles approximatifs qui pourraient être utilisés pour générer le CFrame en utilisant Enum.RotationOrder.XYZ.

ToEulerAnglesYXZ

Retourne des angles approximatifs qui pourraient être utilisés pour générer le CFrame en utilisant Enum.RotationOrder.YXZ.

ToOrientation

ToAxisAngle

Retourne une tuple d'un Vector3 et un nombre qui représente la rotation du CFrame dans la représentation de l'angle de l'axe.

components

Équivalent à CFrame:GetComponents().

Retours

FuzzyEq

Retourne true si l'autre CFrame est suffisamment proche de celui-ci CFrame à la fois en position et en rotation.La valeur epsilon est utilisée pour contrôler la tolérance pour cette ressemblance ; cette valeur est facultative et devrait être une petite valeur positive si elle est fournie.La ressemblance pour la position est composante par composante alors que la rotation utilise une approximation rapide de la différence d'angle.

Paramètres

other: CFrame
epsilon: number
Valeur par défaut : 0.00001 (1e-5)

Retours

AngleBetween

Renvoie l'angle, en radians, entre l'orientation d'un CFrame et d'un autre.Cette fonction ne tient pas compte de la position de CFrame et ne regarde que l'orientation relative.

Paramètres

other: CFrame

Retours

Opérations Maths


Produit une nouvelle CFrame représentant la composition des deux CFrames.


Produit une Vector3 transformée de l'objet en coordonnées du monde.


Produit un CFrame traduit dans l'espace du monde par le Vector3.


Produit un CFrame traduit dans l'espace du monde par le négatif Vector3 .