管理手機控制器配對 | hyperPad Documentation
Logo
Documentation互動管理手機控制器配對
互動

管理手機控制器配對

Published 2026年10月1日
管理手機控制器配對

建立符合遊戲風格的配對畫面。Manage Phone Controller Pairing 會提供配對碼和待處理的請求，並可接受或拒絕手機。

你可以在 Interaction > Controls 找到它。若要開啟提供的畫面，請使用 Show Phone Controller Pairing。

Start 操作會接受請求並監看配對狀態的變化。使用請求的 peerID 搭配 Accept 或 Reject，並使用 Stop 關閉配對。這種行為讓你可以自行建立介面。若要開啟我們提供的完整畫面，請使用 Show Phone Controller Pairing。

連線

  • 輸入連線： 執行你選取的操作。
  • 輸出連線： 在操作執行後執行。使用 Start 時，只要此行為啟用期間配對資訊有變更，輸出也會執行。

Get Info 會讀取一次目前資訊。Start 會在配對碼就緒或請求清單變更時，持續更新你的 UI。

屬性

繪製的參考圖，顯示 Manage Phone Controller Pairing，Player 為 0、Operation 為 Get Info，且 Request ID 為空。

屬性指南。標籤和預設值與 Behavior Editor 相同。

  • Player (0 = next available)。預設值：0。Start 或 Accept 要求使用的玩家。0 會選擇下一個空位。正數則會要求使用指定的空位。
  • Operation。預設值：Get Info。選擇下方列出的操作。
  • Request ID。預設值：空白。使用 Accept 或 Reject 時，請填入所選待處理請求的 peerID。

已佔用的玩家空位不會自動替換。控制器連線後，請使用 Assign Controller 變更指派。

操作

  • Get Info： 讀取目前的配對資訊，但不開啟畫面或啟動工作階段。
  • Start： 開始接受請求，持續五分鐘。此行為啟用期間會監看配對狀態的變化。
  • Stop： 停止接受新請求。已接受的手機仍會保持連線。
  • Accept： 核准由 Request ID 指定的待處理請求。使用 Player 選擇空位。
  • Reject： 拒絕由 Request ID 指定的待處理請求。

請為 Start、Accept、Reject 和 Stop 按鈕分別使用獨立的行為。當畫面需要更新時，請保持 Start 行為啟用。停用後，更新也會停止。若要停止接受請求，請執行 Stop。

輸出

  • code（文字）：目前的六位數配對碼。線上配對碼準備期間，此欄位可能為空。
  • pairing（布林值）：遊戲是否正在接受新請求。
  • requests（陣列）：待處理的請求。每個項目都包含 peerID 和 name。
  • endpoint（文字）：配對 WebSocket 位址。如果自訂 UI 會產生配對 QR 碼，請搭配配對碼使用此位址。
  • message（文字）：回報的配對或連線錯誤。沒有回報錯誤時，此欄位為空。
  • expiresAt（數字）：配對到期時間，以 Unix 毫秒時間表示。
  • success（布林值）：是否沒有回報配對錯誤。這不代表手機已連線，也不代表選取的請求已獲接受。

若要取得連線事件，請使用 Controller Status。若要取得已連線裝置的清單，請使用 Get Controllers。requests 輸出包含等待核准的手機，因此它與已連線裝置清單不同。

範例：顯示配對碼

  1. 在配對畫面新增一個名為 Pairing Code 的 Label。
  2. 新增 Manage Phone Controller Pairing。將 Operation 設為 Start，並將 Player 設為 0。
  3. 新增 Set Label，並選取 Pairing Code 標籤作為 Object A。
  4. 使用輸出連線，將 Manage Phone Controller Pairing 連接到 Set Label。
  5. 將 Manage Phone Controller Pairing 的綠色輸出圖示拖曳到 Set Label 的 Text 欄位。選擇 code。

Manage Phone Controller Pairing 設為 Start，並觸發 Set Label；其 code 輸出被拖曳到 Text 欄位。

白色連線會執行 Set Label。綠色箭頭表示將輸出拖曳到 Text 欄位的另一個操作。

教學動畫顯示將 code 輸出拖曳到 Set Label 的 Text 欄位。

繪製的教學動畫。將輸出放入 Text 欄位後，請選擇 code。

執行遊戲。配對碼就緒時，標籤會更新。當 code 為空時，你可以顯示等待訊息。

範例：接受所選請求

  1. 執行 Start，並使用 requests 填入裝置清單。
  2. 在每個請求的列中顯示其 name，並將該列與對應的 peerID 一起保存。
  3. 在該列的 Accept 按鈕後方新增 Manage Phone Controller Pairing。將 Operation 設為 Accept。
  4. 將所選請求的 peerID 放入 Request ID。Player 保持為 0，或選擇一個空的玩家空位。
  5. 若要建立 Decline 按鈕，請使用另一個 Manage Phone Controller Pairing 行為，將 Operation 設為 Reject，並填入相同的 Request ID。

requests 是由字典組成的陣列。讀取所選項目，再讀取其 peerID 鍵。將該文字提供給 Request ID。把整個 requests 陣列拖曳到 Request ID，並不會選取特定手機。

請求 ID 用來識別等待核准的手機。核准後，請從 Get Controllers 或 Controller Status 讀取已連線控制器的 deviceID。搭配 Assign Controller 使用該裝置 ID。

自訂 QR 碼

如果你的 UI 有 QR 碼產生器，請使用下列欄位編碼 JSON 物件：

{
  "version": 1,
  "endpoint": "<endpoint output>",
  "code": "<code output>"
}

將兩個佔位符替換為此行為目前的輸出。code 就緒後，再產生 QR 碼。玩家可在 Controller Mode 中使用 Scan Pairing Code 掃描。提供的 Show Phone Controller Pairing 畫面會自動為你產生 QR 碼。

瀏覽器遊戲需要可用的線上配對服務。這些操作會使用該服務，但不會設定或部署服務。

配對之後

你的手機控制器可搭配 Controller Event、Map Control Inputs 和控制器選取行為使用。手機會顯示遊戲中該玩家使用的標準控制項。重新綁定控制器時，手機會顯示完整的控制配置，讓玩家選擇新的輸入。

你可以讓配對功能與控制項 UI 分開。Controls Overlay 可用來顯示及變更綁定。Rebind Input 則可讓你建立自己的綁定控制項。