게임 SDK 레퍼런스

@caputchin/game-sdk는 게임 작성자가 상대로 쓰는 계약입니다: register 헬퍼, 푸시 전용 Bridge, 라운드별 GameContext, 그리고 매니페스트의 프리셋 블록을 위한 TypeScript 타입. 그것은 사용자를 향한 위젯과 별도로 공개되니, 게임이 결코 전이적으로 위젯 런타임을 번들하지 않습니다. 자사 게임도 이 같은 공개 API를 씁니다; 비공개 계약은 없습니다.

안내된 빌드는 마켓플레이스 게임 빌드하기를 보세요. 이 SDK가 드러내는 프리셋을 선언하는 매니페스트는 caputchin.json 매니페스트를 보세요.

`register(factory)`

단일 등록 진입점. 당신의 게임 팩토리를 넘기세요; 당신은 매니페스트를 넘기지 않습니다(서버가 색인 시점에 caputchin.json을 읽고 해소된 프리셋을 팩토리의 컨텍스트로 내려보냅니다). 두 번 등록하면 콘솔 경고를 기록하고 마지막 쓰기가 이깁니다; 플랫폼 강제는 없습니다.

register(factory: GameFactory): void

게임 팩토리

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

파라미터	의미
`container`	게임의 샌드박스된 iframe 안의 요소. 여기 렌더링하세요. 스타일은 자연히 범위가 지정됩니다, iframe이 자기 자신의 문서입니다.
`bridge`	호스트로의 푸시 전용 채널(브리지 참고). 게임은 위로 내보냅니다; 구독하지 않습니다. 팩토리가 호출되는 것이 시작 신호입니다.
`ctx`	라운드별 컨텍스트(시드에 해소된 프리셋). 위젯이 검증된 세션 밖에서 게임을 돌릴 수 있으니 타입에서 선택적입니다.
return	위젯이 당신의 게임을 언마운트하면 호출하는 선택적 정리 함수.

브리지

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

멤버	모양	효과
`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 타입을 export합니다. 이것들은 매니페스트 블록을 비춥니다:

타입	설명하는 것
`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 매니페스트: 컨텍스트가 해소하는 프리셋 선언하기.