Server Architecture

RID-based server API, direct rendering/physics access, and object pooling define maximum-performance patterns.

Available Scripts

headless_manager.gd

Manager for dedicated server lifecycle, argument parsing, and headless mode optimization.

rid_performance_server.gd

Expert server wrapper with RID lifecycle management and batch operations.

NEVER Do in Server Architecture

• NEVER forget to free RIDs — RenderingServer.canvas_item_create() without free? Memory leak (GC doesn't track RIDs). MUST call canvas_item_free(rid) when done.
• NEVER mix server API with nodes for same object — Creating RID body AND CharacterBody2D for same entity? Conflicts + double simulation cost. Pick ONE approach.
• NEVER use servers for prototyping — Debugging server code is painful (no Inspector, print_tree, or visual tools). Use Nodes first, optimize to servers later.
• NEVER skip RID validation — Calling body_set_state(invalid_rid, ...) = crash. Use RID.is_valid(rid) OR track RIDs in Array/Dictionary.
• NEVER use servers without profiling first — Premature optimization. Nodes handle 10k+ objects fine in Godot 4. Profile FIRST, then replace bottlenecks with servers.
• NEVER forget to set shape transform — PhysicsServer2D.body_add_shape(body, shape) without transform? Shape at (0,0) offset. Set transform via body_set_shape_transform().
• NEVER use RenderingServer for UI — UI elements via canvas_item_create()? No automatic layering, input, or theming. Use Control nodes for UI.

---

Direct access to rendering without nodes.

# Create canvas item (2D sprite equivalent)
var canvas_item := RenderingServer.canvas_item_create()
RenderingServer.canvas_item_set_parent(canvas_item, get_canvas_item())

# Draw texture
var texture_rid := load("res://icon.png").get_rid()
RenderingServer.canvas_item_add_texture_rect(
    canvas_item,
    Rect2(0, 0, 64, 64),
    texture_rid
)

PhysicsServer2D

Create physics bodies without nodes.

# Create body
var body_rid := PhysicsServer2D.body_create()
PhysicsServer2D.body_set_mode(body_rid, PhysicsServer2D.BODY_MODE_RIGID)

# Create shape
var shape_rid := PhysicsServer2D.circle_shape_create()
PhysicsServer2D.shape_set_data(shape_rid, 16.0)  # radius

# Assign shape to body
PhysicsServer2D.body_add_shape(body_rid, shape_rid)

When to Use Servers

Use servers for:

• Procedural generation (thousands of objects)
• Particle systems
• Voxel engines
• Custom rendering

Use nodes for:

• Regular game objects
• UI
• Prototyping

Reference

• Godot Docs: Using Servers