# AI 앱에서 간단한 HTML 게임 게시하기

upload_game으로 10 MiB 이하의 독립 실행형 HTML 파일 하나를 게시하세요. 적합한 게임, 미니 카탈로그, 공개 범위, 업데이트, 패키지로 바꿀 때를 다룹니다.

Source: https://www.playdrop.ai/ko/create/learn/html-games

간단한 방식은 캔버스 아케이드 게임이나 DOM 퍼즐 같은 표준 HTML 게임 하나를 `upload_game` 호출 한 번으로 게시합니다. PlayDrop SDK, 빌드 폴더, 추가 파일이 필요 없으며, 누구나 휴대폰이나 컴퓨터에서 열 수 있는 링크를 반환합니다.

## 간단한 방식이 맞는 경우

- 게임 전체가 최대 10 MiB(UTF-8 기준 10,485,760바이트)의 HTML 파일 하나이며, 스크립트, 스타일, 이미지, 사운드가 파일 안에 들어 있습니다.
- 일반 브라우저 게임입니다. PlayDrop SDK를 호출하지 않으므로 클라우드 저장, 순위표, 업적, 공유, 파티, 구매, 광고가 없습니다.
- 별도 파일이 필요 없습니다. 등록 정보 이미지나 동영상, 게임 서버가 없습니다.

하나라도 해당하지 않으면 대신 [패키지](https://www.playdrop.ai/ko/create/learn/packaging)를 사용하세요. 사용자가 요청한 기능은 유지하세요. 이 방식에 맞추려고 기능을 빼거나 여러 파일로 된 게임을 한 파일로 합치지 마세요. 업로드는 SDK 호출, 서버 코드, 패키지 전용 카탈로그 필드를 `advanced_upload_required`로 거부합니다.

## 게임 보내기

새 `requestId`, 완전한 HTML, 게임 하나에 대한 미니 카탈로그를 넣어 `upload_game`을 호출하세요.

```json
{
  "requestId": "moon-jump-first-upload",
  "html": "<!doctype html><html><head><meta charset=\"utf-8\"><title>Moon Jump</title></head><body>…</body></html>",
  "catalogue": {
    "apps": [{
      "name": "moon-jump",
      "displayName": "Moon Jump",
      "description": "Jump between lunar platforms and reach the flag.",
      "controls": "Tap or press Space to jump.",
      "tags": ["game-genre/casual"],
      "types": ["solo"],
      "controller": { "support": "off" },
      "authMode": "NONE",
      "primarySurface": "MOBILE_PORTRAIT"
    }]
  }
}
```

- `name`은 게임의 영구 슬러그입니다. 소문자, 숫자, 하이픈으로 1~100자입니다.
- `tags`에는 `game-genre/casual` 같은 장르가 반드시 있어야 합니다. [장르와 태그](https://www.playdrop.ai/ko/create/learn/tags)를 참고하세요.
- `types`는 플레이 방식을 선언합니다. 파일 하나로 된 게임은 보통 `["solo"]`입니다. 파티 인원과 온라인 플레이는 패키지에서 다룹니다.
- `controller.support`는 `off`를 포함해 실제 컨트롤러 지원 여부를 나타냅니다.
- `authMode`는 로그인 방식을 정합니다. `NONE`이나 `OPTIONAL`이면 누구나 플레이할 수 있고, 빼면 기본값 `REQUIRED`가 됩니다. 업데이트할 때마다 넣으세요.
- `primarySurface`는 게임이 맞춰 설계된 화면 방향을 지정합니다. 간단한 업로드는 데스크톱, 가로, 세로 화면 모두에 등록됩니다.

이 밖에 받는 필드는 `subtitle`, `emoji`, `color`, `license`, `creation`, `releaseNotes`, `inspirationPrompt`, `makingOf`, `sourceRepository`, `sourceLocale`, `offlineSupported`, `instant`입니다. 버전 번호는 PlayDrop이 정합니다.

## 플레이할 수 있는 사람 고르기

- `visibility`를 빼면 새 게임은 크리에이터의 계정 설정을 따릅니다(일부 공개나 비공개를 고르지 않았다면 공개). 업데이트는 게임의 현재 공개 대상을 유지합니다.
- `"private"`은 테스트용으로 크리에이터만 열 수 있는 버전을 저장합니다. 나중에 그 버전 그대로 `publish_game_version`으로 게시하고, 다시 업로드하지 마세요.
- `"unlisted"`는 목록에 올리지 않고 링크가 있는 누구에게나 게시하며, `"public"`은 발견될 수 있도록 게시합니다.

사용자가 요청한 대로 따르고, 의도한 것보다 더 넓게 게임을 공개하지 마세요. [누가 플레이할 수 있는지](https://www.playdrop.ai/ko/create/learn/distribution)를 참고하세요.

## 업로드 결과 읽기

업로드 결과에는 `gameId`, `slug`, `version`, `status`, `visibility`, 그리고 소유자용 해당 버전 링크인 `url`이 들어 있습니다. 공개 및 일부 공개 게임은 게임의 영구 페이지인 `shareUrl`도 받으며, 이 링크를 사용자에게 전달하세요. 비공개 버전이면 `url`을 전달하세요. `instant`와 `instantReason`은 [인스턴트](https://www.playdrop.ai/ko/create/learn/instant-games) 자격 여부를 알려 줍니다.

## 게임 업데이트하기

`list_games`를 호출하고 게임의 `gameId`를 넘기며 `name`은 그대로 두세요. 완전한 HTML과 완전한 미니 카탈로그를 다시 보내세요. 업로드할 때마다 전체 스냅샷이 올라가며, 빠뜨린 필드는 새 버전에서 사라집니다. 링크는 그대로 유지됩니다. 처음에 패키지로 업로드한 게임은 파일과 기능이 빠지지 않도록 계속 패키지 방식을 사용해야 합니다.

## 나중에 패키지로 바꾸기

클라우드 저장, 순위표, 등록 정보 아트, 서버를 추가하면 게임은 패키지가 됩니다. 같은 게임의 일반적인 업데이트일 뿐입니다. `name`을 유지하고, `prepare_catalogue_upload`로 업로드하며, `expectedCurrentVersion`을 `list_games`의 현재 버전으로 설정하세요. [패키징](https://www.playdrop.ai/ko/create/learn/packaging)을 읽어 보세요.

## 관련 가이드

- [AI 앱에서 게시하기](https://www.playdrop.ai/ko/create/learn/mcp-publishing): AI 에이전트가 MCP로 PlayDrop에 게시하는 방법: 간단한 방식과 패키지 방식, 비공개 테스트, publish_game_version, 업데이트, 제한, 복구.
- [패키징과 .play](https://www.playdrop.ai/ko/create/learn/packaging): catalogue.json을 루트에 둔 빌드 폴더, ZIP 또는 .play를 구성하고, 등록 정보 미디어와 서버를 선언한 뒤 prepare_catalogue_upload로 업로드하세요.
- [공개 범위와 노출](https://www.playdrop.ai/ko/create/learn/distribution): PlayDrop 게임을 열 수 있는 대상을 고르고, 계정 기본값과 버전 게시가 어떻게 작동하는지, 부스트, 플레이 교환, 인스턴트, 검색이 새 플레이어를 어떻게 데려오는지 알아보세요.