# Kompatibilitas SDK

Ada tiga nomor versi, dan masing-masing menjawab pertanyaan yang berbeda.

| Nomor                          | Di mana                      | Menjawab                                   |
| ------------------------------ | ---------------------------- | ------------------------------------------ |
| Versi SDK platform             | `SDK_VERSION` di host-shell  | Kemampuan apa yang tersedia saat ini?      |
| Versi SDK game                 | ikut ter-bundle di `main.js` | Game ini dibangun dengan SDK yang mana?    |
| Rentang `sdk` di `ralyoo.json` | ditulis developer game       | Platform mana saja yang boleh memuat game? |

## Aturan

1. **Mayor = kontrak pesan.** Game dan platform bicara lewat pesan (`ToGame`/`FromGame`). Selama mayornya sama, arti pesan yang ada tidak pernah berubah dan tidak ada pesan yang dihapus.
2. **Minor hanya menambah.** API baru selalu opsional. Kedua sisi **mengabaikan** tipe pesan yang tidak dikenalnya, jadi:
   - game 1.0 di platform 1.3 jalan persis seperti dulu;
   - game 1.3 di platform 1.0 tetap jalan, hanya fitur barunya tidak berefek.
3. **Game menyatakan kebutuhannya.** Game yang _membutuhkan_ fitur minor tertentu menulis batas bawahnya: `"sdk": ">=1.1 <2"`. Game yang hanya memakai API 1.0 cukup `">=1 <2"`.
4. **Diperiksa dua kali.** Registry menolak unggahan yang rentangnya tidak memuat versi SDK platform. Host-shell memeriksa lagi sebelum memasang game, dan menampilkannya sebagai "butuh versi Ralyoo yang lebih baru" kalau tidak cocok.
5. **Mayor baru tidak mematikan game lama.** Saat mayor 2 terbit, platform tetap menyajikan runtime mayor 1 untuk bundel yang rentangnya `<2`. Bundel lama tidak perlu dibangun ulang.
6. **Deprekasi.** API yang akan dihapus ditandai `@deprecated` minimal satu minor sebelum mayor berikutnya, dan dicatat di CHANGELOG.

## Yang termasuk kontrak

- Semua yang diekspor `@ralyoo/sdk`, `@ralyoo/sdk/governor`, `@ralyoo/sdk/testing`, `@ralyoo/sdk/vite`, `@ralyoo/sdk/manifest`, `@ralyoo/sdk/bundle`, `@ralyoo/sdk/widgets`.
- Bentuk `ralyoo.json` (`MANIFEST_SCHEMA`). Field yang tidak dikenal hanya jadi peringatan, supaya manifest untuk SDK baru tetap terbaca SDK lama.
- Format bundel dan aturan sandbox (lihat dokumentasi developer, bab Bundel).
- Pustaka bersama di `/vendor` (`@ralyoo/sdk/vendor`). Menaikkan mayor salah satu pustaka adalah perubahan mayor SDK; versi lama tetap disajikan di URL lamanya (immutable).

## Yang bukan kontrak

`@ralyoo/sdk/platform` dipakai host-shell dan Ralystudioo. Bentuknya boleh berubah di minor mana pun; game tidak boleh mengimpornya.

## Cara menaikkan versi

1. Ubah `version` di `packages/sdk/package.json` dan `SDK_VERSION` di `src/version.ts` (tes gagal kalau berbeda).
2. Tulis CHANGELOG: Ditambahkan, Diubah, Dihapus, plus bagian Kompatibilitas.
3. Perubahan pesan: tambahkan tipe baru, jangan ubah yang ada. Tes `sdk.test.ts` punya kasus game 1.0 terhadap platform sekarang; biarkan hijau.