첫 게임을 등록하세요.

01 / PREPARE

등록 전에 준비할 것

KOISCORE에 게임을 올리기 전에 “일단 URL만 넣고 나중에 메타데이터 채우기”는 권장하지 않습니다. 검수 큐에서는 런타임 URL·gameId·다국어 제목·썸네일·화면 비율이 한 세트로 보이며, 중간에 gameId를 바꾸면 identity·영수증·머천트 링크까지 모두 다시 맞춰야 합니다. 아래 항목은 콘솔 초안 등록 폼과 MCP register_game_draft에 공통으로 들어가는 최소 준비물입니다. 커뮤니티는 기본 로비만 쓸지, 매치별 인스턴스방까지 필요한지 미리 정해 두면 브릿지·운영 승인 범위를 줄일 수 있습니다.

• 변경하지 않을 kebab-case 게임 ID와 공개 HTTPS 런타임 URL
• 한국어·영어·일본어 제목, 장르, 지원 언어, 정사각형 대표 이미지
• 데스크톱 16:9와 모바일 9:16에서 동작하는 반응형 화면
• 젬 상품이 있다면 서버 지급 키, 젬 가격, 멱등 처리 방식
• 커뮤니티는 기본 게임 로비만 사용할지, 매치·파티별 인스턴스방이 필요한지 결정

02 / MANIFEST

등록 매니페스트

플랫폼에 게임을 등록하려면 아래 JSON 형태의 매니페스트를 개발자 콘솔 UI에 입력하거나, 발급받은 MCP 토큰으로 API·도구에 전달합니다. 모든 등록은 draft 상태로 시작하며, 운영 검수·베타 기간을 거친 뒤 live로 전환됩니다. runtimeUrl은 반드시 공개 HTTPS여야 하고, 로컬 http://127.0.0.1 주소는 샌드박스 미리보기 전용입니다. products 배열은 젬 상품·구독 SKU를 나중에 추가할 수 있으며, 비어 있어도 초안 등록은 가능합니다.

제목(title)은 ko·en·ja 세 locale 모두 채우는 것이 좋습니다. 포털·앱인토스 셸, sitemap, 게임 가이드 페이지가 이 값을 그대로 사용합니다. desktopAspect와 mobileAspect는 CSS aspect-ratio 힌트이며, 실제 픽셀 크기는 iframe 100% 채우기 정책이 우선합니다.

{
  "gameId": "studio-puzzle",
  "title": { "ko": "스튜디오 퍼즐", "en": "Studio Puzzle", "ja": "スタジオパズル" },
  "genres": ["puzzle", "casual"],
  "runtimeUrl": "https://games.example.com/studio-puzzle",
  "thumbnailUrl": "https://games.example.com/studio-puzzle/icon.webp",
  "locales": ["ko", "ja", "en"],
  "desktopAspect": "16 / 9",
  "mobileAspect": "9 / 16",
  "webBannerEnabled": true,
  "products": []
}

03 / PLAYER

iframe을 실제 크기로 채우기

KOISCORE 플레이어에 웹게임을 정상적으로 임베드하려면, 게임 뷰포트를 “제작 해상도 고정값”이 아니라 “부모 iframe의 실제 너비·높이”로 잡아야 합니다. 포털은 데스크톱·모바일·앱 WebView마다 다른 프레임 크기를 주며, 라운지·광고·키보드 표시에 따라 실행 중에도 크기가 변합니다. html·body·루트 컨테이너를 100%로 맞추고 overflow: hidden으로 내부 스크롤을 막은 뒤, 캔버스나 WebGL surface는 ResizeObserver로 다시 레이아웃하는 패턴을 권장합니다.

아래 CSS는 대부분의 2D·3D WebGL 게임에 공통으로 적용할 수 있는 최소 예시입니다. touch-action: none은 모바일에서 페이지 스크롤과 게임 드래그가 충돌하지 않게 합니다. 게임 타이틀·공용 젬 잔액·광고는 KOISCORE 호스트 셸이 그리므로 iframe 안에 동일 UI를 중복 배치하지 마세요.

html, body, #game-root {
  width: 100%;
  height: 100%;
  margin: 0;
  overflow: hidden;
}

canvas {
  display: block;
  width: 100%;
  height: 100%;
  touch-action: none;
}

03B / SAVE DATA

진행 저장은 Platform Player API

세이브·스테이지·점수를 플랫폼에 올릴 때는 등록 gameId로 공통 API만 호출합니다. 게임별 progress URL을 새로 만들지 않습니다. 게스트가 Google로 연결하면 같은 player_id로 데이터가 유지되므로, portal:player-update 수신 후 progress를 다시 읽으면 됩니다.

<script src="https://koiscore.com/portal/koiscore-platform-player-client.js"></script>
<script>
KoiscorePlatformPlayer.configure({ gameId: 'your-registered-game-id' });

KoiscorePlatformPlayer.startSessionSync({
  onChange: async ({ progress }) => {
    if (progress?.ok) loadSave(progress.progress, progress.version);
  },
});

const { progress } = await KoiscorePlatformPlayer.loadState();
if (progress?.ok) loadSave(progress.progress, progress.version);
</script>

계약 상세 · API 레퍼런스 · 샌드박스에서 먼저 검증

채널별 차이

“웹이냐 앱인토스냐”에 따라 게임 런타임 URL·postMessage 계약·identity 형식은 동일합니다. 달라지는 것은 주로 광고 어댑터와 스토어 결제 경로뿐입니다. 즉, 한 번 올바르게 연동해 두면 채널 추가는 플랫폼 설정 문제에 가깝고, 게임 코드를 채널마다 fork할 필요는 없습니다. 아래 표는 검수·기획 미팅에서 자주 나오는 비교 항목을 정리한 것입니다.

즉, 게임 연동 방식은 동일하고 실행 채널이 선택하는 광고 어댑터만 달라집니다. 앱인토스에서는 웹 광고 슬롯을 숨기고 Apps in Toss 광고만 호출합니다.

04 / REVIEW

검수와 출시

초안 등록과 브릿지 연결까지 끝났다면, 운영 검수 전에 스스로 아래 체크리스트를 한 번 돌리는 것을 권장합니다. KOISCORE 검수는 “게임이 재미있는지”보다 “플레이어 셸·결제·로그인·프레임 정책을 어기지 않았는지”에 가깝습니다. 특히 390×844·360×800 모바일 뷰포트에서 내부 스크롤이 생기거나, 음소거 토글이 게임 BGM에 반영되지 않거나, 영수증 멱등성이 없으면 반려 사유로 바로 돌아옵니다.

1. 등록 데이터와 상품 매니페스트를 검증합니다.
2. 390×844, 360×800, 1366×768, 1920×1080 뷰포트를 확인합니다.
3. 언어, 음소거, 포털 메시지, 로비·인스턴스 채팅 요청, 지갑 영수증과 중복 지급 방지를 확인합니다.
4. 설정된 유효 플레이타임·세션 조건을 충족하면 승인하거나 운영자가 강제 출시합니다.