Networking Multiplayer

Networking & Multiplayer (Godot 4.x)

Complete reference for building multiplayer games in Godot 4.x. Covers the high-level multiplayer API, RPCs, synchronization nodes, dedicated servers, and network architecture patterns.

When to Use

Use this skill whenever you are:

• Adding online multiplayer or LAN play to a Godot 4.x project
• Implementing RPCs (@rpc annotation, rpc(), rpc_id())
• Setting up dedicated servers (headless mode, --server CLI flag)
• Using MultiplayerSpawner or MultiplayerSynchronizer nodes
• Building lobbies, matchmaking, or ready-check systems
• Implementing client-side prediction or lag compensation
• Making REST API calls via HTTPRequest or WebSocket clients
• Integrating GodotSteam for Steam relay / NAT traversal
• Debugging desyncs, connection drops, or bandwidth issues

Trigger keywords: multiplayer, networking, RPC, dedicated server, lobby, sync, ENet, WebSocket, WebRTC, peer, authority, client-side prediction, lag compensation, HTTPRequest, GodotSteam, NAT traversal.

Prerequisites

• Godot 4.x (4.0 or later). The MultiplayerAPI redesign is 4.x-only; Godot 3.x uses a different API.

• Basic familiarity with GDScript, scenes, and node architecture. See gdscript and scene-and-nodes.

• For dedicated server deployment: a machine or VPS reachable on your chosen port with firewall rules opened.

• For Steam networking: the GodotSteam plugin compiled into your editor and export templates.

• Windows host (primary): Commands below assume PowerShell. On Windows, use godot.exe or add the Godot binary to your PATH. Example:

  godot --headless --path ~\projects\my-game
  

Procedure

1. Choose a transport peer

2. Create a server

func create_server(port: int = 9999, max_clients: int = 32) -> void:
    var peer := ENetMultiplayerPeer.new()
    var error: Error = peer.create_server(port, max_clients)
    if error != OK:
        push_error("Failed to create server: %s" % error_string(error))
        return
    multiplayer.multiplayer_peer = peer
    print("Server started on port %d" % port)

3. Create a client

func join_server(address: String = "127.0.0.1", port: int = 9999) -> void:
    var peer := ENetMultiplayerPeer.new()
    var error: Error = peer.create_client(address, port)
    if error != OK:
        push_error("Failed to connect: %s" % error_string(error))
        return
    multiplayer.multiplayer_peer = peer

4. Wire up connection signals

func _ready() -> void:
    multiplayer.peer_connected.connect(_on_peer_connected)
    multiplayer.peer_disconnected.connect(_on_peer_disconnected)
    multiplayer.connected_to_server.connect(_on_connected_to_server)      # client only
    multiplayer.connection_failed.connect(_on_connection_failed)            # client only
    multiplayer.server_disconnected.connect(_on_server_disconnected)        # client only

func _on_peer_connected(id: int) -> void:
    print("Peer connected: %d" % id)

func _on_peer_disconnected(id: int) -> void:
    print("Peer disconnected: %d" % id)
    # Clean up the disconnected player's nodes
    var player_node: Node = get_node_or_null(str(id))
    if player_node:
        player_node.queue_free()

func _on_connected_to_server() -> void:
    print("Connected! My ID: %d" % multiplayer.get_unique_id())

5. Define RPCs with @rpc

# @rpc annotation parameters:
# authority mode: "any_peer" or "authority" (default)
# sync mode:     "call_local" or "call_remote" (default)
# transfer mode: "reliable" (default), "unreliable", "unreliable_ordered"
# channel:       0-255 (separate channels for independent ordering)

@rpc("any_peer", "call_local", "reliable")
func chat_message(message: String) -> void:
    var sender_id: int = multiplayer.get_remote_sender_id()
    display_chat(sender_id, message)

# Call an RPC:
chat_message.rpc("Hello everyone!")          # call on ALL peers
chat_message.rpc_id(1, "Hello server!")      # call on specific peer (1 = server)

# Authority-only RPC (only server can call):
@rpc("authority", "call_remote", "reliable")
func update_score(player_id: int, score: int) -> void:
    scores[player_id] = score
    update_scoreboard()

# Unreliable RPC for frequent updates:
@rpc("authority", "call_remote", "unreliable_ordered")
func sync_position(pos: Vector2) -> void:
    global_position = pos

6. Validate ALL client-sent RPCs on the server

HARD RULE: Never trust the client. Every @rpc("any_peer", ...) handler must validate the sender and the requested action on the server before executing or broadcasting.

@rpc("any_peer", "call_local", "reliable")
func request_action(action: String, target_id: int) -> void:
    if not multiplayer.is_server():
        return

    var sender: int = multiplayer.get_remote_sender_id()

    # Validate the sender is allowed to do this
    if not is_valid_action(sender, action, target_id):
        push_warning("Invalid action from peer %d" % sender)
        return

    # Execute on server, then broadcast result to all
    perform_action.rpc(sender, action, target_id)

7. Spawn players with MultiplayerSpawner

Scene structure (all peers):

World
  ├── MultiplayerSpawner
  └── Players (Node — spawn path)

MultiplayerSpawner configuration:

• Spawn Path: ../Players (where spawned scenes are added)
• Auto Spawn List: add PackedScene resources that can be spawned
• OR use spawn_function for custom spawning

func _ready() -> void:
    if multiplayer.is_server():
        multiplayer.peer_connected.connect(_on_peer_connected)

func _on_peer_connected(id: int) -> void:
    spawn_player(id)

func spawn_player(id: int) -> void:
    var player: CharacterBody2D = preload("res://player.tscn").instantiate()
    player.name = str(id)  # name MUST be unique!
    $Players.add_child(player)  # spawner auto-replicates to clients

Custom spawn function:

@onready var spawner: MultiplayerSpawner = $MultiplayerSpawner

func _ready() -> void:
    spawner.spawn_function = custom_spawn

func custom_spawn(data: Variant) -> Node:
    var player_data: Dictionary = data as Dictionary
    var player: CharacterBody2D = preload("res://player.tscn").instantiate()
    player.name = str(player_data["id"])
    player.global_position = player_data["position"]
    player.set_multiplayer_authority(player_data["id"])
    return player

# Trigger spawn (server only):
func spawn_player(id: int, pos: Vector2) -> void:
    spawner.spawn({"id": id, "position": pos})

8. Sync properties with MultiplayerSynchronizer

Scene structure:

Player (CharacterBody2D)
  ├── MultiplayerSynchronizer
  ├── Sprite2D
  └── CollisionShape2D

Replication config — add properties with sync modes:

Visibility filters (only sync to peers that can "see" this object):

@onready var sync: MultiplayerSynchronizer = $MultiplayerSynchronizer

func _ready() -> void:
    if multiplayer.is_server():
        sync.set_visibility_for(peer_id, true)   # enable for specific peer
        sync.set_visibility_for(peer_id, false)  # disable

# Custom visibility check:
sync.visibility_update_mode = MultiplayerSynchronizer.VISIBILITY_PROCESS_IDLE
sync.add_visibility_filter(func(peer: int) -> bool:
    var peer_pos: Vector2 = get_peer_position(peer)
    return global_position.distance_to(peer_pos) < 1000.0
)

9. Set authority correctly

# Set authority (who controls this node):
player_node.set_multiplayer_authority(peer_id)

# Check authority:
if is_multiplayer_authority():
    # This peer controls this node — process input, send updates
    handle_input()

# Transfer authority (e.g., player picks up object):
func pick_up(object: Node) -> void:
    if multiplayer.is_server():
        object.set_multiplayer_authority(multiplayer.get_unique_id())

10. Run a dedicated server (headless mode)

Windows (PowerShell):

godot --headless --path ~\projects\my-game

Linux/macOS:

godot --headless --path /path/to/project

Detect headless mode in code:

func _ready() -> void:
    if DisplayServer.get_name() == "headless":
        # Headless mode — start as server
        create_server()
    else:
        # Graphical mode — show lobby UI
        show_lobby_menu()

# Alternative: use command-line arguments
func _ready() -> void:
    if "--server" in OS.get_cmdline_args():
        create_server()

11. Build a lobby system

# Autoload: LobbyManager
extends Node

signal player_list_updated(players: Dictionary)

var players: Dictionary = {}  # { peer_id: { "name": String, "ready": bool } }

func _ready() -> void:
    multiplayer.peer_connected.connect(_on_peer_connected)
    multiplayer.peer_disconnected.connect(_on_peer_disconnected)

@rpc("any_peer", "call_local", "reliable")
func register_player(player_name: String) -> void:
    var id: int = multiplayer.get_remote_sender_id()
    players[id] = {"name": player_name, "ready": false}
    sync_player_list.rpc(players)

@rpc("any_peer", "call_local", "reliable")
func set_ready(ready: bool) -> void:
    var id: int = multiplayer.get_remote_sender_id()
    if id in players:
        players[id]["ready"] = ready
        sync_player_list.rpc(players)
        check_all_ready()

@rpc("authority", "call_local", "reliable")
func sync_player_list(updated_players: Dictionary) -> void:
    players = updated_players
    player_list_updated.emit(players)

func check_all_ready() -> void:
    if not multiplayer.is_server():
        return
    if players.size() < 2:
        return
    for player_data: Dictionary in players.values():
        if not player_data["ready"]:
            return
    start_game.rpc()

@rpc("authority", "call_local", "reliable")
func start_game() -> void:
    get_tree().change_scene_to_packed(preload("res://game.tscn"))

12. Implement client-side prediction

Concept: client moves immediately, server validates, client corrects if wrong.

extends CharacterBody2D

var server_position: Vector2 = Vector2.ZERO
var correction_threshold: float = 5.0

func _physics_process(delta: float) -> void:
    if is_multiplayer_authority():
        # Local prediction — move immediately
        var input_dir: Vector2 = Input.get_vector("left", "right", "up", "down")
        velocity = input_dir * speed
        move_and_slide()

        # Send input to server
        send_input.rpc_id(1, input_dir)
    else:
        # Interpolate to last known position (other players)
        global_position = global_position.lerp(server_position, 10.0 * delta)

@rpc("any_peer", "call_remote", "unreliable_ordered")
func send_input(input_dir: Vector2) -> void:
    if not multiplayer.is_server():
        return
    # Server validates and applies movement
    velocity = input_dir * speed
    move_and_slide()
    # Broadcast authoritative position
    sync_position.rpc(global_position)

@rpc("authority", "call_remote", "unreliable_ordered")
func sync_position(pos: Vector2) -> void:
    server_position = pos
    # Snap if too far off (correction)
    if global_position.distance_to(pos) > correction_threshold:
        global_position = pos

13. Make REST API calls with HTTPRequest

@onready var http: HTTPRequest = $HTTPRequest

func _ready() -> void:
    http.request_completed.connect(_on_request_completed)

func fetch_leaderboard() -> void:
    var error: Error = http.request(
        "https://api.example.com/leaderboard",
        ["Authorization: Bearer %s" % api_key],
        HTTPClient.METHOD_GET
    )

func post_score(score: int) -> void:
    var body: String = JSON.stringify({"score": score})
    http.request(
        "https://api.example.com/scores",
        ["Content-Type: application/json"],
        HTTPClient.METHOD_POST,
        body
    )

func _on_request_completed(
    result: int,
    response_code: int,
    headers: PackedStringArray,
    body: PackedByteArray
) -> void:
    if result != HTTPRequest.RESULT_SUCCESS:
        push_error("HTTP request failed: %d" % result)
        return
    var json: Variant = JSON.parse_string(body.get_string_from_utf8())
    process_response(json)

Security: Never hardcode API keys in source. Use YOUR_KEY placeholders in examples and load real keys from environment variables or a .env file excluded from version control.

14. Use a WebSocket client

var ws := WebSocketPeer.new()

func _ready() -> void:
    ws.connect_to_url("wss://echo.websocket.org")

func _process(_delta: float) -> void:
    ws.poll()
    var state: WebSocketPeer.State = ws.get_ready_state()

    if state == WebSocketPeer.STATE_OPEN:
        while ws.get_available_packet_count() > 0:
            var packet: PackedByteArray = ws.get_packet()
            handle_message(packet.get_string_from_utf8())

    elif state == WebSocketPeer.STATE_CLOSED:
        var code: int = ws.get_close_code()
        print("WebSocket closed: %d" % code)
        set_process(false)

func send_message(msg: String) -> void:
    ws.send_text(msg)

15. Test multiplayer locally

From the editor: Debug > Run Multiple Instances > set to 2, 3, or 4.

From command line (Windows PowerShell):

# Instance 1 (server):
godot --path . -- --server

# Instance 2 (client):
godot --path . -- --client

Parse custom args:

func _ready() -> void:
    var args: PackedStringArray = OS.get_cmdline_user_args()
    if "--server" in args:
        create_server()
    elif "--client" in args:
        join_server()

Pitfalls

Verification

Run through this checklist to confirm your multiplayer implementation is correct and secure:

• Server validates ALL client inputs — never trust the client. Every @rpc("any_peer") handler checks multiplayer.is_server() and validates the sender.
• Unique node names for multiplayer-spawned nodes (use peer ID as the node name).
• Authority set correctly on player nodes via set_multiplayer_authority(peer_id).
• Connection signals handle disconnection cleanup (peer_disconnected → queue_free).
• RPCs use appropriate transfer mode — reliable for important events, unreliable_ordered for position.
• MultiplayerSynchronizer uses visibility filters for large worlds.
• Dedicated server uses headless mode (--headless).
• Port forwarding or relay service configured for WAN play (default port 9999 in examples — change for production).
• Lobby waits for all players to be ready before starting.
• Timeouts handle unresponsive peers gracefully.

Quick verification commands

Check that a server is listening on port 9999 (Windows PowerShell):

netstat -an | findstr 9999

Expected output (server running):

TCP    0.0.0.0:9999    0.0.0.0:0    LISTENING

Check that a client can reach the server:

Test-NetConnection -ComputerName 127.0.0.1 -Port 9999

Expected: TcpTestSucceeded : True

Verify headless server starts without errors:

godot --headless --path ~\projects\my-game 2>&1 | Select-Object -First 20

Look for Server started on port 9999 in the output.

Run two instances locally for integration testing:

# Terminal 1 — server
godot --path . -- --server

# Terminal 2 — client
godot --path . -- --client

Confirm both terminals print Peer connected: <id> and the client prints Connected! My ID: <id>.

Related Skills

• GDScript fundamentals → gdscript
• Export for dedicated server → export-and-deployment
• Performance optimization → performance-optimization
• Scene architecture → scene-and-nodes