godot-server-architecture

$npx mdskill add thedivergentai/GD-Agentic-Skills/godot-server-architecture

Build authoritative dedicated multiplayer hosts with ENet/DTLS and telemetry.

  • Solves headless server boot, authority validation, and safe packet decoding.
  • Depends on ENet, DTLS, WebSocketMultiplayerPeer, and Godot 4.7+.
  • Recommends patterns based on dedicated host role and network hardening needs.
  • Delivers blueprints for matchmaker handoff, health telemetry, and kick logic.

SKILL.md

.github/skills/godot-server-architectureView on GitHub ↗
---
name: godot-server-architecture
description: "Expert blueprint for dedicated / headless multiplayer hosts: ENet/DTLS, authority validation, safe packet decode, matchmaker handoff, and health telemetry. Use when building authoritative servers, --headless hosts, or hardening host networking. Keywords: dedicated server, headless, ENet, DTLS, authority, safe_packet_decoder, multiplayer host, WebSocketMultiplayerPeer."
---

## Godot 4.7 Baseline

- Expert patterns in this skill target **Godot 4.7+** (stable, 2026-06-18).
- Consult the [Godot 4.7 migration guide](https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.7.html) when upgrading projects from 4.6.
- **NEVER** assume 4.6 defaults (stretch mode, audio area_mask, RichTextLabel percent flags) without checking 4.7 migration notes.

# Server Architecture (Dedicated Host)

Authoritative **multiplayer host** patterns — headless boot, ENet/DTLS, packet safety, kicks, and telemetry.

> RID SceneTree-bypass rendering/physics swarms belong in [godot-performance-optimization](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-performance-optimization/SKILL.md) (and `physics_server_direct.gd` / `rid_performance_server.gd` only when the host sim truly needs server RIDs). Lobby/RPC gameplay APIs: [godot-multiplayer-networking](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-multiplayer-networking/SKILL.md).

## Skill boundary (Do NOT Load)

| Use **this skill** for | Use **godot-multiplayer-networking** for |
| :--- | :--- |
| `--headless` / dedicated export boot | Lobby UI, matchmaking UX, friend invites |
| ENet/DTLS host peer + safe decode | RPC signatures, `@rpc` gameplay handlers |
| Authority validation on privileged ops | MultiplayerSynchronizer / scene replication |
| Kick, health telemetry, matchmaker handoff | Client prediction, lag compensation |

**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** [headless_init_manager.gd](scripts/headless_init_manager.gd) (`--headless` / `dedicated_server` feature).
2. **Safe decode** — **MANDATORY** [safe_packet_decoder.gd](scripts/safe_packet_decoder.gd) before any untrusted `get_var`.
3. **Host peer** — [enet_optimized_host.gd](scripts/enet_optimized_host.gd); add [dtls_secure_server.gd](scripts/dtls_secure_server.gd) when encrypting UDP.
4. **Authority** — [server_authority_validator.gd](scripts/server_authority_validator.gd) on every privileged RPC.
5. **Ops** — [peer_kick_manager.gd](scripts/peer_kick_manager.gd), [server_health_exporter.gd](scripts/server_health_exporter.gd); matchmaker handoff via [server_matchmaker_client.gd](scripts/server_matchmaker_client.gd).

## Available Scripts

### [headless_init_manager.gd](scripts/headless_init_manager.gd)
Detect/initialize dedicated server logic for `--headless` / `dedicated_server`.

### [headless_manager.gd](scripts/headless_manager.gd)
Headless runtime manager companion patterns.

### [enet_optimized_host.gd](scripts/enet_optimized_host.gd)
High-performance ENet UDP hosts with bandwidth/client limits.

### [dtls_secure_server.gd](scripts/dtls_secure_server.gd)
DTLS + X509 hardening for ENet UDP.

### [safe_packet_decoder.gd](scripts/safe_packet_decoder.gd)
Forbid object decoding on untrusted packets (RCE guard).

### [manual_network_poll.gd](scripts/manual_network_poll.gd)
Manual `multiplayer.poll()` when auto-poll is disabled.

### [isolated_multiplayer_api.gd](scripts/isolated_multiplayer_api.gd)
Isolated MultiplayerAPI instances (client+server in one process).

### [server_authority_validator.gd](scripts/server_authority_validator.gd)
`get_remote_sender_id()` gates for authoritative requests.

### [websocket_server_compat.gd](scripts/websocket_server_compat.gd)
HTML5-compatible `WebSocketMultiplayerPeer` hosts.

### [peer_kick_manager.gd](scripts/peer_kick_manager.gd)
Graceful peer termination with reason propagation.

### [server_matchmaker_client.gd](scripts/server_matchmaker_client.gd)
Load-balancer / matchmaker handoff to game hosts.

### [server_health_exporter.gd](scripts/server_health_exporter.gd)
Headless telemetry for monitoring stacks.

### [physics_server_direct.gd](scripts/physics_server_direct.gd) / [rid_performance_server.gd](scripts/rid_performance_server.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](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-performance-optimization/SKILL.md). **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 `TRANSFER_MODE_RELIABLE` for continuous streams** — Prefer unreliable for high-rate transforms.
- **NEVER use `get_var(true)` on untrusted packets** — Object decode = RCE. **MANDATORY** safe_packet_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 `connected_to_server` / 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.

```gdscript
# 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 [server_health_exporter.gd](scripts/server_health_exporter.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.

| Topic | Reference |
|-------|-----------|
| RID canvas/physics cookbook | [rendering-physics-server-cookbook.md](references/rendering-physics-server-cookbook.md) |

## 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](https://docs.godotengine.org/en/stable/tutorials/performance/using_servers.html) — RID-based RenderingServer/PhysicsServer/NavigationServer workflow when SceneTree nodes are too slow.
- [RenderingServer](https://docs.godotengine.org/en/stable/classes/class_renderingserver.html) — `canvas_item_*` / `instance_*` / `free_rid` for procedural draw and mesh swarms without MeshInstance nodes.
- [PhysicsServer3D](https://docs.godotengine.org/en/stable/classes/class_physicsserver3d.html) — `body_create`, space binding, and direct-state queries for headless authoritative simulation.
- [PhysicsServer2D](https://docs.godotengine.org/en/stable/classes/class_physicsserver2d.html) — 2D body/shape RIDs mirroring the same SceneTree-bypass pattern.
- [RID](https://docs.godotengine.org/en/stable/classes/class_rid.html) — opaque server handles; every `*_create()` needs a matching `free_rid` to avoid leaks.
- [High-level multiplayer](https://docs.godotengine.org/en/stable/tutorials/networking/high_level_multiplayer.html) — authority, RPCs, and peer lifecycle for dedicated hosts and isolated MultiplayerAPI branches.
- [ENetMultiplayerPeer](https://docs.godotengine.org/en/stable/classes/class_enetmultiplayerpeer.html) — UDP host creation, channels/bandwidth limits, and DTLS host setup on `peer.host`.
- [WebSocket multiplayer](https://docs.godotengine.org/en/stable/tutorials/networking/websocket.html) — browser-compatible peer path when ENet UDP is unavailable (HTML5 clients).
- [Exporting for dedicated servers](https://docs.godotengine.org/en/stable/tutorials/export/exporting_for_dedicated_servers.html) — dedicated-server export presets and stripping visuals/audio for production hosts.
- [Command line tutorial](https://docs.godotengine.org/en/stable/tutorials/editor/command_line_tutorial.html) — `--headless` and CLI flags used by headless init/managers.
- [Binary serialization API](https://docs.godotengine.org/en/stable/tutorials/io/binary_serialization_api.html) — `get_var(false)` / object-decoding rules that block RCE on untrusted packets.
- [DTLSServer](https://docs.godotengine.org/en/stable/classes/class_dtlsserver.html) — DTLS accept path complementary to ENet `dtls_server_setup` with X509/TLSOptions.

### Related Skills

#### Prerequisites
- [godot-project-foundations](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-project-foundations/SKILL.md) — project layout, Autoloads, and feature tags that dedicated-server and headless launches depend on.
- [godot-gdscript-mastery](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-gdscript-mastery/SKILL.md) — typed RID arrays, `@rpc` annotations, and safe Variant decoding patterns used across server scripts.
- [godot-physics-3d](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-physics-3d/SKILL.md) — node-level PhysicsBody3D/space concepts before bypassing them with PhysicsServer3D RIDs.

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

#### Downstream / consumers
- [godot-procedural-generation](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-procedural-generation/SKILL.md) — mass object/voxel spawners that consume RenderingServer/PhysicsServer RID pools.
- [godot-monte-carlo-balancer](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-monte-carlo-balancer/SKILL.md) — retune economy/TTK after authoritative server tick rates or validation change effective combat windows.
- [godot-genre-battle-royale](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-genre-battle-royale/SKILL.md) — large-peer dedicated hosts that need interest grids, kick/health exporters, and RID-scale sim.

#### Master
- [godot-master](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-master/SKILL.md) — library router and mirrored module entry; open when discovering which Domain Skill owns a cross-cutting server concern.

More from thedivergentai/GD-Agentic-Skills

SkillDescription
godot-2d-animationExpert patterns for 2D animation in Godot using AnimatedSprite2D and skeletal cutout rigs. Use when implementing sprite frame animations, procedural animation (squash/stretch), cutout bone hierarchies, or frame-perfect timing systems. Trigger keywords: AnimatedSprite2D, SpriteFrames, animation_finished, animation_looped, frame_changed, frame_progress, set_frame_and_progress, cutout animation, skeletal 2D, Bone2D, procedural animation, animation state machine, advance(0).
godot-2d-physicsExpert patterns for Godot 2D physics including collision layers/masks, Area2D triggers, raycasting, and PhysicsDirectSpaceState2D queries. Use when implementing collision detection, trigger zones, line-of-sight systems, or manual physics queries. Trigger keywords: CollisionShape2D, CollisionPolygon2D, collision_layer, collision_mask, set_collision_layer_value, set_collision_mask_value, Area2D, body_entered, body_exited, RayCast2D, force_raycast_update, PhysicsPointQueryParameters2D, PhysicsShapeQueryParameters2D, direct_space_state, move_and_collide, move_and_slide.
godot-3d-lightingExpert patterns for Godot 3D lighting including DirectionalLight3D shadow cascades, OmniLight3D attenuation, SpotLight3D projectors, VoxelGI vs SDFGI, and LightmapGI baking. Use when implementing realistic 3D lighting, shadow optimization, global illumination, or light probes. Trigger keywords: DirectionalLight3D, OmniLight3D, SpotLight3D, shadow_enabled, directional_shadow_mode, directional_shadow_split, omni_range, omni_attenuation, spot_range, spot_angle, VoxelGI, SDFGI, LightmapGI, ReflectionProbe, Environment, WorldEnvironment.
godot-3d-materialsExpert patterns for Godot 3D PBR materials using StandardMaterial3D including albedo, metallic/roughness workflows, normal maps, ORM texture packing, transparency modes, and shader conversion. Use when creating realistic 3D surfaces, PBR workflows, or material optimization. Trigger keywords: StandardMaterial3D, BaseMaterial3D, albedo_texture, metallic, metallic_texture, roughness, roughness_texture, normal_texture, normal_enabled, orm_texture, transparency, alpha_scissor, alpha_hash, cull_mode, ShaderMaterial, shader parameters.
godot-3d-world-buildingExpert patterns for 3D level design using GridMap with MeshLibrary, CSG constructive solid geometry, occlusion, and runtime GridMap builders. Use when building 3D levels, modular tilesets, or BSP-style geometry. For sky/fog/Environment recipes, route to godot-3d-lighting. Trigger keywords: GridMap, MeshLibrary, set_cell_item, get_cell_item, map_to_local, local_to_map, CSGCombiner3D, CSGBox3D, CSGSphere3D, CSGPolygon3D, OccluderInstance3D, bake CSG.
godot-ability-systemExpert patterns for RPG/action ability systems including cooldown strategies, combo systems, ability chaining, skill trees with prerequisites, upgrade paths, and resource management. Use when implementing unlockable abilities, character progression, or complex skill systems. Trigger keywords: PlayerAbility, AbilityManager, cooldown, SkillTree, SkillNode, prerequisites, can_use, execute, ComboSystem, ability_chain, global_cooldown, charge_system, upgrade_path.
godot-adapt-2d-to-3dExpert patterns for migrating 2D games to 3D including node type conversions, camera systems (third-person, first-person, orbit), physics layer migration, sprite-to-model art pipeline, and control scheme adaptations. Use when porting 2D projects to 3D or adding 3D elements. Trigger keywords: CharacterBody2D to CharacterBody3D, Area2D to Area3D, Camera2D to Camera3D, Vector2 to Vector3, collision_layer migration, sprite to MeshInstance3D, 2D to 3D conversion.
godot-adapt-3d-to-2dExpert patterns for simplifying 3D games to 2D including dimension reduction strategies, 2.5D fake-depth, isometric ports, camera flattening, physics conversion, 3D-to-sprite art pipeline, and control simplification. Use when porting 3D to 2D, building 2.5D / isometric / fake-depth gameplay, creating 2D versions for mobile, or prototyping. Trigger keywords: CharacterBody3D to CharacterBody2D, Camera3D to Camera2D, Vector3 to Vector2, flatten Z-axis, 2.5D, isometric, fake depth, Y-sort, simulated Z, orthogonal projection, 3D to sprite conversion, performance optimization.
godot-adapt-desktop-to-mobileExpert patterns for porting desktop games to mobile including touch control schemes (virtual joystick, gesture detection), UI scaling for small screens, performance optimization for mobile GPUs, battery life management, and platform-specific features. Use when creating mobile ports or cross-platform mobile builds. Trigger keywords: TouchScreenButton, virtual_joystick, gesture_detector, InputEventScreenTouch, InputEventScreenDrag, mobile_optimization, battery_saving, adaptive_performance, MOBILE_ENABLED.
godot-adapt-mobile-to-desktopExpert patterns for scaling mobile games to desktop including mouse/keyboard controls, increased resolution and graphical fidelity, expanded UI layouts, settings menus, window management, and platform-specific features. Use when creating desktop ports or cross-platform releases. Trigger keywords: mouse_controls, keyboard_shortcuts, resolution_scaling, graphics_settings, fullscreen_toggle, window_modes, Steam_integration, desktop_optimization.