godot-docs/classes/class_multiplayerpeer.rst

:github_url: hide

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

.. _class_MultiplayerPeer:

MultiplayerPeer
===============

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

**Inherited By:** :ref:`ENetMultiplayerPeer<class_ENetMultiplayerPeer>`, :ref:`MultiplayerPeerExtension<class_MultiplayerPeerExtension>`, :ref:`WebRTCMultiplayerPeer<class_WebRTCMultiplayerPeer>`, :ref:`WebSocketMultiplayerPeer<class_WebSocketMultiplayerPeer>`

A high-level network interface to simplify multiplayer interactions.

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

Manages the connection to multiplayer peers. Assigns unique IDs to each client connected to the server. See also :ref:`MultiplayerAPI<class_MultiplayerAPI>`.

**Note:** The high-level multiplayer API protocol is an implementation detail and isn't meant to be used by non-Godot servers. It may change without notice.

**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.

Tutorials
---------

- :doc:`High-level multiplayer <../tutorials/networking/high_level_multiplayer>`

- `WebRTC Signaling Demo <https://godotengine.org/asset-library/asset/537>`__

Properties
----------

+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------+
| :ref:`bool<class_bool>`                             | :ref:`refuse_new_connections<class_MultiplayerPeer_property_refuse_new_connections>` | ``false`` |
+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------+
| :ref:`int<class_int>`                               | :ref:`transfer_channel<class_MultiplayerPeer_property_transfer_channel>`             | ``0``     |
+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------+
| :ref:`TransferMode<enum_@GlobalScope_TransferMode>` | :ref:`transfer_mode<class_MultiplayerPeer_property_transfer_mode>`                   | ``2``     |
+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------+

Methods
-------

+----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                                          | :ref:`generate_unique_id<class_MultiplayerPeer_method_generate_unique_id>` **(** **)** |const|            |
+----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| :ref:`ConnectionStatus<enum_MultiplayerPeer_ConnectionStatus>` | :ref:`get_connection_status<class_MultiplayerPeer_method_get_connection_status>` **(** **)** |const|      |
+----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                                          | :ref:`get_packet_peer<class_MultiplayerPeer_method_get_packet_peer>` **(** **)** |const|                  |
+----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                                          | :ref:`get_unique_id<class_MultiplayerPeer_method_get_unique_id>` **(** **)** |const|                      |
+----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| void                                                           | :ref:`poll<class_MultiplayerPeer_method_poll>` **(** **)**                                                |
+----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| void                                                           | :ref:`set_target_peer<class_MultiplayerPeer_method_set_target_peer>` **(** :ref:`int<class_int>` id **)** |
+----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+

Signals
-------

.. _class_MultiplayerPeer_signal_connection_failed:

- **connection_failed** **(** **)**

Emitted when a connection attempt fails.

----

.. _class_MultiplayerPeer_signal_connection_succeeded:

- **connection_succeeded** **(** **)**

Emitted when a connection attempt succeeds.

----

.. _class_MultiplayerPeer_signal_peer_connected:

- **peer_connected** **(** :ref:`int<class_int>` id **)**

Emitted by the server when a client connects.

----

.. _class_MultiplayerPeer_signal_peer_disconnected:

- **peer_disconnected** **(** :ref:`int<class_int>` id **)**

Emitted by the server when a client disconnects.

----

.. _class_MultiplayerPeer_signal_server_disconnected:

- **server_disconnected** **(** **)**

Emitted by clients when the server disconnects.

Enumerations
------------

.. _enum_MultiplayerPeer_ConnectionStatus:

.. _class_MultiplayerPeer_constant_CONNECTION_DISCONNECTED:

.. _class_MultiplayerPeer_constant_CONNECTION_CONNECTING:

.. _class_MultiplayerPeer_constant_CONNECTION_CONNECTED:

enum **ConnectionStatus**:

- **CONNECTION_DISCONNECTED** = **0** --- The ongoing connection disconnected.

- **CONNECTION_CONNECTING** = **1** --- A connection attempt is ongoing.

- **CONNECTION_CONNECTED** = **2** --- The connection attempt succeeded.

Constants
---------

.. _class_MultiplayerPeer_constant_TARGET_PEER_BROADCAST:

.. _class_MultiplayerPeer_constant_TARGET_PEER_SERVER:

- **TARGET_PEER_BROADCAST** = **0** --- Packets are sent to the server and then redistributed to other peers.

- **TARGET_PEER_SERVER** = **1** --- Packets are sent to the server alone.

Property Descriptions
---------------------

.. _class_MultiplayerPeer_property_refuse_new_connections:

- :ref:`bool<class_bool>` **refuse_new_connections**

+-----------+-----------------------------------+
| *Default* | ``false``                         |
+-----------+-----------------------------------+
| *Setter*  | set_refuse_new_connections(value) |
+-----------+-----------------------------------+
| *Getter*  | is_refusing_new_connections()     |
+-----------+-----------------------------------+

If ``true``, this ``MultiplayerPeer`` refuses new connections.

----

.. _class_MultiplayerPeer_property_transfer_channel:

- :ref:`int<class_int>` **transfer_channel**

+-----------+-----------------------------+
| *Default* | ``0``                       |
+-----------+-----------------------------+
| *Setter*  | set_transfer_channel(value) |
+-----------+-----------------------------+
| *Getter*  | get_transfer_channel()      |
+-----------+-----------------------------+

The channel to use to send packets. Many network APIs such as ENet and WebRTC allow the creation of multiple independent channels which behaves, in a way, like separate connections. This means that reliable data will only block delivery of other packets on that channel, and ordering will only be in respect to the channel the packet is being sent on. Using different channels to send **different and independent** state updates is a common way to optimize network usage and decrease latency in fast-paced games.

**Note:** The default channel (``0``) actually works as 3 separate channels (one for each :ref:`TransferMode<enum_@GlobalScope_TransferMode>`) so that :ref:`@GlobalScope.TRANSFER_MODE_RELIABLE<class_@GlobalScope_constant_TRANSFER_MODE_RELIABLE>` and :ref:`@GlobalScope.TRANSFER_MODE_UNRELIABLE_ORDERED<class_@GlobalScope_constant_TRANSFER_MODE_UNRELIABLE_ORDERED>` does not interact with each other by default. Refer to the specific network API documentation (e.g. ENet or WebRTC) to learn how to set up channels correctly.

----

.. _class_MultiplayerPeer_property_transfer_mode:

- :ref:`TransferMode<enum_@GlobalScope_TransferMode>` **transfer_mode**

+-----------+--------------------------+
| *Default* | ``2``                    |
+-----------+--------------------------+
| *Setter*  | set_transfer_mode(value) |
+-----------+--------------------------+
| *Getter*  | get_transfer_mode()      |
+-----------+--------------------------+

The manner in which to send packets to the ``target_peer``. See :ref:`TransferMode<enum_@GlobalScope_TransferMode>`.

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

.. _class_MultiplayerPeer_method_generate_unique_id:

- :ref:`int<class_int>` **generate_unique_id** **(** **)** |const|

Returns a randomly generated integer that can be used as a network unique ID.

----

.. _class_MultiplayerPeer_method_get_connection_status:

- :ref:`ConnectionStatus<enum_MultiplayerPeer_ConnectionStatus>` **get_connection_status** **(** **)** |const|

Returns the current state of the connection. See :ref:`ConnectionStatus<enum_MultiplayerPeer_ConnectionStatus>`.

----

.. _class_MultiplayerPeer_method_get_packet_peer:

- :ref:`int<class_int>` **get_packet_peer** **(** **)** |const|

Returns the ID of the ``MultiplayerPeer`` who sent the most recent packet.

----

.. _class_MultiplayerPeer_method_get_unique_id:

- :ref:`int<class_int>` **get_unique_id** **(** **)** |const|

Returns the ID of this ``MultiplayerPeer``.

----

.. _class_MultiplayerPeer_method_poll:

- void **poll** **(** **)**

Waits up to 1 second to receive a new network event.

----

.. _class_MultiplayerPeer_method_set_target_peer:

- void **set_target_peer** **(** :ref:`int<class_int>` id **)**

Sets the peer to which packets will be sent.

The ``id`` can be one of: :ref:`TARGET_PEER_BROADCAST<class_MultiplayerPeer_constant_TARGET_PEER_BROADCAST>` to send to all connected peers, :ref:`TARGET_PEER_SERVER<class_MultiplayerPeer_constant_TARGET_PEER_SERVER>` to send to the peer acting as server, a valid peer ID to send to that specific peer, a negative peer ID to send to all peers except that one. By default, the target peer is :ref:`TARGET_PEER_BROADCAST<class_MultiplayerPeer_constant_TARGET_PEER_BROADCAST>`.

.. |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.)`