:github_url: hide

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

.. _class_MultiplayerAPI:

MultiplayerAPI
==============

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

High-level multiplayer API.

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

This class implements the high-level multiplayer API. See also :ref:`MultiplayerPeer<class_MultiplayerPeer>`.

By default, :ref:`SceneTree<class_SceneTree>` has a reference to this class that is used to provide multiplayer capabilities (i.e. RPCs) across the whole scene.

It is possible to override the MultiplayerAPI instance used by specific Nodes by setting the :ref:`Node.custom_multiplayer<class_Node_property_custom_multiplayer>` property, effectively allowing to run both client and server in the same scene.

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

Properties
----------

+-----------------------------------------------+-------------------------------------------------------------------------------------+------------------+
| :ref:`bool<class_bool>`                       | :ref:`allow_object_decoding<class_MultiplayerAPI_property_allow_object_decoding>`   | ``false``        |
+-----------------------------------------------+-------------------------------------------------------------------------------------+------------------+
| :ref:`MultiplayerPeer<class_MultiplayerPeer>` | :ref:`multiplayer_peer<class_MultiplayerAPI_property_multiplayer_peer>`             |                  |
+-----------------------------------------------+-------------------------------------------------------------------------------------+------------------+
| :ref:`bool<class_bool>`                       | :ref:`refuse_new_connections<class_MultiplayerAPI_property_refuse_new_connections>` | ``false``        |
+-----------------------------------------------+-------------------------------------------------------------------------------------+------------------+
| :ref:`NodePath<class_NodePath>`               | :ref:`root_path<class_MultiplayerAPI_property_root_path>`                           | ``NodePath("")`` |
+-----------------------------------------------+-------------------------------------------------------------------------------------+------------------+

Methods
-------

+-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                            | :ref:`clear<class_MultiplayerAPI_method_clear>` **(** **)**                                                                                                                                                                                        |
+-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`PackedInt32Array<class_PackedInt32Array>` | :ref:`get_peers<class_MultiplayerAPI_method_get_peers>` **(** **)** |const|                                                                                                                                                                        |
+-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                           | :ref:`get_remote_sender_id<class_MultiplayerAPI_method_get_remote_sender_id>` **(** **)** |const|                                                                                                                                                  |
+-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                           | :ref:`get_unique_id<class_MultiplayerAPI_method_get_unique_id>` **(** **)** |const|                                                                                                                                                                |
+-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                         | :ref:`has_multiplayer_peer<class_MultiplayerAPI_method_has_multiplayer_peer>` **(** **)** |const|                                                                                                                                                  |
+-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                         | :ref:`is_server<class_MultiplayerAPI_method_is_server>` **(** **)** |const|                                                                                                                                                                        |
+-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                            | :ref:`poll<class_MultiplayerAPI_method_poll>` **(** **)**                                                                                                                                                                                          |
+-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Error<enum_@GlobalScope_Error>`           | :ref:`send_bytes<class_MultiplayerAPI_method_send_bytes>` **(** :ref:`PackedByteArray<class_PackedByteArray>` bytes, :ref:`int<class_int>` id=0, :ref:`TransferMode<enum_@GlobalScope_TransferMode>` mode=2, :ref:`int<class_int>` channel=0 **)** |
+-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Signals
-------

.. _class_MultiplayerAPI_signal_connected_to_server:

- **connected_to_server** **(** **)**

Emitted when this MultiplayerAPI's :ref:`multiplayer_peer<class_MultiplayerAPI_property_multiplayer_peer>` successfully connected to a server. Only emitted on clients.

----

.. _class_MultiplayerAPI_signal_connection_failed:

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

Emitted when this MultiplayerAPI's :ref:`multiplayer_peer<class_MultiplayerAPI_property_multiplayer_peer>` fails to establish a connection to a server. Only emitted on clients.

----

.. _class_MultiplayerAPI_signal_peer_connected:

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

Emitted when this MultiplayerAPI's :ref:`multiplayer_peer<class_MultiplayerAPI_property_multiplayer_peer>` connects with a new peer. ID is the peer ID of the new peer. Clients get notified when other clients connect to the same server. Upon connecting to a server, a client also receives this signal for the server (with ID being 1).

----

.. _class_MultiplayerAPI_signal_peer_disconnected:

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

Emitted when this MultiplayerAPI's :ref:`multiplayer_peer<class_MultiplayerAPI_property_multiplayer_peer>` disconnects from a peer. Clients get notified when other clients disconnect from the same server.

----

.. _class_MultiplayerAPI_signal_peer_packet:

- **peer_packet** **(** :ref:`int<class_int>` id, :ref:`PackedByteArray<class_PackedByteArray>` packet **)**

Emitted when this MultiplayerAPI's :ref:`multiplayer_peer<class_MultiplayerAPI_property_multiplayer_peer>` receives a ``packet`` with custom data (see :ref:`send_bytes<class_MultiplayerAPI_method_send_bytes>`). ID is the peer ID of the peer that sent the packet.

----

.. _class_MultiplayerAPI_signal_server_disconnected:

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

Emitted when this MultiplayerAPI's :ref:`multiplayer_peer<class_MultiplayerAPI_property_multiplayer_peer>` disconnects from server. Only emitted on clients.

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

.. _class_MultiplayerAPI_property_allow_object_decoding:

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

+-----------+----------------------------------+
| *Default* | ``false``                        |
+-----------+----------------------------------+
| *Setter*  | set_allow_object_decoding(value) |
+-----------+----------------------------------+
| *Getter*  | is_object_decoding_allowed()     |
+-----------+----------------------------------+

If ``true``, the MultiplayerAPI will allow encoding and decoding of object during RPCs.

\ **Warning:** Deserialized objects can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats such as remote code execution.

----

.. _class_MultiplayerAPI_property_multiplayer_peer:

- :ref:`MultiplayerPeer<class_MultiplayerPeer>` **multiplayer_peer**

+----------+-----------------------------+
| *Setter* | set_multiplayer_peer(value) |
+----------+-----------------------------+
| *Getter* | get_multiplayer_peer()      |
+----------+-----------------------------+

The peer object to handle the RPC system (effectively enabling networking when set). Depending on the peer itself, the MultiplayerAPI will become a network server (check with :ref:`is_server<class_MultiplayerAPI_method_is_server>`) and will set root node's network mode to authority, or it will become a regular client peer. All child nodes are set to inherit the network mode by default. Handling of networking-related events (connection, disconnection, new clients) is done by connecting to MultiplayerAPI's signals.

----

.. _class_MultiplayerAPI_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``, the MultiplayerAPI's :ref:`multiplayer_peer<class_MultiplayerAPI_property_multiplayer_peer>` refuses new incoming connections.

----

.. _class_MultiplayerAPI_property_root_path:

- :ref:`NodePath<class_NodePath>` **root_path**

+-----------+----------------------+
| *Default* | ``NodePath("")``     |
+-----------+----------------------+
| *Setter*  | set_root_path(value) |
+-----------+----------------------+
| *Getter*  | get_root_path()      |
+-----------+----------------------+

The root path to use for RPCs and replication. Instead of an absolute path, a relative path will be used to find the node upon which the RPC should be executed.

This effectively allows to have different branches of the scene tree to be managed by different MultiplayerAPI, allowing for example to run both client and server in the same scene.

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

.. _class_MultiplayerAPI_method_clear:

- void **clear** **(** **)**

Clears the current MultiplayerAPI network state (you shouldn't call this unless you know what you are doing).

----

.. _class_MultiplayerAPI_method_get_peers:

- :ref:`PackedInt32Array<class_PackedInt32Array>` **get_peers** **(** **)** |const|

Returns the peer IDs of all connected peers of this MultiplayerAPI's :ref:`multiplayer_peer<class_MultiplayerAPI_property_multiplayer_peer>`.

----

.. _class_MultiplayerAPI_method_get_remote_sender_id:

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

Returns the sender's peer ID for the RPC currently being executed.

\ **Note:** If not inside an RPC this method will return 0.

----

.. _class_MultiplayerAPI_method_get_unique_id:

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

Returns the unique peer ID of this MultiplayerAPI's :ref:`multiplayer_peer<class_MultiplayerAPI_property_multiplayer_peer>`.

----

.. _class_MultiplayerAPI_method_has_multiplayer_peer:

- :ref:`bool<class_bool>` **has_multiplayer_peer** **(** **)** |const|

Returns ``true`` if there is a :ref:`multiplayer_peer<class_MultiplayerAPI_property_multiplayer_peer>` set.

----

.. _class_MultiplayerAPI_method_is_server:

- :ref:`bool<class_bool>` **is_server** **(** **)** |const|

Returns ``true`` if this MultiplayerAPI's :ref:`multiplayer_peer<class_MultiplayerAPI_property_multiplayer_peer>` is valid and in server mode (listening for connections).

----

.. _class_MultiplayerAPI_method_poll:

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

Method used for polling the MultiplayerAPI. You only need to worry about this if you are using :ref:`Node.custom_multiplayer<class_Node_property_custom_multiplayer>` override or you set :ref:`SceneTree.multiplayer_poll<class_SceneTree_property_multiplayer_poll>` to ``false``. By default, :ref:`SceneTree<class_SceneTree>` will poll its MultiplayerAPI for you.

\ **Note:** This method results in RPCs being called, so they will be executed in the same context of this function (e.g. ``_process``, ``physics``, :ref:`Thread<class_Thread>`).

----

.. _class_MultiplayerAPI_method_send_bytes:

- :ref:`Error<enum_@GlobalScope_Error>` **send_bytes** **(** :ref:`PackedByteArray<class_PackedByteArray>` bytes, :ref:`int<class_int>` id=0, :ref:`TransferMode<enum_@GlobalScope_TransferMode>` mode=2, :ref:`int<class_int>` channel=0 **)**

Sends the given raw ``bytes`` to a specific peer identified by ``id`` (see :ref:`MultiplayerPeer.set_target_peer<class_MultiplayerPeer_method_set_target_peer>`). Default ID is ``0``, i.e. broadcast to all peers.

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