Référence technique

SDK client PlayDrop pour les jeux sur navigateur

SDK navigateur facultatif pour tout jeu PlayDrop : cycle de vie de l’hôte, connexion, sauvegardes, classements, achats, publicités, amis, manettes, multijoueur et bibliothèques partagées, avec une seule balise script.

Le SDK PlayDrop est facultatif : les jeux qui ne l’utilisent pas fonctionnent aussi sur PlayDrop. Ajoutez-le pour profiter des fonctionnalités de la plateforme, comme la connexion des joueurs, les sauvegardes, les succès et les classements, les achats en Crédits, les publicités, les amis et les cartes de jeu dans PlayDrop Chat, les liens de partage, la pause et l’audio gérés par l’hôte, les manettes, le multijoueur hébergé et la génération par IA. PlayDrop Cloud l’intègre pour vous ; avec PlayDrop Connector, votre agent ajoute une seule balise script.

Ajoutez le SDK et respectez le cycle de vie de l’hôte

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>

Chargez le SDK depuis le CDN de PlayDrop ; aucune installation de paquet n’est nécessaire. Affichez la première image jouable et préparez la gestion des entrées avant d’appeler sdk.host.ready(). Suspendez la simulation lors d’une pause de l’hôte, reprenez sans créer de boucles en double et respectez la politique audio de l’hôte.

Identité, sauvegardes et langue

sdk.me expose l’identité du joueur et sdk.me.appData stocke ses sauvegardes privées ; sdk.achievements et sdk.leaderboards gèrent les succès et les scores. Les sauvegardes, les succès et les classements fonctionnent sans vérification préalable de la connexion. Utilisez sdk.me.isLoggedIn pour les fonctionnalités qui nécessitent un véritable compte, comme les achats ou le multijoueur. Les modes aperçu et capture ne doivent pas enregistrer la progression du joueur. sdk.host.language indique la langue du joueur : proposez votre jeu en anglais, et aussi dans votre langue si elle est différente. Traduire une fiche ne traduit pas le contenu du jeu. À une pause naturelle, comme une victoire, sdk.host.requestReview() permet à PlayDrop de demander un avis au joueur, au plus une fois par jeu ; votre jeu ne connaît jamais la réponse, ne la récompensez donc jamais.

Bibliothèques, ressources et multijoueur

sdk.libs charge les versions prises en charge de Three.js, Phaser, Rapier, nipplejs et Colyseus. sdk.assets fournit des références de catalogue, de pack et de ressource ; sdk.social fournit les amis, les cartes de jeu et les actions de partage. Pour le multijoueur hébergé, sdk.multiplayer.getConnection() renvoie l’adresse du serveur et le jeton du joueur connecté ; rejoignez la partie avec le client Colyseus. La page SDK serveur couvre les serveurs hébergés ; un serveur que vous gérez vous-même n’a besoin de rien du SDK. Les anciennes API de salles relais ont été retirées.

Testez avec le SDK avant de publier

Lancez votre serveur de développement habituel et ouvrez https://www.playdrop.ai/creators/<username>/apps/game/<slug>/dev?url=http://localhost:5173/ dans Chrome pour jouer dans le véritable cadre PlayDrop, avec l’hôte du SDK. N’importe quel port localhost ou URL https fonctionne. Les fonctionnalités qui nécessitent un compte, comme les sauvegardes et les achats, fonctionnent dès que le jeu a été envoyé une première fois ; un envoi privé suffit. Dans le navigateur, la génération de médias s’exécute sous forme de tâches asynchrones, avec un coût en Crédits confirmé par l’hôte. Consultez catalogue.json pour les métadonnées de la fiche.

Jouer ensemble

Pendant le jeu, utilisez await sdk.multiplayer.join("game") pour rejoindre une salle ou utiliser la réservation du groupe faite par l’hôte. Si le groupe ne peut pas rejoindre, la demande échoue au lieu de séparer les joueurs. getConnection() fournit toujours immédiatement les détails de connexion aux jeux existants. Gardez la même salle entre les manches et maintenez le réseau lorsque les interfaces de l’hôte suspendent les commandes du jeu.

Appelez sdk.social.openParty() après une action du joueur pour ouvrir le groupe dans l’hôte. Lisez les membres avec await sdk.social.getParty() ou sdk.social.onPartyChange(callback). Les jeux ne peuvent ni modifier les groupes de la plateforme ni contrôler les microphones. La voix est gérée par l’hôte web ou natif, selon le consentement, la sourdine, les blocages et la disponibilité.

Pour une voix spatiale fluide, appelez sdk.multiplayer.voice.updateSpatialState({ listener: { position, forward, up }, speakers: [{ userId, position }] }) avec des vecteurs finis { x, y, z }. Ces indications règlent le volume et la position stéréo, jamais les autorisations. Le serveur applique les règles d’équipe et de proximité.

Utilisez sdk.device.localPlayers et sdk.device.onLocalPlayersChange(callback) pour les emplacements locaux sélectionnés { playerIndex, gamepadKey }. La liste des manettes connectées est distincte ; un emplacement déconnecté conserve son identité. Le mode local ne rejoint pas les salles en ligne. La recette copiable playdrop-metagame/recipes/play-together présente les deux modes, deux destinations et les règles des salles.

Manettes

Lisez les manettes physiques et les manettes téléphone PlayDrop avec sdk.device, de la même façon sur toutes les plateformes. Appelez enableControllerInput() une fois après init(), lisez gamepad(playerIndex) dans la boucle de jeu (0 correspond à P1) et utilisez onButton pour les appuis et relâchements. Les axes et les boutons suivent l’ordre standard des manettes du navigateur ; les boutons portent des noms de position comme south et east, et pad.label("south") renvoie l’intitulé propre à la manette, comme "A" ou "Cross". Le bouton Menu appartient à PlayDrop et met le jeu en pause.

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

N’appelez pas navigator.getGamepads() : les manettes téléphone n’atteignent les jeux qu’à travers le SDK, et PlayDrop journalise un avertissement quand un jeu lit directement l’API du navigateur. Si l’hôte ne peut pas fournir les manettes, enableControllerInput() est rejetée avec controller_input_unavailable ou controller_input_timeout et le jeu continue de tourner. pad.has("dpad") indique si une commande existe ; déclarez les commandes nécessaires à votre jeu dans catalogue.json.