catalogue.json: PlayDrop 게임 메타데이터 및 현지화
PlayDrop Connector 형식의 게임 제목, 설명, 장르 태그, 등록 정보 이미지와 동영상, 번역 및 선택형 server 필드에 대한 레퍼런스입니다.
PlayDrop Connector는 catalogue.json 메타데이터를 게임 파일과 함께 전송하므로 명령줄 도구는 필요하지 않습니다. Studio 게임의 메타데이터는 PlayDrop Cloud에서 관리합니다.
prepare_catalogue_upload로 완전한 비공개 업로드
{
"requestId": "my-game-v1-unique-request",
"catalogue": {
"apps": [
{
"name": "my-game",
"displayName": "My Game",
"file": "index.html",
"version": "1.0.0",
"visibility": "PRIVATE",
"authMode": "OPTIONAL",
"surfaceTargets": {
"desktop": true,
"mobileLandscape": false,
"mobilePortrait": false
}
}
]
},
"expectedCurrentVersion": {
"my-game": null
},
"files": [
{
"path": "index.html",
"text": "<!doctype html><html><head><title>My Game</title></head><body><button onclick=\"this.textContent=Number(this.textContent)+1\">0</button></body></html>"
}
]
}새 비공개 게임을 위한 완전한 prepare_catalogue_upload 요청입니다. 예제 HTML을 빌드된 게임으로 바꾸고 각 업로드에 고유한 requestId를 사용하세요. catalogue 객체는 catalogue.json의 내용입니다. files와 expectedCurrentVersion은 해당 객체 외부의 도구 요청 필드입니다.
apps[].file은 files[].path 중 하나와 정확히 일치해야 합니다. file을 생략하면 기본값은 index.html이 아닌 <name>.html입니다. surfaceTargets는 desktop, mobileLandscape, mobilePortrait 불리언이 있는 객체입니다. 테스트한 화면 환경을 하나 이상 활성화하세요. 버전과 공개 범위를 명시하세요. 예제는 인라인 텍스트를 사용하지만 첨부 파일이나 서명된 업로드에서도 같은 경로를 사용할 수 있습니다.
준비 후 요청된 파일을 전송하고 동일한 requestId로 complete_catalogue_upload를 호출하세요. 비공개 버전을 열어 테스트하세요. 업데이트 시 list_games를 읽고 같은 name, 새로운 version, 전체 스냅샷을 제공하세요. expectedCurrentVersion[name]에는 서버가 반환한 현재 공개 버전을 넣고 없으면 null을 넣으세요. 이 필드는 충돌 확인용이며 업로드할 버전이 아닙니다. 중단된 업로드는 원래 요청 ID로 재개하세요. 준비가 되면 보관된 테스트 버전을 publish_game_version으로 공개하세요.
기존 단일 게임 형식 호환 예제
아래 예시는 기존 단일 게임 형식입니다. 전체 카탈로그는 여러 게임, 에셋, 팩, 명세도 지원하므로 커넥터에 최신 스키마를 요청하세요. 업데이트마다 버전과 공개 범위를 명시한 전체 스냅샷을 보냅니다. 카탈로그에서 생략한 항목은 삭제되지 않습니다.
업데이트할 때는 소문자 슬러그를 그대로 유지하세요. 필요에 따라 표시 제목, 정확한 설명, 조작법, 원본 언어 및 기존 태그를 추가하세요. 아래 예시는 기존 platformer 장르 태그를 사용합니다.
{
"apps": [{
"name": "moon-jump",
"displayName": "Moon Jump",
"description": "Jump between lunar platforms and reach the finish.",
"controls": "Arrow keys to move. Space to jump.",
"sourceLocale": "en",
"tags": ["game-genre/platformer"]
}]
}지원 필드 및 제한
name: 소문자, 숫자 또는 하이픈으로 이루어진 1–100자이며, 문자 또는 숫자로 시작해야 합니다. displayName: 비어 있지 않은 제목. subtitle: 최대 120자. description: H1 제목, 임베드 미디어, 표가 없는 최대 3,000자의 Markdown. inspirationPrompt: 최대 400자의 한 줄 일반 텍스트. 텍스트 제한은 JavaScript UTF-16 코드 단위를 기준으로 계산합니다.
선택 필드로는 controls, releaseNotes, makingOf, emoji, color, sourceRepository, license, tags, sourceLocale, listingLocalizations, listingMedia, server가 있습니다. 태그는 기존 group-slug/tag-slug 참조를 사용하며, 고유 태그는 최대 20개까지 지정할 수 있습니다. server에는 업로드한 server.js의 Colyseus 룸을 "server": { "rooms": ["game"] }처럼 나열합니다. 서버 SDK를 참고하세요. 게시하기 전에 현재 허용되는 라이선스 값과 전체 필드 규칙을 커넥터에 요청하세요. 네이티브 앱용 선택 힌트: prefetch에는 iOS, macOS, Android용 PlayDrop 앱이 플레이 전에 다운로드할 수 있는 업로드 파일을 "prefetch": { "required": ["game.js"], "optional": ["music.mp3"] }처럼 나열합니다(시작 페이지는 항상 포함됩니다). "offlineSupported": true를 지정하면 필수 파일이 저장된 뒤 이 앱들이 게임을 오프라인으로 제공할 수 있습니다. 잘못된 값은 무시되며 업로드를 막지 않습니다. 웹사이트에서는 평소처럼 게임을 불러옵니다.
인스턴트 게임: 시작 파일(시작 페이지와 prefetch.required, 목록이 없으면 업로드한 모든 파일)이 10 MB 이하이고 2초 안에 플레이할 수 있으면 "instant": true를 지정하세요. 인스턴트 게임에는 번개 배지가 붙고 PlayDrop 휴대폰 앱의 인스턴트 피드에서 플레이됩니다. 추가 레벨과 부가 콘텐츠는 prefetch.optional에 넣고, 셰이더 컴파일 등 준비 작업은 ready() 호출 전에 끝내고, 미리보기에는 타이틀 화면이 아닌 게임플레이를 보여 주고, 게스트를 허용(authMode OPTIONAL 또는 NONE)해 모두가 피드에서 게임을 볼 수 있게 하세요. PlayDrop은 업로드할 때 크기를 확인하고 휴대폰에서 느리게 시작되는 버전의 배지를 제거합니다. 기준에 못 미치는 게임도 게시는 됩니다.
등록 정보 이미지 및 동영상
등록 정보 미디어는 index.html 옆에 경로로 이름을 지정한 파일로 업로드하세요. 아트에 게임 제목을 넣은 listing/icon.png, listing/hero-landscape.png(16:9), listing/hero-portrait.png(9:16), 그리고 listing/screenshots/landscape/0.png 같은 스크린샷과 동영상 listing/videos/landscape/0.mp4(트레일러), listing/videos/portrait/0.mp4(모바일 티저)를 올릴 수 있습니다. 동영상은 게임 카드와 게임 페이지에서 소리 없이 재생되며, 트레일러는 컴퓨터와 TV에서, 티저는 휴대폰에서 재생됩니다. 게임플레이를 보여 주고 첫 플레이를 이끌어 내는 가장 빠른 방법입니다. 이미지는 PNG, 동영상은 MP4 형식입니다.
등록 정보를 정확하게 번역하기
영어는 항상 게시하고, 본인의 언어가 다르다면 그 언어도 함께 게시하세요. sourceLocale을 원본 언어로 설정하세요. listingLocalizations는 영어, 프랑스어, 독일어, 스페인어, 브라질 포르투갈어, 인도네시아어, 일본어, 한국어, 번체 중국어, 간체 중국어를 지원합니다. 각 번역에는 locale과 displayName이 필요하며, 원본과 함께 업로드하면 PlayDrop이 sourceHash를 채워 줍니다. 번역된 아트는 listing/locales/<locale>/ 아래에 업로드하세요. 예를 들어 프랑스어 제목이 들어간 listing/locales/fr/hero-landscape.png는 해당 번역과 자동으로 연결됩니다. 원본이 변경되면 번역을 갱신하세요. 등록 정보를 번역해도 게임 자체는 번역되지 않습니다.
플레이어, 파티 및 컨트롤러
각 게임 항목에서 types, party, controller, roomVoice로 게임 플레이 방식을 선언하세요.
{
"types": ["solo", "online", "party"],
"party": { "local": [1, 2, 3, 4], "online": [1, 2, 3, 4] },
"controller": { "support": "optional", "type": "simpler" },
"roomVoice": true
}types에는 solo(혼자 플레이 가능), online(네트워크로 다른 사람과 플레이), party(그룹이 함께 플레이)를 조합합니다. party.local은 한 화면에서 플레이할 수 있는 정확한 인원수이고, party.online은 함께 온라인에 입장할 수 있는 친구 그룹 크기(최대 4명)이며 방 정원이 아닙니다. 인원수는 정확히 일치해야 하므로 [2, 4]는 3명을 포함하지 않습니다. party에는 party 유형, party.online에는 online이 필요하며, party.local에 1이 있으면 solo도 필요합니다. roomVoice: true는 방 음성을 켜며 online이 필요합니다.
controller.support는 off(controller를 생략했을 때의 기본값), optional, required 중 하나입니다. off가 아니면 controller.type에 게임에 필요한 최소 조작 장치를 지정합니다.
any: 방향, 확인, 취소. 리모컨을 포함한 모든 컨트롤러로 플레이할 수 있습니다.simpler: 아날로그 스틱 1개, 페이스 버튼 4개, 메뉴. PlayDrop 휴대폰 컨트롤러와 표준 게임패드가 해당됩니다.standard: 방향 패드, 누를 수 있는 스틱 2개, 페이스 버튼 4개, 숄더 버튼 2개, 트리거 2개, 메뉴.custom: 게임 전용 휴대폰 조작용으로 예약되어 있으며 아직 사용할 수 없습니다.
컨트롤러 지원을 켜면 선언한 모든 로컬 인원수를 컨트롤러로 플레이할 수 있어야 합니다. 컨트롤러 입력은 SDK로 읽으세요. 기존 게임은 players와 controllerMode를 계속 사용할 수 있지만 새 게임은 이 필드를 사용하며, 한 항목에서 두 방식을 섞을 수 없습니다. 호스트는 로컬 또는 온라인 중 하나만 선택합니다. 선언은 Cloud, CLI, MCP 업로드, 보관된 비공개 버전 및 게시 후에도 유지됩니다. 사용 가능 여부는 플랫폼 제공 범위와 호스트 버전에도 달려 있습니다.
MCP 서버 업로드에는 빌드된 ESM .mjs/.js 번들을 SERVER 설명자로 제공하고 server.entry로 지정하세요. Cloud/CLI 소스 프로젝트는 TypeScript 진입점을 유지합니다. PlayDrop이 Colyseus와 서버 SDK 런타임을 제공하며, 게임에 음성 공급자 인증 정보를 포함하면 안 됩니다.