---
type: reference
title: Referensi game SDK
summary: Permukaan @caputchin/game-sdk lengkap yang menjadi dasar penulisan penulis game, fungsi register, jembatan push-only, konteks per-ronde, dan tipe preset.
---

`@caputchin/game-sdk` adalah kontrak yang menjadi dasar penulisan penulis game: sebuah helper `register`, sebuah `Bridge` push-only, `GameContext` per-ronde, dan tipe TypeScript untuk blok preset manifest. Ia diterbitkan terpisah dari widget menghadap-pengguna agar game tak pernah secara transitif membundel runtime widget. Game milik sendiri memakai API publik yang sama ini; tak ada kontrak privat.

Untuk build terpandu, lihat [Bangun game marketplace](/docs/marketplace-game-development/build-a-marketplace-game). Untuk manifest yang mendeklarasikan preset yang dimunculkan SDK ini, lihat [Manifest caputchin.json](/docs/marketplace-game-development/the-caputchin-json-manifest).

## `register(factory)`

Titik masuk pendaftaran tunggal. Lewatkan game factory-mu; kamu **tak** melewatkan manifest (server membaca `caputchin.json` saat-indeks dan mengirim preset terselesaikan ke bawah sebagai konteks factory). Mendaftarkan dua kali mencatat peringatan konsol dan tulisan terakhir menang; tak ada penegakan platform.

```ts
register(factory: GameFactory): void
```

## Game factory

```ts
type GameFactory = (
  container: HTMLElement,
  bridge: Bridge,
  ctx?: GameContext,
) => (() => void) | void
```

| Parameter | Makna |
|---|---|
| `container` | Sebuah elemen di dalam iframe ber-sandbox game. Render di sini. Gaya tercakup secara alami, iframe adalah dokumennya sendiri. |
| `bridge` | Kanal push-only ke host (lihat [Jembatan](#the-bridge)). Game memancar ke atas; ia tak berlangganan. Factory yang dipanggil adalah sinyal mulai. |
| `ctx` | [Konteks](#the-context) per-ronde (seed plus preset terselesaikan). Opsional dalam tipe karena widget bisa menjalankan game di luar sesi terverifikasi. |
| return | Fungsi pembersihan opsional yang dipanggil widget jika ia melepas game-mu. |

## Jembatan [#the-bridge]

Jembatan adalah push-only: game melaporkan event ke host dan tak pernah mendengarkan. Anggotanya:

| Anggota | Bentuk | Efek |
|---|---|---|
| `pass` | `pass(result: { trace: string }): void` | Menandakan ronde **lolos**, menyerahkan host `trace` opaque. Server menjalankan-ulang [`run`](/docs/marketplace-game-development/replay-contract) game di bawah seed yang diterbitkan untuk menghitung vonis otoritatif, jadi game **tak** melaporkan skor di sini. Panggilan pertama melepaskan verifikasi yang ditahan dan mengunci token; panggilan berikutnya diabaikan. |
| `error` | `error(err: { code: string; message?: string }): void` | Game itu sendiri gagal (muatan aset, eksepsi internal). Memunculkan event `error` ke pengguna. Berbeda dari pemain kalah, yang ditandakan dengan tak memanggil apa pun. |
| `setSize` | `setSize(width: number, height: number): void` | Mengubah ukuran iframe secara eksplisit agar cocok konten. Panggil setelah cat pertama; widget juga mengukur-otomatis anak pertama game, jadi kebanyakan game tak pernah butuh ini. |
| `layout` | `readonly layout: 'inline' \| 'modal' \| 'fullscreen' \| null` | Presentasi terselesaikan yang game jalankan di bawahnya, atau `null` saat tak diketahui. |

Sengaja tak ada `complete`, tak ada pendengar `start`, tak ada metode `unmount` (kembalikan fungsi pembersihan sebagai gantinya), dan tak ada sinyal kegagalan di luar keheningan.

## Konteks [#the-context]

```ts
interface GameContext {
  seed:   Seed          | null
  locale: ResolvedLocale | null
  skin:   ResolvedSkin   | null
  config: ResolvedConfig | null
}
```

| Bidang | Makna |
|---|---|
| `seed` | Seed putar-ulang per-ronde (sebuah [`Seed`](/docs/marketplace-game-development/replay-contract) dari kontrak putar-ulang). Semai semua keacakan game darinya. `null` saat game berjalan di luar sesi terverifikasi. |
| `locale` | Objek bahasa terselesaikan: `_lang` (BCP-47), `_direction`, plus kunci teks-mu yang diratakan. `null` jika manifest-mu tak mengirim blok `locales`. |
| `skin` | Skin terselesaikan: `_theme` plus kunci warna/aset-mu yang diratakan, URL aset sudah absolut. `_theme` selalu mode konkret yang skin diselesaikan untuknya, `light` atau `dark` (tak pernah `any`), jadi preset agnostik-tema melaporkan mode aktual pengunjung. `null` jika tak ada blok `skins`. |
| `config` | Konfigurasi terselesaikan: skalar bertipe-mu yang diratakan. `null` jika tak ada blok `configurations`. |

Masing-masing `null` saat blok manifest yang sesuai absen, jadi selalu sediakan cadangan bawaan.

## Tipe preset

SDK mengekspor tipe TypeScript untuk menulis `caputchin.json` (dan berkas split `.caputchin/`) dengan pemeriksaan-tipe. Ini mencerminkan blok [manifest](/docs/marketplace-game-development/the-caputchin-json-manifest):

| Tipe | Mendeskripsikan |
|---|---|
| `GameManifest` | Seluruh `caputchin.json`. Sumber kebenaran penulis + pengindeks; tak pernah dibaca di peramban. |
| `LocalePreset` / `ResolvedLocale` | Preset locale yang dideklarasikan / objek terselesaikan yang diterima game. |
| `SkinPreset` / `ResolvedSkin` / `SkinSchemaEntry` / `SkinValueType` | Preset skin, skin terselesaikan, dan skema tipe per-kunci. |
| `ConfigPreset` / `ResolvedConfig` / `ConfigSchemaEntry` / `ConfigValueType` | Preset konfigurasi, config terselesaikan, dan skema tipe per-kunci. |
| `LocalesFile` / `SkinsFile` / `ConfigurationsFile` | Objek tingkat-atas tiap berkas split `.caputchin/<axis>.json`. |
| `MarketplaceMetadata` / `PreferredPresentation` | Blok `marketplace` dan petunjuk jejak `preferred`. |

Tulis sebuah berkas split dengan impor `satisfies` agar kompiler memeriksanya:

```ts
import type { LocalesFile } from "@caputchin/game-sdk";
export default { schema: { /* ... */ }, presets: { /* ... */ } } satisfies LocalesFile;
```

## Apa yang sengaja absen

- Tak ada `sessionId` atau pengenal platform yang mencapai game.
- Tak ada hook siklus-hidup `start` / `pause` / `resume`; panggilan factory adalah mulai.
- Tak ada `maxScore` atau rentang skor platform; skor vonis adalah apa pun yang dikembalikan `run`-mu.

Kontrak sengaja mungil agar ia tetap stabil lintas tahun pertumbuhan katalog.

## Lihat juga

- [Bangun game marketplace](/docs/marketplace-game-development/build-a-marketplace-game): tutorial yang memakai permukaan ini.
- [Kontrak putar-ulang](/docs/marketplace-game-development/replay-contract): `Seed`, trace, dan vonis yang dirujuk jembatan dan konteks.
- [Manifest caputchin.json](/docs/marketplace-game-development/the-caputchin-json-manifest): mendeklarasikan preset yang diselesaikan konteks.