AgentSkillsCN

godot-server-architecture

提供低级别服务器访问的专家蓝图（RenderingServer、PhysicsServer2D/3D、NavigationServer），通过RID实现最高性能。绕过场景树的开销，适用于程序化生成、粒子系统与体素引擎。在节点运行速度过慢，或需管理数千个对象时使用。关键词：RenderingServer、PhysicsServer、NavigationServer、RID、canvas_item、body_create、低级别、性能。

SKILL.md
--- frontmatter
name: godot-server-architecture
description: "Expert blueprint for low-level server access (RenderingServer, PhysicsServer2D/3D, NavigationServer) using RIDs for maximum performance. Bypasses scene tree overhead for procedural generation, particle systems, and voxel engines. Use when nodes are too slow OR managing thousands of objects. Keywords RenderingServer, PhysicsServer, NavigationServer, RID, canvas_item, body_create, low-level, performance."

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.

gdscript
# 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.

gdscript
# 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

Related