Generasi kode native

*Konten ini diterjemahkan menggunakan AI (Beta) dan mungkin mengandung kesalahan. Untuk melihat halaman ini dalam bahasa Inggris, klik di sini.

Dengan dukungan Luau untuk generasi kode native, skrip¹ dalam permainan Anda dapat dikompilasi langsung menjadi instruksi kode mesin yang dieksekusi oleh CPU, daripada bytecode biasa yang dijalankan oleh VM Luau. Fitur ini dapat meningkatkan kecepatan eksekusi untuk beberapa skrip yang didukung, terutama yang memiliki banyak perhitungan numerik dan sedikit panggilan ke pustaka Luau yang berat atau API Roblox.

1 Generasi kode native hanya didukung untuk skrip sisi server dan skrip sisi klien di perangkat Android. Di masa depan, lebih banyak perangkat mungkin akan didukung.

Aktifkan generasi kode native

Untuk mengaktifkan generasi kode native untuk Script, tambahkan komentar --!native di bagian atas:²

--!native
print("Halo dari kode native!")

Ini mengaktifkan generasi kode native untuk semua fungsi dalam skrip, dan ruang lingkup tingkat atas, jika dianggap menguntungkan. Tidak ada perubahan tambahan yang diperlukan; perilaku skrip yang dieksekusi secara native persis sama seperti sebelumnya dan hanya kinerjanya yang berbeda. Semua fitur bahasa Luau dan semua API Roblox tetap didukung.

Sebagai alternatif, Anda dapat mengaktifkan generasi kode native untuk fungsi individu dengan menambahkan atribut @native:

@native
local function f(x)
return (x + 1)
end
2 Di masa depan, beberapa skrip mungkin secara otomatis mulai berjalan secara native jika dianggap menguntungkan, tetapi komentar --!native yang ditempatkan secara manual saat ini diperlukan.

Praktik terbaik

Tips berikut akan membantu Anda mendapatkan manfaat maksimal dari generasi kode native:

  • Sebaiknya aktifkan fitur ini di dalam skrip yang melakukan banyak perhitungan langsung di dalam Luau. Jika Anda memiliki banyak operasi matematis pada tabel dan terutama tipe buffer, skrip tersebut mungkin merupakan kandidat yang baik.

  • Hanya fungsi skrip yang dikompilasi secara native. Kode di ruang lingkup luar atas sering kali hanya dieksekusi sekali dan tidak mendapatkan manfaat sebanyak fungsi yang dipanggil berkali-kali, terutama yang dipanggil setiap frame.

  • Disarankan agar Anda mengukur waktu yang dibutuhkan skrip atau fungsi dengan dan tanpa kompilasi native untuk menilai kapan sebaiknya menggunakannya. Alat Script Profiler dapat mengukur kinerja fungsi untuk membuat keputusan yang tepat.

  • Mungkin menggoda untuk menempatkan komentar --!native di setiap skrip hanya untuk berjaga-jaga jika beberapa di antaranya akan dieksekusi lebih cepat, tetapi generasi kode native memiliki beberapa kekurangan:

    • Waktu kompilasi kode diperlukan yang dapat meningkatkan waktu startup server.
    • Memori tambahan diperlukan untuk menyimpan kode yang dikompilasi secara native.
    • Ada batasan pada jumlah total kode yang diizinkan untuk dikompilasi secara native dalam sebuah permainan.

Masalah ini dapat diatasi dengan penggunaan yang bijaksana dari atribut @native.

Kode yang harus dihindari

Meskipun semua fitur akan berperilaku sama dengan atau tanpa generasi kode native diaktifkan, beberapa di antaranya tidak akan berjalan secara native dan mungkin menyebabkan de‑optimisasi atau fallback ke eksekusi yang diinterpretasikan. Ini termasuk:

  • Penggunaan panggilan getfenv()/setfenv() yang sudah tidak didukung.
  • Penggunaan berbagai fungsi bawaan Luau seperti math.asin() dengan argumen non-numerik.
  • Mengoper parameter yang tidak bertipe dengan benar ke fungsi bertipe, misalnya memanggil foo(true) ketika foo dideklarasikan sebagai function foo(arg: string). Ingatlah untuk selalu menggunakan anotasi tipe yang benar.

Saat menggunakan Script Profiler, Anda dapat membandingkan waktu yang diambil oleh versi biasa dari fungsi versus yang dikompilasi secara native. Jika sebuah fungsi di dalam skrip --!native atau yang ditandai dengan @native tidak tampak dieksekusi secara native, satu atau lebih faktor dari daftar di atas mungkin memicu de‑optimisasi.

Gunakan anotasi tipe

Generasi kode native berusaha untuk menyimpulkan tipe yang paling mungkin untuk variabel tertentu guna mengoptimalkan jalur kode. Misalnya, diasumsikan bahwa a + b dilakukan pada angka, atau bahwa tabel diakses di t.X. Namun, dengan adanya overloading operator, a dan b mungkin adalah tabel atau tipe Vector3, atau t mungkin adalah tipe data Roblox.

Meskipun generasi kode native akan mendukung tipe apa pun, kesalahan prediksi dapat memicu pemeriksaan yang tidak perlu, yang mengakibatkan eksekusi kode yang lebih lambat.

Untuk menyelesaikan beberapa masalah umum, anotasi tipe Luau pada argumen fungsi diperiksa, tetapi sangat disarankan untuk menganotasi argumen Vector3:

--!native
-- "v" diasumsikan sebagai tabel; fungsi berjalan lebih lambat karena pemeriksaan tabel
local function sumComponentsSlow(v)
return v.X + v.Y + v.Z
end
-- "v" dideklarasikan sebagai Vector3; kode khusus untuk vektor dihasilkan
local function sumComponentsFast(v: Vector3)
return v.X + v.Y + v.Z
end

Alat Studio

Alat Studio berikut didukung untuk skrip --!native dan fungsi @native.

Debugging

Debugging umum dari skrip didukung, tetapi tampilan untuk lokal/upvalues mungkin tidak lengkap dan kehilangan variabel dari bingkai call stack yang dieksekusi secara native.

Perlu dicatat juga bahwa saat melakukan debugging kode yang dipilih untuk kompilasi native, menempatkan breakpoints akan menonaktifkan eksekusi native untuk fungsi-fungsi tersebut.

Script Profiler

Dalam Script Profiler, fungsi yang dieksekusi secara native menampilkan <native> di sampingnya:

Contoh fungsi native yang ditandai di Script Profiler

Jika sebuah fungsi yang ditandai @native atau di dalam skrip --!native tidak menunjukkan anotasi <native>, fungsi tersebut mungkin tidak dieksekusi secara native karena penempatan breakpoint, penggunaan kode yang tidak disarankan, atau anotasi tipe yang tidak cocok.

Luau heap

Dalam profiler Luau heap, memori yang digunakan oleh fungsi native ditampilkan sebagai elemen [native] dalam grafik.

Contoh penggunaan memori native yang ditandai dalam profiler Luau Heap

Analisis ukuran

Setiap skrip yang dikompilasi secara native mengkonsumsi memori. Ketika ukuran kode yang dikompilasi mencapai batas yang telah ditentukan, kompilasi native berhenti dan kode yang tersisa dijalankan secara non‑native. Ini membuat penting untuk memilih skrip dengan hati-hati untuk kompilasi native.

Untuk memantau ukuran kode native dari fungsi dan skrip individu:

  1. Pastikan Anda berada di tampilan Server melalui tombol toggle client/server.
  2. Panggil debug.dumpcodesize() dari Command Bar.

Di jendela Output, Anda akan melihat jumlah total skrip dan fungsi yang telah dikompilasi secara native hingga saat pemanggilan, memori yang dikonsumsi oleh kode native mereka, dan batas ukuran kode native. Setelah ringkasan, Anda akan melihat tabel untuk setiap skrip yang dikompilasi secara native dalam urutan menurun berdasarkan ukuran kode.

Contoh ukuran kode native yang ditampilkan di jendela Output.

Untuk setiap skrip, output menampilkan jumlah fungsi yang dikompilasi dan konsumsi memori kode native. Setiap fungsi kemudian dicantumkan dalam urutan menurun berdasarkan ukuran kode native, dengan fungsi anonim ditampilkan sebagai [anonymous] dan seluruh skrip ditampilkan sebagai [top level]. Di kolom terakhir, persentase dihitung sehubungan dengan batas ukuran kode native. Perlu dicatat bahwa ukuran kode native dari fungsi dilaporkan dengan tepat tetapi konsumsi memori untuk skrip dibulatkan ke ukuran halaman terdekat.

Batasan dan pemecahan masalah

Mengompilasi kode menjadi instruksi untuk CPU tertentu memerlukan memori penyimpanan tambahan. Selain itu, optimasi untuk fungsi kompleks mungkin memerlukan waktu terlalu lama untuk dilakukan. Menyentuh batas internal akan melaporkan kesalahan di jendela Output Studio, termasuk:

Fungsi 'f' di baris 20 melebihi batas instruksi blok kode tunggal

Kesalahan ini berarti bahwa satu blok kode di dalam fungsi menggunakan lebih dari 64K instruksi. Ini dapat dihindari dengan menyederhanakan fungsi atau membaginya menjadi fungsi-fungsi kecil yang terpisah.

Fungsi 'f' di baris 20 melebihi batas blok kode fungsi

Kesalahan ini berarti bahwa satu fungsi mengandung lebih dari 32K blok kode internal. Blok kode internal tidak sepenuhnya mencerminkan blok kontrol aliran dalam skrip Anda, tetapi kesalahan ini dapat dihindari dengan menyederhanakan aliran kontrol dalam fungsi atau membaginya menjadi fungsi-fungsi kecil yang terpisah.

Fungsi 'f' di baris 200 melebihi batas instruksi modul total

Kesalahan ini berarti bahwa, secara total, fungsi telah mencapai batas 1 juta instruksi untuk seluruh skrip. Dalam beberapa kasus, fungsi yang dilaporkan itu sendiri mungkin memiliki banyak instruksi, atau batas tersebut mungkin telah dicapai oleh fungsi-fungsi sebelumnya dalam skrip. Untuk menghindari masalah ini, disarankan untuk memindahkan fungsi yang sangat besar ke dalam skrip non‑native terpisah atau menggunakan @native pada fungsi-fungsi lainnya. Anda juga dapat mencoba menandai skrip terpisah tersebut dengan --!native, tetapi 1 juta instruksi memakan banyak memori dan Anda mungkin melebihi batas memori.

Fungsi 'f' di baris 20 mengalami kegagalan penurunan internal (atau)
Kesalahan internal: Generasi kode native gagal (penurunan assembly)

Terkadang sebuah fungsi mengandung bagian kode yang kompleks yang tidak dapat ditangani oleh kompilator kode native saat ini. Untuk menghindari kesalahan ini, periksa ekspresi kompleks dalam kode dan pisahkan atau sederhanakan, tetapi juga pertimbangkan untuk membuka laporan bug dengan contoh kode yang gagal karena alasan ini.

Batas alokasi memori tercapai untuk generasi kode native

Kesalahan ini berarti bahwa batas memori keseluruhan untuk data kode native telah tercapai. Untuk menghindari ini, coba hapus --!native dari skrip yang lebih banyak memori, sehingga lebih banyak skrip kecil dapat muat di bawah batas. Sebagai alternatif, pindahkan fungsi besar atau yang jarang dipanggil ke modul non‑native terpisah.

©2026 Roblox Corporation. Roblox, logo Roblox, dan Powering Imagination termasuk dalam merek dagang kami yang terdaftar dan tidak terdaftar di AS dan negara lainnya.