---
type: reference
title: Referensi skema kustomisasi
summary: Model tipe-bidang dan preset bersama di balik setiap permukaan yang bisa dikustomisasi, tipe bidang yang diizinkan tiap sumbu, nilai yang diterima masing-masing, dan bagaimana skema dan preset didefinisikan serta diselesaikan.
---

Ini adalah referensi tunggal untuk **model tipe-bidang dan preset** Caputchin, fondasi bersama di bawah setiap permukaan yang bisa dikustomisasi:

- [Kustomisasi game](/docs/game-customization/overview): bahasa, skin, dan konfigurasi game marketplace.
- [Skema game kustom](/docs/custom-game-development/dashboard-schema): skema yang kamu tulis sendiri untuk game kustom.
- [Manifest game marketplace](/docs/marketplace-game-development/the-caputchin-json-manifest): blok `locales` / `skins` / `configurations` yang dideklarasikan penulis game.
- [White-label widget](/docs/widget-customization/white-label): skema bawaan shell widget.

Keempatnya memakai tipe bidang yang sama dan model preset yang sama yang dijelaskan di sini. Kustomisasi dibangun dari **preset**, dan sebuah preset adalah kantong **bidang** bertipe.

## Tipe bidang per sumbu

Tiap sumbu mengizinkan set tipe bidang tetap:

| Sumbu | Tipe bidang yang diizinkan |
|---|---|
| Configuration | `boolean`, `number`, `range`, `list`, `string`, `link` |
| Locale | hanya `string` |
| Skin | `color`, `image`, `audio`, `video`, `boolean`, `number`, `range`, `list` |

Sebuah skin bukan hanya warna dan aset: ia juga bisa memaparkan tombol skalar `boolean`,
`number`, `range`, dan `list` (sakelar "shadows", angka radius-sudut, pilihan "pattern").
Ini berperilaku persis seperti padanan konfigurasinya dan diselesaikan ke nilai bertipenya (sebuah
`boolean` tetap `true`, sebuah `number` tetap `8`); nilai `color` dan aset diselesaikan ke string.
Skin tak mengizinkan `string` atau `link` (teks bebas milik bahasa; target tautan adalah
konfigurasi).

## Apa yang diterima tiap tipe

| Tipe | Nilai | Aturan |
|---|---|---|
| `string` | Teks bebas | Teks apa pun. |
| `boolean` | Sebuah sakelar | `true` atau `false`. |
| `number` | Sebuah angka | Angka hingga mana pun. |
| `range` | Angka berbatas | Angka hingga dalam minimum dan maksimum bidang. Step adalah kenyamanan slider; nilai luar-step tetap diterima. |
| `list` | Satu pilihan | Harus salah satu dari opsi yang didaftar bidang. |
| `link` | Sebuah URL | URL `http` atau `https`. Kredensial tersemat ditolak. |
| `color` | Sebuah warna | Warna hex (`#rgb`, `#rgba`, `#rrggbb`, atau `#rrggbbaa`) atau nilai `rgb()` / `rgba()`. Warna bernama dan ruang warna lain tak diterima. |
| `image` | Sebuah gambar | Berkas yang diunggah atau URL `https` yang berakhir `.png`, `.jpg`, `.jpeg`, `.webp`, `.svg`, atau `.gif`. |
| `audio` | Sebuah klip audio | Berkas yang diunggah atau URL `https` yang berakhir `.mp3`, `.ogg`, atau `.wav`. |
| `video` | Sebuah video | Berkas yang diunggah atau URL `https` yang berakhir `.mp4` atau `.webm`. |

Caputchin memvalidasi setiap nilai saat kamu menyimpan, jadi sebuah nilai yang tak cocok dengan tipenya ditolak sebelum ia bisa mencapai pengunjung.

## Kunci tercadang

Di samping bidang kontennya, sebuah preset membawa beberapa **kunci metadata** tercadang (masing-masing berawalan garis-bawah) yang mengontrol bagaimana ia dipilih dan diselesaikan, bukan apa yang ia tampilkan. Bagaimana kamu menyetelnya bergantung pada permukaan: [penulis game marketplace](/docs/marketplace-game-development/the-caputchin-json-manifest) menulisnya secara literal di `caputchin.json`; di editor dasbor (game kustom, white-label) kamu menyetelnya lewat kontrol dan tak pernah mengetik kuncinya. Bagaimanapun maknanya sama.

| Kunci | Sumbu | Makna |
|---|---|---|
| `_lang` | Locale | Language tag BCP-47 yang dilayani preset locale (`en`, `es`, dan seterusnya). Preset dikelompokkan olehnya; beberapa preset bisa berbagi satu `_lang` (mis. dua varian Inggris). |
| `_direction` | Locale | `ltr` atau `rtl`. Opsional, diturunkan-otomatis dari `_lang` untuk bahasa kanan-ke-kiri (`ar`, `he`, `fa`, `ur`, `yi`, `ps`, `sd`); jarang disetel dengan tangan. |
| `_theme` | Skin | `light`, `dark`, atau `any`. Preset `light` / `dark` muncul hanya di bawah latar itu; preset `any` berfungsi di bawah keduanya dan layak untuk salah satu. Default ke `light` saat absen. |
| `_default` | Semua | Menandai preset yang dipilih server untuk kelompoknya saat pengunjung tak memilih satu. Satu default per kelompok (per mode untuk skin); sebuah skin `any` bisa menjadi default untuk terang, gelap, atau keduanya. |
| `_extends` | Semua | Menamai preset lain untuk diwarisi. Lihat [Memperluas preset](#extending-a-preset). |

Kunci metadata tercadang **disingkirkan saat penyelesaian**: `_extends` dan `_default` tak pernah mencapai game, dan hanya metadata yang bertahan (`_lang`, `_direction`, `_theme`) plus bidang konten yang diratakan yang dikirim.

## Memperluas preset [#extending-a-preset]

`_extends` membiarkan satu preset mewarisi setiap nilai dari yang lain, jadi kamu menulis hanya bidang yang berbeda alih-alih mengulang seluruh preset. Setel `_extends` ke **nama preset lain di sumbu yang sama**; preset yang memperluas dimulai dari semua nilai preset itu dan menimpa kunci yang ia setel sendiri.

```json
{
  "skins": {
    "presets": {
      "brand-light": { "_theme": "light", "accent": "#2da44e", "bg": "#ffffff" },
      "brand-light-warm": { "_extends": "brand-light", "accent": "#d97706" }
    }
  }
}
```

Di sini `brand-light-warm` mewarisi `bg` dari `brand-light` dan mengubah hanya `accent`.

Dua detail:

- **Jalan pintas tema skin.** Pada preset skin, `_extends` boleh menamai sebuah tema (`light` atau `dark`) ketimbang preset. Bentuk itu diselesaikan ke preset mana pun yang `_default` untuk tema itu, cara nyaman untuk mendasari varian pada "skin terang default" tanpa menamainya.
- **Ia diselesaikan habis.** `_extends` diikuti lalu disingkirkan; game menerima hasil yang tergabung penuh, tak pernah kunci `_extends` itu sendiri.

## Dari mana sebuah skema berasal

Set bidang yang bisa diisi preset (**skema**-nya) punya tiga sumber, semua memakai tipe bidang yang sama di atas:

- **Game marketplace**: skema berasal dari manifest penulis game, diambil saat kamu membuka editor. Kamu menimpa preset game tapi tak mengubah skemanya.
- **Game kustom**: kamu mendefinisikan skema sendiri di dasbor, lalu menulis preset terhadapnya. Lihat [game kustom](/docs/game-customization/custom-games).
- **Shell widget (white-label)**: skema bawaan yang tetap. Kamu menimpa presetnya; set bidang tak dideklarasikan-penulis. Lihat [white-label widget](/docs/widget-customization/white-label).

## Preset dan penyelesaian

Dalam sebuah sumbu, bidang dikelompokkan menjadi preset bernama, dan server menyelesaikan satu preset efektif per kelompok dari cakupan berlapis, kunci situs di atas tim di atas default bawaan, dihitung per nilai. Selektor berbeda per sumbu: locale dipilih oleh bahasa peramban pengunjung, skin oleh preferensi terang atau gelap pengunjung (preset yang mode-nya `any` layak untuk salah satu), dan konfigurasi server-otoritatif (pengunjung tak bisa memilihnya). Lihat [ikhtisar](/docs/game-customization/overview#troop-and-site-key-scope) untuk model cakupan.

## Lihat juga

- [Ikhtisar kustomisasi game](/docs/game-customization/overview): mendaftarkan dan mengelola game, plus how-to per-sumbu untuk [konfigurasi](/docs/game-customization/configurations), [bahasa](/docs/game-customization/locale), dan [skin](/docs/game-customization/skin).
- [Skema dasbor game kustom](/docs/custom-game-development/dashboard-schema): menulis sebuah skema sendiri untuk game kustom.
- [Manifest caputchin.json](/docs/marketplace-game-development/the-caputchin-json-manifest): mendeklarasikan blok ini sebagai penulis game marketplace.
- [White-label widget](/docs/widget-customization/white-label): tipe yang sama diterapkan ke shell widget.