# PlayDrop 遊戲中的本機派對、手把與手機控制器

透過 sdk.device 讀取實體手把與 PlayDrop 手機控制器，追蹤本機玩家插槽，並宣告控制器支援與本機派對人數。

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

本機派對是好幾個人在同一個螢幕上一起玩，每人一個控制器：可以是實體手把，或是掃描代碼後由 PlayDrop 變成控制器的手機。無論在網站或 App 中，你的遊戲都透過 SDK 以相同方式讀取每個控制器。

## 宣告控制器與派對人數

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

- `controller.support` 為 `off`、`optional` 或 `required`。每款遊戲都要宣告，包括 `off`。
- `controller.type` 指定遊戲所需的最低操控：`any`（方向、確認與取消）、`simpler`（一支搖桿、四個正面按鍵和選單鍵；手機控制器符合條件）或 `standard`（十字鍵、兩支可按壓的搖桿、四個正面按鍵、兩個肩鍵、兩個扳機和選單鍵）。
- `party.local` 列出同一螢幕上的確切玩家人數；`1` 需要 `solo` 類型。開啟控制器支援時，列出的每種人數都必須能用控制器遊玩。

## 讀取控制器

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

- 在 `init()` 之後呼叫一次 `enableControllerInput()`。主機端無法提供輸入時，它會以 `controller_input_unavailable` 或 `controller_input_timeout` 拒絕；遊戲會繼續執行。
- `gamepad(playerIndex)` 會以瀏覽器的標準配置傳回快照：`axes`（左 x/y、右 x/y，範圍 -1 到 1）、十七個 `buttons`、`source`（`physical` 或 `virtual`）和 `id`。`playerIndex` 為 0 代表玩家 1。
- 按鍵依位置命名，例如 `south` 和 `east`。`pad.label("south")` 會提供要顯示的提示：依控制器不同，可能是「A」、「Cross」或「B」。`pad.has("dpad")` 可判斷某個操控是否存在。
- 選單鍵和 Home 鍵屬於 PlayDrop，讀取時永遠是放開狀態。
- 絕不要呼叫 `navigator.getGamepads()`：手機控制器只能透過 SDK 傳到遊戲，而且 PlayDrop 會記錄警告。

## 本機玩家插槽

`sdk.device.localPlayers` 列出玩家選擇的插槽 `{ playerIndex, gamepadKey }`，`onLocalPlayersChange(callback)` 會回報變更。中斷連線的控制器會保留它的插槽。玩家名單變更或清空時，請回到合理的選單，而不是讓遊戲當掉。單獨一個控制器只是一般輸入，不是派對。

從按鈕呼叫 `sdk.social.openParty({ mode: "local" })`，會開啟 PlayDrop 的配對視窗，顯示手機 QR code 與已連接的手把。只提供你宣告過的模式。

## 本機或線上，不能兩者兼具

主機端會以本機派對或線上派對其中一種方式啟動遊戲，絕不會兩者同時：本機玩家無法加入線上房間。若要和朋友線上遊玩，請參閱[線上派對與語音](https://www.playdrop.ai/zh-hant/create/learn/online-party)。

## 為客廳沙發而設計

顯示每位玩家的顏色和控制器提示，讓任何人按下按鍵就能加入，並讓 HUD 從沙發上也看得清楚。單人遊玩時請保留觸控與鍵盤操控。

## 相關指南

- [線上派對與語音](https://www.playdrop.ai/zh-hant/create/learn/online-party): 讓朋友一起線上玩你的遊戲：宣告派對人數、開啟 PlayDrop 的派對視窗、用 sdk.multiplayer.join 加入預留的房間，並控制房間語音。
- [全螢幕與安全區域](https://www.playdrop.ai/zh-hant/create/learn/viewport): 讓 PlayDrop 遊戲填滿螢幕，並用 SDK 實際測量的 reservedCorners，讓 HUD 保持在 CSS 安全區域內、避開主機端的控制項。
- [catalogue.json](https://www.playdrop.ai/zh-hant/create/learn/catalogue-json): PlayDrop 遊戲使用的 catalogue.json 欄位：身分、上架資訊、遊玩方式、顯示環境、登入、即玩、預先載入、媒體、翻譯、分數與伺服器。