---
type: reference
title: Справочник игрового SDK
summary: Полная поверхность @caputchin/game-sdk, против которой пишет автор игры, функция register, push-only мост, пер-раундовый контекст и типы пресетов.
---

`@caputchin/game-sdk` это контракт, против которого пишет автор игры: хелпер `register`, push-only `Bridge`, пер-раундовый `GameContext` и типы TypeScript для блоков пресетов манифеста. Он публикуется отдельно от обращённого к пользователю виджета, так что игры никогда транзитивно не встраивают рантайм виджета. Собственные игры используют тот же публичный API; приватного контракта нет.

Для руководимого построения смотри [Построй игру для маркетплейса](/docs/marketplace-game-development/build-a-marketplace-game). Для манифеста, который объявляет пресеты, выводимые этим SDK, смотри [Манифест caputchin.json](/docs/marketplace-game-development/the-caputchin-json-manifest).

## `register(factory)`

Единственная точка входа регистрации. Передай свою игровую фабрику; ты **не** передаёшь манифест (сервер читает `caputchin.json` во время индексации и шлёт разрешённые пресеты вниз как контекст фабрики). Регистрация дважды логирует предупреждение в консоль, и побеждает последняя запись; платформенного принуждения нет.

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

## Игровая фабрика

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

| Параметр | Значение |
|---|---|
| `container` | Элемент внутри iframe игры в песочнице. Рендери сюда. Стиль естественно ограничен, iframe это свой собственный документ. |
| `bridge` | Push-only канал к хосту (смотри [Мост](#the-bridge)). Игра испускает вверх; она не подписывается. Вызванная фабрика и есть сигнал старта. |
| `ctx` | Пер-раундовый [контекст](#the-context) (сид плюс разрешённые пресеты). Опционален в типе, потому что виджет может запустить игру вне проверенной сессии. |
| return | Опциональная функция очистки, которую виджет вызывает, если размонтирует твою игру. |

## Мост [#the-bridge]

Мост push-only: игра отчитывается о событиях хосту и никогда не слушает. Его члены:

| Член | Форма | Эффект |
|---|---|---|
| `pass` | `pass(result: { trace: string }): void` | Сигналит, что раунд **пройден**, вручая хосту непрозрачную `trace`. Сервер перезапускает [`run`](/docs/marketplace-game-development/replay-contract) игры под выданным сидом, чтобы вычислить авторитетный вердикт, так что игра **не** отчитывается о счёте здесь. Первый вызов отпускает удерживаемую проверку и блокирует токен; поздние вызовы игнорируются. |
| `error` | `error(err: { code: string; message?: string }): void` | Сама игра сбоила (загрузка ассета, внутреннее исключение). Всплывает событием `error` пользователю. Отлично от проигрыша игрока, о котором сигналят, не вызывая ничего. |
| `setSize` | `setSize(width: number, height: number): void` | Явно изменить размер iframe под содержимое. Вызови после первой отрисовки; виджет также авто-измеряет первого ребёнка игры, так что большинству игр это никогда не нужно. |
| `layout` | `readonly layout: 'inline' \| 'modal' \| 'fullscreen' \| null` | Разрешённое представление, под которым работает игра, или `null`, когда неизвестно. |

Намеренно нет `complete`, нет слушателя `start`, нет метода `unmount` (возвращай функцию очистки вместо этого) и нет сигнала сбоя помимо молчания.

## Контекст [#the-context]

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

| Поле | Значение |
|---|---|
| `seed` | Пер-раундовый сид реплея ([`Seed`](/docs/marketplace-game-development/replay-contract) из контракта реплея). Засевай всю случайность игры из него. `null`, когда игра работает вне проверенной сессии. |
| `locale` | Разрешённый объект языка: `_lang` (BCP-47), `_direction` плюс твои уплощённые текстовые ключи. `null`, если твой манифест не поставляет блока `locales`. |
| `skin` | Разрешённый скин: `_theme` плюс твои уплощённые ключи цвета/ассета, URL ассетов уже абсолютные. `_theme` всегда конкретный режим, под который разрешён скин, `light` или `dark` (никогда `any`), так что тема-агностичный пресет сообщает реальный режим посетителя. `null`, если нет блока `skins`. |
| `config` | Разрешённая конфигурация: твои уплощённые типизированные скаляры. `null`, если нет блока `configurations`. |

Каждый `null`, когда соответствующий блок манифеста отсутствует, так что всегда предоставляй встроенный откат.

## Типы пресетов

SDK экспортирует типы TypeScript для авторствования `caputchin.json` (и сплит-файлов `.caputchin/`) с проверкой типов. Они зеркалят блоки [манифеста](/docs/marketplace-game-development/the-caputchin-json-manifest):

| Тип | Описывает |
|---|---|
| `GameManifest` | Весь `caputchin.json`. Источник истины автора + индексатора; никогда не читается в браузере. |
| `LocalePreset` / `ResolvedLocale` | Объявленный пресет локали / разрешённый объект, который получает игра. |
| `SkinPreset` / `ResolvedSkin` / `SkinSchemaEntry` / `SkinValueType` | Пресеты скина, разрешённый скин и типовая схема на каждый ключ. |
| `ConfigPreset` / `ResolvedConfig` / `ConfigSchemaEntry` / `ConfigValueType` | Пресеты конфигурации, разрешённый config и типовая схема на каждый ключ. |
| `LocalesFile` / `SkinsFile` / `ConfigurationsFile` | Объект верхнего уровня каждого сплит-файла `.caputchin/<axis>.json`. |
| `MarketplaceMetadata` / `PreferredPresentation` | Блок `marketplace` и подсказка следа `preferred`. |

Авторствуй сплит-файл с импортом `satisfies`, чтобы компилятор его проверял:

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

## Что намеренно отсутствует

- Никакой `sessionId` или платформенные идентификаторы не доходят до игры.
- Нет хуков жизненного цикла `start` / `pause` / `resume`; вызов фабрики это старт.
- Нет `maxScore` или платформенного диапазона счёта; счёт вердикта это то, что возвращает твой `run`.

Контракт намеренно крошечный, чтобы оставаться стабильным сквозь годы роста каталога.

## См. также

- [Построй игру для маркетплейса](/docs/marketplace-game-development/build-a-marketplace-game): руководство, которое использует эту поверхность.
- [Контракт реплея](/docs/marketplace-game-development/replay-contract): `Seed`, трасса и вердикт, на которые ссылаются мост и контекст.
- [Манифест caputchin.json](/docs/marketplace-game-development/the-caputchin-json-manifest): объявление пресетов, которые разрешает контекст.