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

Hérite de : RefCounted < Object

Hérité par : WebRTCPeerConnectionExtension

L'interface de connexion par pair via WebRTC.

Description

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.

Tutoriels

• Documentation WebRTC

• API multijoueur de haut niveau

Méthodes

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)

---

Signaux

data_channel_received(channel: WebRTCDataChannel) 🔗

Emitted when a new in-band channel is received, i.e. when the channel was created with negotiated: false (default).

The object will be an instance of WebRTCDataChannel. You must keep a reference of it or it will be closed automatically. See create_data_channel().

---

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

Emitted when a new ICE candidate has been created. The three parameters are meant to be passed to the remote peer over the signaling server.

---

session_description_created(type: String, sdp: String) 🔗

Emitted after a successful call to create_offer() or set_remote_description() (when it generates an answer). The parameters are meant to be passed to set_local_description() on this object, and sent to the remote peer over the signaling server.

---

Énumérations

enum ConnectionState: 🔗

ConnectionState STATE_NEW = 0

La connexion est nouvelle, les canaux de données et une offre peut être créée dans cet état.

ConnectionState STATE_CONNECTING = 1

Le pair se connecte, ICE est en cours, aucun des transports n’a échoué.

ConnectionState STATE_CONNECTED = 2

Le pair est connecté, tous les transports ICE sont connectés.

ConnectionState STATE_DISCONNECTED = 3

Au moins un transport ICE est déconnecté.

ConnectionState STATE_FAILED = 4

Un ou plusieurs des transports ICE ont échoué.

ConnectionState STATE_CLOSED = 5

La connexion par les pairs est fermée (après avoir appelé close() par exemple).

---

enum GatheringState: 🔗

GatheringState GATHERING_STATE_NEW = 0

The peer connection was just created and hasn't done any networking yet.

GatheringState GATHERING_STATE_GATHERING = 1

The ICE agent is in the process of gathering candidates for the connection.

GatheringState GATHERING_STATE_COMPLETE = 2

The ICE agent has finished gathering candidates. If something happens that requires collecting new candidates, such as a new interface being added or the addition of a new ICE server, the state will revert to gathering to gather those candidates.

---

enum SignalingState: 🔗

SignalingState SIGNALING_STATE_STABLE = 0

There is no ongoing exchange of offer and answer underway. This may mean that the WebRTCPeerConnection is new (STATE_NEW) or that negotiation is complete and a connection has been established (STATE_CONNECTED).

SignalingState SIGNALING_STATE_HAVE_LOCAL_OFFER = 1

The local peer has called set_local_description(), passing in SDP representing an offer (usually created by calling create_offer()), and the offer has been applied successfully.

SignalingState SIGNALING_STATE_HAVE_REMOTE_OFFER = 2

The remote peer has created an offer and used the signaling server to deliver it to the local peer, which has set the offer as the remote description by calling set_remote_description().

SignalingState SIGNALING_STATE_HAVE_LOCAL_PRANSWER = 3

The offer sent by the remote peer has been applied and an answer has been created and applied by calling set_local_description(). This provisional answer describes the supported media formats and so forth, but may not have a complete set of ICE candidates included. Further candidates will be delivered separately later.

SignalingState SIGNALING_STATE_HAVE_REMOTE_PRANSWER = 4

A provisional answer has been received and successfully applied in response to an offer previously sent and established by calling set_local_description().

SignalingState SIGNALING_STATE_CLOSED = 5

La WebRTCPeerConnection a été fermée.

---

Descriptions des méthodes

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

Ajoute un candidat de glace généré par un pair distant (et reçu sur le serveur de signalisation). Voir ice_candidate_created.

---

void close() 🔗

Ferme la connexion de ce pair et tous les canaux de données lui étant associés.

Note : Vous ne pouvez pas réutiliser cet objet pour une nouvelle connexion sans appeler initialize().

---

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

Renvoie un nouveau WebRTCDataChannel (ou null lors d'un échec) avec une étiquette label donnée et optionnellement configuré via le dictionnaire options. Cette méthode peut seulement être appelée lorsque la connexion est dans l'état STATE_NEW.

Il y a deux façons de créer un canal de données fonctionnel : soit appeler create_data_channel() sur un seul de ses pairs et écouter data_channel_received sur l'autre, ou appeler create_data_channel() sur les deux pairs, avec les mêmes valeurs, et l'option "negotiated" définie à true..

Les options valides sont :

{
    "negotiated": true, # Quand défini à true (false par défaut), signifie que le canal est négocié hors bande. "id" doit être aussi défini. "data_channel_received" ne sera pas appelé.
    "id": 1, # Quand "negotiated" vaut true, cette valeur doit aussi être définie à la même valeur sur les deux pairs.

    # Seul un entre maxRetransmits et maxPacketLifeTime peut être spécifié, pas les deux. Ils rendent le canal moins fiable (mais aussi meilleur en temps réel).
    "maxRetransmits": 1, # Spécifiez le nombre maximum d'essais que le pair va faire pour retransmettre les paquets s'ils ne sont pas reconnus.
    "maxPacketLifeTime": 100, # Spécifiez la quantité maximale de temps avant de renoncer à des retransmissions de paquets non reconnus (en millisecondes).
    "ordered": true, # Quand en mode non fiable (c.-à-d. "maxRetransmits" ou "maxPacketLifetime" est défini), "ordered" (true par défaut) spécifie si l'ordre des paquets doit être imposée.

    "protocol": "my-custom-protocol", # Une chaîne de sous-protocole personnalisée pour ce canal.
}

Note : Vous devez garder une référence aux canaux créés de cette façon, ou ils seront fermés.

---

Error create_offer() 🔗

Crée une nouvelle offre SDP pour démarrer une connexion WebRTC avec un pair distant. Au moins un WebRTCDataChannel doit avoir été créé avant d’appeler cette méthode.

Si cette fonction renvoie @GlobalScope.OK, session_description_created sera appelé lorsque la session est prête à être envoyée.

---

ConnectionState get_connection_state() const 🔗

Returns the connection state.

---

GatheringState get_gathering_state() const 🔗

Returns the ICE GatheringState of the connection. This lets you detect, for example, when collection of ICE candidates has finished.

---

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 = {}) 🔗

Ré-initialise la connexion de ce pair, fermant n'importe quelle précédente connexion active, et retourne à l'état STATE_NEW. Un dictionnaire d'options de configuration peut être passé pour configurer la connexion du pair.

Les options de configuration valides sont :

{
    "iceServers": [
        {
            "urls": [ "stun:stun.example.com:3478" ], # Un ou plusieurs serveurs STUN.
        },
        {
            "urls": [ "turn:turn.example.com:3478" ], # Un ou plusieurs serveurs TURN.
            "username": "un_nom_utilisateur", # Le nom d'utilisateur facultatif pour le serveur TURN.
            "credential": "un_mot_de_passe", # Le mot de passe facultatif pour le serveur TURN.
        }
    ]
}

---

Error poll() 🔗

Appelez cette méthode fréquemment (par ex. dans Node._process() ou Node._physics_process()) pour recevoir correctement les signaux.

---

void set_default_extension(extension_class: StringName) static 🔗

Sets the extension_class as the default WebRTCPeerConnectionExtension returned when creating a new WebRTCPeerConnection.

---

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

Sets the SDP description of the local peer. This should be called in response to session_description_created.

After calling this function the peer will start emitting ice_candidate_created (unless an Error different from @GlobalScope.OK is returned).

---

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

Sets the SDP description of the remote peer. This should be called with the values generated by a remote peer and received over the signaling server.

If type is "offer" the peer will emit session_description_created with the appropriate answer.

If type is "answer" the peer will start emitting ice_candidate_created.