PlayDrop의 게임 수명 주기: 로딩, 준비, 일시 정지, 오디오

SDK를 로드하고, 초기 상태를 읽고, 변경 사항을 구독하고, 첫 화면을 준비한 다음에야 ready()를 호출하세요. 그때까지 PlayDrop은 로딩 화면을 계속 보여 줍니다.

<script src="https://assets.playdrop.ai/sdk/playdrop.js"></script>
<script type="module">
  const sdk = await playdrop.init();
  let paused = sdk.host.isPaused;
  setAudio(sdk.host.audioAllowed);
  sdk.host.onAudioAllowedChange(setAudio);
  sdk.host.onPause(() => { paused = true; });
  sdk.host.onResume(() => { paused = false; last = performance.now(); });

  try {
    await loadFirstLevel();
  } catch (error) {
    sdk.host.error("Could not load the first level");
    throw error;
  }
  drawFirstFrame();
  sdk.host.ready();
</script>

에셋을 로드하기 전이 아니라, 설계한 첫 화면이 보이고 입력이 작동할 때 ready()를 호출하세요. sdk.host.error(message)는 게임을 시작할 수 없다고 PlayDrop에 알립니다. setLoadingState와 firstFrameReady는 같은 단계의 이전 이름이니 ready()를 사용하세요.

sdk.host.phase는 preview, play 또는 editor이며, onPhaseChange가 단계 전환을 알려 줍니다. 미리 보기와 캡처는 실제 세션 없이 게임을 보여 주므로, play 밖에서는 저장, 점수, 업적, 구매를 절대 기록하지 마세요. sdk.host.mode는 보통 play이고, 로컬 Dev 프레임에서는 dev입니다.

onPause(reason)와 onResume(reason)은 플레이어가 일시 정지 메뉴를 열거나, 탭을 숨기거나, 로그인하거나, 무언가를 구매할 때, 또는 광고나 PlayDrop 창이 게임을 가릴 때 실행됩니다. reason은 tab_hidden, auth_prompt, purchase_flow, host_overlay, detail_hidden, route_change, native_background 중 하나이며, sdk.host.isPaused는 현재 상태입니다.

일시 정지된 동안에는 시뮬레이션과 타이머를 멈추세요. 재개할 때는 게임이 앞으로 건너뛰지 않도록 프레임 시계를 초기화하세요.

let last = performance.now();
function frame(now) {
  const dt = paused ? 0 : Math.min((now - last) / 1000, 0.05);
  last = now;
  if (!paused) update(dt);
  render();
  requestAnimationFrame(frame);
}
requestAnimationFrame(frame);

Esc 키와 컨트롤러의 메뉴 버튼은 PlayDrop의 일시 정지 메뉴에 속하므로 게임에서 바인딩하지 마세요. 네트워크 게임에서는 일시 정지 중에도 방 연결을 유지하세요. 한 플레이어가 일시 정지했다고 다른 플레이어가 멈추면 안 됩니다.

init() 후에 sdk.host.audioAllowed를 한 번 읽고, 그다음부터는 onAudioAllowedChange를 따르세요. 이 값은 플레이어의 음소거, 단계, 일시 정지를 합친 결과이며, 탭이 숨겨져 일시 정지된 동안에는 음악이 재생 위치를 유지할 수 있도록 true로 남습니다. 이유나 호스트 볼륨도 필요하면 onAudioPolicyChange가 { enabled, reason, volume }을 알려 줍니다.

const audio = new AudioContext();
function setAudio(allowed) {
  (allowed ? audio.resume() : audio.suspend()).catch(() => {});
}

오디오는 호스트가 허용할 때까지 음소거 상태로 시작하며, 브라우저는 여전히 소리를 재생하기 전에 플레이어의 조작을 요구합니다. 게임 내 볼륨 설정은 추가 제한으로 유지하세요. 호스트 음소거가 항상 우선합니다. 거부된 play()와 resume() promise를 처리하세요.

네이티브 앱은 게임이 시작되기 전에 파일을 내려받아 오프라인 플레이용으로 보관할 수 있습니다. catalogue.json에 선언하세요.

{
  "prefetch": { "required": ["game.js", "assets/level-1.png"], "optional": ["assets/music.mp3"] },
  "offlineSupported": true
}

시작 페이지는 항상 포함됩니다. required 파일은 플레이 전에, optional 파일은 그 후에 가져옵니다. offlineSupported: true를 설정하면 필수 파일이 저장된 뒤 앱이 게임을 오프라인으로 제공할 수 있습니다. 잘못된 값은 무시되며 업로드를 막지 않습니다. 웹사이트는 평소처럼 게임을 불러옵니다. 인스턴트 게임에서는 필수 파일의 크기가 시작 크기가 됩니다.

기기 데이터 지원을 알리는 호스트에서는 오프라인에서 기록한 저장, 점수, 업적이 기기에 남아 있다가 온라인이 되면 동기화되며, 오프라인 순위표에는 플레이어 본인의 최고 기록만 표시됩니다. 브라우저에는 오프라인 대기열이 없으므로 실패한 저장을 처리하세요. 게임이 인터넷에서 불러오는 것은 여전히 연결이 필요합니다.

네이티브 앱에서 sdk.haptics.selection(), impact("light" | "medium" | "heavy"), notification("success" | "warning" | "error")는 짧은 진동 피드백을 줍니다. sdk.haptics.supported는 호스트가 이를 지원하는지 알려 줍니다. 웹에서는 아무 동작도 하지 않으며, 음소거와는 무관합니다.