Dokumentacja techniczna

SDK klienta PlayDrop dla gier przeglądarkowych

Opcjonalne SDK dla gier PlayDrop: logowanie, zapisy, rankingi, zakupy, reklamy, znajomi, kontrolery i tryb wieloosobowy jednym tagiem script.

PlayDrop SDK jest opcjonalne: gry bez niego działają w PlayDrop. Dodaj je, aby korzystać z funkcji platformy, takich jak logowanie graczy, zapisy, osiągnięcia i rankingi, zakupy za kredyty, reklamy, znajomi i karty gier na czacie PlayDrop, linki do udostępniania, wstrzymywanie i dźwięk zarządzane przez hosta, sterowanie kontrolerami, hostowany tryb wieloosobowy i generowanie z AI. PlayDrop Cloud integruje je za ciebie; z PlayDrop Connector twój agent dodaje jeden tag script.

Dodaj SDK i stosuj się do cyklu życia hosta

html

<script src="https://assets.playdrop.ai/sdk/playdrop.js"></script>
<script type="module">
  const sdk = await playdrop.init();
  // Wyrenderuj grę i przygotuj sterowanie, a potem:
  sdk.host.ready();
  sdk.host.onPause(() => pauseGame());
  sdk.host.onResume(() => resumeGame());
  sdk.host.onAudioPolicyChange(({ enabled }) => setAudioEnabled(enabled));
</script>

Załaduj SDK z CDN PlayDrop; nie trzeba instalować żadnego pakietu. Wyrenderuj pierwszą grywalną klatkę i przygotuj sterowanie, zanim wywołasz sdk.host.ready(). Wstrzymaj symulację przy pauzie hosta, wznów bez zdublowanych pętli i przestrzegaj zasad dźwięku hosta.

Tożsamość, zapisy i język

sdk.me udostępnia tożsamość gracza, a sdk.me.appData przechowuje prywatne zapisy; sdk.achievements i sdk.leaderboards obsługują osiągnięcia i wyniki. Zapisy, osiągnięcia i rankingi działają bez wstępnego sprawdzania logowania. Używaj sdk.me.isLoggedIn do funkcji wymagających prawdziwego konta, takich jak zakupy lub tryb wieloosobowy. Tryby podglądu i przechwytywania nie mogą zapisywać postępów gracza. sdk.host.language podaje język gracza: dostarcz angielski oraz własny język, jeśli jest inny. Przetłumaczenie strony gry nie tłumaczy treści gry. W naturalnej przerwie, takiej jak wygrana, sdk.host.requestReview() pozwala PlayDrop poprosić gracza o recenzję, najwyżej raz na grę; twoja gra nigdy nie dowie się odpowiedzi, więc nigdy jej nie nagradzaj.

Biblioteki, zasoby i tryb wieloosobowy

sdk.libs ładuje obsługiwane wersje Three.js, Phaser, Rapier, nipplejs i Colyseus. sdk.assets udostępnia odwołania do katalogu, pakietów i zasobów; sdk.social udostępnia znajomych, karty gier i akcje udostępniania. W hostowanym trybie wieloosobowym sdk.multiplayer.getConnection() zwraca adres serwera i token zalogowanego gracza; dołącz za pomocą klienta Colyseus. Strona SDK serwera opisuje hostowane serwery; serwer, który prowadzisz sam, nie potrzebuje niczego z SDK. Stare API pokoi przekaźnikowych zostały wycofane.

Przetestuj z SDK przed publikacją

Uruchom swój zwykły serwer deweloperski i otwórz https://www.playdrop.ai/creators/<username>/apps/game/<slug>/dev?url=http://localhost:5173/ w Chrome, aby zagrać w prawdziwej ramce PlayDrop z hostem SDK. Działa dowolny port localhost lub adres https. Funkcje wymagające konta, takie jak zapisy i zakupy, działają po jednorazowym przesłaniu gry; wystarczy przesłanie prywatne. Generowanie multimediów w przeglądarce działa jako zadania asynchroniczne z kosztem w kredytach potwierdzanym przez hosta. Zobacz catalogue.json, aby poznać metadane strony gry.

Graj razem

Użyj await sdk.multiplayer.join("game") w fazie gry. Dołącza niezależnie albo wykorzystuje rezerwację grupy hosta. Błąd grupy kończy się odrzuceniem, zamiast po cichu rozdzielać graczy do innych pokoi. getConnection() pozostaje natychmiastowym API szczegółów połączenia dla istniejących gier. Zachowaj ten sam pokój między rundami i utrzymuj sieć aktywną, gdy nakładki hosta wstrzymują wejście gry.

Użyj sdk.social.openParty() z akcji gracza, aby otworzyć okno grupy hosta. Odczytuj członkostwo przez await sdk.social.getParty() lub sdk.social.onPartyChange(callback). Gry nie mogą zmieniać grup platformy ani sterować mikrofonami. Głos grupy i pokoju działa w hoście webowym/natywnym i podlega zgodzie gracza, wyciszeniu, blokadom oraz kwalifikowalności do wdrożenia.

Aby odtwarzanie w pokoju było płynne, wywołaj sdk.multiplayer.voice.updateSpatialState({ listener: { position, forward, up }, speakers: [{ userId, position }] }), używając skończonych wektorów { x, y, z }. Wskazówki wpływają na głośność i panoramę, nigdy na autoryzację. Serwer egzekwuje drużyny i kwalifikowalność według bliskości.

Użyj sdk.device.localPlayers i sdk.device.onLocalPlayersChange(callback) dla wybranych lokalnych slotów kontrolerów { playerIndex, gamepadKey }. Lista podłączonych kontrolerów jest osobna; odłączony slot zachowuje swoją tożsamość. Tryb lokalny nie może dołączać do pokoi online. Kopiowalny przepis playdrop-metagame/recipes/play-together pokazuje oba tryby, dwa cele i zasady pokoi.

Kontrolery

Odczytuj fizyczne kontrolery i kontrolery PlayDrop na telefonie przez sdk.device, tak samo na każdej platformie. Wywołaj enableControllerInput() raz po init(), odczytuj gamepad(playerIndex) w pętli gry (0 to G1) i używaj onButton dla naciśnięć i zwolnień. Osie i przyciski podążają za standardową kolejnością gamepada przeglądarki; przyciski mają nazwy pozycyjne, takie jak south i east, a pad.label("south") zwraca podpowiedź dla danego kontrolera, taką jak "A" lub "Cross". Menu należy do PlayDrop i wstrzymuje grę.

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

Nie wywołuj navigator.getGamepads(): kontrolery z telefonu docierają do gier tylko przez SDK, a PlayDrop zapisuje ostrzeżenie, gdy gra odczytuje API przeglądarki bezpośrednio. Jeśli host nie może dostarczyć wejścia kontrolera, enableControllerInput() odrzuca z controller_input_unavailable lub controller_input_timeout, a gra działa dalej. pad.has("dpad") mówi, czy dany element sterowania istnieje; zadeklaruj sterowanie, którego potrzebuje twoja gra, w catalogue.json.