Menyimulasikan runtime yang berkata tidak: cara kami membuat sandbox browser agar bertindak seperti WeChat

Sun, 19 Jul 2026 00:00:00 GMT

Menyimulasikan runtime yang berkata tidak: cara kami membuat sandbox browser agar bertindak seperti WeChat

Oleh Oleg Sidorkin, CTO dan Co-Founder Cinevva

Kami baru-baru ini merilis mode mini game WeChat di Game Creator kami: profil build yang menjaga game buatan AI tetap berada dalam subset platform web yang dapat bertahan ketika di-porting ke runtime WeChat. Profil ini berupa serangkaian aturan pembuatan. Tanpa UI DOM, tanpa Pointer Lock, audio hanya mp3, dan tanpa kode dinamis. Model mengikuti aturan tersebut sebagaimana model biasanya mengikuti aturan, yaitu: biasanya.

“Biasanya” tidak cukup ketika setiap pelanggaran tidak terlihat di browser tetapi berakibat fatal setelah diekspor. Game dengan bilah kesehatan HTML berjalan sempurna di pratinjau kami, tetapi hanya menampilkan layar kosong di WeChat karena mini game WeChat sama sekali tidak memiliki DOM. Jadi, kami membangun sesuatu yang mengubah aturan tersebut dari sekadar saran menjadi hukum fisika: sandbox mode ketat yang membuat browser itu sendiri menolak melakukan hal-hal yang tidak dapat dilakukan WeChat. Tulisan ini membahas cara kerjanya.

Keputusan inti: simulasikan ketiadaan, bukan keberadaan

Pendekatan yang paling jelas adalah mengemulasikan WeChat: mengimplementasikan wx.createCanvas, wx.onTouchStart, wx.setStorageSync, lalu menjalankan game terhadap permukaan API wx.* yang diemulasikan. Kami memilih arah sebaliknya, dan alasannya terletak pada bentuk pipeline ekspor kami.

Game dalam mode WeChat tetap ditulis menggunakan API browser. Saat pengemasan, sebuah adaptor (dengan pendekatan weapp-adapter yang menjadi standar komunitas) memetakan API browser tersebut ke wx.*. Artinya, game kami tidak pernah memanggil wx.* secara langsung, sehingga emulator wx akan menguji jalur kode yang sebenarnya tidak ada. Penyebab port gagal bukanlah ketiadaan wx.* di browser. Penyebabnya adalah keberadaan API browser yang tidak memiliki padanan di WeChat dan diam-diam digunakan selama proses pembuatan. document.createElement('div'). requestPointerLock(). IndexedDB. File .ogg yang dapat didekode dengan baik di Chrome tetapi tidak akan pernah bisa di WeChat pada iOS.

Karena itu, sandbox menyimulasikan ketiadaan. Segala sesuatu yang tidak dimiliki WeChat dihapus, diracuni, atau ditandai dalam pratinjau, sehingga sejak frame pertama game dikembangkan di dalam irisan kemampuan kedua platform.

Tempatnya berada: service worker yang sudah tersedia

Pratinjau editor kami memiliki jalur penyajian yang tidak biasa sehingga penerapan ini nyaris tanpa biaya. Game di editor tidak disajikan dari jaringan. Sebuah service worker mencegat permintaan /game/* dan menyajikan file dari IndexedDB, sehingga iframe pratinjau dapat dimuat ulang secara instan tanpa perjalanan bolak-balik ke server. Worker tersebut sudah menyuntikkan dua file virtual ke setiap halaman game: skrip penangkap error yang meneruskan output konsol dan crash ke editor, serta pemeriksa adegan secara langsung.

Sandbox menjadi file virtual ketiga, _wechat-strict.js, yang disuntikkan ke halaman tepat setelah skrip penangkap dan sebelum kode game apa pun dijalankan. Urutan ini sangat krusial karena dua alasan. Sandbox harus berjalan setelah skrip penangkap agar panggilan console.error miliknya sudah terhubung dan diteruskan ke editor, serta sebelum modul game agar racun sudah terpasang ketika baris pertama kode game dieksekusi.

Aktivasinya menggunakan trik satu baris. Toggle WeChat di kreator disimpan dalam localStorage, dan iframe pratinjau memiliki origin yang sama dengan editor, sehingga harness cukup membaca flag tersebut secara langsung:

try {
  if (localStorage.getItem('cinevva-gc-profile') !== 'wechat-minigame') return;
} catch (e) { return; }

Untuk setiap game non-WeChat, skrip ini hanya melakukan satu perbandingan string lalu keluar lebih awal. Tidak ada flag build, perjalanan bolak-balik ke server, maupun state yang perlu disinkronkan dengan service worker.

Daftar racun dan taksonomi dua tingkat

Tidak setiap pelanggaran layak mendapat respons yang sama, sehingga harness membedakan dua tingkat. API yang tidak tersedia di WeChat akan melempar error karena itulah yang terjadi setelah ekspor, dan crash saat pembuatan merupakan pratinjau yang jujur atas crash saat peninjauan. Hal-hal yang tersedia tetapi akan bermasalah kemudian ditandai sebagai error konsol yang mencolok tanpa mengubah perilakunya, karena memblokirnya justru akan menyembunyikan keadaan game yang sebenarnya dari orang yang sedang mengiterasinya.

Tingkat lempar error: pembuatan elemen UI HTML apa pun melalui createElement maupun createElementNS (Three.js membuat canvas melalui varian NS, sehingga kedua jalur memerlukan gerbang yang sama), eval, new Function, requestPointerLock, dan pendaftaran service worker. Setiap error yang dilempar menyertakan cara memperbaikinya di dalam pesan:

throw violate("document.createElement('" + tag + "') — Mini game WeChat tidak memiliki DOM. " +
  "Gambar UI di canvas (canvas 2D offscreen -> THREE.CanvasTexture pada quad screen-space) " +
  "dan lakukan hit-test ketukan sendiri.");

Tingkat penandaan: membaca indexedDB (mengembalikan undefined, persis seperti WeChat, ditambah error yang mengarahkan ke localStorage), audio dalam format apa pun yang tidak dapat didekode oleh WeChat iOS (diperiksa di tiga tempat: konstruktor Audio, setter src pada prototipe elemen media, dan URL yang diambil), permintaan jaringan ke origin apa pun selain milik game atau CDN aset kami (di WeChat, origin tersebut memerlukan domain yang masuk daftar izin dan terdaftar ICP), serta kemunculan Tone.js dalam bentuk apa pun.

Ada juga audit pascapemuatan yang berjalan sesaat setelah halaman stabil: audit ini menelusuri dan melaporkan elemen HTML apa pun yang berasal dari markup milik game, bukan dari pembuatan dinamis. HUD statis dapat lolos dari gerbang createElement, jadi gerbang tersebut saja tidak cukup.

Setiap laporan dideduplikasi berdasarkan pesan dan dibatasi maksimal lima puluh per sesi. Bug loop terbalik yang membuat satu div per frame hanya menghasilkan satu error, bukan banjir pesan yang menenggelamkan sinyal penting.

Empat pengecualian yang paling banyak memberi kami pelajaran

Membangun sandbox sebagian besar berarti memutuskan apa yang tidak boleh diracuni, dan setiap pengecualian yang kami buat berasal dari alat kami sendiri yang rusak selama pengembangan.

Debugger kami berjalan menggunakan eval. Alat execute_js milik kreator, yang digunakan AI untuk memeriksa game yang sedang berjalan, mengevaluasi kode melalui handler pesan milik skrip penangkap, yang memanggil eval. Meracuni eval secara naif akan membutakan AI itu sendiri. Solusinya: sebelum meracuni, harness menyimpan fungsi asli pada properti non-enumerable, lalu handler skrip penangkap menggunakannya sebagai fallback:

Object.defineProperty(window, '__cinevvaRealEval', { value: window.eval, enumerable: false });
window.eval = function () { throw violate('eval() dilarang dalam mini game WeChat.'); };
// skrip penangkap, saat menerima pesan:
returnValue = (window.__cinevvaRealEval || eval)(e.data.code);

Kode game yang mencoba menggunakan eval tetap berhenti. Debugger tidak.

Perekam juga membuat elemen. Perekam reel kami disuntikkan ke iframe game sebagai

Cinevva Blog

Menyimulasikan runtime yang berkata tidak: cara kami membuat sandbox browser agar bertindak seperti WeChat

Menyimulasikan runtime yang berkata tidak: cara kami membuat sandbox browser agar bertindak seperti WeChat

Keputusan inti: simulasikan ketiadaan, bukan keberadaan

Tempatnya berada: service worker yang sudah tersedia

Daftar racun dan taksonomi dua tingkat

Empat pengecualian yang paling banyak memberi kami pelajaran