CFrame

Mostrar obsoleto

*Este conteúdo é traduzido por IA (Beta) e pode conter erros. Para ver a página em inglês, clique aqui.

O tipo de dado CFrame , curto para quadro de coordenadas , descreve uma posição e orientação 3D.É composto por um componente posicional e um componente rotacional e inclui operações aritméticas essenciais para trabalhar com dados 3D no Roblox.


-- Crie um CFrame em uma determinada posição e rotação de Euler
local cf = CFrame.new(0, 5, 0) * CFrame.fromEulerAngles(math.rad(45), 0, 0)

Para uma introdução ao tipo de dados CFrame , veja CFrames.

Componente Posicional

O componente posicional está disponível como um Vector3 .Além disso, os componentes da posição de um objeto CFrame também estão disponíveis nas propriedades X , Y e Z como um Vector3 .

Componente de Rotação

armazena dados de rotação 3D em uma matriz de rotação 3×3 .Esses valores são retornados pela função CFrame:GetComponents() após os valores posicionais x e y e z.Esta matriz é usada internamente ao fazer cálculos envolvendo rotações, usando radianos como sua unidade (para conversão de um para o outro, use math.rad() ou math.deg()).Para mais informações sobre como o Motor do Roblox realiza rotações, veja Enum.RotationOrder .

A tabela abaixo representa a matriz de rotação de um objeto CFrame e sua relação com as propriedades vetoriais disponíveis, como LookVector e RightVector.Embora os componentes individuais da matriz de rotação raramente sejam úteis por conta própria, as propriedades do vetor que se originam nelas são muito mais úteis.


<th>YVector, UpVector</th>
<th>ZVector, -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, DireitoVector
Ao contrário dos outros, LookVector representa os componentes de coluna negados.O LookVector é útil porque muitas Instâncias tais como o Camera e Attachments tratam esse vetor como a direção para a qual a instância está apontando.

Resumo

Construtores

Propriedades

Métodos

Operações matemáticas

Construtores

new

Cria uma identidade em branco CFrame .

new

Retorna um CFrame sem rotação com a posição fornecida de Vector3.

Parâmetros

pos: Vector3

new

Retorna um novo CFrame localizado em pos e voltado para lookAt , assumindo que (0, 1, 0) seja considerado "para cima" no espaço mundial.

Este sobrecarregamento de construtor foi substituído por CFrame.lookAt(), que realiza um objetivo semelhante. Permanece por causa da compatibilidade com versões anteriores.

Em ângulos de inclinação altos (em torno de 82 graus), você pode experimentar instabilidade numérica.Se este for um problema, ou se você precisar de um vetor "para cima" diferente, use CFrame.fromMatrix() para construir com mais precisão o CFrame.Além disso, se lookAt estiver diretamente acima de pos (ângulo de inclinação de 90 graus), o vetor "para cima" muda para o eixo X.

Parâmetros

pos: Vector3
lookAt: Vector3

new

Retorna um CFrame com uma posição composta pelos componentes x, y e z fornecidos.

Parâmetros

new

Retorna um CFrame a partir da posição ( x , y , z ) e quaternário ( qX , qY , qZ , qW ).Espera-se que o quaternion seja de comprimento de unidade para representar uma rotação válida.Se esse não for o caso, o quaternion será normalizado.

Parâmetros

new

Cria um CFrame a partir da posição ( x , y , z ) com uma orientação especificada pela matriz de rotação.

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

Parâmetros

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

lookAt

Retorna um novo CFrame com a posição de at e voltado para lookAt , opcionalmente especificando a direção para cima ( up ) com um padrão de (0, 1, 0) .

Parâmetros

lookAt: Vector3
Valor Padrão: Vector3.yAxis

lookAlong

Retorna um novo CFrame com a posição de at e voltado ao longo de direction , opcionalmente especificando a direção para cima ( up ) com um padrão de (0, 1, 0) .

Este construtor é equivalente a CFrame.lookAt(at, at + direction) .

Parâmetros

direction: Vector3
Valor Padrão: Vector3.yAxis

fromRotationBetweenVectors

Retorna um CFrame representando a orientação necessária para girar do primeiro Vector3 para o segundo, com a posição definida para zero.

Parâmetros

from: Vector3

Vetor que representa a direção "de" .

Vetor que representa a direção "para".

fromEulerAngles

Retorna um girado CFrame de ângulos rx, ry e rz em radianos.As rotações são aplicadas no opcional Enum.RotationOrder com um padrão de XYZ , equivalente a:


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

Parâmetros

rx: number
ry: number
rz: number
Valor Padrão: Enum.RotationOrder.XYZ

fromEulerAnglesXYZ

Retorna um girado CFrame de ângulos rx , ry e rz em radianos usando Enum.RotationOrder.XYZ , equivalente a:


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

Parâmetros

rx: number
ry: number
rz: number

fromEulerAnglesYXZ

Retorna um girado CFrame de ângulos rx , ry e rz em radianos usando Enum.RotationOrder.YXZ , equivalente a:


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

Parâmetros

rx: number
ry: number
rz: number

Angles

Equivalente a fromEulerAnglesXYZ().

Parâmetros

rx: number
ry: number
rz: number

fromOrientation

Equivalente a fromEulerAnglesYXZ().

Parâmetros

rx: number
ry: number
rz: number

fromAxisAngle

Retorna uma rotação CFrame de uma unidade Vector3 e uma rotação em radianos.

Parâmetros

fromMatrix

Retorna um CFrame de uma tradução e as colunas de uma matriz de rotação.Se vZ for excluído, a terceira coluna é calculada como vX:Cross(vY).Unit .

Parâmetros

pos: Vector3

A posição 3D do CFrame .

Equivalente a RightVector.

Equivalente a UpVector.

Equivalente a - LookVector.

Propriedades

identity

Uma identidade CFrame.Essa propriedade é uma constante e deve ser acessada globalmente em oposição a através de um objeto individual CFrame.

Position

A posição 3D do CFrame .

Rotation

Uma cópia do CFrame sem tradução.

A coordenada X da posição.

A coordenada Y da posição.

A coordenada Z da posição.

LookVector

O componente de direção para frente da orientação do objeto CFrame, equivalente à coluna negada ZVector ou à coluna negada da matriz de rotação.


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)

Adicionar um objeto CFrame de um objeto LookVector produz um CFrame movido para a frente em qualquer direção que ele esteja enfrentando por 1 unidade.

RightVector

O componente de direção à direita da orientação do objeto CFrame . Equivalente a XVector ou à primeira coluna da matriz de rotação.


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

O componente de direção para cima da orientação do objeto CFrame . Equivalente a YVector ou à segunda coluna da matriz de rotação.


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

O componente X da orientação do objeto CFrame . Equivalente a RightVector ou à primeira coluna da matriz de rotação.


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

O componente Y da orientação do objeto CFrame . Equivalente a UpVector ou à segunda coluna da matriz de rotação.


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

O componente Z da orientação do objeto CFrame . Equivalente ao negado LookVector ou à terceira coluna da matriz de rotação.


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étodos

Inverse

Retorna o inverso do CFrame.

Devolução

Lerp

Retorna um CFrame interpolado entre si e goal pela fração alpha.

Parâmetros

goal: CFrame
alpha: number

Devolução

Orthonormalize

Retorna uma cópia ortonormalizada do CFrame.A propriedade BasePart.CFrame automáticamente aplica ortonormalização, mas outras APIs que tomam CFrames não o fazem, então este método é ocasionalmente necessário ao atualizar incrementalmente um CFrame e usá-lo com eles.

Devolução

ToWorldSpace

Recebe um ou mais objetos CFrame e os retorna transformados de objeto para o espaço mundial. Equivalente a:

CFrame * cf

Parâmetros

Devolução

ToObjectSpace

Recebe um ou mais objetos CFrame e os retorna transformados do mundo para o espaço de objetos. Equivalente a:

CFrame:Inverse() * cf

Parâmetros

Devolução

PointToWorldSpace

Recebe um ou mais objetos Vector3 e os retorna transformados de objeto para o espaço mundial. Equivalente a:

CFrame * v3

Parâmetros

Devolução

PointToObjectSpace

Recebe um ou mais objetos Vector3 e os retorna transformados do mundo para o espaço de objetos. Equivalente a:

CFrame:Inverse() * v3

Parâmetros

Devolução

VectorToWorldSpace

Recebe um ou mais objetos Vector3 e os retorna girados do objeto para o espaço mundial. Equivalente a:

(CFrame - CFrame.Position) * v3

Parâmetros

Devolução

VectorToObjectSpace

Recebe um ou mais objetos Vector3 e os retorna girados do mundo para o espaço de objeto. Equivalente a:

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

Parâmetros

Devolução

GetComponents

Retorna os valores x , y , z , R00 , R01 , R02 , R10 , R11 , R12 , R20 , R21 , e R22 , onde x``y``zCFrameR00R22 representam a posição da matriz de rotação e ‑ representam sua matriz de rotação 3×3.

Devolução

ToEulerAngles

Retorna ângulos aproximados que podem ser usados para gerar o CFrame usando o opcional Enum.RotationOrder.Se você não fornecer order, o método usa Enum.RotationOrder.XYZ.

Parâmetros

Valor Padrão: Enum.RotationOrder.XYZ

ToEulerAnglesXYZ

Retorna ângulos aproximados que podem ser usados para gerar o CFrame usando Enum.RotationOrder.XYZ.

ToEulerAnglesYXZ

Retorna ângulos aproximados que podem ser usados para gerar o CFrame usando Enum.RotationOrder.YXZ.

ToOrientation

ToAxisAngle

Retorna um tuple de um Vector3 e um número que representa a rotação do CFrame na representação do ângulo do eixo.

Devolução

components

Equivalente a CFrame:GetComponents().

Devolução

FuzzyEq

Retorna true se o outro CFrame estiver suficientemente próximo desse CFrame em ambas as posições e rotações.O valor epsilon é usado para controlar a tolerância para essa semelhança; esse valor é opcional e deve ser um pequeno valor positivo se fornecido.A semelhança para posição é componente a componente enquanto a rotação usa uma aproximação rápida da diferença de ângulo.

Parâmetros

other: CFrame
epsilon: number
Valor Padrão: 0.00001 (1e-5)

Devolução

AngleBetween

Retorna o ângulo, em radianos, entre a orientação de um CFrame e outro.Essa função não leva em consideração a posição de CFrame e só olha para a orientação relativa.

Parâmetros

other: CFrame

Devolução

Operações matemáticas


Produz um novo CFrame representando a composição dos dois CFrames.


Produz um Vector3 transformado de objeto para coordenadas mundiais.


Produz um CFrame traduzido no espaço mundial pelo Vector3.


Produz um CFrame traduzido no espaço mundial pelo negativo Vector3 .