# SDK client di PlayDrop per giochi da browser

SDK facoltativo per qualsiasi gioco PlayDrop: ciclo di vita dell’host, accesso, salvataggi, classifiche, acquisti, annunci, amici, controller e multiplayer.

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

L’SDK di PlayDrop è facoltativo: i giochi che non lo usano funzionano comunque su PlayDrop. Aggiungilo per le funzioni della piattaforma come accesso dei giocatori, salvataggi, obiettivi e classifiche, acquisti in crediti, annunci, amici e carte di gioco nella Chat di PlayDrop, link di condivisione, pausa e audio gestiti dall’host, input dei controller, multiplayer ospitato e generazione con l’IA. [PlayDrop Cloud](https://www.playdrop.ai/it/create) lo integra per te; con [PlayDrop Connector](https://www.playdrop.ai/it/create/connectors), il tuo agente aggiunge un solo tag script.

## Aggiungi l’SDK e segui il ciclo di vita dell’host

Carica l’SDK dalla CDN di PlayDrop; non serve installare alcun pacchetto. Mostra il primo frame giocabile e prepara l’input prima di chiamare `sdk.host.ready()`. Metti in pausa la simulazione quando l’host va in pausa, riprendi senza duplicare i loop e rispetta la politica audio dell’host.

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

## Identità, salvataggi e lingua

`sdk.me` espone l’identità del giocatore e `sdk.me.appData` conserva i salvataggi privati; `sdk.achievements` e `sdk.leaderboards` gestiscono obiettivi e punteggi. Salvataggi, obiettivi e classifiche funzionano senza un controllo preventivo dell’accesso. Usa `sdk.me.isLoggedIn` per le funzioni che richiedono un vero account, come gli acquisti o il multiplayer. Le modalità anteprima e cattura non devono scrivere i progressi del giocatore. `sdk.host.language` indica la lingua del giocatore: offri l’inglese più la tua lingua quando è diversa. Tradurre una scheda non traduce il contenuto del gioco. In una pausa naturale, come dopo una vittoria, `sdk.host.requestReview()` permette a PlayDrop di chiedere una recensione al giocatore, al massimo una volta per gioco; il tuo gioco non conosce mai la risposta, quindi non premiarla mai.

## Librerie, asset e multiplayer

`sdk.libs` carica le versioni supportate di Three.js, Phaser, Rapier, nipplejs e Colyseus. `sdk.assets` fornisce riferimenti a cataloghi, pacchetti e asset; `sdk.social` fornisce amici, carte di gioco e azioni di condivisione. Per il multiplayer ospitato, `sdk.multiplayer.getConnection()` restituisce l’indirizzo del server e il token del giocatore connesso; entra con il client Colyseus. La pagina [SDK server](https://www.playdrop.ai/it/create/learn/server-sdk) copre i server ospitati; un server che gestisci tu non richiede nulla dall’SDK. Le vecchie API delle stanze relay sono state ritirate.

## Prova con l’SDK prima di pubblicare

Avvia il tuo solito server di sviluppo e apri `https://www.playdrop.ai/creators/<username>/apps/game/<slug>/dev?url=http://localhost:5173/` in Chrome per giocare dentro il vero frame di PlayDrop con l’host dell’SDK. Funziona qualsiasi porta localhost o URL https. Le funzioni che richiedono un account, come salvataggi e acquisti, funzionano dopo che il gioco è stato caricato una volta; basta un caricamento privato. La generazione di contenuti multimediali nel browser viene eseguita come attività asincrone con un costo in crediti confermato dall’host. Vedi [catalogue.json](https://www.playdrop.ai/it/create/learn/catalogue-json) per i metadati della scheda.

## Giocare insieme

Usa `await sdk.multiplayer.join("game")` nella fase di gioco. Entra in modo indipendente oppure usa la prenotazione del gruppo dell’host. Un errore del gruppo viene rifiutato invece di dividere in silenzio i giocatori in un’altra stanza. `getConnection()` resta l’API immediata per i dettagli di connessione dei giochi esistenti. Mantieni la stessa stanza tra un round e l’altro e tieni attiva la rete mentre gli overlay dell’host mettono in pausa l’input del gioco.

Usa `sdk.social.openParty()` da un’azione del giocatore per aprire il popup del gruppo dell’host. Leggi i membri con `await sdk.social.getParty()` o `sdk.social.onPartyChange(callback)`. I giochi non possono modificare i gruppi della piattaforma né controllare i microfoni. La voce di gruppo e di stanza vive nell’host web/nativo e resta soggetta a consenso del giocatore, silenziamento, blocchi e idoneità al rollout.

Per una riproduzione fluida nella stanza, chiama `sdk.multiplayer.voice.updateSpatialState({ listener: { position, forward, up }, speakers: [{ userId, position }] })`, usando vettori `{ x, y, z }` finiti. I suggerimenti influiscono su volume e panning, mai sull’autorizzazione. Il server applica l’idoneità di squadre e prossimità.

Usa `sdk.device.localPlayers` e `sdk.device.onLocalPlayersChange(callback)` per gli slot dei controller locali selezionati `{ playerIndex, gamepadKey }`. L’inventario dei controller collegati è separato; uno slot scollegato mantiene la sua identità. La modalità locale non può entrare nelle stanze online. La ricetta copiabile `playdrop-metagame/recipes/play-together` mostra entrambe le modalità, due destinazioni e le politiche delle stanze.

## Controller

Leggi i controller fisici e i controller su telefono di PlayDrop tramite `sdk.device`, allo stesso modo su ogni piattaforma. Chiama `enableControllerInput()` una volta dopo `init()`, leggi `gamepad(playerIndex)` nel loop di gioco (0 è P1) e usa `onButton` per pressioni e rilasci. Assi e pulsanti seguono l’ordine standard dei gamepad del browser; i pulsanti hanno nomi posizionali come `south` ed `east` e `pad.label("south")` restituisce il testo per quel controller, come `"A"` o `"Cross"`. Menu appartiene a PlayDrop e mette in pausa il gioco.

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

Non chiamare `navigator.getGamepads()`: i controller su telefono raggiungono i giochi solo tramite l’SDK, e PlayDrop registra un avviso quando un gioco legge direttamente l’API del browser. Se l’host non può fornire l’input dei controller, `enableControllerInput()` viene rifiutata con `controller_input_unavailable` o `controller_input_timeout` e il gioco continua a funzionare. `pad.has("dpad")` indica se un comando esiste; dichiara i comandi di cui il tuo gioco ha bisogno in [catalogue.json](https://www.playdrop.ai/it/create/learn/catalogue-json).