# Gruppi locali, gamepad e telefoni come controller nei giochi PlayDrop

Leggi i gamepad fisici e i telefoni usati come controller con sdk.device, segui i posti dei giocatori locali, dichiara controller e dimensioni dei gruppi locali.

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

Un gruppo locale è formato da più persone che giocano sullo stesso schermo, ognuna con un controller: un gamepad fisico o un telefono che PlayDrop trasforma in controller scansionando un codice. Il tuo gioco legge ogni controller allo stesso modo tramite l’SDK, sul sito e nelle app.

## Dichiara controller e dimensioni dei gruppi

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

- `controller.support` vale `off`, `optional` o `required`. Dichiaralo per ogni gioco, compreso `off`.
- `controller.type` indica i comandi minimi di cui il gioco ha bisogno: `any` (direzioni, Conferma e Annulla), `simpler` (una levetta, quattro pulsanti frontali e Menu; i telefoni usati come controller sono adatti) oppure `standard` (croce direzionale, due levette cliccabili, quattro pulsanti frontali, due dorsali, due grilletti e Menu).
- `party.local` elenca i numeri esatti di giocatori sullo stesso schermo; un `1` richiede il tipo `solo`. Con il supporto ai controller attivo, ogni numero elencato deve essere giocabile con i controller.

## Leggi i controller

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

- Chiama `enableControllerInput()` una volta dopo `init()`. Viene rifiutata con `controller_input_unavailable` o `controller_input_timeout` quando l’host non può fornire l’input; il gioco continua a funzionare.
- `gamepad(playerIndex)` restituisce un’istantanea nel layout standard del browser: `axes` (x/y sinistra e x/y destra da -1 a 1), diciassette `buttons`, `source` (`physical` o `virtual`) e `id`. `playerIndex` 0 è il giocatore 1.
- I pulsanti hanno nomi legati alla posizione, come `south` ed `east`. `pad.label("south")` fornisce l’indicazione da mostrare: «A», «Croce» o «B» a seconda del controller. `pad.has("dpad")` indica se un comando esiste.
- Menu e Home appartengono a PlayDrop e risultano sempre rilasciati.
- Non chiamare mai `navigator.getGamepads()`: i telefoni usati come controller arrivano ai giochi solo tramite l’SDK, e PlayDrop registra un avviso.

## Posti dei giocatori locali

`sdk.device.localPlayers` elenca i posti scelti dai giocatori, `{ playerIndex, gamepadKey }`, e `onLocalPlayersChange(callback)` segnala le modifiche. Un controller disconnesso mantiene il suo posto. Quando l’elenco dei giocatori cambia o si svuota, torna a un menu sensato invece di andare in crash. Un solo controller è un normale input, non un gruppo.

Da un pulsante, `sdk.social.openParty({ mode: "local" })` apre la finestra di abbinamento di PlayDrop con il codice QR per i telefoni e i gamepad collegati. Offri solo le modalità che hai dichiarato.

## Locale oppure online, non entrambi

L’host avvia un gioco come gruppo locale oppure come gruppo online, mai entrambi: i giocatori locali non possono entrare nelle stanze online. Per giocare online con gli amici vedi [gruppi online e voce](https://www.playdrop.ai/it/create/learn/online-party).

## Pensa al divano

Mostra il colore e l’indicazione del controller di ogni giocatore, permetti a chiunque di unirsi premendo un pulsante e mantieni l’HUD leggibile dal divano. Conserva i comandi touch e da tastiera per il gioco in solitaria.

## Guide correlate

- [Gruppi online e voce](https://www.playdrop.ai/it/create/learn/online-party): Fai giocare gli amici insieme online: dimensioni dei gruppi, finestra del gruppo di PlayDrop, stanze riservate con sdk.multiplayer.join e voce della stanza.
- [Schermo intero e aree sicure](https://www.playdrop.ai/it/create/learn/viewport): Fai riempire lo schermo a un gioco PlayDrop e tieni l’HUD nelle aree sicure CSS e lontano dai comandi dell’host con i reservedCorners misurati dall’SDK.
- [catalogue.json](https://www.playdrop.ai/it/create/learn/catalogue-json): Campi di catalogue.json usati dai giochi PlayDrop: identità, scheda, modalità, superfici, accesso, Instant, precarico, media, traduzioni, punteggi e server.