Ciclo di vita del gioco su PlayDrop: caricamento, avvio, pausa e audio

Carica l’SDK, leggi lo stato iniziale, iscriviti alle modifiche, prepara la prima schermata e solo allora chiama ready(). Fino a quel momento PlayDrop tiene visibile la sua schermata di caricamento.

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

Chiama ready() quando la prima schermata prevista è visibile e l’input funziona, non prima che gli asset siano caricati. sdk.host.error(message) comunica a PlayDrop che il gioco non può partire. setLoadingState e firstFrameReady sono nomi meno recenti per lo stesso passaggio; usa ready().

sdk.host.phase vale preview, play o editor, e onPhaseChange segnala i cambi di fase. Anteprime e acquisizioni mostrano il gioco senza una vera sessione: non scrivere mai salvataggi, punteggi, obiettivi o acquisti fuori da play. sdk.host.mode vale play di norma e dev nel frame Dev locale.

onPause(reason) e onResume(reason) scattano quando il giocatore apre il menu di pausa, nasconde la scheda del browser, accede, compra qualcosa, oppure quando un annuncio o una finestra di PlayDrop copre il gioco. reason è uno tra tab_hidden, auth_prompt, purchase_flow, host_overlay, detail_hidden, route_change o native_background; sdk.host.isPaused indica lo stato attuale.

Durante la pausa, ferma la simulazione e i timer. Alla ripresa, azzera l’orologio dei frame così il gioco non salta in avanti:

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 e il pulsante Menu di un controller appartengono al menu di pausa di PlayDrop; non associarli a comandi del tuo gioco. In un gioco in rete, mantieni attiva la connessione alla stanza durante la pausa: la pausa di un giocatore non deve fermare gli altri.

Leggi sdk.host.audioAllowed una volta dopo init(), poi segui onAudioAllowedChange. Combina l’audio disattivato dal giocatore, la fase e la pausa, e resta true durante una pausa dovuta alla scheda del browser nascosta, così la musica può mantenere la sua posizione. onAudioPolicyChange segnala { enabled, reason, volume } quando ti servono anche il motivo o il volume dell’host.

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

L’audio parte disattivato finché l’host non lo consente, e i browser richiedono comunque un gesto del giocatore prima di riprodurre suoni. Mantieni un’eventuale impostazione del volume nel gioco come limite aggiuntivo; l’audio disattivato dall’host vince sempre. Gestisci le promise rifiutate di play() e resume().

Le app native possono scaricare i file di un gioco prima che parta e conservarli per giocare offline. Dichiarali in catalogue.json:

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

La pagina di ingresso è sempre inclusa. I file required vengono scaricati prima del gioco, quelli optional dopo. offlineSupported: true permette alle app di offrire il gioco offline una volta salvati i suoi file obbligatori. I valori non validi vengono ignorati e non bloccano mai un caricamento. Il sito carica i giochi come al solito. Per i giochi Instant, i file obbligatori costituiscono la dimensione di avvio.

Sugli host che dichiarano il supporto ai dati sul dispositivo, salvataggi, punteggi e obiettivi ottenuti offline restano sul dispositivo e si sincronizzano una volta online; le classifiche offline mostrano solo il record del giocatore. Nel browser non c’è una coda offline, quindi gestisci un salvataggio non riuscito. Tutto ciò che il gioco carica da internet richiede comunque una connessione.

Nelle app native sdk.haptics.selection(), impact("light" | "medium" | "heavy") e notification("success" | "warning" | "error") danno un breve riscontro tattile; sdk.haptics.supported indica se l’host lo supporta. Sul web non fanno nulla e sono indipendenti dall’audio disattivato.