게임에 친구를 초대하세요.

1. HTML에서 불러오기

index.html에서 게임 코드보다 먼저 불러옵니다. 아래 두 예약 경로는 업로드 후 플랫폼이 제공합니다. 공개 URL과 게임 ID만 포함되며 비밀키를 넣지 않습니다.

<script src="./platform-config.js"></script>
<script src="./platform-network.js"></script>
<script src="./game.js"></script>

game.json에 "network": "play-v1"을 지정하세요. 로컬 게임 폴더만 열어서는 예약 경로를 사용할 수 없으므로 업로드 미리보기에서 확인하세요.

2. 모임 만들기와 초대

아래는 모임 생성 부분의 예시입니다. 네트워크 오류는 게임 UI에 표시하고, 반환된 토큰은 URL이나 채팅에 노출하지 마세요.

try {
  const member = await PlatformNetwork.request(
    "lobbies", "POST", { nickname: "푸른기사" }
  );
  const inviteUrl = PlatformNetwork.invite(member.lobbyId);
  // inviteUrl을 게임의 초대 UI에 표시합니다.
  // member.token은 본인 요청에만 사용합니다.
} catch (error) {
  // error.message를 오류 UI에 표시합니다.
}

입장은 lobbies/모임ID/join에 POST, 모임 상태는 lobbies/모임ID/poll에 GET으로 요청합니다. 상태 조회에는 네 번째 인자로 회원 토큰을 전달합니다. 연결 루프와 경기 상태 교환의 전체 예시는 ZIP의 lobby.js와 multiplayer.js를 참고하세요. 토큰은 메모리에만 보관하세요.

3. 배정된 경기 연결하기

모임 poll 응답의 assignment로 연결합니다. 동일 matchId에는 한 번만 만들고, 경기가 바뀌거나 나갈 때 close()를 호출하세요.

const rtcConfig = await PlatformNetwork.request("config");
const connection = PlatformNetwork.createConnection({
  room: assignment.id,
  token: assignment.token,
  role: assignment.role, // host 또는 guest
  rtcConfig,
  onopen: () => showConnected(),
  onmessage: data => applyGameMessage(data),
  ondisconnect: () => pauseGame(),
  onerror: error => showError(error.message),
});
connection.start();
connection.send({ type: "input", unit: 0, x: 300, y: 450 });
// 종료 시: connection.close();

send()는 전송 가능 여부를 반환합니다. 입력 확인·재전송과 스냅샷 순서는 게임이 관리합니다. SDK는 끊어진 전송을 최대 30초 재시도하며, 양방향 응답을 확인한 뒤 게임을 재개하세요.

관전은 signal 콜백으로 모임 signal API를 연결하고 receiveSignal()에 수신 신호를 전달합니다. channelOptions로 비순차·재전송 없는 관전 채널을 선택할 수 있습니다. 예제 ZIP에 전체 구현이 포함되어 있습니다.

4. 제공 API

연동 전 확인할 점

• 운영 환경의 멀티플레이는 게시 승인 후 사용할 수 있습니다. 승인 전에는 싱글·AI 흐름을 확인하세요.
• 게임 파일은 상대 경로를 사용하세요. 외부 스크립트·임의 API·서비스 워커는 현재 실행 정책으로 제한됩니다.
• Supabase 서비스 키와 TURN 공유 비밀키를 게임 파일에 넣지 마세요. TURN 임시 인증정보는 모임 인증 후 서버에서 발급합니다.
• 결제, 공식 랭킹, 호스트 이전, 페이지 새로고침 후 경기 복원은 현재 SDK에 포함되지 않습니다.

계정 프로필과 개인 기록

게시된 게임은 실행 화면이 준비되면 로그인 회원의 라이브러리에 자동 등록됩니다. SDK로 로그인 토큰을 전달받지 않고 게임별 닉네임과 설정을 저장할 수 있습니다.

const state = await PlatformStorage.init();
if (state.mode === 'account') {
  const saved = await PlatformStorage.saveProfile({
    nickname: 'Knight',
    settings: { sound: false },
    revision: state.profile.revision,
  });
  state.profile = saved.profile;
}

게스트 설정은 게임에서 로컬로 보관하고 미리보기는 계정에 저장하지 않습니다. SAVE_CONFLICT는 다른 기기에서 프로필을 바꾼 경우이며 load()로 최신 내용을 확인한 뒤 충돌을 해결하세요. 범용 진행도 저장 슬롯과 검증된 랭킹은 아직 제공하지 않습니다.