Riferimento tecnico

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.

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 lo integra per te; con PlayDrop Connector, il tuo agente aggiunge un solo tag script.

Aggiungi l’SDK e segui il ciclo di vita 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>

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.

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

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.