Multiplayer & Networking

Relevant source files

• core/io/http_client.cpp
• core/io/http_client.h
• core/io/http_client_tcp.cpp
• core/io/http_client_tcp.h
• doc/classes/HTTPClient.xml
• doc/classes/HTTPRequest.xml
• editor/export/export_template_manager.cpp
• editor/export/export_template_manager.h
• modules/gridmap/icons/GridMapDock.svg
• modules/multiplayer/SCsub
• modules/multiplayer/doc_classes/MultiplayerSpawner.xml
• modules/multiplayer/doc_classes/MultiplayerSynchronizer.xml
• modules/multiplayer/doc_classes/SceneMultiplayer.xml
• modules/multiplayer/doc_classes/SceneReplicationConfig.xml
• modules/multiplayer/editor/editor_network_profiler.cpp
• modules/multiplayer/editor/editor_network_profiler.h
• modules/multiplayer/editor/multiplayer_editor_plugin.cpp
• modules/multiplayer/editor/multiplayer_editor_plugin.h
• modules/multiplayer/editor/replication_editor.cpp
• modules/multiplayer/editor/replication_editor.h
• modules/multiplayer/icons/ReplicationDock.svg
• modules/multiplayer/multiplayer_debugger.cpp
• modules/multiplayer/multiplayer_debugger.h
• modules/multiplayer/multiplayer_spawner.cpp
• modules/multiplayer/multiplayer_spawner.h
• modules/multiplayer/multiplayer_synchronizer.cpp
• modules/multiplayer/multiplayer_synchronizer.h
• modules/multiplayer/register_types.cpp
• modules/multiplayer/scene_cache_interface.cpp
• modules/multiplayer/scene_cache_interface.h
• modules/multiplayer/scene_multiplayer.cpp
• modules/multiplayer/scene_multiplayer.h
• modules/multiplayer/scene_replication_config.cpp
• modules/multiplayer/scene_replication_config.h
• modules/multiplayer/scene_replication_interface.cpp
• modules/multiplayer/scene_replication_interface.h
• modules/multiplayer/scene_rpc_interface.cpp
• modules/multiplayer/scene_rpc_interface.h
• modules/multiplayer/tests/test_multiplayer_spawner.h
• modules/multiplayer/tests/test_scene_multiplayer.h
• scene/main/http_request.cpp
• scene/main/http_request.h

Godot provides a multi-layered networking stack ranging from low-level TCP/UDP/HTTP protocols to a high-level "Scene Replication" system. The architecture is designed to abstract the underlying transport layer, allowing developers to swap between ENet, WebSockets, or WebRTC without rewriting game logic.

High-Level Multiplayer

The high-level multiplayer system is built directly into the Node hierarchy and managed by the MultiplayerAPI. It provides a server-authoritative model by default but supports various topologies. The system relies on NodePath consistency across connected peers to identify which objects should receive data or execute commands.

Core Components

• MultiplayerAPI: The interface that manages the network life cycle, including peer connections and packet dispatching modules/multiplayer/scene_multiplayer.h40-41
• SceneMultiplayer: The default implementation of MultiplayerAPI that handles the heavy lifting of RPCs and replication modules/multiplayer/scene_multiplayer.cpp31
• RPC (Remote Procedure Call): A mechanism to call functions on remote peers using the rpc method on any Node modules/multiplayer/scene_rpc_interface.cpp31
• Scene Replication: Automates the synchronization of node properties and the spawning/despawning of nodes across the network using MultiplayerSpawner modules/multiplayer/multiplayer_spawner.cpp31 and MultiplayerSynchronizer modules/multiplayer/multiplayer_synchronizer.cpp31

System Architecture: High-Level Networking

Sources: modules/multiplayer/scene_multiplayer.h40-41 modules/multiplayer/scene_multiplayer.cpp31 modules/multiplayer/scene_rpc_interface.cpp31 modules/multiplayer/multiplayer_spawner.cpp31 modules/multiplayer/multiplayer_synchronizer.cpp31 modules/multiplayer/scene_replication_interface.cpp129-154

For details on replication and RPC configuration, see High-Level Multiplayer.

Network Transport Layer

Godot abstracts low-level networking through the MultiplayerPeer class. This allows the high-level system to remain agnostic of the specific protocol used (e.g., UDP vs. WebSockets).

Transport Options

• ENet: A UDP-based protocol providing reliability and sequencing features, typically used for desktop games.
• WebSocket: Used primarily for web-based games or tools requiring firewall-friendly connections.
• WebRTC: Designed for peer-to-peer (P2P) communication, essential for web-based multiplayer without a dedicated relay server.
• HTTP: Managed via HTTPClient and HTTPRequest for RESTful API interactions, such as fetching player profiles or leaderboards core/io/http_client.h37

Transport Abstraction Map

Sources: modules/multiplayer/scene_multiplayer.h40-41 core/io/http_client.h37 modules/multiplayer/scene_multiplayer.cpp73-89

For details on configuring specific protocols and handling low-level packets, see Network Transport Layer.

Low-Level Networking APIs

Godot provides several classes for direct low-level network communication, allowing fine-grained control over data transmission via PacketPeer and StreamPeer implementations.

UDP and TCP

• PacketPeerUDP: Handles connectionless UDP packets. It supports multicast groups and broadcast.
• StreamPeerTCP: Provides a stream-oriented connection over TCP.

HTTPClient and HTTPRequest

The HTTP system allows for web communication, supporting both raw management and node-based automation.

• HTTPClient: A low-level, RefCounted client for HTTP/1.1 core/io/http_client.h37 It defines common HTTP methods such as GET, POST, and PUT core/io/http_client.cpp35-45
  • connect_to_host(host, port, tls_options): Initiates connection core/io/http_client.cpp143
  • poll(): Updates the internal state machine core/io/http_client.cpp164
• HTTPRequest: A Node wrapper for HTTPClient that simplifies common tasks like downloading files to disk scene/main/http_request.h86-89 and handling redirects automatically scene/main/http_request.h102-106
  • request(): Parses URLs and manages the client lifecycle scene/main/http_request.cpp109-122
  • cancel_request(): Properly cleans up threads and files scene/main/http_request.cpp192-216

HTTP Request Workflow

Sources: scene/main/http_request.cpp42-44 core/io/http_client.cpp143-147 scene/main/http_request.h179-180 core/io/http_client.h168-169

Security and TLS

Godot uses mbedTLS as the backend for secure communication. TLSOptions objects are used to configure how clients and servers verify identities.

• TLSOptions::client(): Returns a default client configuration for secure HTTPS connections.
• TLSOptions::client_unsafe(): Allows connecting to servers with self-signed certificates (not recommended for production).

Sources: core/io/http_client.cpp35-45 scene/main/http_request.cpp109-122 core/io/http_client.h37 scene/main/http_request.h86-89 scene/main/http_request.h102-106 scene/main/http_request.cpp192-216