Technische Referenz

PlayDrop-Client-SDK für Browserspiele

Optionales Browser-SDK für jedes PlayDrop-Spiel: Host-Lebenszyklus, Anmeldung, Spielstände, Bestenlisten, Käufe, Werbung, Freunde, Controller, Multiplayer und gemeinsam genutzte Bibliotheken – mit einem einzigen Script-Tag.

Das PlayDrop-SDK ist optional: Auch Spiele ohne SDK laufen auf PlayDrop. Binden Sie es für Plattformfunktionen ein, etwa Spieleranmeldung, Spielstände, Erfolge und Bestenlisten, Käufe mit Credits, Werbung, Freunde und Spielkarten in PlayDrop Chat, Links zum Teilen, vom Host gesteuerte Pause und Audiowiedergabe, Controller-Eingaben, gehosteten Multiplayer und KI-Generierung. PlayDrop Cloud integriert es für Sie; mit PlayDrop Connector fügt Ihr Agent ein einziges Script-Tag hinzu.

SDK einbinden und den Host-Lebenszyklus beachten

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>

Laden Sie das SDK vom CDN von PlayDrop; eine Paketinstallation ist nicht nötig. Rendern Sie den ersten spielbaren Frame und bereiten Sie die Eingabe vor, bevor Sie sdk.host.ready() aufrufen. Pausieren Sie die Simulation, wenn der Host pausiert, setzen Sie sie ohne doppelte Schleifen fort und befolgen Sie die Audiorichtlinie des Hosts.

Identität, Spielstände und Sprache

sdk.me stellt die Spieleridentität bereit und sdk.me.appData speichert private Spielstände; sdk.achievements und sdk.leaderboards verwalten Erfolge und Punktestände. Spielstände, Erfolge und Bestenlisten funktionieren ohne vorherige Anmeldeprüfung. Verwenden Sie sdk.me.isLoggedIn für Funktionen, die ein echtes Konto erfordern, etwa Käufe oder Multiplayer. In Vorschau- und Aufnahmemodi darf kein Spielerfortschritt gespeichert werden. sdk.host.language liefert die Sprache des Spielers: Bieten Sie Ihr Spiel auf Englisch an und zusätzlich in Ihrer eigenen Sprache, falls diese abweicht. Das Übersetzen eines Spieleintrags übersetzt keine Spielinhalte. An einer natürlichen Pause, etwa nach einem Sieg, lässt sdk.host.requestReview() PlayDrop den Spieler um eine Bewertung bitten, höchstens einmal pro Spiel; Ihr Spiel erfährt die Antwort nie, belohnen Sie sie also nie.

Bibliotheken, Assets und Multiplayer

sdk.libs lädt unterstützte Versionen von Three.js, Phaser, Rapier, nipplejs und Colyseus. sdk.assets stellt Katalog-, Pack- und Asset-Referenzen bereit; sdk.social bietet Freunde, Spielkarten und Aktionen zum Teilen. Für gehosteten Multiplayer liefert sdk.multiplayer.getConnection() die Serveradresse und das Token des angemeldeten Spielers; verbinden Sie sich damit über den Colyseus-Client. Die Seite zum Server-SDK behandelt gehostete Server; ein Server, den Sie selbst betreiben, braucht nichts vom SDK. Die alten Relay-Room-APIs wurden eingestellt.

Vor der Veröffentlichung mit dem SDK testen

Starten Sie Ihren gewohnten Dev-Server und öffnen Sie https://www.playdrop.ai/creators/<username>/apps/game/<slug>/dev?url=http://localhost:5173/ in Chrome, um das Spiel im echten PlayDrop-Rahmen mit dem SDK-Host zu spielen. Jeder localhost-Port und jede https-URL funktioniert. Funktionen, die ein Konto erfordern, etwa Spielstände und Käufe, funktionieren, sobald das Spiel einmal hochgeladen wurde; ein privater Upload genügt. Die Mediengenerierung im Browser läuft als asynchrone Aufgaben mit vom Host bestätigten Credit-Kosten. Die Metadaten des Spieleintrags finden Sie unter catalogue.json.

Zusammen spielen

Verwende während des Spiels await sdk.multiplayer.join("game"), um einem Raum beizutreten oder die Gruppenreservierung des Hosts zu nutzen. Bei einem Gruppenfehler wird die Anfrage abgelehnt, statt Spieler auf andere Räume aufzuteilen. getConnection() liefert bestehenden Spielen weiterhin sofort die Verbindungsdaten. Behalte den Raum zwischen Runden bei und halte die Netzwerkverbindung aktiv, wenn Host-Oberflächen die Spieleingabe pausieren.

Rufe sdk.social.openParty() nach einer Spieleraktion auf, um das Gruppenfenster des Hosts zu öffnen. Lies Mitglieder mit await sdk.social.getParty() oder sdk.social.onPartyChange(callback). Spiele dürfen Plattformgruppen nicht ändern und Mikrofone nicht steuern. Sprachchat wird im Web- oder nativen Host verwaltet und berücksichtigt Zustimmung, Stummschaltung, Blockierungen und Verfügbarkeit.

Rufe für flüssige räumliche Sprachwiedergabe sdk.multiplayer.voice.updateSpatialState({ listener: { position, forward, up }, speakers: [{ userId, position }] }) mit endlichen { x, y, z }-Vektoren auf. Hinweise beeinflussen Lautstärke und Stereoposition, niemals Berechtigungen. Der Server prüft Team- und Nähekriterien.

Verwende sdk.device.localPlayers und sdk.device.onLocalPlayersChange(callback) für ausgewählte lokale Controllerplätze { playerIndex, gamepadKey }. Die Liste verbundener Controller ist unabhängig; getrennte Plätze behalten ihre Identität. Der lokale Modus kann keinen Online-Räumen beitreten. Das kopierbare Rezept playdrop-metagame/recipes/play-together zeigt beide Modi, zwei Ziele und Raumregeln.

Controller

Lesen Sie physische Controller und PlayDrop-Handy-Controller auf jeder Plattform gleich über sdk.device. Rufen Sie enableControllerInput() einmal nach init() auf, lesen Sie gamepad(playerIndex) in der Spielschleife (0 ist P1) und verwenden Sie onButton für Drücken und Loslassen. Achsen und Tasten folgen der Standard-Gamepad-Reihenfolge des Browsers; Tasten haben Positionsnamen wie south und east, und pad.label("south") liefert die Beschriftung für den jeweiligen Controller, etwa "A" oder "Cross". Die Menütaste gehört PlayDrop und pausiert das Spiel.

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

Rufen Sie nicht navigator.getGamepads() auf: Handy-Controller erreichen Spiele nur über das SDK, und PlayDrop protokolliert eine Warnung, wenn ein Spiel die Browser-API direkt liest. Kann der Host keine Controller-Eingaben liefern, lehnt enableControllerInput() mit controller_input_unavailable oder controller_input_timeout ab, und das Spiel läuft weiter. pad.has("dpad") zeigt, ob ein Bedienelement vorhanden ist; die Bedienelemente, die Ihr Spiel braucht, deklarieren Sie in catalogue.json.