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

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

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](https://www.playdrop.ai/pl/create) integruje je za ciebie; z [PlayDrop Connector](https://www.playdrop.ai/pl/create/connectors) twój agent dodaje jeden tag script.

## Dodaj SDK i stosuj się do cyklu życia hosta

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.

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

## 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](https://www.playdrop.ai/pl/create/learn/server-sdk) 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](https://www.playdrop.ai/pl/create/learn/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ę.

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

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](https://www.playdrop.ai/pl/create/learn/catalogue-json).