godot-docs/classes/class_webrtcmultiplayerpeer.rst

:github_url: hide

.. Generated automatically by doc/tools/make_rst.py in Godot's source tree.
.. DO NOT EDIT THIS FILE, but the WebRTCMultiplayerPeer.xml source instead.
.. The source is found in doc/classes or modules/<name>/doc_classes.

.. _class_WebRTCMultiplayerPeer:

WebRTCMultiplayerPeer
=====================

**Inherits:** :ref:`MultiplayerPeer<class_MultiplayerPeer>` **<** :ref:`PacketPeer<class_PacketPeer>` **<** :ref:`RefCounted<class_RefCounted>` **<** :ref:`Object<class_Object>`

A simple interface to create a peer-to-peer mesh network composed of :ref:`WebRTCPeerConnection<class_WebRTCPeerConnection>` that is compatible with the :ref:`MultiplayerAPI<class_MultiplayerAPI>`.

Description
-----------

This class constructs a full mesh of :ref:`WebRTCPeerConnection<class_WebRTCPeerConnection>` (one connection for each peer) that can be used as a :ref:`MultiplayerAPI.multiplayer_peer<class_MultiplayerAPI_property_multiplayer_peer>`.

You can add each :ref:`WebRTCPeerConnection<class_WebRTCPeerConnection>` via :ref:`add_peer<class_WebRTCMultiplayerPeer_method_add_peer>` or remove them via :ref:`remove_peer<class_WebRTCMultiplayerPeer_method_remove_peer>`. Peers must be added in :ref:`WebRTCPeerConnection.STATE_NEW<class_WebRTCPeerConnection_constant_STATE_NEW>` state to allow it to create the appropriate channels. This class will not create offers nor set descriptions, it will only poll them, and notify connections and disconnections.

\ :ref:`MultiplayerPeer.connection_succeeded<class_MultiplayerPeer_signal_connection_succeeded>` and :ref:`MultiplayerPeer.server_disconnected<class_MultiplayerPeer_signal_server_disconnected>` will not be emitted unless ``server_compatibility`` is ``true`` in :ref:`initialize<class_WebRTCMultiplayerPeer_method_initialize>`. Beside that data transfer works like in a :ref:`MultiplayerPeer<class_MultiplayerPeer>`.

\ **Note:** When exporting to Android, make sure to enable the ``INTERNET`` permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android.

Methods
-------

+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`add_peer<class_WebRTCMultiplayerPeer_method_add_peer>` **(** :ref:`WebRTCPeerConnection<class_WebRTCPeerConnection>` peer, :ref:`int<class_int>` peer_id, :ref:`int<class_int>` unreliable_lifetime=1 **)** |
+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                  | :ref:`close<class_WebRTCMultiplayerPeer_method_close>` **(** **)**                                                                                                                                                |
+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Dictionary<class_Dictionary>`   | :ref:`get_peer<class_WebRTCMultiplayerPeer_method_get_peer>` **(** :ref:`int<class_int>` peer_id **)**                                                                                                            |
+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Dictionary<class_Dictionary>`   | :ref:`get_peers<class_WebRTCMultiplayerPeer_method_get_peers>` **(** **)**                                                                                                                                        |
+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`               | :ref:`has_peer<class_WebRTCMultiplayerPeer_method_has_peer>` **(** :ref:`int<class_int>` peer_id **)**                                                                                                            |
+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`initialize<class_WebRTCMultiplayerPeer_method_initialize>` **(** :ref:`int<class_int>` peer_id, :ref:`bool<class_bool>` server_compatibility=false, :ref:`Array<class_Array>` channels_config=[] **)**      |
+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                  | :ref:`remove_peer<class_WebRTCMultiplayerPeer_method_remove_peer>` **(** :ref:`int<class_int>` peer_id **)**                                                                                                      |
+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Method Descriptions
-------------------

.. _class_WebRTCMultiplayerPeer_method_add_peer:

- :ref:`Error<enum_@GlobalScope_Error>` **add_peer** **(** :ref:`WebRTCPeerConnection<class_WebRTCPeerConnection>` peer, :ref:`int<class_int>` peer_id, :ref:`int<class_int>` unreliable_lifetime=1 **)**

Add a new peer to the mesh with the given ``peer_id``. The :ref:`WebRTCPeerConnection<class_WebRTCPeerConnection>` must be in state :ref:`WebRTCPeerConnection.STATE_NEW<class_WebRTCPeerConnection_constant_STATE_NEW>`.

Three channels will be created for reliable, unreliable, and ordered transport. The value of ``unreliable_lifetime`` will be passed to the ``maxPacketLifetime`` option when creating unreliable and ordered channels (see :ref:`WebRTCPeerConnection.create_data_channel<class_WebRTCPeerConnection_method_create_data_channel>`).

----

.. _class_WebRTCMultiplayerPeer_method_close:

- void **close** **(** **)**

Close all the add peer connections and channels, freeing all resources.

----

.. _class_WebRTCMultiplayerPeer_method_get_peer:

- :ref:`Dictionary<class_Dictionary>` **get_peer** **(** :ref:`int<class_int>` peer_id **)**

Returns a dictionary representation of the peer with given ``peer_id`` with three keys. ``connection`` containing the :ref:`WebRTCPeerConnection<class_WebRTCPeerConnection>` to this peer, ``channels`` an array of three :ref:`WebRTCDataChannel<class_WebRTCDataChannel>`, and ``connected`` a boolean representing if the peer connection is currently connected (all three channels are open).

----

.. _class_WebRTCMultiplayerPeer_method_get_peers:

- :ref:`Dictionary<class_Dictionary>` **get_peers** **(** **)**

Returns a dictionary which keys are the peer ids and values the peer representation as in :ref:`get_peer<class_WebRTCMultiplayerPeer_method_get_peer>`.

----

.. _class_WebRTCMultiplayerPeer_method_has_peer:

- :ref:`bool<class_bool>` **has_peer** **(** :ref:`int<class_int>` peer_id **)**

Returns ``true`` if the given ``peer_id`` is in the peers map (it might not be connected though).

----

.. _class_WebRTCMultiplayerPeer_method_initialize:

- :ref:`Error<enum_@GlobalScope_Error>` **initialize** **(** :ref:`int<class_int>` peer_id, :ref:`bool<class_bool>` server_compatibility=false, :ref:`Array<class_Array>` channels_config=[] **)**

Initialize the multiplayer peer with the given ``peer_id`` (must be between 1 and 2147483647).

If ``server_compatibilty`` is ``false`` (default), the multiplayer peer will be immediately in state :ref:`MultiplayerPeer.CONNECTION_CONNECTED<class_MultiplayerPeer_constant_CONNECTION_CONNECTED>` and :ref:`MultiplayerPeer.connection_succeeded<class_MultiplayerPeer_signal_connection_succeeded>` will not be emitted.

If ``server_compatibilty`` is ``true`` the peer will suppress all :ref:`MultiplayerPeer.peer_connected<class_MultiplayerPeer_signal_peer_connected>` signals until a peer with id :ref:`MultiplayerPeer.TARGET_PEER_SERVER<class_MultiplayerPeer_constant_TARGET_PEER_SERVER>` connects and then emit :ref:`MultiplayerPeer.connection_succeeded<class_MultiplayerPeer_signal_connection_succeeded>`. After that the signal :ref:`MultiplayerPeer.peer_connected<class_MultiplayerPeer_signal_peer_connected>` will be emitted for every already connected peer, and any new peer that might connect. If the server peer disconnects after that, signal :ref:`MultiplayerPeer.server_disconnected<class_MultiplayerPeer_signal_server_disconnected>` will be emitted and state will become :ref:`MultiplayerPeer.CONNECTION_CONNECTED<class_MultiplayerPeer_constant_CONNECTION_CONNECTED>`.

You can optionally specify a ``channels_config`` array of :ref:`TransferMode<enum_@GlobalScope_TransferMode>` which will be used to create extra channels (WebRTC only supports one transfer mode per channel).

----

.. _class_WebRTCMultiplayerPeer_method_remove_peer:

- void **remove_peer** **(** :ref:`int<class_int>` peer_id **)**

Remove the peer with given ``peer_id`` from the mesh. If the peer was connected, and :ref:`MultiplayerPeer.peer_connected<class_MultiplayerPeer_signal_peer_connected>` was emitted for it, then :ref:`MultiplayerPeer.peer_disconnected<class_MultiplayerPeer_signal_peer_disconnected>` will be emitted.

.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`
.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`
.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`