Buku Panduan Ruang Rupa Interaktif

Museum seni virtual 3D yang dijelajahi lewat browser: siswa mengapresiasi lukisan, berlatih lewat soal dan poin, lalu berkarya di Studio AI dan memajang karyanya di galeri.

Mulai membaca

Tiga kegiatan yang saling terhubung: mengapresiasi (berjalan di museum 3D dan membaca karya), berlatih (soal per lukisan, dinilai di server), dan berkarya (Studio AI dan Galeri Karya Siswa).

Bab IPendahuluan

Karya asli sulit dikunjungi, dan kegiatan mengapresiasi serta membuat karya biasanya berjalan sendiri-sendiri. Ruang Rupa Interaktif menjembatani keduanya: museum seni virtual di browser laptop dan ponsel, tanpa instal aplikasi.

Tujuan

Pengalaman berkunjung ke museum seni dari perangkat sekolah maupun ponsel siswa.
Mengenalkan aliran seni lukis dan karya patung melalui informasi yang dikurasi guru.
Mengukur pemahaman lewat soal per lukisan dengan penilaian yang adil.
Mendorong siswa berkarya dan saling mengapresiasi secara aman, dengan batas jatah dan moderasi guru.
Alat kelola sederhana tanpa server khusus.

Sasaran pengguna

Siswa: menjelajah, berlatih, berkarya, mengumpulkan poin.
Tamu: menjelajah dan berlatih tanpa poin; tanpa Studio AI.
Guru (manajer): kelas, lukisan, soal, moderasi, rekap.
Admin dan pemilik: mengatur peran dan melihat log.

Keunggulan

Berjalan di browser; kontrol keyboard, mouse, layar sentuh (joystick), dan mode VR.
Museum lengkap: plaza, fasad, aula, Ruang Lukisan 12 bingkai, patung, Sayap Karya Siswa, booth Studio AI, denah, dan tampilan dari atas.
Kunci jawaban tidak dikirim sebelum menjawab; poin tidak bisa ganda.
Studio AI dengan jatah harian, saringan kata, dan moderasi guru.
Multiplayer opsional lewat Firebase dengan identitas samaran.
Dikelola lewat Google Sheets dan Apps Script; biaya rendah.

Batasan

Data lukisan contoh hanya contoh; semua keterangan wajib diverifikasi guru.
Studio AI bergantung pada kuota layanan generator gambar dan dapat gagal bila kuota habis.
Multiplayer memerlukan Firebase; tanpa itu museum berjalan sebagai pengalaman tunggal.
Perlu browser modern dengan WebGL dan internet.
Gambar koleksi sebaiknya domain publik atau karya sendiri, dengan sumber dan lisensi tercatat.

Bab IIKonsep dan Definisi

Istilah dunia museum

Plaza: halaman depan; pengunjung mulai di sini.
Fasad dan serambi: muka gedung berpapan MUSEUM SENI; pintu terbuka otomatis saat didekati.
Aula: ruang utama yang menghubungkan Ruang Lukisan, Sayap Karya Siswa, dan booth Studio AI.
Ruang Lukisan: ruang pamer berisi 12 bingkai bernomor dan empat patung.
Sayap Karya Siswa: sisi timur aula, tempat karya Studio AI dipajang.
Booth Studio AI: sudut barat aula; memasukinya membuka panel Studio AI.
Denah dan Lihat dari atas; avatar (Merah, Biru, Hijau, Kuning) dan papan nama di atasnya.

Zona

Zona	Area	Efek
A, Museum	aula, Ruang Lukisan, plaza	tampilan museum
C, Studio AI	booth	panel Studio AI muncul
D, Galeri Karya Siswa	Sayap Karya Siswa	penomoran halaman karya muncul

Huruf B tidak dipakai. Zona dipilih otomatis dari posisi, atau lewat menu Tempat.

Isi dan pembelajaran

Aliran koleksi (9): Romantisme, Naturalisme, Realisme, Impresionisme, Ekspresionisme, Kubisme, Surealisme, Abstrak, Nusantara.
Status lukisan: draf (belum tampil) atau terbit.
Soal: pilihan ganda, maksimal lima soal aktif per lukisan. Latihan: seluruh soal aktif satu lukisan lewat tombol Kerjakan.
Poin: bawaan 10 per soal (1–20), hanya jawaban pertama. Bonus: 5 poin bila semua soal benar pada jawaban pertama, sekali per lukisan.
Rekap: poin per siswa dan kelas untuk guru; ekspor CSV.

Studio AI

Tema (maks. 100 karakter), aliran (5), palet (4), detail tambahan (maks. 150 karakter, opsional).
Jatah harian per siswa (bawaan 2) dan kuota kelas (bawaan 60).
Pajang ke galeri; arsip (maks. 30 per siswa) saat Coba lagi; moderasi guru: menunggu, disetujui, ditolak; suka satu kali per karya, tidak untuk karya sendiri.

Pengguna dan akses

Peran: tamu, siswa, manajer, admin, pemilik — ditentukan di server. Siswa masuk kelas dengan kode kelas. Login dengan akun Google atau akun sandi (buku tamu). Layar dan Firebase memakai ID anonim agar email tidak tersebar.

Istilah teknis

Google Sheets (basis data), Apps Script (Code.gs), Script Properties (pengaturan rahasia), Deploy, Cache, Lock, A-Frame (mesin 3D). Label versi di pojok kiri bawah berubah merah bila ada bagian bermasalah.

Bab IIIArsitektur Sistem

Bagian	Peran
Browser	halaman web statis (mis. GitHub Pages)
Server	satu aplikasi web Apps Script (`Code.gs`) sebagai pintu semua permintaan
Basis data	satu file Google Sheets
Gambar	Google Drive: folder karya Studio AI dan folder koleksi
Generator gambar	Cloudflare Workers AI, model flux-1-schnell
Multiplayer	Firebase Realtime Database (opsional)

Peran file

index.html: kerangka, login, lobi, panel Studio AI, penghubung ke server, pemuat bertahap, multiplayer, bagian KONFIGURASI.
museum.js: dunia 3D, gerak, panel lukisan, latihan, menu, denah.
admin.js: Panel Admin delapan tab. akun.js: masuk dan daftar dengan sandi.
Code.gs: seluruh logika server.

Semua file memakai satu nomor versi; VERSI di halaman harus sama dengan VERSI_ di server.

Cara browser berbicara dengan server

Setiap permintaan adalah POST ke alamat /exec berisi token, nama fungsi, dan argumen. Tiga fungsi publik tanpa token: daftarAkun, masukSandi, getKelasPublik. Fungsi lain memerlukan token sah dan harus ada di daftar putih. Token tidak sah mengembalikan kode AUTH dan pengguna kembali ke layar masuk. Pesan teknis hanya untuk guru; siswa menerima pesan ramah.

Lembar Google Sheets

Siswa, Pengguna, Kelas, Akun (sandi disimpan sebagai hash), Koleksi, BankSoal, Poin, GaleriAI, ArsipKarya, Suka, Log; Nilai adalah lembar lama yang tidak dipakai. Lembar yang belum ada dibuat otomatis oleh server.

Penyimpanan gambar

Drive dengan akses lihat lewat tautan. Folder RuangRupa_Karya dan RuangRupa_Koleksi dibuat otomatis. Alamat gambar lain tidak diterima server.

Bab IVTata Letak Museum

Koordinat: satuan meter; x ke timur, z positif ke arah plaza. Awal kunjungan di plaza (sekitar x 0, z 16).
Plaza: taman berpagar rendah, air mancur, bangku, lampu, tanaman pot; tiga undak (0,17 m) menuju serambi.
Fasad dan pintu: papan MUSEUM SENI, empat kolom; pintu lebar 5 m, tinggi 4 m, terbuka otomatis saat didekati. Tombol Masuk gedung memindahkan ke aula.
Aula: plafon 6 m; menuju Ruang Lukisan (belakang), Sayap Karya Siswa (timur), booth Studio AI (barat); ada papan denah.

Ruang Lukisan Era Modernisme

Plafon 5 m, karpet merah, 12 bingkai emas berkaca dan 4 patung. Penomoran searah jarum jam dari pintu:

Bingkai	Dinding
1–4	barat
5–6	belakang
7–10	timur (dari jauh ke dekat)
11–12	depan

Bingkai tanpa lukisan terbit menampilkan “Kosong”. Gambar tampil dengan rasio asli. Klik atau ketuk lukisan: kamera mendekat dan panel informasi terbuka.

Patung

Patung Figur Manusia, Arca Candi, Patung Abstrak, dan Garuda Wisnu. Punya panel informasi, tanpa latihan soal. Model disusun dari bentuk dasar 3D; keterangan perlu diverifikasi guru.

Sayap Karya Siswa (Zona D)

Menampilkan karya Studio AI yang disetujui, lengkap dengan kartu karya (pembuat, tema, aliran, palet). Karya sendiri ditandai “Karyamu”. Satu halaman memuat hingga 12 karya; daftar diperbarui sekitar tiap 45 detik.

Booth Studio AI (Zona C)

Sekitar 6 x 6 meter di sudut barat aula. Masuk: panel Studio AI muncul; keluar: panel menutup. Panel juga dapat dibuka dari menu Tempat.

Denah dan tampilan dari atas

Denah dibuat dari data dunia yang sama dan dapat dibuka layar penuh. Lihat dari atas mengangkat kamera; pengecekan tabrakan dan zona dihentikan selama mode ini.

Bab VPanduan Pengunjung (Siswa)

Kebutuhan dan masuk

Browser modern (Chrome, Edge, Safari terbaru), internet, dan akun Google atau akun email-sandi. Laptop memberi pengalaman terbaik; ponsel lewat joystick sentuh.

Mendaftar akun buku tamu

Isi: Saya adalah (Siswa atau Lainnya), nama lengkap (2–60), nama pendek (2–20, tampil di atas avatar), kode kelas (khusus siswa), email, asal sekolah atau instansi, kata sandi (8–64) dan ulangi.
Nama pendek hanya huruf Latin, angka, spasi, titik, apostrof, tanda hubung; nama tidak pantas ditolak.
Batas pendaftaran 300 akun per hari; lima kali salah masuk mengunci akun 15 menit; sesi sandi sekitar 6 jam.
Pendaftar “Lainnya” menjadi tamu: dapat menjelajah dan berlatih, tanpa poin dan Studio AI.
Akun Google dimasukkan ke kelas oleh guru lewat tab Pengguna.

Lobi

Pilih nama panggilan dan warna avatar, lalu Masuk pameran, atau Ganti akun untuk keluar.

Kontrol gerak

Perangkat	Kontrol
Keyboard	W/panah atas maju, S/panah bawah mundur, A dan D geser, Q/E atau panah kiri-kanan putar, Z balik badan, Shift berlari, Esc tutup panel
Mouse	seret untuk menoleh, klik lantai untuk berjalan, roda atau tombol +/− zoom, tombol 0 zoom normal (30–90°, bawaan 80°)
Sentuh	joystick kanan bawah, geser layar menoleh, cubit dua jari zoom, ketuk lantai berjalan

Kecepatan sekitar 1,3 m/detik berjalan dan 2,6 m/detik berlari. Sistem tabrakan mencegah menembus dinding, kolom, dan patung.

Tempat: Museum, Studio AI, Galeri Karya Siswa, Masuk gedung, Ruang Lukisan, Lihat dari atas, Denah.
Mode gerak (sentuh atau VR): Joystick, VR layar penuh, Kacamata VR.
Pengaturan: Geser layar, Bayangan, Zoom normal, Layar penuh. Admin: hanya guru.
Bila museum berat di laptop, matikan Bayangan.

Menjelajah dan etika

Dekati bingkai lalu klik; panel memuat judul, pelukis, tahun, aliran, penjelasan, fakta menarik, kalimat motivasi, sumber, dan lisensi. Gunakan nama yang sopan, tema Studio AI yang layak untuk sekolah, hormati karya teman; tombol Suka hanya untuk apresiasi.

Bab VIStudio AI

Siswa memutuskan apa yang digambar (tema), dengan gaya apa (aliran), dan dengan suasana warna apa (palet). Dirancang sebagai alat belajar aman: batas jatah, saringan kata, dan persetujuan guru.

Siswa: dapat memakai dan memajang. Tamu: ditolak. Guru: dapat mencoba dengan jatah yang sama.
Buka lewat booth di sudut barat aula atau menu Tempat.

Parameter

Isian	Aturan
Tema	wajib, maks. 100 karakter, bahasa Indonesia (diterjemahkan otomatis)
Aliran seni	Impresionisme, Kubisme, Ekspresionisme, Batik kontemporer, Surealisme
Palet warna	hangat, dingin, monokrom, warna komplementer
Detail tambahan	opsional, maks. 150 karakter
Jatah	2 gambar per siswa per hari (waktu Jakarta); kuota kelas 60 per hari

Sistem menambahkan ketentuan ramah keluarga, tanpa teks, tanpa tanda tangan, dan tanpa tanda air.

Langkah

Buka Studio AI; isi tema, aliran, palet, detail.
Tekan Buat gambar (sekitar 10–30 detik).
Pilih Pajang di pameran atau Coba lagi (gambar masuk arsip pribadi, maks. 30).
Karya langsung tampil bila persetujuan otomatis aktif; bila tidak berstatus menunggu sampai disetujui guru.

Satu siswa, satu karya terpajang: memajang karya baru memindahkan yang lama ke arsip dan mengatur suka kembali ke nol.

Di balik layar

Membuat gambar (generateArt): periksa token dan peran; potong teks sesuai batas; terjemahkan; saringan kata (kata utuh, angka pengganti huruf diubah kembali); susun prompt; kunci proses; periksa jatah harian dan kuota kelas; panggil generator; simpan ke Drive; jatah bertambah hanya bila berhasil.
Memajang (pajangKarya): gambar harus di folder karya dan milik pemanggil; prompt dibaca dari deskripsi berkas, bukan dari browser; status ditentukan AUTO_SETUJU.
Galeri dan suka: hanya karya disetujui tampil (cache sekitar 30 detik, ID anonim); suka dilakukan dalam kunci.

Pengaturan pemilik atau admin (Script Properties)

CF_ACCOUNT_ID dan CF_TOKEN: kredensial generator.
DAILY_LIMIT (bawaan 2) dan GLOBAL_LIMIT (bawaan 60).
AUTO_SETUJU: untuk sekolah sebaiknya dikosongkan agar semua karya melewati moderasi.
FOLDER_ID: folder karya; dibuat otomatis bila kosong.

Tips tema

Sebut objek dan tempat konkret; tambahkan waktu atau suasana pada detail; padukan aliran dan palet dengan sengaja; rencanakan tema karena jatah terbatas; hindari nama orang sungguhan dan kata tidak pantas.

Pesan galat

Pesan	Arti
Studio AI hanya untuk siswa	pengguna berperan tamu
Tema memuat kata yang tidak sesuai…	saringan kata menolak; ubah tema
Jatah membuat gambar hari ini habis	jatah harian siswa terpakai
Kuota gambar kelas hari ini sudah habis	batas total harian tercapai
Generator gambar belum dikonfigurasi	`CF_ACCOUNT_ID` atau `CF_TOKEN` belum diisi
Gagal membuat gambar	layanan menolak atau kuota habis; jatah tidak berkurang
Pilih avatar di lobi dahulu	nama dan avatar belum disimpan
Gambar tidak valid	bukan dari folder karya atau bukan milik pemanggil

Moderasi

Status karya: menunggu, disetujui, ditolak. Hanya yang disetujui tampil di Sayap Karya Siswa; karya tampil dapat disembunyikan kapan saja.

Bab VIILatihan Soal dan Sistem Poin

Setiap lukisan terbit dapat memiliki sampai lima soal aktif, masing-masing dengan 2–5 pilihan.

Alur siswa

Klik lukisan sampai panel informasi terbuka.
Tekan Kerjakan: semua soal aktif tampil sekaligus, urutan pilihan diacak.
Pilih satu jawaban pada setiap soal, lalu kirim (semua soal wajib dijawab).
Hasil tampil per soal: benar atau salah, jawaban benar, pembahasan, poin, bonus, total.
Tanda selesai: satu untuk sudah dikerjakan, satu lagi untuk semua soal benar pada jawaban pertama.

Aturan poin (dinilai di server)

Hanya siswa yang dihitung; guru dan tamu boleh berlatih tanpa poin.
Poin per soal 1–20 (bawaan 10), hanya untuk jawaban pertama; mengulang tidak menambah poin.
Bonus 5 poin bila semua soal satu lukisan benar pada jawaban pertama, sekali per lukisan.
Lock server mencegah poin ganda.

Contoh: lukisan 4 soal x 10 poin. Benar semua pada percobaan pertama = 40 + bonus 5 = 45. Benar 3 soal = 30, tanpa bonus; mengulang tidak menambah poin untuk soal yang sama.

Keamanan penilaian

Kunci tidak dikirim ke browser sebelum menjawab; pilihan diacak tetapi membawa nomor aslinya; server memeriksa status terbit dan rentang jawaban; poin dicatat di lembar Poin dengan kunci. Total poin tampil di HUD dan papan nama (dikirim server lewat ID anonim). Guru melihat rekap di tab Rekap dan mengunduh CSV.

Bab VIIIPanduan Guru dan Admin

Peran	Kewenangan
Tamu	menjelajah dan berlatih; tanpa poin dan Studio AI
Siswa	berlatih dengan poin, Studio AI, memajang dan menyukai karya
Manajer (guru)	kelas, lukisan, soal, moderasi, rekap, pindah kelas siswa, reset sandi akun sandi
Admin	semua kewenangan manajer + tambah/cabut peran manajer dan admin + Log
Pemilik	ditetapkan lewat `OWNER_EMAIL`; wewenang penuh dan tidak dapat diubah lewat aplikasi

Peran staf hanya untuk akun Google; tidak ada yang dapat mengubah peran dirinya; tidak boleh memberi peran lebih tinggi dari miliknya; hanya pemilik yang dapat menurunkan admin.

Panel Admin (delapan tab)

Muncul di menu bagi manajer ke atas. Selama panel terbuka, penggambaran 3D dihentikan agar ringan.

Langkah awal: daftar periksa: buat kelas, unggah lukisan, tulis soal, terbitkan.
Kelas: nama (maks. 30), urutan, status aktif/nonaktif (kelas tidak dihapus), kode kelas 4–20 huruf atau angka tanpa spasi; bagikan hanya kepada siswa kelas itu.
Lukisan: gambar JPG/PNG (diperkecil sampai sisi terpanjang 1024 px, maks. 2 MB); isi judul, pelukis, tahun, aliran, nomor bingkai (1–12), penjelasan, fakta, motivasi, sumber, lisensi. Syarat terbit: gambar, pelukis, sumber, dan lisensi terisi, nomor bingkai belum dipakai.
Soal: pertanyaan (min. 5 huruf), 2–5 pilihan, kunci, poin 1–20, pembahasan; “Hapus” berarti menonaktifkan. Impor massal: menu Ruang Rupa > Siapkan lembar InputSoal, isi satu soal per baris, lalu Impor soal dari InputSoal (kolom status OK atau GALAT).
Moderasi: Setujui atau Tolak karya menunggu; Sembunyikan karya tampil; karya ditolak dapat disetujui kembali.
Rekap: per siswa, per kelas, per lukisan; Unduh CSV aman dari injeksi rumus.
Pengguna: daftar peran dan kelas, pindah kelas, reset sandi, tambah/cabut peran (admin ke atas).
Log: khusus admin dan pemilik; 200 catatan terbaru.

Mengelola langsung di Sheets

Teks Koleksi boleh diedit langsung, tetapi tambah lukisan baru lewat panel. Gunakan InputSoal untuk soal. Ubah peran di Pengguna dengan hati-hati. Jangan ubah manual Akun, Poin, Suka, Siswa, Log, ArsipKarya. Perubahan dapat terlambat terlihat karena cache: koleksi sekitar 2 menit, galeri 30 detik, papan nama dan poin 45 detik.

Rutinitas

Sebelum belajar: label versi bersih, buka museum sebagai guru, pastikan lukisan terbit dan soal tampil, bagikan kode kelas.
Selama belajar: pantau Moderasi.
Setelah belajar: lihat Rekap, unduh CSV, periksa Log.
Berkala: cadangkan spreadsheet, tinjau karya tampil, periksa kuota Studio AI.

Bab IXPemasangan dan Pengaturan Dasar

Penting: pada tangkapan layar pemasangan, tutup atau samarkan nilai rahasia (CF_TOKEN, HMAC_SECRET, alamat web app, Client ID) sebelum dimasukkan ke buku.

Prasyarat

Akun Google (Sheets, Apps Script, Drive), akses Google Cloud Console, akun Cloudflare dengan Workers AI, akun GitHub atau hosting statis, dan (opsional) proyek Firebase. Berkas: index.html, museum.js, admin.js, akun.js, Code.gs dengan versi sama.

Sebelas langkah

Spreadsheet basis data: buat spreadsheet baru; lembar dibuat otomatis oleh server.
Kode server: Extensions > Apps Script dari spreadsheet; tempel Code.gs.
OAuth Client ID: Google Cloud Console, tipe Web application; tambahkan alamat hosting pada Authorized JavaScript origins. ID yang sama dipakai di index.html dan Script Property.
Generator gambar: akun Cloudflare Workers AI; catat Account ID dan buat API token.
Script Properties: lihat tabel di bawah.
Deploy: Web app, Execute as Me, Who has access Anyone; salin alamat /exec. Perubahan kode diterbitkan lewat New version (alamat tetap).
Konfigurasi index.html: API_URL, GOOGLE_CLIENT_ID, FB (kosongkan databaseURL untuk mematikan multiplayer).
Firebase (opsional): aktifkan Realtime Database; aturan seketat mungkin; hanya ID anonim, posisi, arah, warna avatar.
Hosting dan uji: unggah empat berkas ke satu folder; buka dengan Ctrl+Shift+R; label versi tanpa tulisan merah.
Pemanasan dan menu: jalankan pasangPemanasan sekali (pemicu 5 menit untuk mengisi cache); menu Ruang Rupa muncul setelah spreadsheet dimuat ulang (atau jalankan onOpen).
Data awal dan uji alur: masuk sebagai pemilik, ikuti Langkah awal, uji sebagai siswa dari daftar sampai karya tampil di galeri, cek Rekap dan Log.

Script Properties

Kunci	Fungsi
`GOOGLE_CLIENT_ID` (wajib)	memastikan token login berasal dari aplikasi ini
`OWNER_EMAIL` (wajib)	akun pemilik
`HMAC_SECRET` (wajib)	teks acak ≥ 32 karakter untuk sesi, ID anonim, dan sandi; jangan diubah setelah ada akun sandi; jangan dibagikan
`CF_ACCOUNT_ID`, `CF_TOKEN`	Studio AI
`DAILY_LIMIT`, `GLOBAL_LIMIT`	jatah per siswa (2) dan total (60) per hari
`AUTO_SETUJU`	`true` = karya langsung tampil; kosong = menunggu guru (disarankan)
`WAJIB_KODE`	`true` = pendaftar siswa wajib kode kelas (bawaan false)
`FOLDER_ID`, `FOLDER_KOLEKSI`	folder Drive; dibuat otomatis bila kosong

Parameter tertanam

Server: poin soal 10, bonus 5, poin 1–20, maks. 5 soal aktif, 2–5 pilihan, bingkai 1–12, tema 100 dan detail 150 karakter, arsip 30, pendaftaran 300 per hari, sandi 8–64, gagal masuk 5 kali lalu kunci 15 menit, sesi 6 jam, unggah maks. 2 MB (JPG/PNG diperiksa dari isi), cache koleksi 120 detik, galeri 30 detik, papan nama dan poin 45 detik. Halaman: PER = 12, bidang pandang 80° (30–90°), jalan 1,3 m/s, lari 2,6 m/s, joystick 1,6 m/s.

Mengubah pilihan Studio AI

Tambah aliran atau palet pada kolom di index.html dan pasangan nama beserta petunjuk gaya (bahasa Inggris) pada ALIRAN/PALET di Code.gs; nama harus persis sama. Tambah kata terlarang di KATA_TERLARANG. Ubah jatah lewat Script Properties. Setiap perubahan kode wajib diikuti kenaikan versi di semua berkas dan deploy ulang.

Pembaruan dan cadangan

Ganti nomor versi serempak (VERSI, VERSI_, penanda ?v=, penanda di akhir berkas js), deploy New version, unggah halaman, buka dengan Ctrl+Shift+R. Salin spreadsheet berkala, simpan salinan kode, putar CF_TOKEN bila dicurigai bocor, dan pertimbangkan membersihkan penghitung harian lama di Script Properties pada pemakaian bertahun-tahun.

Bab XAlur Logika Keseluruhan

Pemuatan: kotak login tampil segera; A-Frame, museum.js, admin.js, lalu Firebase dimuat di latar belakang. Adegan 3D disuntikkan lewat templat setelah mesin siap. Penggambaran 3D dihentikan di layar login.
Login dan profil: token Google diverifikasi server (audiens, penerbit, email terverifikasi, masa berlaku); pengguna baru dibuat sebagai siswa; jalur sandi mengembalikan token sesi bertanda tangan. Data pameran dipramuat selagi siswa memilih avatar (berlaku 60 detik).
Masuk pameran: simpan avatar dan ambil galeri, koleksi, poin dalam satu panggilan gabungan; museum dibangun dalam delapan bagian (gedung, fasad, Ruang Lukisan, patung, dekor, spanduk, sayap, booth); gagal berarti kembali ke lobi dengan pesan.
Selama di museum: tiap frame membaca gerak dan memeriksa tabrakan; tiap 250 ms memeriksa pintu; tiap 300 ms menentukan zona; tiap 45 detik di zona galeri memperbarui daftar karya; posisi multiplayer dikirim paling sering tiap 2 detik dengan denyut 15 detik.
Membaca dan berlatih: klik dibedakan dari geseran; Kerjakan memanggil getSoalLukisan, lalu kirimJawabanLukisan.
Studio AI: generateArt → pajangKarya atau arsipkanKarya → persetujuan guru → sukaiKarya.
Guru: setiap fungsi admin memeriksa peran di baris pertama; perubahan membersihkan cache terkait dan dicatat di Log.
Galat dan konsistensi: satu fungsi penghubung menangani galat; siswa menerima pesan ramah, guru pesan teknis. Lock melindungi pendaftaran, poin, suka, pajang, moderasi, dan pembuatan gambar.

Bab XIKeamanan, Privasi, dan Keselamatan Konten

Prinsip: browser tidak dipercaya; data pribadi minimum (yang tampil hanya nama panggilan, warna avatar, poin); konten aman untuk anak.
Identitas: token Google diverifikasi ke Google; sandi disimpan sebagai hash dengan garam unik per akun dan rahasia server; lima kegagalan mengunci 15 menit; token sesi bertanda tangan, kedaluwarsa sekitar 6 jam.
Otorisasi: peran diperiksa di server; hanya fungsi daftar putih yang berjalan; akun sandi tidak pernah menjadi staf; pemilik ditetapkan lewat pengaturan server; tamu dibatasi dari Studio AI, pajang karya, dan poin.
Privasi: email tidak dikirim ke pengguna lain; karya, suka, dan multiplayer memakai ID anonim yang tidak dapat dibalik; Firebase hanya memuat ID anonim dan posisi; lembar Akun menyimpan nama lengkap dan asal sekolah, jadi batasi akses spreadsheet kepada pengelola. Sekolah disarankan menyiapkan pemberitahuan atau persetujuan penggunaan.
Integritas penilaian: kunci tidak dikirim sebelum menjawab; poin hanya jawaban pertama, dikunci, dan hanya untuk siswa.
Konten Studio AI: saringan kata pada tema, detail, terjemahan, dan nama; perintah selalu ditutup ketentuan ramah keluarga; jatah dan kuota; gambar harus dari folder karya dan milik pemanggil; karya menunggu persetujuan guru dan dapat disembunyikan kapan saja. Saringan kata tidak sempurna, jadi moderasi guru tetap dianjurkan.
Teknis lain: unggahan diperiksa dari isi (JPG/PNG, maks. 2 MB); CSV dan impor soal menandai sel berawalan rumus; pesan galat teknis tidak ditampilkan ke siswa.
Saran: aplikasi diterbitkan dengan akses Anyone, jadi keamanan bertumpu pada token dan pemeriksaan server; atur aturan Firebase seketat mungkin; pastikan semua lukisan domain publik atau berizin; jaga CF_TOKEN dan HMAC_SECRET; batasi siapa yang dapat mengedit proyek Apps Script.

Bab XIIKinerja dan Optimasi

Masalah pada versi 2.21

Mesin 3D (> 1 MB) dan Firebase dimuat di kepala halaman sehingga login tertahan; masuk pameran memerlukan tiga panggilan server berurutan; ratusan elemen 3D dibangun sekaligus; gambar dimuat penuh sehingga memori GPU ponsel habis; antialias aktif tanpa batas resolusi dan penggambaran terus berjalan walau tak terlihat.

Perbaikan versi 2.22 dan 2.23

Pemuatan: mesin 3D dan Firebase dimuat setelah login tampil; Firebase hanya bila multiplayer aktif.
Jaringan dan server: satu panggilan gabungan dan pramuat data; server membaca lembar sekali per permintaan pada jalur baca-saja; Log hanya 200 baris terakhir; pemanasan cache tiap 5 menit; hasil fungsi lama dan baru dibandingkan pada data uji dan identik.
Tampilan: museum dibangun dalam delapan bagian; gambar Drive diminta kecil (1024 px lukisan, 512 px karya siswa); di sentuh tanpa antialias, rasio piksel maks. 2, kanvas teks diperkecil; penggambaran dihentikan di layar login dan saat Panel Admin terbuka.

Memeriksa kinerja

Apps Script: menu Executions. Browser: F12, tab Network dengan Disable cache. Sasaran perancangan (perkiraan, bukan hasil pengukuran lapangan): login sampai lobi sekitar 3 detik, masuk pameran sekitar 5 detik, tanpa layar putih di ponsel; ukur di perangkat sekolah sebelum dijadikan klaim.

Tips pengguna

Matikan Bayangan bila berat, gunakan Layar penuh, tutup tab lain, dan di ponsel hindari membuka banyak aplikasi.

Bab XIIIPemecahan Masalah

Gejala	Tindakan
Label versi merah: error pada museum, admin, akun	berkas gagal dimuat atau beda versi; pastikan semua satu folder dan versi, lalu Ctrl+Shift+R
Label: error pada server	`Code.gs` versi terbaru belum diterbitkan; New version dan cocokkan alamat `/exec`
Label: error pada index	buka konsol (F12), baca baris merah
Halaman putih atau lama	periksa koneksi, Ctrl+Shift+R, periksa alamat
Tombol Login Google tidak muncul	pemblokir iklan memblokir skrip Google, atau alamat belum ada di Authorized JavaScript origins
Sesi habis	masuk lagi
Museum tidak tampil	pastikan WebGL, satu versi, koneksi memadai; coba matikan ekstensi
Kamera tetap menunduk setelah Lihat dari atas	pakai `museum.js` versi 2.23
Lukisan tidak muncul	masih draf, gambar belum diunggah, atau cache (tunggu sekitar 2 menit)
Soal tidak tampil	lukisan belum terbit, soal nonaktif, atau pilihan kurang dari dua
Karya Studio AI tidak tampil	menunggu atau ditolak; periksa Moderasi; setelah disetujui tunggu sekitar 30 detik
Poin tidak bertambah	akun bukan siswa, bukan jawaban pertama, atau lukisan tanpa soal aktif
Avatar lain tidak terlihat	`databaseURL` kosong, Firebase gagal dimuat, atau aturan menolak
Menu Ruang Rupa tidak muncul	jalankan `onOpen` sekali, muat ulang spreadsheet
Impor soal GALAT	baca alasan di kolom status, perbaiki baris, impor lagi
Perubahan kode server tidak berlaku	terbitkan New version pada deployment

Bab XIVRiwayat Pengembangan

v1.05–v1.06: gerak lebih natural, pembedaan klik dan geser, joystick sentuh, patung.
Tahap 1: lembar Koleksi dan panel informasi lukisan.
Tahap 2A (v2.04+): peran, kelas, log; tab Lukisan, Soal, Log.
v2.09: kelas diatur guru; zoom cubit dan roda mouse; denah nyata.
v2.12: menu ringkas yang dapat dilipat.
Tahap 3 (v2.13): latihan soal, poin, tanda selesai, Rekap dengan CSV.
Tahap 4A (v2.14): papan nama dari server, kunci Firebase ber-ID anonim, Moderasi.
v2.15: pintu lebih lebar, 12 bingkai tampil, denyut multiplayer.
Tahap 4B (v2.16): Sayap Karya Siswa, booth Studio AI, kartu karya, denah baru.
v2.17: peran tamu, kode kelas saat daftar, aturan nama, saringan kata, prompt dipegang server.
v2.18–v2.21: tanah dan undak halus, kolom serambi, plafon dan lampu, penomoran bingkai, gerak halus, plakat, bingkai emas berkaca.
v2.22–v2.23: optimasi kecepatan, perbaikan inisialisasi mesin 3D, label versi diagnostik, plakat bergaya museum, kamera tegak setelah Lihat dari atas, optimasi Panel Admin, impor soal lewat spreadsheet.

Catatan Penting

Jangan mengunggah dokumen berisi data pribadi ke tempat umum.

GURU VOKASI