# Grupos locais, controles físicos e controles de celular no PlayDrop

Leia controles físicos e de celular do PlayDrop com sdk.device, acompanhe as posições dos jogadores locais e declare suporte a controles e tamanhos de grupo.

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

Um grupo local é formado por várias pessoas jogando em uma só tela, cada uma com um controle: um controle físico ou um celular que o PlayDrop transforma em controle quando alguém escaneia um código. Seu jogo lê todos os controles do mesmo jeito pelo SDK, no site e nos apps.

## Declare os controles e os tamanhos de grupo

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

- `controller.support` é `off`, `optional` ou `required`. Declare-o em todo jogo, inclusive com `off`.
- `controller.type` indica os controles mínimos de que o jogo precisa: `any` (direções, Confirmar e Cancelar), `simpler` (um analógico, quatro botões frontais e Menu; os controles de celular se enquadram) ou `standard` (direcional, dois analógicos clicáveis, quatro botões frontais, dois botões de ombro, dois gatilhos e Menu).
- `party.local` lista os números exatos de jogadores em uma só tela; um `1` exige o tipo `solo`. Com o suporte a controles ativado, todo número listado precisa ser jogável com controles.

## Leia os controles

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

- Chame `enableControllerInput()` uma vez depois de `init()`. A chamada é rejeitada com `controller_input_unavailable` ou `controller_input_timeout` quando o host não consegue fornecer a entrada; o jogo continua rodando.
- `gamepad(playerIndex)` retorna um snapshot no layout padrão do navegador: `axes` (x/y esquerdo e x/y direito, de -1 a 1), dezessete `buttons`, `source` (`physical` ou `virtual`) e `id`. O `playerIndex` 0 é o jogador 1.
- Os botões têm nomes por posição, como `south` e `east`. `pad.label("south")` informa o nome do botão a mostrar: "A", "Cross" ou "B", conforme o controle. `pad.has("dpad")` diz se o controle tem determinado comando.
- Menu e Home pertencem ao PlayDrop e sempre aparecem como não pressionados.
- Nunca chame `navigator.getGamepads()`: os controles de celular só chegam aos jogos pelo SDK, e o PlayDrop registra um aviso.

## Posições dos jogadores locais

`sdk.device.localPlayers` lista as posições que os jogadores escolheram, `{ playerIndex, gamepadKey }`, e `onLocalPlayersChange(callback)` informa as mudanças. Um controle desconectado mantém sua posição. Quando a lista de jogadores mudar ou ficar vazia, volte para um menu adequado em vez de travar. Um controle sozinho é uma entrada comum, não um grupo.

A partir de um botão, `sdk.social.openParty({ mode: "local" })` abre a janela de pareamento do PlayDrop, com o QR code para os celulares e os controles físicos conectados. Ofereça só os modos que você declarou.

## Local ou online, nunca os dois

O host inicia um jogo como grupo local ou como grupo online, nunca os dois: jogadores locais não podem entrar em salas online. Para jogar online com amigos, veja [grupos online e voz](https://www.playdrop.ai/pt-br/create/learn/online-party).

## Pense no sofá

Mostre a cor de cada jogador e o nome dos botões do controle dele, deixe qualquer pessoa entrar apertando um botão e mantenha o HUD legível do sofá. Mantenha os controles por toque e por teclado para o modo solo.

## Guias relacionados

- [Grupos online e voz](https://www.playdrop.ai/pt-br/create/learn/online-party): Amigos jogam juntos online: declare tamanhos de grupo, abra a janela de grupo do PlayDrop, entre em salas reservadas com sdk.multiplayer.join e controle a voz.
- [Tela cheia e áreas seguras](https://www.playdrop.ai/pt-br/create/learn/viewport): Faça o jogo ocupar a tela toda, com o HUD dentro das áreas seguras do CSS e longe dos controles do host, usando os reservedCorners medidos pelo SDK.
- [catalogue.json](https://www.playdrop.ai/pt-br/create/learn/catalogue-json): Os campos do catalogue.json que os jogos do PlayDrop usam: identidade, listagem, modos de jogo, superfícies, login, Instantâneo, pré-carregamento, mídia, traduções, pontuações e servidores.