caputchin.json 매니페스트

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

이 페이지는 필드 레퍼런스입니다. 빌드는 마켓플레이스 게임 빌드하기를; 공개는 마켓플레이스에 공개하기를 보세요. 정확한 타입은 SDK에서 GameManifest로 export됩니다(SDK 레퍼런스를 보세요).

최소 단일 게임

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

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

marketplace 블록

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

이 블록은 완전히 선택입니다. 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로 그것을 자체 호스팅합니다(커스텀 게임).

run 산출물

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

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

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

색인기가 강제하는 제약

이것들은 색인 시점에 검증됩니다; 위반은 manifest-error로 공개를 실패시킵니다(공개 오류 레퍼런스를 보세요).

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해야 하는지는 리플레이 계약을 보세요.

width / height 픽셀 풋프린트, 또는 리터럴 "full". 임베드가 width / height를 설정하지 않은 채 두면 위젯이 그것을 적용함(full을 포함한 명시적 임베드 값이 대신 이김). 픽셀 값은 iframe을 그 수로 크기 조정함; "full"은 그 축을 부모를 채우도록 늘림, 임베드 width="full"이 가지는 같은 효과. 위젯의 내장 기본 풋프린트로 물러나려면 생략.

layout 위젯이 게임 둘레에 짓는 셸: inline, modal, 또는 fullscreen. 임베드가 layout을 설정하지 않은 채 둘 때만 쓰임(그 기본값 auto). 해소 순서: 임베드의 layout 속성, 그다음 이 preferred layout, 그다음 inline.

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

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

프리셋 블록

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

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이 이깁니다: 한 축이 인라인과 파일 둘 다로 선언되면, 인라인 블록이 쓰이고 파일이 무시됩니다(그것이 죽었음을 알도록 공개가 경고합니다). 각 축을 정확히 한 곳에 두세요.

컬렉션

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

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

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

함께 보기

마켓플레이스 게임 빌드하기: 이 매니페스트가 가리키는 번들 만들기.
리플레이 계약: run 산출물이 무엇을 export해야 하는지.
공개 오류 레퍼런스: 모든 매니페스트 검증 오류와 승인된 라이선스 목록.
맞춤화 스키마 레퍼런스: 프리셋 블록이 쓰는 필드 타입.

caputchin.json 매니페스트

이 페이지에서