Referensi game SDK

@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. Untuk manifest yang mendeklarasikan preset yang dimunculkan SDK ini, lihat Manifest caputchin.json.

`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.

register(factory: GameFactory): void

Game factory

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). Game memancar ke atas; ia tak berlangganan. Factory yang dipanggil adalah sinyal mulai.
`ctx`	Konteks 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

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` 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

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

Bidang	Makna
`seed`	Seed putar-ulang per-ronde (sebuah `Seed` 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:

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:

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: tutorial yang memakai permukaan ini.
Kontrak putar-ulang: Seed, trace, dan vonis yang dirujuk jembatan dan konteks.
Manifest caputchin.json: mendeklarasikan preset yang diselesaikan konteks.