CFrames | Dokumentasi - Pusat Kreator Roblox

A CFrame, singkatan dari Kerangka Koordinat, adalah tipe data yang digunakan untuk memutar dan memposisikan objek 3D. Sebagai properti objek atau unit mandiri, CFrame berisi koordinat X, Y, dan Z global serta data rotasi untuk setiap sumbu. Selain itu, CFrames berisi fungsi-fungsi berguna untuk bekerja dengan objek di ruang 3D.

Memposisikan CFrame

Anda dapat membuat CFrame kosong di posisi default (0, 0, 0) dengan menggunakan CFrame.new(). Untuk memposisikan CFrame di titik tertentu, berikan koordinat X, Y, dan Z sebagai argumen ke CFrame.new(). Dalam contoh berikut, properti CFrame bagian redBlock berubah menjadi newCFrame, memindahkannya ke (-2, 2, 4).


local Workspace = game:GetService("Workspace")

local redBlock = Workspace.RedBlock

-- Membuat CFrame baru
local newCFrame = CFrame.new(-2, 2, 4)

-- Menimpa CFrame red block yang saat ini dengan CFrame baru
redBlock.CFrame = newCFrame

Sebagai alternatif, Anda dapat memberikan posisi Vector3 baru ke CFrame.new() dan mencapai hasil yang sama:


local Workspace = game:GetService("Workspace")

local redBlock = Workspace.RedBlock

-- Membuat CFrame baru
local newVector3 = Vector3.new(-2, 2, 4)
local newCFrame = CFrame.new(newVector3)

-- Menimpa CFrame red block yang saat ini dengan CFrame baru
redBlock.CFrame = newCFrame

Memutar CFrame

Untuk membuat CFrame yang diputar, gunakan konstruktor CFrame.fromEulerAnglesXYZ(), dengan memberikan sudut rotasi dalam radian untuk sumbu yang diinginkan. Parameter untuk CFrame.fromEulerAnglesXYZ() adalah dalam radian, bukan derajat; jika Anda lebih suka derajat, gunakan math.rad() untuk mengonversi derajat ke radian. Dalam contoh berikut, bagian redBlock berputar 45 derajat berlawanan arah jarum jam pada sumbu Y-nya.


local Workspace = game:GetService("Workspace")

local redBlock = Workspace.RedBlock

-- Membuat CFrame baru yang diputar
local newCFrame = CFrame.fromEulerAnglesXYZ(0, math.rad(45), 0)

-- Menimpa CFrame red block yang saat ini dengan CFrame baru
redBlock.CFrame = newCFrame

Menghadapkan CFrame ke arah sebuah titik

Anda dapat menggunakan CFrame.lookAt() untuk mengarahkan permukaan depan dari CFrame ke titik tertentu di dunia. Contoh berikut memposisikan redBlock pada (0, 3, 0) dan mengarahkan permukaan depannya, ditandai dengan lingkaran putih, ke bagian blueCube.


local Workspace = game:GetService("Workspace")

local redBlock = Workspace.RedBlock
local blueCube = Workspace.BlueCube

redBlock.Position = Vector3.new(0, 3, 0)

-- Mengarahkan permukaan depan red block ke blue cube
redBlock.CFrame = CFrame.lookAt(redBlock.Position, blueCube.Position)

Menggeser CFrame

Untuk menggeser objek dengan jumlah tertentu dari posisinya saat ini, tambahkan atau kurangi Vector3 ke atau dari CFrame baru di posisi objek tersebut. Untuk mendapatkan posisi Vector3 objek yang diformat dengan benar untuk digunakan dengan CFrame.new(), seperti yang terlihat di sini, properti Position (redBlock.Position) adalah jalan pintas yang nyaman.


local Workspace = game:GetService("Workspace")

local redBlock = Workspace.RedBlock

redBlock.CFrame = CFrame.new(redBlock.Position) + Vector3.new(0, 1.25, 0)

Anda dapat menggunakan teknik yang sama untuk menggeser objek dari posisi objek lainnya. Dalam contoh berikut, Vector3 ditambahkan ke CFrame baru yang dibuat di posisi kubus biru, bukan posisi blok.


local Workspace = game:GetService("Workspace")

local redBlock = Workspace.RedBlock
local blueCube = Workspace.BlueCube

redBlock.CFrame = CFrame.new(blueCube.Position) + Vector3.new(0, 2, 0)

Orientasi CFrame dinamis

Konstruktor CFrame.new() dan CFrame.fromEulerAnglesXYZ() memposisikan atau memutar objek pada orientasi tertentu di dalam dunia, tetapi terkadang Anda tidak dapat mengandalkan posisi dan sudut rotasi dunia yang tetap. Misalnya:

Menempatkan harta karun yang mengapung tepat di depan pemain yang mungkin berdiri di mana saja di dunia, menghadap ke arah mana saja.
Membuat jin ajaib muncul tepat di atas bahu kanan pemain.

Dalam kasus ini, gunakan metode CFrame daripada konstruktornya.

Posisi relatif

Fungsi CFrame:ToWorldSpace() mengubah CFrame objek — menghormati orientasi lokalnya sendiri — ke orientasi dunia yang baru. Ini menjadikannya ideal untuk menggeser sebuah bagian relatif terhadap dirinya sendiri atau objek lain, terlepas dari bagaimana posisinya/rotasinya saat ini.

Dalam contoh berikut, bagian redBlock menggeser 2 stud relatif terhadap sumbu Y dari kubus biru (anak panah hijau yang menunjuk melaluinya) dan tidak relatif terhadap sumbu Y global yang menunjuk langsung ke atas.


local Workspace = game:GetService("Workspace")

local redBlock = Workspace.RedBlock
local blueCube = Workspace.BlueCube

local offsetCFrame = CFrame.new(0, 2, 0)
redBlock.CFrame = blueCube.CFrame:ToWorldSpace(offsetCFrame)

Rotasi relatif

Anda juga dapat menggunakan CFrame:ToWorldSpace() untuk memutar objek relatif terhadap dirinya sendiri. Dalam contoh berikut, bagian redBlock berputar 70 derajat berlawanan arah jarum jam pada sumbu Y-nya dan 20 derajat searah jarum jam pada sumbu Z-nya.


local Workspace = game:GetService("Workspace")

local redBlock = Workspace.RedBlock

local rotatedCFrame = CFrame.fromEulerAnglesXYZ(0, math.rad(70), math.rad(20))
redBlock.CFrame = redBlock.CFrame:ToWorldSpace(rotatedCFrame)

Menghadapkan permukaan tertentu ke arah sebuah titik

Anda dapat membuat bagian depan objek menghadap objek lain dengan memberikan titik Vector3 sebagai parameter kedua dari CFrame.new(). Anda juga dapat menggunakan rotasi relatif untuk membuat permukaan mana pun dari objek menghadap titik Vector3. Contoh berikut melakukan dua operasi CFrame berturut-turut:

Mengarahkan permukaan depan, yang ditandai dengan lingkaran putih, ke target.
Memutar CFrame untuk membuat permukaan atas, yang ditandai dengan lingkaran hitam, menghadap ke target.


local Workspace = game:GetService("Workspace")

local redBlock = Workspace.RedBlock
local blueCube = Workspace.BlueCube

-- Mengarahkan permukaan depan red block ke blue cube
redBlock.CFrame = CFrame.lookAt(redBlock.Position, blueCube.Position)

-- Memutar CFrame relatif terhadap dirinya sendiri sehingga permukaan atas (bukan depan) menghadap blue cube
local rotatedCFrame = CFrame.fromEulerAnglesXYZ(math.rad(-90), 0, 0)
redBlock.CFrame = redBlock.CFrame:ToWorldSpace(rotatedCFrame)

Menemukan titik di antara dua titik

Anda dapat menggunakan interpolasi linier, atau lerp, untuk memposisikan CFrame di antara dua titik. Dalam contoh berikut, bagian redBlock dipindahkan antara bagian greenCube dan cyanCube. Nilai 0.7 menempatkannya 70% dari jarak dari kubus hijau.


local Workspace = game:GetService("Workspace")

local redBlock = Workspace.RedBlock
local greenCube = Workspace.GreenCube
local cyanCube = Workspace.CyanCube

redBlock.CFrame = greenCube.CFrame:Lerp(cyanCube.CFrame, 0.7)