KKOISCORE DEVELOPERS포털로 이동

PLAYER SANDBOX / NO PRODUCTION WRITE

올리기 전에 실행하세요.

개발 PC IP와 포트만 입력하면 게임 URL·HTTPS 터널·포털 미리보기까지 자동으로 연결됩니다. 이 페이지는 게임 등록·젬·정산·라이브 상태를 변경하지 않습니다.

PREVIEW / ISOLATED

포털 조건 미리보기

KOISCORE에 등록하기 전에 “우리 게임이 포털 iframe 안에서 정말 동작할까?”를 확인하려면 플레이어 샌드박스를 쓰면 됩니다. 이 페이지는 운영 koiscore.com 위에서 돌아가지만, 게임 런타임은 개발 PC의 localhost 또는 Quick Tunnel HTTPS URL을 iframe으로 불러옵니다. 등록·젬·정산·live 상태는 전혀 바꾸지 않으며, 모든 테스트 API는 /api/sandbox/*로 분리되어 있습니다. 즉, 샌드박스에서 아무리 젬을 바꿔도 실제 사용자 지갑이나 베타·live 매출 데이터에는 영향이 없습니다.

운영 HTTPS 페이지에서 로컬 게임을 보려면 브라우저 mixed-content 정책 때문에 “localhost를 직접 iframe src로 넣기”가 불가능합니다. 그래서 개발 PC에서 Cloudflare Quick Tunnel 같은 에이전트를 잠깐 켜 임시 https://*.trycloudflare.com 주소를 만들고, 아래 UI에 IP·포트를 입력해 샌드박스 실행을 누르면 터널 URL이 자동으로 연결됩니다. 터널 프로세스를 끄면 URL도 닫히므로, QA가 끝난 뒤에는 반드시 에이전트를 종료하세요.

운영 HTTPS(koiscore.com)에서 로컬 게임을 보려면 개발 PC에서 터널 에이전트를 한 번 실행해야 합니다. IP만 입력하고 샌드박스 실행을 누르면 임시 HTTPS 주소가 자동으로 연결됩니다.
샌드박스 API(/api/sandbox)만 사용하며 운영 계정·출시 데이터와 분리됩니다. 코이젬은 샌드박스에서만 숫자 클릭으로 바꿀 수 있으며 정식·베타 서비스에는 절대 노출되지 않습니다.
화면
채널
멀티플레이 계정계정마다 별도 프로필·playerId·채팅 작성자를 사용합니다.
로그인 상태샌드박스 세션 확인 중
프로필 · 젬
?
젬 버튼을 누르면 숫자 입력창이 뜹니다. 포털 미리보기에서도 젬을 누르면 바로 바꿀 수 있습니다.
가짜 상품 · 결제 API 테스트

젬 잔액은 위에서 바로 수정하세요. 여기는 게임/서버가 쓰는 가짜 SKU·order·confirm 흐름 검증용입니다.GET /api/sandbox/gems/products → POST …/orders → POST …/payments/toss/confirm

IP 입력 후 샌드박스 실행을 누르면 포털이 새 탭에서 열립니다. 화면(9:16 / 16:9)은 포털과 동일하게 적용됩니다.

LOCAL / WORKFLOW

직접 배포 없이 확인하기

터미널에서 샌드박스 CLI를 쓰면 위 UI와 같은 미리보기를 한 번에 열 수 있습니다. 게임 dev server(Vite·webpack-dev-server 등)를 먼저 띄운 뒤, 아래 명령을 실행하면 Quick Tunnel URL 발급 → 개발자센터 샌드박스 탭 자동 오픈 → 포털 프레임에 게임 embed까지 이어집니다. --game-id는 실제 등록 예정 id와 맞추면 portal:init의 gameId·테스트 SKU prefix·채팅 room namespace가 출시 후와 동일하게 동작해 디버깅이 쉬워집니다.

npm exec --yes --package=https://koiscore.com/tools/koiscore-sandbox-cli.tgz -- \
  koiscore-sandbox --port 5173 --game-id your-game

위 한 줄을 실행한 뒤에는 (1) 터널 URL이 살아 있는지, (2) 포털 미리보기 iframe에 게임이 100% 채워지는지, (3) 음소거·언어·로그인 테스트 계정 전환이 portal:init/postMessage로 반영되는지 순서대로 확인하세요. CLI를 종료하면 터널과 미리보기가 함께 끊깁니다. 운영 API 키·관리자 토큰·프로덕션 DB가 붙은 백엔드를 터널로 노출하면 안 됩니다. 게임 정적 파일 + 샌드박스 API만 노출되는지 팀 규칙으로 막아 두세요.

  1. 게임 개발 서버를 http://localhost:5173처럼 실행합니다.
  2. 위 명령을 실행하면 임시 https://랜덤주소.trycloudflare.com이 발급됩니다.
  3. 개발자센터가 자동으로 열리고 해당 게임 URL로 미리보기가 시작됩니다.
  4. 모바일·데스크톱, 웹·앱, 언어와 음소거를 바꾸며 확인합니다.
  5. 검수를 통과한 뒤에만 draft 등록과 스테이징 배포를 진행합니다.

MCP로 미리보기 URL 받기

Cursor·Codex 등에 KOISCORE MCP를 연결해 두었다면, UI 클릭 대신 build_sandbox_preview 도구로 같은 포털 미리보기 URL을 받을 수 있습니다. 에이전트에게 “localhost:5173 터널 URL로 샌드박스 미리보기 만들어줘”라고 시키면 runtimeUrl과 portalPreviewUrl이 JSON으로 돌아옵니다. CI에서 headless로 프레임만 확인할 때도 이 도구를 쓰되, 발급된 MCP 토큰은 secret store에만 두세요.

MCP 자동등록 문서에서 게임 수정·상품 SKU·샌드박스 미리보기 도구 목록과 호출 예시를 확인하세요.

로컬 API 연결

샌드박스 iframe 안의 게임이 KOISCORE API를 부르면, 실제 운영 /api/profile가 아니라 현재 호스트의 /api/sandbox가 portal:init.api.baseUrl 및 koiscoreApiBase로 주입됩니다. 테스트 로그인·프로필·identity assertion·채팅·가짜 젬 지갑은 모두 이 prefix 아래 ephemeral 데이터입니다. 서버를 재시작하거나 샌드박스 세션을 리셋하면 사라지며, draft 등록·베타·live 사용자 기록으로 복사·승격되지 않습니다. 운영 JWT·JWKS를 샌드박스에서 검증 테스트하려면 별도 staging 환경을 쓰세요.

identity.avatarUrl과 player.avatarUrl은 iframe에서 바로 쓸 수 있는 절대 HTTPS URL로 내려옵니다. 샌드박스 프로필 사진을 올리면 /api/sandbox/profile/avatar/… 경로가 생기고, 없으면 운영과 동일한 공통 더미 이미지가 사용됩니다. 게임 UI는 이 URL을 영구 식별자로 저장하지 말고 표시용 캐시만 허용하세요.

멀티플레이 계정 A/B 검수

로비·매치방·DM이 “두 명이 실제로 다른 사용자로 보이는지” 확인하려면 샌드박스를 브라우저 탭 두 개로 열고 각각 다른 테스트 계정을 선택하면 됩니다. 운영 Google 계정 두 개를 쓸 필요 없이, 샌드박스 전용 계정 A/계정 B 프로필이 서로 다른 profileId와 게임별 playerId를 받습니다. 채팅 작성자 이름·차단·신고도 이 id 기준으로 분리되므로, 멀티플레이 버그가 게임 서버 문제인지 포털 커뮤니티 문제인지 빠르게 가릴 수 있습니다.

  1. 첫 번째 탭에서 계정 A와 테스트 로그인을 선택하고 포털 미리보기를 엽니다.
  2. 두 번째 탭에서 계정 B와 테스트 로그인을 선택해 같은 게임과 room ID를 엽니다.
  3. 두 계정은 서로 다른 profileId와 게임별 playerId를 받으며 채팅 작성자도 분리됩니다.
  4. lobby와 매치별 인스턴스방을 각각 확인합니다. 이 데이터는 서버 재시작 시 삭제되고 운영으로 이전되지 않습니다.
Quick Tunnel은 개발 전용이며 CLI를 종료하면 함께 닫힙니다. 비밀키·운영 DB·관리 API가 포함된 서버를 터널로 노출하면 안 됩니다. KOISCORE 저장소 내부 개발만 npm run sandbox:lan을 사용하며 실제 런칭 URL과 운영 API는 HTTPS 검수 단계에서 별도로 연결합니다.

샌드박스까지 통과했으면 다음 단계는 immutable HTTPS URL 배포 → 콘솔 draft 등록 → 베타 URL 공유입니다. Googlebot이 크롤링하기 좋은 텍스트는 베타 플레이 페이지가 아니라 배포·베타 가이드, 브릿지 문서, SEO 가이드, 게임별 /games/guide/… 페이지에 쌓입니다. 샌드박스 UI 자체도 이 설명 섹션과 함께 index 대상이므로, 팀 내부 wiki 대신 공개 문서 URL을 QA 온보딩 링크로 공유해도 됩니다.