# Grupy lokalne, gamepady i kontrolery na telefonie w grach PlayDrop

Odczytuj gamepady i kontrolery PlayDrop na telefonie przez sdk.device, śledź lokalne sloty graczy, deklaruj obsługę kontrolerów i rozmiary grup lokalnych.

Source: https://www.playdrop.ai/pl/create/learn/local-party

Grupa lokalna to kilka osób grających na jednym ekranie, każda z kontrolerem: fizycznym gamepadem albo telefonem, który PlayDrop zamienia w kontroler po zeskanowaniu kodu. Twoja gra odczytuje każdy kontroler tak samo przez SDK, na stronie internetowej i w aplikacjach.

## Zadeklaruj kontrolery i rozmiary grup

```json
{
  "types": ["solo", "party"],
  "party": { "local": [1, 2, 3, 4] },
  "controller": { "support": "optional", "type": "simpler" }
}
```

- `controller.support` ma wartość `off`, `optional` lub `required`. Deklaruj je w każdej grze, także `off`.
- `controller.type` określa minimalne sterowanie, którego potrzebuje gra: `any` (kierunki, Confirm i Cancel), `simpler` (jeden drążek, cztery przyciski czołowe i Menu; spełniają to kontrolery na telefonie) lub `standard` (krzyżak, dwa klikalne drążki, cztery przyciski czołowe, dwa przyciski ramieniowe, dwa spusty i Menu).
- `party.local` wymienia dokładne liczby graczy na jednym ekranie; `1` wymaga typu `solo`. Przy włączonej obsłudze kontrolerów każda wymieniona liczba musi być grywalna z kontrolerami.

## Odczytuj kontrolery

```js
await sdk.device.enableControllerInput().catch(() => { /* keep keyboard and touch */ });

const stop = sdk.device.onButton(({ playerIndex, button, pressed }) => {
  if (button === "south" && pressed) jump(playerIndex);
});

function update() {
  for (const slot of sdk.device.localPlayers) {
    const pad = sdk.device.gamepad(slot.playerIndex);
    if (pad?.connected) move(slot.playerIndex, pad.axes[0], pad.axes[1]);
  }
  requestAnimationFrame(update);
}
update();
```

- Wywołaj `enableControllerInput()` raz po `init()`. Gdy host nie może dostarczyć wejścia, wywołanie zostaje odrzucone z `controller_input_unavailable` lub `controller_input_timeout`; gra działa dalej.
- `gamepad(playerIndex)` zwraca migawkę w standardowym układzie przeglądarki: `axes` (lewy x/y, prawy x/y od -1 do 1), siedemnaście `buttons`, `source` (`physical` lub `virtual`) i `id`. `playerIndex` 0 to gracz 1.
- Przyciski mają nazwy pozycyjne, takie jak `south` i `east`. `pad.label("south")` podaje podpowiedź do wyświetlenia: „A”, „Cross” lub „B” w zależności od kontrolera. `pad.has("dpad")` mówi, czy dany element sterowania istnieje.
- Menu i Home należą do PlayDrop i zawsze są odczytywane jako zwolnione.
- Nigdy nie wywołuj `navigator.getGamepads()`: kontrolery na telefonie docierają do gier tylko przez SDK, a PlayDrop zapisuje ostrzeżenie.

## Lokalne sloty graczy

`sdk.device.localPlayers` wymienia sloty wybrane przez graczy, `{ playerIndex, gamepadKey }`, a `onLocalPlayersChange(callback)` zgłasza zmiany. Odłączony kontroler zachowuje swój slot. Gdy skład graczy się zmienia lub staje się pusty, wróć do sensownego menu zamiast się zawieszać. Jeden kontroler sam w sobie to zwykłe wejście, a nie grupa.

Wywołane po naciśnięciu przycisku w grze `sdk.social.openParty({ mode: "local" })` otwiera okno parowania PlayDrop z kodem QR dla telefonów i podłączonymi gamepadami. Oferuj tylko te tryby, które zadeklarowano.

## Lokalnie albo online, nigdy oba naraz

Host uruchamia grę albo jako grupę lokalną, albo jako grupę online, nigdy obie naraz: gracze lokalni nie mogą dołączać do pokoi online. Grę online ze znajomymi opisuje poradnik [grupy online i głos](https://www.playdrop.ai/pl/create/learn/online-party).

## Projektuj z myślą o kanapie

Pokazuj kolor każdego gracza i podpowiedzi dla jego kontrolera, pozwól każdemu dołączyć naciśnięciem przycisku i dbaj o to, by interfejs był czytelny z kanapy. Zachowaj sterowanie dotykowe i klawiaturą do gry w pojedynkę.

## Powiązane poradniki

- [Grupy online i głos](https://www.playdrop.ai/pl/create/learn/online-party): Pozwól znajomym grać razem online: zadeklaruj rozmiary grup, otwórz okno grupy, dołączaj do zarezerwowanych pokoi przez sdk.multiplayer.join i steruj głosem.
- [Pełny ekran i bezpieczne obszary](https://www.playdrop.ai/pl/create/learn/viewport): Spraw, by gra PlayDrop wypełniała ekran, a jej interfejs mieścił się w bezpiecznych obszarach CSS i omijał przyciski hosta dzięki reservedCorners z SDK.
- [catalogue.json](https://www.playdrop.ai/pl/create/learn/catalogue-json): Pola catalogue.json gier PlayDrop: tożsamość, strona gry, tryby gry, powierzchnie, logowanie, Instant, wstępne ładowanie, media, tłumaczenia, wyniki i serwery.