ゲーム SDK リファレンス

@caputchin/game-sdk は、ゲームの作者が対して書く契約です。register ヘルパー、push 専用の Bridge、ラウンドごとの GameContext、そしてマニフェストのプリセットブロックの TypeScript の型です。ユーザー向けのウィジェットとは別に公開されるので、ゲームは決して推移的にウィジェットのランタイムをバンドルしません。ファーストパーティのゲームもこの同じ公開 API を使います。私的な契約はありません。

ガイド付きの作成はマーケットプレイスゲームを作るを参照してください。この SDK が表に出すプリセットを宣言するマニフェストは caputchin.json マニフェストを参照してください。

`register(factory)`

単一の登録のエントリーポイント。あなたのゲームファクトリーを渡します。マニフェストは渡し ません（サーバーがインデックス時に caputchin.json を読み、解決済みのプリセットをファクトリーのコンテキストとして送り下ろします）。2 回登録するとコンソールの警告がログされ、最後の書き込みが勝ちます。プラットフォームの強制はありません。

register(factory: GameFactory): void

ゲームファクトリー

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

パラメータ	意味
`container`	ゲームのサンドボックス化された iframe の中の要素。ここにレンダリングします。スタイルは自然にスコープづけされます。iframe はそれ自身のドキュメントです。
`bridge`	ホストへの push 専用のチャネル（ブリッジ参照）。ゲームは上向きに発します。購読はしません。ファクトリーが呼ばれることが開始のシグナルです。
`ctx`	ラウンドごとのコンテキスト（シードに加えて解決済みのプリセット）。ウィジェットが検証済みのセッションの外でゲームを走らせ得るので、型では任意です。
return	ウィジェットがあなたのゲームをアンマウントするときに呼ぶ、任意のクリーンアップ関数。

ブリッジ

ブリッジは push 専用です。ゲームはイベントをホストに報告し、決して聞きません。そのメンバー：

メンバー	形	効果
`pass`	`pass(result: { trace: string }): void`	ラウンドが通ったことを知らせ、不透明な `trace` をホストに渡します。サーバーは、権威ある判定を計算するために、発行されたシードのもとでゲームの `run` を再実行するので、ゲームはここでスコアを報告しません。最初の呼び出しが保留中の検証を解放してトークンをロックします。後の呼び出しは無視されます。
`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 メソッド（代わりにクリーンアップ関数を返す）も、沈黙を超える失敗のシグナルもありません。

コンテキスト

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

フィールド	意味
`seed`	ラウンドごとのリプレイのシード（リプレイ契約の `Seed`）。すべてのゲームのランダム性をそれからシードします。ゲームが検証済みのセッションの外で走るときは `null`。
`locale`	解決済みの言語オブジェクト：`_lang`（BCP-47）、`_direction`、に加えてあなたの平坦化されたテキストキー。マニフェストが `locales` ブロックを出荷しないなら `null`。
`skin`	解決済みのスキン：`_theme` に加えてあなたの平坦化された色/アセットのキー、アセットの URL はすでに絶対。`_theme` は常にスキンが解決された具体的なモード、`light` か `dark`（決して `any` ではない）なので、テーマに依存しないプリセットも訪問者の実際のモードを報告します。`skins` ブロックがないなら `null`。
`config`	解決済みの構成：あなたの平坦化された型付きスカラー。`configurations` ブロックがないなら `null`。

対応するマニフェストのブロックが欠けているとき、それぞれが null なので、常に組み込みのフォールバックを与えてください。

プリセットの型

SDK は、型チェックつきで caputchin.json（と分割された .caputchin/ ファイル）を作るための TypeScript の型をエクスポートします。これらはマニフェストのブロックを映します：

型	何を記述するか
`GameManifest`	`caputchin.json` 全体。作者 + インデクサーの真実の源。ブラウザでは決して読まれません。
`LocalePreset` / `ResolvedLocale`	宣言されたロケールのプリセット / ゲームが受け取る解決済みのオブジェクト。
`SkinPreset` / `ResolvedSkin` / `SkinSchemaEntry` / `SkinValueType`	スキンのプリセット、解決済みのスキン、キーごとの型スキーマ。
`ConfigPreset` / `ResolvedConfig` / `ConfigSchemaEntry` / `ConfigValueType`	構成のプリセット、解決済みの構成、キーごとの型スキーマ。
`LocalesFile` / `SkinsFile` / `ConfigurationsFile`	各 `.caputchin/<axis>.json` 分割ファイルのトップレベルのオブジェクト。
`MarketplaceMetadata` / `PreferredPresentation`	`marketplace` ブロックと、`preferred` のフットプリントのヒント。

コンパイラがチェックするよう、satisfies インポートで分割ファイルを作ります：

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

意図的に欠けているもの

sessionId もプラットフォームの識別子もゲームに届きません。
start / pause / resume のライフサイクルのフックはありません。ファクトリーの呼び出しが開始です。
maxScore もプラットフォームのスコア範囲もありません。判定のスコアはあなたの run が返すものです。

契約は意図的に小さく、カタログの何年もの成長にわたって安定したままです。

あわせて読む

マーケットプレイスゲームを作る：この面を使うチュートリアル。
リプレイ契約：ブリッジとコンテキストが指す Seed、トレース、判定。
caputchin.json マニフェスト：コンテキストが解決するプリセットを宣言する。