---
type: reference
title: 게임 SDK 레퍼런스
summary: 게임 작성자가 상대로 쓰는 완전한 @caputchin/game-sdk 표면, register 함수, 푸시 전용 브리지, 라운드별 컨텍스트, 그리고 프리셋 타입.
---

`@caputchin/game-sdk`는 게임 작성자가 상대로 쓰는 계약입니다: `register` 헬퍼, 푸시 전용 `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` | 호스트로의 푸시 전용 채널([브리지](#the-bridge) 참고). 게임은 위로 내보냅니다; 구독하지 않습니다. 팩토리가 호출되는 것이 시작 신호입니다. |
| `ctx` | 라운드별 [컨텍스트](#the-context)(시드에 해소된 프리셋). 위젯이 검증된 세션 밖에서 게임을 돌릴 수 있으니 타입에서 선택적입니다. |
| return | 위젯이 당신의 게임을 언마운트하면 호출하는 선택적 정리 함수. |

## 브리지 [#the-bridge]

브리지는 푸시 전용입니다: 게임은 호스트에 이벤트를 보고하고 결코 듣지 않습니다. 그 멤버:

| 멤버 | 모양 | 효과 |
|---|---|---|
| `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`, 에 당신의 평탄화된 텍스트 키. 당신의 매니페스트가 `locales` 블록을 내지 않으면 `null`. |
| `skin` | 해소된 스킨: `_theme`에 당신의 평탄화된 색상/자산 키, 자산 URL은 이미 절대적. `_theme`은 늘 스킨이 해소된 구체적 모드, `light` 또는 `dark`(결코 `any` 아님)이니, 테마 불가지론 프리셋이 방문자의 실제 모드를 보고합니다. `skins` 블록이 없으면 `null`. |
| `config` | 해소된 구성: 당신의 평탄화된 타입 지정 스칼라. `configurations` 블록이 없으면 `null`. |

대응하는 매니페스트 블록이 없을 때 각각 `null`이니, 늘 내장 대체를 제공하세요.

## 프리셋 타입

SDK는 타입 확인과 함께 `caputchin.json`(그리고 분할된 `.caputchin/` 파일)을 작성하기 위한 TypeScript 타입을 export합니다. 이것들은 [매니페스트](/docs/marketplace-game-development/the-caputchin-json-manifest) 블록을 비춥니다:

| 타입 | 설명하는 것 |
|---|---|
| `GameManifest` | 전체 `caputchin.json`. 작성자 + 색인기 진실 소스; 브라우저에서 결코 읽히지 않음. |
| `LocalePreset` / `ResolvedLocale` | 선언된 로케일 프리셋 / 게임이 받는 해소된 객체. |
| `SkinPreset` / `ResolvedSkin` / `SkinSchemaEntry` / `SkinValueType` | 스킨 프리셋, 해소된 스킨, 그리고 키별 타입 스키마. |
| `ConfigPreset` / `ResolvedConfig` / `ConfigSchemaEntry` / `ConfigValueType` | 구성 프리셋, 해소된 구성, 그리고 키별 타입 스키마. |
| `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): 컨텍스트가 해소하는 프리셋 선언하기.