/dedicated-server

name: dedicated-server
description: Use when building dedicated servers — headless export, server architecture, lobby management, and deployment

Dedicated Server in Godot 4.3+

All examples target Godot 4.3+ with no deprecated APIs. GDScript is shown first, C# follows.

**Related skills:** See **multiplayer-basics** for ENet setup, RPCs, and authority model. See **multiplayer-sync** for state synchronization and interpolation.

---

1. Headless Export

A dedicated server runs without a display, GPU, or audio device. Godot supports this through the `--headless` flag and a dedicated export preset.

--headless Flag

Pass `--headless` on the command line to suppress the display and audio drivers at runtime:

./my_game.x86_64 --headless

`--headless` is a runtime flag that works on any exported binary. Godot 4 has no separate server platform or server export template: a dedicated-server export uses the regular template, so the binary keeps its rendering code (a smaller binary needs a custom-compiled template). What the export changes is the PCK and a feature tag — see below.

Server Export Preset

In the Godot editor, create a dedicated **Linux** export preset:

1. Open **Project → Export**. 2. Add a **Linux** preset and name it `Linux Server`. 3. On the **Resources** tab, set **Export Mode** to **Export as dedicated server**. This adds the `dedicated_server` feature tag — which makes the binary start with the headless display and dummy audio drivers even without `--headless` — and marks `res://` as **Strip Visuals**: visual resources are exported as placeholders (e.g. a texture keeps only its size). Set folders the server needs intact to **Keep**. 4. Use the **Exclude** filter on the same tab to drop client-only files (audio, client-only scenes) from the server PCK entirely.

Feature Tags

Use `OS.has_feature()` to branch between server and client code at runtime. Define a custom `server` feature on the export preset's **Features** tab (**Custom (comma-separated)** field) or rely on the built-in `dedicated_server` feature that a dedicated-server export sets automatically:

# boot.gd — autoload, runs before any scene loads
extends Node

func _ready() -> void:
    if OS.has_feature("dedicated_server") or DisplayServer.get_name() == "headless":
        # Disable rendering-dependent systems
        RenderingServer.set_render_loop_enabled(false)
        # Start server logic
        ServerBootstrap.start()
    else:
        # Start client logic
        ClientBootstrap.start()

// Boot.cs — autoload, runs before any scene loads.
using Godot;

public partial class Boot : Node
{
    public override void _Ready()
    {
        if (OS.HasFeature("dedicated_server") || DisplayServer.GetName() == "headless")
        {
            // Disable the render loop. The window is invisible but the engine still ticks.
            RenderingServer.SetRenderLoopEnabled(false);
            ServerBootstrap.Start();
        }
        else
        {
            ClientBootstrap.Start();
        }
    }
}

> **Note:** the export preset configuration (custom features, exclude filter, "Export as dedicated server" mode) is identical regardless of language — see the GDScript section above for preset settings.

**Feature tag summary:**

| Tag | Set by | Notes | |-----|--------|-------| | `dedicated_server` | Dedicated-server export | Most reliable way to detect a server binary | | *(no tag)* `--headless` | CLI flag | Not a feature tag — `OS.has_feature("headless")` is `false`; check `DisplayServer.get_name() == "headless"` | | Custom `server` | Your export preset's Custom Features | Useful when sharing a binary between roles |

---

2. Server Architecture

Game Loop Without Rendering

On a headless server, `_process` and `_physics_process` still run normally — but nothing is rendered. Keep all server logic in `_physics_process` for deterministic, fixed-rate updates.

GDScript

# server_main.gd — add as autoload named ServerMain
extends Node

## Physics frames per second — matches Project Settings → Physics → Common → Physics Ticks Per Second.
## Override via --tick-rate CLI argument (see Section 5).
var tick_rate: int = 60

## Current server tick counter.
var server_tick: int = 0


func _ready() -> void:
    # Guard: this node does nothing on the client.
    if not _is_server():
        set_process(false)
        set_physics_process(false)
        return

    Engine.physics_ticks_per_second = tick_rate
    print("[Server] Started — tick rate: %d Hz" % tick_rate)


func _physics_process(_delta: float) -> void:
    server_tick += 1
    _tick_game_logic()


func _tick_game_logic() -> void:
    # All authoritative game simulation goes here.
    # Never reference Camera, CanvasLayer, or any rendering node from this path.
    pass


## Returns true when this process is acting as the authoritative server.
func _is_server() -> bool:
    # Covers both: dedicated binary and hosted listen-server.
    return multiplayer.is_server()

Server-Only Logic Separated from Client

Structure your scenes so server-only nodes are in a dedicated branch and skipped on clients:

# world.gd
extends Node

@onready var server_systems: Node = $ServerSystems   # physics, AI, scoring
@onready var client_systems: Node = $ClientSystems   # camera, HUD, audio


func _ready() -> void:
    # Disable server systems on clients and vice versa.
    server_systems.set_process_mode(
        PROCESS_MODE_ALWAYS if multiplayer.is_server() else PROCESS_MODE_DISABLED
    )
    client_systems.set_process_mode(
        PROCESS_MODE_DISABLED if multiplayer.is_server() else PROCESS_MODE_ALWAYS
    )

Engine.is_editor_hint() + is_server Checks

Use these guards at the top of scripts that must behave differently in the editor, on the server, and on clients:

func _ready() -> void:
    if Engine.is_editor_hint():
        return  # Skip all runtime setup in