---
type: reference
title: caputchin.json 매니페스트
summary: 마켓플레이스 게임을 설명하는 caputchin.json 매니페스트의 모든 필드, marketplace 블록, 배포 포인터, 리플레이 run 산출물, 프리셋 블록, 그리고 .caputchin 분할 파일.
---

당신의 저장소 루트의 `caputchin.json`은 마켓플레이스 게임의 작성자이자 색인기 진실 소스입니다. 색인기는 게임의 정체성, 그 번들이 어디 사는지, 어떤 프리셋을 제공하는지, 어떻게 리플레이하는지를 알려고 서버 측에서 그것을 읽습니다. 그것은 브라우저에서 **결코** 읽히지 않습니다; SDK는 런타임에 그것을 로드하지 않습니다.

이 페이지는 필드 레퍼런스입니다. 빌드는 [마켓플레이스 게임 빌드하기](/docs/marketplace-game-development/build-a-marketplace-game)를; 공개는 [마켓플레이스에 공개하기](/docs/marketplace-game-development/publish-to-the-marketplace)를 보세요. 정확한 타입은 SDK에서 `GameManifest`로 export됩니다([SDK 레퍼런스](/docs/marketplace-game-development/game-sdk-reference)를 보세요).

## 최소 단일 게임

```json
{
  "terms_accepted": true,
  "license": "MIT",
  "marketplace": {
    "name": "Leaf Memory",
    "description": "Match pairs of tropical leaves before the timer runs out.",
    "preview": "preview.png"
  },
  "npm": "@your-org/leaf-memory",
  "entry": "dist/leaf-memory.js"
}
```

## 최상위 필드

| 필드 | 필수 | 목적 |
|---|---|---|
| `terms_accepted` | 색인에 | [마켓플레이스 제출 약관](/legal/submission-terms)을 받아들임을 확인하려면 리터럴 `true`여야 함. 다른 어떤 값(또는 없음)도 매니페스트를 색인에서 떨굼. 자체 호스팅 전용 매니페스트는 생략 가능. |
| `license` | 색인에 | 당신의 코드와 번들된 자산을 덮는 SPDX 식별자나 표현식. 승인된 식별자로 평가되어야 함([공개 오류 레퍼런스](/docs/marketplace-game-development/publish-failed-reference#approved-licenses)를 보세요). |
| `marketplace` | 색인에 | 존재가 "나를 색인하라" 신호임. 없으면 마켓플레이스가 무시하는 유효한 [자체 호스팅](/docs/custom-game-development/overview) 게임. [marketplace 블록](#the-marketplace-block)을 보세요. |
| `npm` | `entry`와 함께 | 색인기가 jsDelivr URL로 해소하는 npm 패키지 좌표. |
| `entry` | `npm`과 함께 | 빌드된 번들로의 저장소 상대 경로. 실행 가능한 게임에는 `entry`, `npm`, 또는 둘 다가 있어야 함. |
| `games` | 컬렉션에 | 컬렉션 래퍼를 위한 서브 매니페스트 경로. `entry` / `npm`과 상호 배타적. [컬렉션](#collections)을 보세요. |
| `run` | 선택 | 전용 헤드리스 리플레이 산출물. [run 산출물](#the-run-artifact)을 보세요. |
| `preferred` | 선택 | 호스트가 존중할 수 있는 표현 힌트. [preferred 블록](#the-preferred-block)을 보세요. |
| `locales` / `skins` / `configurations` | 선택 | iframe에서 SDK가 소비하는 프리셋 블록. [프리셋 블록](#preset-blocks)을 보세요. |

`version` 필드는 없습니다: 색인기가 직접 번들을 불변 ref에 고정합니다(공개된 npm 버전이나 해소된 커밋 SHA).

## marketplace 블록 [#the-marketplace-block]

| 필드 | 목적 |
|---|---|
| `name` | 카드 제목. 저장소 이름(단일 / 래퍼)이나 leaf-dir 이름(컬렉션 자식)으로 물러남. |
| `description` | 카드 부제와 상세 페이지 본문. |
| `preview` | 이미지 경로(저장소 루트 상대) 또는 절대 URL. 약 600x315, 대상 중앙. |
| `version` | 상세 페이지용 표시 전용 버전 문자열. 선택. |
| `support` | 작성자가 선언한 호환성 플래그(`responsive`, `touch`, `accessible`, `audio`, ...), 플랫폼이 결코 검증하지 않음; 필터와 카드 아이콘으로 드러남. |
| `author` | 선택적 `{ name?, url?, email? }`. `name` / `url`은 상세 페이지에 작성자 표기로 렌더링됨; `email`은 결코 보이지 않고 [공개 실패 이메일](/docs/marketplace-game-development/publish-to-the-marketplace#get-notified-when-a-publish-fails)의 **옵트인**임. 세 하위 필드 모두 독립적. |

이 블록은 완전히 선택입니다. `name` / `url`을 생략하면 상세 페이지가 그저 작성자 표기를 보이지 않습니다(페이지의 다른 곳에 보이는 GitHub 소유자는 별도의, 늘 있는 정체성이지, 이 표기의 대체가 아닙니다). `email`을 생략하면 공개 실패 알림을 받지 못합니다. 원하는 하위 필드만 설정하세요.

## 배포 포인터

색인기는 저장된 무결성 해시가 유효하게 유지되도록 각 게임의 번들을 불변 ref에 고정하고, 모든 실행에서 다시 해소합니다(일일 cron에 수동 "Publish or update"):

- `entry` + `npm`은 `cdn.jsdelivr.net/npm/<npm>@<resolved-version>/<entry>`로 해소됩니다.
- `entry`만은 `cdn.jsdelivr.net/gh/<owner>/<repo>@<commit-sha>/<entry>`로 해소됩니다.
- `npm`만은 고정된 버전의 패키지 기본 엔트리로 해소됩니다.

사용자 측 버전 고정은 없습니다; 빌드를 동결하려면, 사용자가 위젯의 `game-src`로 그것을 자체 호스팅합니다([커스텀 게임](/docs/custom-game-development/self-hosted-game)).

## run 산출물 [#the-run-artifact]

기본적으로 리플레이 자체 확인은 당신의 라이브 `entry` 번들을 돌립니다. 당신의 게임이 크거나 프레임워크 또는 WASM 기반일 때, 대신 전용 가벼운 헤드리스 `run` 산출물을 내세요:

```json
{
  "run": {
    "entry": "dist/run.js",
    "modules": [
      { "name": "sim.wasm", "type": "wasm", "path": "dist/sim.wasm" }
    ]
  }
}
```

| 필드 | 의미 |
|---|---|
| `run.entry` | 헤드리스 `run` 번들로의 저장소 상대 경로([리플레이 계약](/docs/marketplace-game-development/replay-contract) `run` export). |
| `run.modules` | run이 `name`으로 임포트하는 모듈 엔트리의 선택적 배열. |

### 색인기가 강제하는 제약

이것들은 색인 시점에 검증됩니다; 위반은 `manifest-error`로 공개를 실패시킵니다([공개 오류 레퍼런스](/docs/marketplace-game-development/publish-failed-reference)를 보세요).

**`run.entry`:**

- **JavaScript**여야 함: basename이 `[a-zA-Z0-9_-]+.js`와 일치해야 함. run 산출물은 늘 JS임(WASM은 모듈로 나옴, 아래).
- 깨끗한 저장소 상대 경로여야 함: 선행 슬래시 없음, `..` 순회 없음, 공백 없음, `?` / `#` 없음, `scheme://` 접두사 없음.

**각 `run.modules[]` 엔트리**는 `{ name, type, path }`임:

- `name`은 `[a-zA-Z0-9_-]+.(wasm|js)`와 일치해야 함, 모듈은 **JS 또는 WASM**, 그 밖의 어떤 것도 아님. `name`은 엔트리가 쓰는 임포트 지정자임.
- `type`은 확장자와 일치해야 함: `.wasm` 이름에는 `wasm`, `.js` 이름에는 `js`.
- `name`은 리플레이 호스트가 내부적으로 쓰는 **예약된** 이름(`entry.js`, `artifact.js`)이 아니어야 함.
- `name`은 배열 안에서 **고유**해야 함(중복 없음).
- `path`는 깨끗한 저장소 상대 경로여야 함(`run.entry`와 같은 규칙).
- 최대 **16**개 모듈.

라이브 `entry`를 직접 리플레이하려면 `run`을 생략하세요. 산출물이 무엇을 export해야 하는지는 [리플레이 계약](/docs/marketplace-game-development/replay-contract)을 보세요.

## preferred 블록 [#the-preferred-block]

선택적 `preferred` 블록은 표현 힌트를 지닙니다. 모든 키는 권고입니다: 호스트가 그것을 존중할 수 있고, 그것은 결코 명시적 임베드 속성을 재정의하지 않습니다.

```json
{
  "preferred": { "width": 360, "height": 480, "layout": "modal" }
}
```

기본적으로 컨테이너를 가득 채워야 하는 반응형 게임은 어느 축에든 `"full"`을 선언할 수 있습니다:

```json
{
  "preferred": { "width": "full", "height": 480 }
}
```

| 필드 | 의미 |
|---|---|
| `width` / `height` | 픽셀 풋프린트, 또는 리터럴 `"full"`. 임베드가 `width` / `height`를 설정하지 않은 채 두면 위젯이 그것을 적용함(`full`을 포함한 명시적 임베드 값이 대신 이김). 픽셀 값은 iframe을 그 수로 크기 조정함; `"full"`은 그 축을 부모를 채우도록 늘림, 임베드 `width="full"`이 가지는 같은 효과. 위젯의 내장 기본 풋프린트로 물러나려면 생략. |
| `layout` | 위젯이 게임 둘레에 짓는 셸: `inline`, `modal`, 또는 `fullscreen`. 임베드가 `layout`을 설정하지 않은 채 둘 때만 쓰임(그 기본값 `auto`). 해소 순서: 임베드의 `layout` 속성, 그다음 이 preferred layout, 그다음 `inline`. |

이 힌트는 플랫폼이 서버 측에서 해소하는 게임(마켓플레이스 게임, 또는 사이트 키 없이 주어진 게임 id)에만 존중됩니다. 플랫폼이 마운트 전에 읽을 수 없는 자체 호스팅 `game-src` 번들은 풋프린트와 layout 힌트를 둘 다 무시합니다.

## 프리셋 블록 [#preset-blocks]

`locales`, `skins`, `configurations`는 각각 선택적 `schema`(키별 타입과 문서)에 더해 `presets`(이름 붙은 옵션 뱅크)를 선언합니다. 위젯은 방문자의 선택을 이것들을 상대로 해소하고 평탄화된 결과를 [`ctx`](/docs/marketplace-game-development/game-sdk-reference)로 당신의 게임에 건넵니다. 전체 필드 타입 카탈로그는 공유된 [맞춤화 스키마 레퍼런스](/docs/references/customization-schema)입니다; 같은 타입이 [커스텀 게임의 대시보드 스키마](/docs/custom-game-development/dashboard-schema)를 움직입니다.

`skins.schema` 필드는 `color`, 자산(`image` / `audio` / `video`), 또는 `configurations`와 같은 제약 형태를 쓰는 스칼라(`boolean`, `number`, `range`, `list`)일 수 있습니다(`{ "type": "range", "min": 0, "max": 24 }`, `["dots","stripes"]` 등). 스칼라 스킨 값은 구성 값과 정확히 똑같이 `ctx.skin`에서 그 타입 지정 값으로 해소됩니다(`number`는 진짜 숫자); 색상과 자산 값은 문자열로 해소됩니다.

스킨 프리셋의 `_theme`은 그것이 동작하는 모드를 선언합니다: `light`, `dark`, 또는 `any`(생략하면 `any`). `light`나 `dark` 프리셋은 그 모드에서만 보입니다; `any` 프리셋은 어느 배경에서든 읽히고 둘 다에 자격이 있습니다. 모드당 하나의 기본값이 있습니다. `_default: true`로 표시된 프리셋은 자격 있는 모드(들)의 기본값이니, `any` 기본값은 둘 다를 덮습니다; 한 모드에 여러 자격 있는 프리셋이 기본값으로 플래그되면, 선언 순서상 첫째가 그것을 이깁니다. 모드별 프리셋을 `any` 위에 나열해 그 모드에 전용 스킨을 주고 `any` 프리셋이 다른 모드로 떨어지게 하세요.

## `.caputchin/` 분할 파일

프리셋 블록(특히 전체 로케일 묶음)은 `caputchin.json`을 길게 만듭니다. 어떤 축이든 `.caputchin/` 폴더 아래 자기 파일로 옮겨, 매니페스트를 짧게 두세요:

```
caputchin.json
.caputchin/locales.json
.caputchin/skins.json
.caputchin/configurations.json
```

각 파일의 최상위 객체가 **곧** 그 축 블록입니다(`{ schema?, presets }`). 셋 다 선택입니다. 우선순위는 축 전체 대체, `caputchin.json`이 이깁니다: 한 축이 인라인과 파일 둘 다로 선언되면, 인라인 블록이 쓰이고 파일이 무시됩니다(그것이 죽었음을 알도록 공개가 경고합니다). 각 축을 정확히 한 곳에 두세요.

## 컬렉션 [#collections]

저장소는 여러 게임을 낼 수 있습니다. 컬렉션 래퍼는 `entry` / `npm` 대신 자식 경로를 선언합니다:

```json
{
  "marketplace": { "name": "Caputchin Core Pack", "description": "The official pack." },
  "games": ["./packages/leaf-memory", "./packages/dino-runner"]
}
```

각 경로는 자기 자신의 `caputchin.json`을 든 자식 디렉터리를 가리킵니다. 자식 id는 `owner/repo/<leaf-dir>`입니다. 컬렉션 페이지 없이 자식을 색인하려면 래퍼의 `marketplace` 블록을 생략하세요.

## 함께 보기

- [마켓플레이스 게임 빌드하기](/docs/marketplace-game-development/build-a-marketplace-game): 이 매니페스트가 가리키는 번들 만들기.
- [리플레이 계약](/docs/marketplace-game-development/replay-contract): `run` 산출물이 무엇을 export해야 하는지.
- [공개 오류 레퍼런스](/docs/marketplace-game-development/publish-failed-reference): 모든 매니페스트 검증 오류와 승인된 라이선스 목록.
- [맞춤화 스키마 레퍼런스](/docs/references/customization-schema): 프리셋 블록이 쓰는 필드 타입.