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

Inizializza l’SDK, chiama ready al primo frame giocabile, gestisci pausa e ripresa, rispetta l’audio dell’host e precarica i file per app native e offline.

Source: https://www.playdrop.ai/it/create/learn/lifecycle

PlayDrop mostra intorno al tuo gioco la propria schermata di caricamento, il menu di pausa, il comando per disattivare l’audio e altre finestre. L’API del ciclo di vita mantiene il gioco al passo con questi elementi: si ferma mentre PlayDrop lo mette in pausa e riproduce suoni solo quando la politica audio di PlayDrop lo consente.

## Inizializza, poi segnala che sei pronto

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.

```html
<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()`.

## Fasi: anteprima, gioco ed editor

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

## Pausa e ripresa

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

```js
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.

## Audio

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.

```js
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()`.

## Precarica e gioca offline nelle app

Le app native possono scaricare i file di un gioco prima che parta e conservarli per giocare offline. Dichiarali in [catalogue.json](https://www.playdrop.ai/it/create/learn/catalogue-json):

```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](https://www.playdrop.ai/it/create/learn/instant-games), 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.

## Vibrazione

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.

## Guide correlate

- [Schermo intero e aree sicure](https://www.playdrop.ai/it/create/learn/viewport): Fai riempire lo schermo a un gioco PlayDrop e tieni l’HUD nelle aree sicure CSS e lontano dai comandi dell’host con i reservedCorners misurati dall’SDK.
- [Salvataggi cloud](https://www.playdrop.ai/it/create/learn/cloud-saves): Salva e carica i progressi con sdk.me.appData e sdk.me.updateAppData, per ospiti e giocatori con accesso: regole per scritture, anteprime e gioco offline.
- [Giochi Instant](https://www.playdrop.ai/it/create/learn/instant-games): Cosa rende Instant un gioco PlayDrop: formato verticale, accesso per ospiti, massimo 10 MiB di file di avvio e partenza entro 2 secondi. Differenze dai giochi normali.
- [SDK client](https://www.playdrop.ai/it/create/learn/sdk): Riferimento dell’SDK browser di PlayDrop: host, identità, salvataggi, controller, social, multiplayer, negozio, annunci, classifiche, obiettivi, asset e IA.