遊戲體驗

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

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

本機派對是好幾個人在同一個螢幕上一起玩，每人一個控制器：可以是實體手把，或是掃描代碼後由 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 類型。開啟控制器支援時，列出的每種人數都必須能用控制器遊玩。

讀取控制器

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 與已連接的手把。只提供你宣告過的模式。

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

主機端會以本機派對或線上派對其中一種方式啟動遊戲，絕不會兩者同時：本機玩家無法加入線上房間。若要和朋友線上遊玩，請參閱線上派對與語音。

為客廳沙發而設計

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