Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

WebRTCPeerConnection

繼承： RefCounted < Object

被繼承： WebRTCPeerConnectionExtension

與 WebRTC 對等體連接的介面。

說明

A WebRTC connection between the local computer and a remote peer. Provides an interface to connect, maintain, and monitor the connection.

Setting up a WebRTC connection between two peers may not seem a trivial task, but it can be broken down into 3 main steps:

• The peer that wants to initiate the connection (A from now on) creates an offer and sends it to the other peer (B from now on).

• B receives the offer, generates an answer, and sends it to A.

• A and B then generate and exchange ICE candidates with each other.

After these steps, the connection should be established. Refer to the linked tutorials for details.

教學

• WebRTC documentation

• 高級多人遊戲

方法

Error	add_ice_candidate(media: String, index: int, name: String)
void	close()
WebRTCDataChannel	create_data_channel(label: String, options: Dictionary = {})
Error	create_offer()
ConnectionState	get_connection_state() const
GatheringState	get_gathering_state() const
SignalingState	get_signaling_state() const
Error	initialize(configuration: Dictionary = {})
Error	poll()
void	set_default_extension(extension_class: StringName) static
Error	set_local_description(type: String, sdp: String)
Error	set_remote_description(type: String, sdp: String)

---

訊號

data_channel_received(channel: WebRTCDataChannel) 🔗

當收到一個新的帶內通道時發出，即在通道是用negotiated: false（默認）。

該物件將是WebRTCDataChannel的一個實例。你必須保持它的引用，否則它將被自動關閉。參閱create_data_channel()。

---

ice_candidate_created(media: String, index: int, name: String) 🔗

當新的 ICE 候選者被建立時觸發。這三個參數是為了通過訊號伺服器傳遞給遠端對等體。

---

session_description_created(type: String, sdp: String) 🔗

在成功呼叫 create_offer() 或 set_remote_description() 後觸發，當它產生一個應答時。這些參數是為了傳遞給這個物件上的 set_local_description()，並通過訊號伺服器發送給遠端對等體。

---

列舉

enum ConnectionState: 🔗

ConnectionState STATE_NEW = 0

連接是新的，資料通道和提交可以在這種狀態下建立。

ConnectionState STATE_CONNECTING = 1

對等體正在連接，ICE 正在進行中，沒有任何傳輸失敗。

ConnectionState STATE_CONNECTED = 2

對等體已連接，所有的 ICE 傳輸都已連接。

ConnectionState STATE_DISCONNECTED = 3

至少有一個 ICE 傳輸被斷開連接。

ConnectionState STATE_FAILED = 4

一個或更多的 ICE 傳輸失敗。

ConnectionState STATE_CLOSED = 5

對等連接已關閉，例如在呼叫 close() 後。

---

enum GatheringState: 🔗

GatheringState GATHERING_STATE_NEW = 0

對等體連接剛剛建立，還沒有做任何聯網工作。

GatheringState GATHERING_STATE_GATHERING = 1

ICE 代理正在收集候選連接。

GatheringState GATHERING_STATE_COMPLETE = 2

ICE 代理已完成候選連接的收集。如果發生了需要收集新候選的情況，例如新新增了接口、新新增了 ICE 伺服器，則會返回收集狀態，進行候選項的收集。

---

enum SignalingState: 🔗

SignalingState SIGNALING_STATE_STABLE = 0

沒有正在進行的要約和答覆的交換。這可能意味著 WebRTCPeerConnection 是新的（STATE_NEW），或者協商已完成並且連接已經建立（STATE_CONNECTED）。

SignalingState SIGNALING_STATE_HAVE_LOCAL_OFFER = 1

本地對等體已呼叫 set_local_description()，正在傳入代表邀約的 SDP（通常由呼叫 create_offer() 建立），邀約已成功套用。

SignalingState SIGNALING_STATE_HAVE_REMOTE_OFFER = 2

遠端對等體已建立邀約，並將其使用訊號伺服器傳遞給了本地對等體，本地對等體已調用 set_remote_description() 將邀約設定為遠程描述。

SignalingState SIGNALING_STATE_HAVE_LOCAL_PRANSWER = 3

已套用遠端對等體發送的邀約，已建立恢復並呼叫了 set_local_description() 進行套用。這個臨時應答描述了支援的媒體格式等資訊，但可能不包含完整的 ICE 候選項。後續會單獨發送更多候選項。

SignalingState SIGNALING_STATE_HAVE_REMOTE_PRANSWER = 4

已經接收到初步回應，並已成功地套用到之前通過呼叫 set_local_description() 發送並建立的邀請中。

SignalingState SIGNALING_STATE_CLOSED = 5

該 WebRTCPeerConnection 已關閉連接。

---

方法說明

Error add_ice_candidate(media: String, index: int, name: String) 🔗

新增一個由遠端對等體產生的凍結候選，並通過信令伺服器接收。請參閱ice_candidate_created。

---

void close() 🔗

關閉對等體連接和與之相關的所有資料通道。

注意：你不能為一個新的連接重複使用這個物件，除非你呼叫 initialize()。

---

WebRTCDataChannel create_data_channel(label: String, options: Dictionary = {}) 🔗

返回新的 WebRTCDataChannel，或在失敗時返回 null，具有給定的 label，並通過 options 字典進行配置。這個方法只有在連接處於 STATE_NEW 狀態時才能被呼叫。

有兩種方法來建立工作資料通道：要麼只在其中一個對等體上呼叫 create_data_channel()，並在另一個對等體上監聽data_channel_received，要麼在兩個對等體上呼叫 create_data_channel()，數值相同，並將 "negotiated" 選項設定為 true。

有效的 options 是：

{
    "negotiated": true, # 當設定為 "true"時，預設關閉，意味著該通道是在頻帶外協商的。"id"也必須被設定。"data_channel_received" 將不會被呼叫。
    "id":1, # 當 "negotiated"為真時，這個值也必須被設定為兩個對等體的相同值。

    # 只能指定maxRetransmits和maxPacketLifeTime中的一個，不能同時指定。它們會使通道變得不可靠，但在即時性方面會更好。
    "maxRetransmits":1, # 指定對等體在封包未被確認時嘗試重傳的最大次數。
    "maxPacketLifeTime":100, # 指定放棄重傳未被確認的封包之前的最大時間，以毫秒為單位。
    "ordered": true, # 當處於不可靠模式時，即 "maxRetransmits "或 "maxPacketLifetime "被設定，"ordered"指定是否要強制執行封包排序，預設為true。

    "protocol":"my-custom-protocol", # 這個通道的自訂子協定字串。
}

注意：你必須保持對以這種方式建立的通道的引用，否則它將被關閉。

---

Error create_offer() 🔗

建立一個新的 SDP 提交，以開始與遠端對等體的 WebRTC 連接。在呼叫此方法之前，至少要建立一個 WebRTCDataChannel。

如果這個函式返回 @GlobalScope.OK，當會話準備好被發送時，session_description_created 將被呼叫。

---

ConnectionState get_connection_state() const 🔗

Returns the connection state.

---

GatheringState get_gathering_state() const 🔗

返回連接的 ICE GatheringState。你可以據此來偵測，例如，ICE 候選項的收集是否完成。

---

SignalingState get_signaling_state() const 🔗

Returns the signaling state on the local end of the connection while connecting or reconnecting to another peer.

---

Error initialize(configuration: Dictionary = {}) 🔗

重新初始化這個對等體連接，關閉任何先前活動的連接，並回到 STATE_NEW 狀態。傳入配置選項字典 configuration 能夠對該對等體連接進行配置。

有效的 configuration 選項有：

{
    "iceServers": [
        {
            "urls": [ "stun:stun.example.com:3478" ], # 若干 STUN 服務器。
        },
        {
            "urls": [ "turn:turn.example.com:3478" ], # 若干 TURN 服務器。
            "username": "a_username", # TURN 伺服器的使用者名，選填。
            "credential": "a_password", # TURN 伺服器的密碼，選填。
        }
    ]
}

---

Error poll() 🔗

經常呼叫這個方法以正確接收訊號，例如在 Node._process() 或 Node._physics_process() 中。

---

void set_default_extension(extension_class: StringName) static 🔗

將 extension_class 設定為建立新 WebRTCPeerConnection 時返回的預設 WebRTCPeerConnectionExtension。

---

Error set_local_description(type: String, sdp: String) 🔗

設定本地對等體的 SDP 描述。這應是在回應 session_description_created 時呼叫的。

呼叫此函式後，對等體將開始發出 ice_candidate_created，除非返回與 @GlobalScope.OK 不同的 Error。

---

Error set_remote_description(type: String, sdp: String) 🔗

設定遠程對等體的 SDP 描述。套用遠端對等體產生的值來呼叫，並通過訊號伺服器接收。

如果 type 為 "offer"，對等體將發出 session_description_created 並給出適當的應答。

如果 type 為 "answer"，對等體將開始發出 ice_candidate_created。