Ciclo de vida do jogo no PlayDrop: carregamento, pronto, pausa e áudio

Carregue o SDK, leia o estado inicial, inscreva-se nas mudanças, prepare a primeira tela e só então chame ready(). O PlayDrop mantém a tela de carregamento até lá.

<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>

Chame ready() quando a primeira tela planejada estiver visível e a entrada funcionar, e não antes de os assets terminarem de carregar. sdk.host.error(message) avisa o PlayDrop de que o jogo não consegue iniciar. setLoadingState e firstFrameReady são nomes antigos para a mesma etapa; use ready().

sdk.host.phase é preview, play ou editor, e onPhaseChange informa as mudanças. As prévias e as capturas mostram o jogo sem uma sessão real: nunca grave salvamentos, pontuações, conquistas ou compras fora de play. sdk.host.mode é play normalmente e dev no frame Dev local.

onPause(reason) e onResume(reason) são disparados quando o jogador abre o menu de pausa, oculta a aba, entra na conta, compra algo ou quando um anúncio ou uma janela do PlayDrop cobre o jogo. reason é um destes valores: tab_hidden, auth_prompt, purchase_flow, host_overlay, detail_hidden, route_change ou native_background; sdk.host.isPaused é o estado atual.

Durante a pausa, pare a simulação e os timers. Ao retomar, reinicie o relógio de quadros para que o jogo não dê um salto para a frente:

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);

A tecla Esc e o botão Menu de um controle pertencem ao menu de pausa do PlayDrop; não associe ações a eles no seu jogo. Em um jogo em rede, mantenha a conexão com a sala ativa durante a pausa: pausar um jogador não pode parar os outros.

Leia sdk.host.audioAllowed uma vez depois de init() e depois acompanhe onAudioAllowedChange. Esse valor combina o silenciamento do jogador, a fase e a pausa, e continua verdadeiro durante uma pausa por aba oculta, para que a música mantenha sua posição. onAudioPolicyChange informa { enabled, reason, volume } quando você também precisa do motivo ou do volume do host.

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

O áudio começa silenciado até o host permitir, e os navegadores ainda exigem um gesto do jogador antes de tocar som. Mantenha qualquer configuração de volume do jogo como um limite adicional; o silenciamento do host sempre prevalece. Trate as promises rejeitadas de play() e resume().

Os apps nativos podem baixar os arquivos de um jogo antes de ele começar e guardá-los para jogar offline. Declare-os no catalogue.json:

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

A página de entrada sempre é incluída. Os arquivos required são baixados antes de jogar; os optional, depois. offlineSupported: true permite que os apps ofereçam o jogo offline depois que os arquivos obrigatórios estiverem armazenados. Valores inválidos são ignorados e nunca bloqueiam um envio. O site carrega os jogos normalmente. Nos jogos Instantâneos, os arquivos obrigatórios são os arquivos iniciais.

Em hosts que anunciam suporte a dados no dispositivo, salvamentos, pontuações e conquistas feitos offline ficam no dispositivo e são sincronizados quando há conexão; os placares offline mostram só o recorde do próprio jogador. No navegador não há fila offline, então trate a falha de um salvamento. Tudo o que o jogo carrega da internet continua precisando de conexão.

Nos apps nativos, sdk.haptics.selection(), impact("light" | "medium" | "heavy") e notification("success" | "warning" | "error") dão uma resposta tátil curta; sdk.haptics.supported diz se o host tem esse recurso. Essas chamadas não fazem nada na web e não dependem do silenciamento.