Model Prosedural

ProceduralModels adalah sejenis Model berbasis parameter yang memungkinkan Anda membangun dan menghasilkan objek 3D menggunakan kode. Alih-alih mengedit konten model secara manual, Anda mendefinisikan strukturnya melalui modul generator dan serangkaian atribut. Ketika atribut tersebut berubah, atau ketika model diubah ukurannya, generator secara otomatis dijalankan untuk memperbarui model.

Model prosedural mempermudah Anda untuk:

• Menyesuaikan model tanpa merusak dengan mengubah parameter alih-alih membangunnya kembali. Misalnya, mengubah nilai StepSize pada tangga spiral secara otomatis menghasilkan kembali tangga dengan jumlah langkah yang diperbarui.
• Secara otomatis terintegrasi dengan sistem Studio yang ada seperti undo/redo, Team Create, dan alat penarik dengan mengimplementasikan satu fungsi OnGenerate.
• Mempertahankan kinerja tinggi, dengan model yang berfungsi seperti objek standar hingga parameter mereka berubah.
• Menghasilkan konten baik saat pengeditan maupun saat runtime, menggunakan sistem yang sama di Studio dan di dalam game.
• Membagikan model yang diparameterisasi di Creator Store, membuat aset lebih fleksibel dan dapat disesuaikan.

Menyisipkan model prosedural

Anda dapat menambahkan model prosedural ke game Anda dengan cara berikut:

• Menyisipkan objek ProceduralModel secara manual ke dalam Workspace. Opsi ini menyertakan template generator ModuleScript untuk membantu Anda memulai.

  

• Menghasilkan model prosedural menggunakan Assistant atau Roblox Studio MCP server.

• Menyisipkan model prosedural dari Creator Store untuk menggunakan atau menyesuaikan model yang sudah ada.

Untuk menyesuaikan bagaimana model prosedural dihasilkan, Anda dapat mendefinisikan modul generator Anda sendiri.

Fungsi OnGenerate

Fungsi OnGenerate berada di inti setiap ProceduralModel dalam bentuk OnGenerate(params, targetContainer).

Fungsi yang ditentukan oleh pengembang ini bertanggung jawab untuk menghasilkan konten model berdasarkan parameter yang diberikan dan menulis hasilnya ke dalam wadah yang diberikan.

OnGenerate memiliki dua tanggung jawab utama:

• Memproses parameter input untuk menentukan struktur model
• Menulis hasil yang dihasilkan sesuai dengan struktur itu ke targetContainer yang diberikan

Bagian berikut menjelaskan:

• Kapan dan bagaimana mesin memanggil OnGenerate
• Bagaimana mesin memproses konten yang ditulis ke targetContainer

Modul generator

Fungsi OnGenerate didefinisikan di dalam ModuleScript yang dikenal sebagai modul generator. ProceduralModel mengidentifikasi modul generator mana yang akan digunakan melalui propertinya Generator.

Modul generator adalah modul Luau standar, tetapi diperlukan langsung oleh mesin sebagai bagian dari proses generasi. Mereka mengikuti struktur yang telah ditentukan dan mengembalikan tabel dengan field yang terstandarisasi.

Struktur modul generator
local MyGenerator = {}

MyGenerator.Attributes = {
    DoSomething = true,
    AmountOfSomething = 137,
}

type Params = {
    Size: Vector3,
    Attributes: typeof(MyGenerator.Attributes),
    Pause: (self: any) -> (),
}
function MyGenerator.OnGenerate(params: Params, targetContainer: GeneratedFolder)
    
end

return MyGenerator

Field yang terstandarisasi meliputi:

• Attributes: Sebuah peta yang mendefinisikan nama parameter dan nilai defaultnya.
• OnGenerate: Fungsi yang menerima tabel params dan targetContainer.

Tabel params di dalam OnGenerate mencakup:

• Attributes: Sebuah tabel yang berisi atribut yang didefinisikan modul atau semua atribut model jika tidak ada yang ditentukan.
• Size: Parameter yang mencerminkan dimensi model pada skala satu.
• Pause: Metode yang memungkinkan penggandaan berhenti secara efisien selama tugas pembuatan yang kompleks.

Fungsi OnGenerate harus menghasilkan konten di sekitar asal dalam targetContainer. Ini tidak boleh langsung memodifikasi hierarki DataModel utama.

Parameter

Parameter adalah masukan yang mengontrol generasi. Ini mencakup properti Size bawaan dari ProceduralModel, serta atribut kustom yang ditentukan dalam modul generator. Parameter eksplisit ini diteruskan langsung ke OnGenerate. Parameter implisit, seperti kode sumber modul atau status sandboxing, juga memicu regenerasi ketika berubah tetapi tidak diteruskan ke OnGenerate.

Set lengkap parameter meliputi:

• Eksplisit:

  • Size: Mendefinisikan daerah di sekitar asal tempat konten dihasilkan.
  • Attributes: Sebuah peta yang berisi nilai input atribut saat ini.
• Implisit:

  • Generator: Modul yang menyediakan logika penggenerasian.
  • Kode sumber: Perubahan pada kode Luau modul generator.
  • Sandboxing: Perubahan pada status sandboxing modul generator.

Perilaku Regenerasi

Untuk mempertahankan kinerja dan menyederhanakan interaksi API, OnGenerate tidak dipanggil segera saat parameter berubah. Sebagai gantinya, ProceduralModel ditandai sebagai kotor, menunjukkan bahwa regenerasi tertunda. Regenerasi yang tertunda biasanya terjadi kemudian dalam frame yang sama.

Jika regenerasi gagal, status kotor dihapus hingga terjadi perubahan parameter lain. Jika sebuah tempat disimpan sementara model dalam keadaan kotor, status tersebut akan bertahan dan model ditambahkan ke antrian generasi pada saat game berikutnya dimuat.

Proses Eksekusi

Saat waktu pemrosesan tersedia, mesin melakukan regenerasi model kotor dengan langkah-langkah berikut:

1. Membutuhkan modul generator, yield jika perlu.
2. Memulai thread baru untuk proses generasi.
3. Membangun tabel parameter, menormalkan Size berdasarkan skala model saat ini.
4. Menerapkan nilai atribut default pada semua atribut yang hilang.
5. Menginisialisasi GeneratedFolder sementara sebagai targetContainer.
6. Memanggil OnGenerate.
7. Setelah OnGenerate mengembalikan:

   • Jika berhasil, memigrasikan hasil dalam targetContainer ke dalam ProceduralModel.
   • Jika generasi gagal, menggunakan placeholder kegagalan sebagai gantinya.

Jika parameter berubah lagi sementara thread generasi yield, proses generasi yang tertunda akan dibatalkan dan dimulai kembali dengan parameter yang diperbarui.

Hasil Generasi

Menempatkan hasil yang dihasilkan ke dalam model melibatkan langkah-langkah berikut:

1. Menghentikan semua thread anak yang bocor selama generasi.
2. Memposisikan hasil menggunakan PivotTo.
3. Jika Scale model tidak 1, menggunakan ScaleTo untuk membatalkan normalisasi ukuran.
4. Menginduk hasil ke dalam GeneratedFolder model.
5. Jika modul generator berada dalam sandbox, memastikan ModuleScripts di hasil tidak melebihi kemampuan modul generator.
6. Mengisi atribut yang hilang pada model dengan nilai defaultnya.
7. Menghapus status kotor model.

Detail Generasi

Selain alur generasi inti, detail berikut menggambarkan perilaku dan pertimbangan yang mempengaruhi bagaimana generasi ProceduralModel bekerja.

Ukuran

Karena normalisasi skala diterapkan selama generasi, ProceduralModel mendukung beberapa alur kerja pengukuran:

• Mengubah properti Size menghasilkan kembali model dengan konten baru.
• Mengubah Scale secara seragam mengubah ukuran hasil yang ada menggunakan ScaleTo.

Timeout

Sebagai pengaman, modul generator yang melakukan terlalu banyak pekerjaan tanpa yield akan dihentikan. Jika generasi mencapai kesalahan "Script Timeout", tambahkan panggilan tambahan ke parameters:Pause() untuk memungkinkan mesin menunda pekerjaan yang tersisa ke frame berikutnya.

Memanggil parameters:Pause() sangat hemat biaya dan biasanya kembali segera selama eksekusi generator normal, sehingga dapat dipanggil dengan bebas di awal loop tanpa memengaruhi kinerja.

Riwayat Undo

Hasil yang dihasilkan dikelompokkan dengan perubahan parameter yang memicu mereka menggunakan penggantian waypoint undo. Jika beberapa perubahan parameter terjadi dalam satu frame, hasilnya diasosiasikan dengan waypoint terbaru.

Sandboxing

ProceduralModel mendukung sandboxing. Semua model prosedural pihak ketiga yang Anda sisipkan dari Creator Store dikarantina secara default untuk membantu mencegah perubahan yang tidak diinginkan pada game Anda.

Kode generasi berjalan dalam konteks modul generator dan menggunakan status sandboxing modul tersebut. Pengaturan ini tidak terlihat secara default. Untuk melihat atau memodifikasinya, set Workspace.SandboxedInstanceMode = Experimental. Ini mengekspos properti Sandboxed dan Capabilities di ModuleScript.

Modul generator yang dikarantina biasanya memerlukan setidaknya kemampuan berikut:

• RunServerScript (untuk mengeksekusi modul)
• CreateInstances
• Basic

Sandboxing untuk ProceduralModel dan modul generatornya independen satu sama lain. Ketika diterapkan pada modul generator, sandboxing tidak memengaruhi skrip runtime normal di dalam ProceduralModel. Ini memungkinkan Anda menjaga generasi saat pengeditan dengan ketat tanpa memengaruhi perilaku dalam game.

Penyimpanan

ProceduralModels dapat menghasilkan ProceduralModels lainnya. Ketika ini terjadi, mesin memproses hierarki dari atas ke bawah dalam langkah generasi yang sama jika memungkinkan, dengan model yang lebih dalam dihasilkan terakhir.

Pembatasan

• Generasi tidak didukung dalam instance Actor.
• Model tidak dapat diubah menjadi paket.
• Sambungan yang dibuat saat menggunakan penarik dengan Joint Surfaces yang diaktifkan tidak dipertahankan di antara regenerasi ProceduralModel.