WebGL template

Sitemap Untuk menggunakan fitur template di Important:, Anda perlu pengetahuan sebelumnya tentang konsep JavaScript dan terminologi.WebGLLogin API yang membuat grafis 2D dan 3D di browser web. Opsi build Unity WebGL memungkinkan Unity untuk mempublikasikan konten sebagai program JavaScript yang menggunakan teknologi HTML5 dan WebGL rendering API untuk menjalankan konten Unity di browser web. More info
Lihat di Glossary, you need prior knowledge of JavaScript concepts and terminology.

Ketika Anda membangun proyek WebGL, Unity menyematkan Pemain di halaman HTML seperti browser dapat membukanya. Templat WebGL adalah pengaturan konfigurasi yang memungkinkan Anda mengontrol tampilan halaman HTML ini, sehingga Anda dapat: menguji, menunjukkan, dan pratinjau aplikasi WebGL Anda di browser.

Untuk mengakses template WebGL:

1. Pergi ke Pengaturan pemainPengaturan yang memungkinkan Anda mengatur berbagai pilihan khusus pemain untuk permainan akhir yang dibangun oleh Unity. More info
   Lihat di Glossary (menu: Edit > Project Settings > Player), dan mengatur pengaturan spesifik platform ke WebGL.
2. Buka Resolution and Presentation.

Secara default, pengaturan WebGL Template memiliki opsi berikut:

• Default: Halaman putih dengan bar pemuatan di kanvas abu-abu.
• Minimal: Templat WebGL minimal dengan hanya kode boilerplate yang diperlukan untuk menjalankan konten WebGL.
• Sitemap A PWA: termasuk file manifestasi web dan kode pekerja layanan.Progressive Web AppAplikasi perangkat lunak yang disampaikan melalui web. Ini menggunakan fitur browser tertentu untuk membuat pengalaman pengguna di par dengan aplikasi asli. More info
  Lihat di Glossary including a web manifest file and service worker code.

Halaman HTML built-in ini berguna untuk menguji dan menunjukkan Pemain minimal.

Anda juga dapat menggunakan JavaScript untuk membangun dan menyediakan template WebGL Anda sendiri untuk menghosting Pemain. Ini berguna untuk tujuan produksi, sehingga Anda dapat melihat pratinjau Pemain yang dihosting di halaman di mana itu akhirnya akan digunakan. Misalnya, jika konten Unity Player berinteraksi dengan elemen lain di halaman melalui antarmuka panggilan eksternal, Anda harus mengujinya dengan halaman yang berisi elemen berinteraksi.

Tambahkan template WebGL

Untuk menambahkan template kustom ke proyek Anda, arahkan ke folder Assets Proyek Anda dan buat folder yang disebut WebGLTemplates. Setiap template adalah subfolder dalam folder WebGLTemplates. Setiap subfolder template berisi file index.html bersama dengan sumber daya lain yang diperlukan halaman, seperti gambar atau stylesheet.

Cara termudah untuk membuat template WebGL kustom baru adalah membuat salinan template bawaan atau minimal. Ini disimpan dalam subfolder yang sesuai di bawah <Unity Installation>/PlaybackEngines/WebGLSupport/BuildTools/WebGLTemplates/. Setiap Proyek Unity mencakup ini secara default. Salin satu dan letakkan di folder Project/Assets/WebGLTemplates Anda sendiri, dan nama kembali ke sesuatu yang berarti sehingga Anda dapat mengidentifikasi template Anda nanti.

Templat di folder WebGLTemplates Proyek Anda muncul dalam pengaturan Template WebGL Unity Player. Nama template sama dengan foldernya. Untuk memberikan opsi ini gambar thumbnail untuk referensi mudah, tambahkan gambar 128x128-piksel ke folder template dan nama thumbnail.png.

variabel template, makro, dan sekian kondisional

Selama proses build, file template pra-proses Unity dan mengevaluasi semua makro dan arahan kondisi termasuk dalam file-file tersebut. Sebagai bagian dari proses ini, penemuan Unity dan mengganti semua deklarasi makro dengan nilai-nilai persediaan Editor. Unity secara otomatis pra-proses semua .html, .php, .css, .js dan .json file di folder template.

Variabel praprosesor internal

Variabel preprocessor internal berikut mengacu pada data dalam Proyek, dan menetapkan nilai untuk mereka pada membangun waktu sesuai dengan nilai-nilai persediaan Editor. JavaScript makro dan directives kondisional dapat menggunakan variabel preprocessor internal ini.

Variable	Type	Description
COMPANY_NAME	String	Nama Perusahaan didefinisikan dalam Pengaturan Pemain.
Catalog	String	Nama Produk yang didefinisikan dalam Pengaturan Pemain.
PRODUK_VERSI	String	Versi yang didefinisikan dalam Pengaturan Pemain.
WIDTH	Integer	Standar Canvas Lebar didefinisikan dalam Pengaturan Pemain > Resolusi dan Presentasi.
HEIGHT	Integer	Tinggi Kanvas Default di Pengaturan Pemain > Resolusi dan Presentasi.
SPLASH_SCREEN_STYLE	String	Ini diatur ke nilai "Dark" ketika Pengaturan Pemain Gaya Splash > Login Gambar diatur ke Light di Dark, jika tidak diatur ke nilai "Light".
BACKGROUND_COLOR	String	Mewakili Warna Latar Belakang didefinisikan dalam bentuk triplet hex.
UNITY_VERSI	String	Versi Unity.
DEVELOPMENT_PLAYER	Boolean	Ini diatur untuk benar jika opsi Development BuildMembangun pengembangan termasuk simbol debug dan memungkinkan Profiler. More info Lihat di Glossary diaktifkan.
DECOMPRESSION_FALLBACK	String	Ini diatur untuk "Gzip" atau "Brotli", tergantung pada metode compressionMetode menyimpan data yang mengurangi jumlah ruang penyimpanan yang dibutuhkan. Kompresi Tekstur, Kompresi Animasi, Kompresi Audio, Membangun Kompresi. Lihat di Glossary digunakan dan yang depresi disertakan dalam build. Jika tidak termasuk, variabel diatur ke string kosong.
INITIAL_MEMORY	Integer	Ukuran awal dari heap memori WASM di megabytes (MB).
USE_WASM	Boolean	Ini diatur untuk benar jika build saat ini adalah build WebAssembly.
USE_THREADS	Boolean	Ini diatur untuk benar jika build saat ini menggunakan benang.
Facebook Twitter Google Plus Pinterest Email	Boolean	Ini diatur untuk benar jika build saat ini mendukung API grafis WebGL1.0.
USE_WEBGL_2_0	Boolean	Ini diatur untuk benar jika build saat ini mendukung API grafis WebGL2.0.
USE_DATA_CACHING	Boolean	Ini diatur untuk benar jika build saat ini menggunakan caching diindeksDB untuk file yang diunduh.
LOADER_FILENAME	String	Ini diatur ke nama file skrip build loader.
DATA_FILENAME	String	Ini diatur ke nama file dari file data utama.
FRAMEWORK_FILENAME	String	Ini diatur ke nama file skrip kerangka build.
Artikelcode_FILENAME	String	Ini diatur ke nama file modul WebAssembly ketika build saat ini adalah build WebAssembly, jika tidak diatur ke nama file modul asm.js.
MEMORY_FILENAME	String	Ini diatur ke nama file dari file memori ketika memori disimpan dalam file eksternal, jika tidak diatur ke string kosong.
SYMBOLS_FILENAME	String	Ini diatur ke nama file dari file JSON yang mengandung simbol debug ketika build saat ini menggunakan simbol debug, jika tidak diatur ke string kosong.
BACKGROUND_FILENAME	String	Ini diatur ke nama file gambar latar belakang ketika gambar latar belakang dipilih dalam Pengaturan Pemain > Login Gambar, jika tidak diatur ke string kosong.

JavaScript macros

JavaScript macro adalah blok kode JavaScript dalam file template, dikelilingi oleh tiga set kurungan keriting. Kode JavaScript ini dapat menggunakan variabel preprocessor internal yang tercantum di atas. Variabel ini ditugaskan pada membangun waktu sesuai dengan nilai-nilai persediaan Editor. Selama build, preprocessor mengevaluasi semua makro dan menggantinya dengan output variabel.

Anda dapat menggunakan makro JavaScript untuk nilai preprocess yang disediakan oleh Editor. makro-makro ini dapat menjadi kompleks seperti yang Anda sukai. Mereka dapat menyertakan beberapa operator, loop, fungsi, dan konstruksi JavaScript lainnya.

Garis contoh berikut adalah dari file index.html yang digunakan dalam template default:

<div id="unity-build-title">{{{ PRODUCT_NAME }}}</div>

Jika nilai Product Name dalam Pengaturan Pemain diatur ke "My WebGL Game", variabel preprocessor internal PRODUK_ NAMA memiliki nilai “My WebGL Game”. Dalam file output index.html, garis muncul sebagai:

<div id="unity-build-title">My WebGL Game</div>

Di bawah ini adalah contoh yang lebih kompleks dari file template index.html yang sama:

canvas.style.background = "url('" + buildUrl + "/{{{ BACKGROUND_FILENAME.replace(/'/g, '%27') }}}') center / cover";

Jika folder build target disebut Let’s try WebGL, dan gambar latar belakang dipilih dalam Pengaturan Pemain, variabel preprocessor internal BACKGROUND_FILENAME memiliki nilai "Let mencoba WebGL.jpg". Dalam file output index.html, perubahan garis menjadi:

canvas.style.background = "url('" + buildUrl + "/Let%27s try WebGL.jpg') center / cover";

Politik

Directives bersyarat #if, #else, dan kontrol #endif apakah Unity mencakup bagian spesifik dari file yang telah diproses dalam file output, atau membuangnya untuk membangun saat ini.

Kode yang dimulai dengan arahan #if dan berakhir dengan arahan #endif disebut kelompok kondisional. Kelompok bersyarat juga dapat mencakup arahan #else. Unity mengevaluasi ekspresi yang ditulis setelah #if sebagai ekspresi JavaScript. Jika ekspresi ini memiliki nilai yang benar (yaitu, nilai yang diterjemahkan ke benar ketika dievaluasi dalam konteks Boolean) Unity menjaga kelompok garis segera mengikuti petunjuk #if dalam file output. Jika ekspresi #if palsu, dan arahan #else disertakan dalam kelompok kondisional, Unity menjaga kelompok garis segera mengikuti arahan #else dalam output. Contoh kelompok kondisional adalah sebagai berikut:

#if EXPRESSION
  // this block is included in the output if EXPRESSION has a truthy value
#else
  // this block is included in the output otherwise
#endif

Mengevaluasi ekspresi JavaScript dapat mencakup kurung, operator logika dan konstruksi JavaScript lainnya. Directives bersyarat dapat bersarang.

variabel pengguna kustom

Ketika Anda memilih template WebGL, menyatukan template dan mencari makro JavaScript dan arahan kondisional. Variabel JavaScript diperlakukan sebagai variabel pengguna kustom jika memenuhi semua kriteria berikut:

• Mereka digunakan dalam makro JavaScript dan arahan kondisional.
• Mereka tidak dinyatakan dalam kode template.
• Mereka tidak variabel preprocessor internal.

Unity secara otomatis menambahkan variabel pengguna kustom ini ke bagian Resolution and Presentation di jendela Player Settings.

Sebagai contoh, jika Anda ingin mengontrol judul halaman index.html yang dihasilkan langsung dari jendela Player Settings, Anda harus memodifikasi garis <title> dari index.html dalam template kustom Anda, seperti ini: <title>{{{ PAGE_TITLE }}}</title> Setelah Anda melakukan ini, pilih ulang template kustom Anda. Ini membuat template lagi, dan Anda harus menemukan lapangan Page Title di bagian Resolution and Presentation > WebGL Template dari Player Settings window.

Ketika Anda memasukkan teks ke dalam bidang ini dan membangun Anda Proyek, PAGE_ variabel kustom TITLE digunakan dalam makro template secara otomatis menjadi teks di bidang Page Title.

Jika Anda ingin menggunakan variabel integer atau float kustom di makro Anda, gunakan fungsi JavaScript parseInt() atau parseFloat() di makro Anda untuk preprocess string nilai yang disediakan oleh Editor. Ini karena variabel pengguna kustom selalu ditugaskan nilai string.

Note: Karakter underscore dalam tampilan nama variabel sebagai ruang di dalam bidang untuk meningkatkan kemampuan membaca.

Struktur file index.html

index.html mengandung kode yang diperlukan untuk memuat build dan harus menyertakan berikut:

• Elemen <canvas>. Waktu runtime unity menggunakan elemen <canvas> untuk membuat aplikasi.
• Kode JavaScript untuk mengunduh build loader. Contoh:

var buildUrl = "Build";
var loaderUrl = buildUrl + "/{{{ LOADER_FILENAME }}}";
var script = document.createElement("script");
script.src = loaderUrl;
script.onload = () => {
  // code for instantiating the build
};
document.body.appendChild(script);`

Dalam contoh ini, {{{ LOADER_FILENAME }}} secara otomatis diselesaikan oleh preprocessor template ketika build dihasilkan.

Atau, Anda dapat mengunduh build loader menggunakan tag script, misalnya: lang-js <script src="Build/{{{ LOADER_FILENAME }}}"></script>

• Kode JavaScript untuk mengulangi build. Unity builds sesaat menggunakan fungsi createUnityInstance(), yang didefinisikan dalam skrip build loader.

Fungsi instansi: createUnityInstance()

Fungsi createUnityInstance() menciptakan contoh baru konten Anda. Anda dapat menggunakannya seperti ini: createUnityInstance(canvas, config, onProgress).then(onSuccess).catch(onError);

Fungsi ini mengembalikan objek Promise, di mana:

Object	Use
canvas	Waktu runtime unity menggunakan objek canvas untuk membuat permainan.
config	Objek config mengandung konfigurasi build, seperti URL kode dan data, nama produk dan perusahaan, dan versi. Untuk informasi lebih lanjut tentang definisi konfigurasi, lihat bagian Membangun Konfigurasi di halaman ini.
onProgress(progress) {...}	WebGL loader menyebut objek callback onProgress setiap kali pembaruan kemajuan unduh. argumen progress yang datang dengan callback onProgress menentukan kemajuan pemuatan sebagai nilai antara 0,0 dan 1.0.
onSuccess(unityInstance) {...}	Penelepon onSuccess disebut setelah bangunan telah berhasil sesaat. Objek instance Unity yang dibuat disediakan sebagai argumen. Objek ini dapat digunakan untuk interaksi dengan build.
onError(message) {...}	Callback onError disebut jika kesalahan terjadi selama membangun instansi. Pesan kesalahan disediakan sebagai argumen.

Fungsi createUnityInstance() didefinisikan dalam skrip build loader dan spesifik untuk membangun yang sesaat. Oleh karena itu, jika Anda menanamkan dua atau lebih membangun dalam dokumen HTML yang sama, pastikan bahwa fungsi createUnityInstance() disebut dari callback onload dari skrip build loader yang sesuai. Untuk informasi lebih lanjut tentang Unity WebGL Loader, lihat Membangun dan Menjalankan Proyek WebGL.

Membangun konfigurasi

Objek konfigurasi berisi konfigurasi build, yang terdiri dari URL kode dan data, nama produk, nama perusahaan, dan versi. Anda dapat mendefinisikannya menggunakan kode berikut:

var buildUrl = "Build";
var config = {
  dataUrl: buildUrl + "/{{{ DATA_FILENAME }}}",
  frameworkUrl: buildUrl + "/{{{ FRAMEWORK_FILENAME }}}",
  codeUrl: buildUrl + "/{{{ CODE_FILENAME }}}",
#if MEMORY_FILENAME
  memoryUrl: buildUrl + "/{{{ MEMORY_FILENAME }}}",
#endif
#if SYMBOLS_FILENAME
  symbolsUrl: buildUrl + "/{{{ SYMBOLS_FILENAME }}}",
#endif
  streamingAssetsUrl: "StreamingAssets",
  companyName: "{{{ COMPANY_NAME }}}",
  productName: "{{{ PRODUCT_NAME }}}",
  productVersion: "{{{ PRODUCT_VERSION }}}",
};

Dalam contoh di atas, URL folder build disimpan sebagai variabel terpisah yang disebut buildUrl. Ini berguna dalam kasus di mana Anda tidak tahu hubungan antara halaman yang timbul dan membangun folder di server hosting. Ini memungkinkan Anda untuk menggunakan ulang kode embedding di dokumen HTML lain. Contoh ketika menggunakan ini adalah jika Anda memindahkan folder Build ke lokasi lain di server Anda. Anda dapat menyesuaikan nilai variabel buildUrl pada halaman embedding, dan Anda dapat menggunakan kode embedding yang sama. Ini juga berlaku untuk folder StreamingAssets (streamingAssetsUrl).

Membangun interaksi

Setelah build berhasil disaatkan, penelepon handler fulfilment dari objek Promise menerima objek instance Unity yang baru diciptakan sebagai argumen. Untuk berinteraksi dengan build, sebut metode berikut dari instance Unity:

Method	Use
unityInstance.SetFullscreen(fullscreen)	Metode SetFullscreen toggles mode layar penuh. Metode ini tidak mengembalikan nilai. Login Mode layar penuh diaktifkan ketika argumen memiliki nilai 1. * Mode layar penuh dinonaktifkan ketika argumen fullscreen memiliki nilai 0.fullscreen argument has a value of 0.
unityInstance.SendMessage(objectName, methodName, value)	Metode SendMesssage mengirim pesan ke GameObjects. Metode ini tidak mengembalikan nilai. - objectName adalah nama objek di Adegan Anda. - methodName adalah nama metode di script, saat ini melekat pada objek itu. - value bisa menjadi string, angka, atau bisa kosong.
unityInstance.Quit().then(onQuit)	Metode Quit() dapat digunakan untuk menghentikan runtime dan membersihkan memori yang digunakan oleh instance Unity. Metode ini mengembalikan objek Promise. - onQuit callback disebut setelah build runtime telah berhenti.