godot-server-architecture

Skill boundary (Do NOT Load)

Do NOT Load lobby/RPC tutorial scripts from multiplayer-networking when only booting a host — follow Host Golden Path here first.

Host Golden Path (MANDATORY)

1. Headless detect/init — MANDATORY [headlessinitmanager.gd](scripts/headlessinitmanager.gd) (--headless / dedicated_server feature).
2. Safe decode — MANDATORY [safepacketdecoder.gd](scripts/safepacketdecoder.gd) before any untrusted get_var.
3. Host peer — [enetoptimizedhost.gd](scripts/enetoptimizedhost.gd); add [dtlssecureserver.gd](scripts/dtlssecureserver.gd) when encrypting UDP.
4. Authority — [serverauthorityvalidator.gd](scripts/serverauthorityvalidator.gd) on every privileged RPC.
5. Ops — [peerkickmanager.gd](scripts/peerkickmanager.gd), [serverhealthexporter.gd](scripts/serverhealthexporter.gd); matchmaker handoff via [servermatchmakerclient.gd](scripts/servermatchmakerclient.gd).

Available Scripts

[headlessinitmanager.gd](scripts/headlessinitmanager.gd)

Detect/initialize dedicated server logic for --headless / dedicated_server.

[headlessmanager.gd](scripts/headlessmanager.gd)

Headless runtime manager companion patterns.

[enetoptimizedhost.gd](scripts/enetoptimizedhost.gd)

High-performance ENet UDP hosts with bandwidth/client limits.

[dtlssecureserver.gd](scripts/dtlssecureserver.gd)

DTLS + X509 hardening for ENet UDP.

[safepacketdecoder.gd](scripts/safepacketdecoder.gd)

Forbid object decoding on untrusted packets (RCE guard).

[manualnetworkpoll.gd](scripts/manualnetworkpoll.gd)

Manual multiplayer.poll() when auto-poll is disabled.

[isolatedmultiplayerapi.gd](scripts/isolatedmultiplayerapi.gd)

Isolated MultiplayerAPI instances (client+server in one process).

[serverauthorityvalidator.gd](scripts/serverauthorityvalidator.gd)

getremotesender_id() gates for authoritative requests.

[websocketservercompat.gd](scripts/websocketservercompat.gd)

HTML5-compatible WebSocketMultiplayerPeer hosts.

[peerkickmanager.gd](scripts/peerkickmanager.gd)

Graceful peer termination with reason propagation.

[servermatchmakerclient.gd](scripts/servermatchmakerclient.gd)

Load-balancer / matchmaker handoff to game hosts.

[serverhealthexporter.gd](scripts/serverhealthexporter.gd)

Headless telemetry for monitoring stacks.

[physicsserverdirect.gd](scripts/physicsserverdirect.gd) / [ridperformanceserver.gd](scripts/ridperformanceserver.gd)

Optional host-side RID sim — only when node physics cannot hold tick budget: > ~200 active bodies per tick, or headless host CPU > 70% on physics step with nodes. Criteria: profile first; if SceneTree bodies dominate, prefer godot-performance-optimization. Do NOT Load RID scripts for ≤64 entity lobbies.

NEVER Do in Server Architecture (Host)

• NEVER trust the client — Validate state, purchases, and damage on the authoritative host.
• NEVER use TRANSFERMODERELIABLE for continuous streams — Prefer unreliable for high-rate transforms.
• NEVER use getvar(true) on untrusted packets — Object decode = RCE. MANDATORY safepacket_decoder.
• NEVER use TCP for fast-paced action — Prefer ENet UDP (or WebSocket for HTML5 constraints).
• NEVER run a dedicated server without stripping visuals — Dedicated Server export / dummy drivers.
• NEVER expect RPCs before connectedtoserver / peer ready.
• NEVER assume UNRELIABLE packets arrive in order.
• NEVER leave SceneTree.multiplayer_poll false without manual poll().
• NEVER mix incompatible engine/multiplayer protocol versions across peers.
• NEVER forget free_rid on server-created RIDs if the host uses Physics/RenderingServer pools.

Host Patterns

Interest management

Large worlds: MultiplayerSynchronizer.public_visibility = false + visibility filters (AABB / grid) so the host does not sync the entire world to every peer.

# Hook on synchronizer — filter peers by grid cell / AABB (no full tutorial)
func _visibility_filter(for_peer: int, node: Node) -> bool:
	return _interest_grid.is_visible_to_peer(for_peer, node.global_position)
# Assign: synchronizer.set_visibility_filter(_visibility_filter)

Health metrics

Watch host FPS, static memory (RID leaks), and orphan counts via [serverhealthexporter.gd](scripts/serverhealthexporter.gd).

Deep recipes (on demand)

LLM-ignorance rule: if a general agent would not know it before reading, it lives here or in scripts/ — never delete, only move.

Reference

Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Using Servers — RID-based RenderingServer/PhysicsServer/NavigationServer workflow when SceneTree nodes are too slow.
• RenderingServer — canvasitem / instance / free_rid for procedural draw and mesh swarms without MeshInstance nodes.
• PhysicsServer3D — bodycreate, space binding, and direct-state queries for headless authoritative simulation.
• PhysicsServer2D — 2D body/shape RIDs mirroring the same SceneTree-bypass pattern.
• RID — opaque server handles; every *create() needs a matching free_rid to avoid leaks.
• High-level multiplayer — authority, RPCs, and peer lifecycle for dedicated hosts and isolated MultiplayerAPI branches.
• ENetMultiplayerPeer — UDP host creation, channels/bandwidth limits, and DTLS host setup on peer.host.
• WebSocket multiplayer — browser-compatible peer path when ENet UDP is unavailable (HTML5 clients).
• Exporting for dedicated servers — dedicated-server export presets and stripping visuals/audio for production hosts.
• Command line tutorial — --headless and CLI flags used by headless init/managers.
• Binary serialization API — get_var(false) / object-decoding rules that block RCE on untrusted packets.
• DTLSServer — DTLS accept path complementary to ENet dtlsserver_setup with X509/TLSOptions.

Related Skills

Prerequisites

• godot-project-foundations — project layout, Autoloads, and feature tags that dedicated-server and headless launches depend on.
• godot-gdscript-mastery — typed RID arrays, @rpc annotations, and safe Variant decoding patterns used across server scripts.
• godot-physics-3d — node-level PhysicsBody3D/space concepts before bypassing them with PhysicsServer3D RIDs.

Complements

• godot-multiplayer-networking — lobby/RPC/synchronizer toolkit that sits on the headless ENet/WebSocket hosts this skill scaffolds.
• godot-adapt-single-to-multiplayer — authority split and prediction shells before wiring dedicated-server validation and interest filters.
• godot-export-builds — dedicated-server export presets and CLI packaging for real multi-instance host tests.
• godot-2d-physics — PhysicsServer2D body/shape patterns for 2D authoritative swarms without SceneTree bodies.
• godot-navigation-pathfinding — NavigationServer RIDs and bake updates when AI agents share the same low-level server path.
• godot-performance-optimization — budgets and profiling that decide when RID servers beat nodes under peer/object load.
• godot-debugging-profiling — Performance monitors and remote debug habits for headless FPS/memory/orphan telemetry.
• godot-platform-web — HTML5 client constraints that force WebSocketMultiplayerPeer instead of ENet.

Downstream / consumers

• godot-procedural-generation — mass object/voxel spawners that consume RenderingServer/PhysicsServer RID pools.
• godot-monte-carlo-balancer — retune economy/TTK after authoritative server tick rates or validation change effective combat windows.
• godot-genre-battle-royale — large-peer dedicated hosts that need interest grids, kick/health exporters, and RID-scale sim.

Master

• godot-master — library router and mirrored module entry; open when discovering which Domain Skill owns a cross-cutting server concern.