Um CFrame, abreviação de Frame de Coordenadas, é um tipo de dado usado para rotacionar e posicionar objetos 3D. Como uma propriedade de objeto ou uma unidade autônoma, um CFrame contém coordenadas globais X, Y e Z, bem como dados de rotação para cada eixo. Além disso, CFrames contêm funções úteis para trabalhar com objetos no espaço 3D.
Posicionar um CFrame
Você pode criar um CFrame vazio na posição padrão de (0, 0, 0) usando CFrame.new(). Para posicionar um CFrame em um ponto específico, forneça as coordenadas X, Y e Z como argumentos para CFrame.new(). No exemplo a seguir, a propriedade CFrame da parte redBlock muda para newCFrame, reposicionando-a para (-2, 2, 4).
Alternativamente, você pode fornecer uma nova posição Vector3 para CFrame.new() e alcançar o mesmo resultado:
Rotacionar um CFrame
Para criar um CFrame rotacionado, use o construtor CFrame.fromEulerAnglesXYZ(), fornecendo um ângulo de rotação em radianos para os eixos desejados. Os parâmetros para CFrame.fromEulerAnglesXYZ() estão em radianos, não em graus; se você preferir graus, use math.rad() para converter graus em radianos. No exemplo a seguir, a parte redBlock gira 45 graus no sentido anti-horário em seu eixo Y.
Direcionar um CFrame para um ponto
Você pode usar CFrame.lookAt() para apontar a superfície frontal de um CFrame para um ponto específico no mundo. O exemplo a seguir posiciona redBlock em (0, 3, 0) e aponta sua superfície frontal, marcada pelo círculo branco, para a parte blueCube.
Deslocar um CFrame
Para deslocar um objeto por um número específico de studs a partir de sua posição atual, adicione ou subtraia um Vector3 a ou de um novo CFrame na posição do objeto. Para obter uma posição Vector3 devidamente formatada de um objeto para usar com CFrame.new(), conforme visto aqui, sua propriedade Position (redBlock.Position) é um atalho conveniente.
Você pode usar a mesma técnica para deslocar um objeto a partir da posição de outro objeto. No exemplo a seguir, um Vector3 é adicionado a um novo CFrame criado na posição do cubo azul em vez da posição do bloco.
Orientação dinâmica de CFrame
Os construtores CFrame.new() e CFrame.fromEulerAnglesXYZ() reposicionam ou rotacionam um objeto em uma orientação específica dentro do mundo, mas às vezes você não pode contar com uma posição fixa no mundo e um ângulo de rotação. Por exemplo:
- Colocar um tesouro flutuante diretamente na frente de um jogador que pode estar em qualquer lugar do mundo, enfrentando qualquer direção.
- Fazer um gênio mágico aparecer diretamente acima do ombro direito de um jogador.
Nesses casos, use os métodos CFrame em vez de seus construtores.
Posição relativa
A função CFrame:ToWorldSpace() transforma o CFrame de um objeto — respeitando sua própria orientação local — para uma nova orientação global. Isso o torna ideal para deslocar uma parte relativa a si mesma ou a outro objeto, independentemente de como está atualmente posicionado/rotacionado.
No exemplo a seguir, a parte redBlock se desloca 2 studs em relação ao eixo Y do cubo azul (a seta verde apontando através dele) e não em relação ao eixo Y global que aponta diretamente para cima.
Rotação relativa
Você também pode usar CFrame:ToWorldSpace() para rotacionar um objeto em relação a si mesmo. No exemplo a seguir, a parte redBlock gira 70 graus no sentido anti-horário em seu eixo Y e 20 graus no sentido horário em seu eixo Z.
Direcionar uma superfície específica para um ponto
Você pode fazer a frente de um objeto apontar para outro objeto fornecendo um ponto Vector3 como o segundo parâmetro de CFrame.new(). Você também pode usar a rotação relativa para fazer qualquer face do objeto apontar para um ponto Vector3. O exemplo a seguir executa duas operações seguidas de CFrame:
- Apontar a superfície frontal, marcada pelo círculo branco, para o alvo.
- Rotacionar o CFrame para que a superfície superior, marcada pelo círculo preto, aponte para o alvo.
Encontrar um ponto entre pontos
Você pode usar interpolação linear, ou lerp, para posicionar um CFrame entre dois pontos. No exemplo a seguir, a parte redBlock se reposiciona entre as partes greenCube e cyanCube. O valor de 0.7 a coloca a 70% da distância do cubo verde.
