기술 참조

브라우저 게임용 PlayDrop 클라이언트 SDK

모든 PlayDrop 게임에서 쓸 수 있는 선택형 브라우저 SDK입니다. 스크립트 태그 하나로 호스트 수명 주기, 로그인, 저장, 리더보드, 구매, 광고, 친구, 컨트롤러, 멀티플레이어, 공유 라이브러리를 이용하세요.

PlayDrop SDK는 선택 사항이며, SDK가 없는 게임도 PlayDrop에서 플레이할 수 있습니다. 플레이어 로그인, 저장, 업적과 리더보드, 크레딧 구매, 광고, PlayDrop Chat의 친구와 게임 카드, 공유 링크, 호스트가 관리하는 일시 정지와 오디오, 컨트롤러 입력, 호스팅 멀티플레이어, AI 생성 같은 플랫폼 기능이 필요할 때 추가하세요. PlayDrop Cloud는 SDK를 대신 통합해 주고, PlayDrop Connector를 사용하면 에이전트가 스크립트 태그 하나를 추가합니다.

SDK 추가 및 호스트 수명 주기 준수

html

<script src="https://assets.playdrop.ai/sdk/playdrop.js"></script>
<script type="module">
  const sdk = await playdrop.init();
  // Render the game and prepare input, then:
  sdk.host.ready();
  sdk.host.onPause(() => pauseGame());
  sdk.host.onResume(() => resumeGame());
  sdk.host.onAudioPolicyChange(({ enabled }) => setAudioEnabled(enabled));
</script>

PlayDrop CDN에서 SDK를 로드하세요. 패키지를 설치할 필요가 없습니다. sdk.host.ready()를 호출하기 전에 플레이 가능한 첫 프레임을 렌더링하고 입력을 준비하세요. 호스트가 일시 정지하면 시뮬레이션을 일시 정지하고, 루프가 중복되지 않도록 재개하며, 호스트 오디오 정책을 따르세요.

신원, 저장 및 언어

sdk.me는 플레이어 신원을 제공하고 sdk.me.appData는 비공개 저장 데이터를 보관합니다. sdk.achievements와 sdk.leaderboards는 업적과 점수를 처리합니다. 저장, 업적, 리더보드는 로그인 사전 확인 없이 작동합니다. 구매나 멀티플레이어처럼 실제 계정이 필요한 기능에는 sdk.me.isLoggedIn을 사용하세요. 미리보기 및 캡처 모드에서는 플레이어 진행 상황을 기록해서는 안 됩니다. sdk.host.language은 플레이어의 언어를 제공합니다. 영어를 기본으로 제공하고, 본인의 언어가 다르다면 그 언어도 함께 제공하세요. 등록 정보를 번역해도 게임 콘텐츠는 번역되지 않습니다. 승리 직후처럼 자연스럽게 쉬는 순간에 sdk.host.requestReview()를 호출하면 PlayDrop이 플레이어에게 리뷰를 요청합니다(게임당 최대 1회). 게임은 답변을 알 수 없으므로 리뷰에 보상을 걸지 마세요.

라이브러리, 에셋 및 멀티플레이어

sdk.libs는 지원되는 버전의 Three.js, Phaser, Rapier, nipplejs 및 Colyseus를 로드합니다. sdk.assets는 카탈로그, 팩 및 에셋 참조를 제공하고, sdk.social은 친구, 게임 카드 및 공유 기능을 제공합니다. 호스팅 멀티플레이어에서는 sdk.multiplayer.getConnection()이 서버 주소와 로그인한 플레이어의 토큰을 반환하므로, Colyseus 클라이언트로 참여하세요. 호스팅 서버는 서버 SDK 페이지에서 다룹니다. 직접 운영하는 서버에는 SDK가 전혀 필요하지 않습니다. 이전 릴레이 룸 API는 폐기되었습니다.

게시 전에 SDK로 테스트하기

평소처럼 개발 서버를 실행하고 Chrome에서 https://www.playdrop.ai/creators/<username>/apps/game/<slug>/dev?url=http://localhost:5173/를 열면, SDK 호스트가 포함된 실제 PlayDrop 프레임 안에서 게임을 플레이할 수 있습니다. localhost 포트나 https URL이라면 무엇이든 사용할 수 있습니다. 저장이나 구매처럼 계정이 필요한 기능은 게임을 한 번 업로드한 뒤부터 작동하며, 비공개 업로드로도 충분합니다. 브라우저 미디어 생성은 호스트가 확인한 크레딧 비용과 함께 비동기 작업으로 실행됩니다. 등록 정보 메타데이터는 catalogue.json을 참고하세요.

함께 플레이하기

플레이 중 await sdk.multiplayer.join("game")를 사용하면 개별적으로 방에 참가하거나 호스트의 파티 예약을 사용합니다. 파티 참가가 실패하면 플레이어를 다른 방으로 나누지 않고 요청을 거부합니다. 기존 게임은 getConnection()으로 계속 연결 정보를 즉시 받을 수 있습니다. 라운드 사이에도 같은 방을 유지하고, 호스트 화면이 게임 입력을 일시 중지해도 네트워크 연결을 유지하세요.

플레이어 동작에서 sdk.social.openParty()를 호출하면 호스트의 파티 창이 열립니다. await sdk.social.getParty() 또는 sdk.social.onPartyChange(callback)으로 구성원을 확인하세요. 게임은 플랫폼 파티를 변경하거나 마이크를 제어할 수 없습니다. 음성은 웹 또는 네이티브 호스트에서 관리하며 동의, 음소거, 차단 및 제공 대상 조건을 따릅니다.

부드러운 공간 음성을 위해 유한한 { x, y, z } 벡터로 sdk.multiplayer.voice.updateSpatialState({ listener: { position, forward, up }, speakers: [{ userId, position }] })을 호출하세요. 힌트는 음량과 스테레오 위치에만 영향을 주며 권한에는 영향을 주지 않습니다. 팀과 거리 조건은 서버가 적용합니다.

선택된 로컬 컨트롤러 슬롯 { playerIndex, gamepadKey }은 sdk.device.localPlayers와 sdk.device.onLocalPlayersChange(callback)으로 확인하세요. 연결된 컨트롤러 목록은 별도이며 연결이 끊긴 슬롯도 식별 정보를 유지합니다. 로컬 모드는 온라인 방에 참가할 수 없습니다. 복사 가능한 playdrop-metagame/recipes/play-together 예제는 두 모드, 두 목적지 및 방 정책을 보여 줍니다.

컨트롤러

물리 컨트롤러와 PlayDrop 휴대폰 컨트롤러는 모든 플랫폼에서 동일하게 sdk.device로 읽습니다. init() 후에 enableControllerInput()을 한 번 호출하고, 게임 루프에서 gamepad(playerIndex)를 읽으며(0이 P1), 버튼 누름과 놓음에는 onButton을 사용하세요. 축과 버튼은 브라우저의 표준 게임패드 순서를 따릅니다. 버튼에는 south, east 같은 위치 이름이 있으며, pad.label("south")는 해당 컨트롤러의 표시 이름(예: "A" 또는 "Cross")을 반환합니다. 메뉴 버튼은 PlayDrop이 사용하며 게임을 일시 정지합니다.

await sdk.device.enableControllerInput();
const stop = sdk.device.onButton(({ playerIndex, button, pressed }) => {
  if (button === "south" && pressed) jump(playerIndex);
});
function update() {
  const pad = sdk.device.gamepad(0);
  if (pad?.connected) move(pad.axes[0], pad.axes[1]);
  requestAnimationFrame(update);
}
update();

휴대폰 컨트롤러는 SDK를 통해서만 게임에 전달되고, 게임이 브라우저 API를 직접 읽으면 PlayDrop이 경고를 기록하므로 navigator.getGamepads()를 호출하지 마세요. 호스트가 컨트롤러 입력을 제공할 수 없으면 enableControllerInput()은 controller_input_unavailable 또는 controller_input_timeout으로 거부되고 게임은 계속 실행됩니다. pad.has("dpad")로 조작 장치가 있는지 확인할 수 있습니다. 게임에 필요한 조작 장치는 catalogue.json에 선언하세요.