godot-autopilot-servers
Skill1 starsChanged 17 days agoMITView on GitHub
Godot server-layer RID tools guide: RenderingServer, PhysicsServer and NavigationServer semantics - RID lifecycles and silent failures, physics tick ordering, navigation sync slots and the editor single-thread assumption. Use for server-side drawing, physics simulation or pathfinding.
In this repository16 other files it gives its agents.
- AGENTS.mdAGENTS.md
- cpp-registrationSkill
- domain-tool-authoringSkill
- gda-demo-e2eSkill
- gda-e2e-analysisSkill
- skill-proposerSkill
- thread-security-gateSkill
- wiki-maintainerSkill
- godot-autopilot-contentSkill
- godot-autopilot-csharpSkill
- godot-autopilot-resourcesSkill
- godot-autopilot-runtimeSkill
- godot-autopilot-scene-systemSkill
- godot-autopilot-scriptingSkill
- godot-autopilotSkill
- godot-autopilot-toolsSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 20
Every create_* tool returns an RID handle.
- Distinctive: line 276
Navigation setters are deferred: Every navigation setter goes through a command queue applied at the server's next sync.
- Distinctive: line 283
First query returns an empty path: Before a map has been synced at least once, path queries silently return an empty path in release builds.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Godot Server RID Tools
Invocation: use the native MCP tools first; when that channel is down, follow the calling ladder in the godot-autopilot-tools skill (the gda CLI, via bunx, a global install, or the standalone gda binary); with no CLI available, work through its references/manual-fallback.md.
godot-autopilot exposes the engine's server layer directly: RenderingServer,
TextServer, PhysicsServer2D, PhysicsServer3D, NavigationServer2D and
NavigationServer3D. These tools create and drive server-side objects through
RID handles - plain integer ids - instead of scene nodes. Use them for
ray/shape/point queries, server-side simulation, pathfinding setup, custom 2D
drawing, render-only 3D setups, environment post-effects, shaders, and font
shaping measurement.
The RID mental model
- Every
create_*tool returns an RID handle. Physics creation tools return an object with the numericidand anis_validflag; navigation tools return the id asrid; render tools return it asresult.rid. Keep the number and pass it as therid/space_rid/map_rid/canvas_item_ridargument of follow-up tools. - Server objects and scene nodes are separate worlds. A body created with
create_physics_2d_bodyorcreate_physics_3d_bodyhas no scene node: nothing appears in the editor scene tree and nothing is written to the scene file. RIDs live only in the running editor process. - Bridges connect RIDs to the edited scene:
get_physics_node_rid(RID of aCollisionObject2D/CollisionObject3Dnode such as aRigidBody2DorCharacterBody3D);get_render_canvas_item_rid(RID of aCanvasItemnode, feeds theadd_render_canvas_item_*draw tools);find_render_node_from_rid(reverse lookup:is_validplus anodesarray ofnode_path/type);get_debug_object_info(resolve an object id, e.g. a hit'scollider_id, to class, name,node_pathorresource_path). - RID shapes are not resources. The RIDs from
create_physics_2d_circle_shapeandcreate_physics_3d_sphere_shapecannot be assigned toCollisionShape2D.shapeorCollisionShape3D.shape- those properties expect aShape2D/Shape3Dresource. To attach collision geometry to a scene node, create a.tresviasave_resourcewithclass_type"CircleShape2D"/"SphereShape3D" and assign it withproperty_set(type_hint"Resource"), or assign insidecode_execute. Use the RID forms only with the server tools. - Several render tools accept RIDs that no tool can create (environments,
instances, sky/viewport attachments); those must come from external sources
such as
code_execute. The tool descriptions call this out.
Physics queries
2D: start with get_physics_2d_space_direct_state - it reports whether the space
is valid, active and attached to a scene, plus the query entry points; queries
fail on inactive spaces.
intersect_physics_2d_ray- closest hit (position,normal,collider_id,rid,shape) or null.space_ridmay be omitted: the tool auto-detects the open editor scene's 2D world.intersect_physics_2d_shape- all colliders overlapping a shape RID;transformplaces it,motionsweeps it along a vector.intersect_physics_2d_point- everything touching one point;max_resultscaps the reply (default 32).
3D: same trio, but space_rid is always required - no auto-detection. Obtain the space
via code_execute (e.g. SceneRoot.get_node("Player").get_world_3d().space), then confirm
with get_physics_3d_space_direct_state.
Shared filters: collision_mask, exclude (array of RIDs),
collide_with_bodies, collide_with_areas; rays also take hit_back_faces and
hit_from_inside. Only the 2D ray auto-detects the space.
Physics bodies, joints and areas
create_physics_2d_body / create_physics_3d_body return a RID, then:
set_physics_2d_body_mode/set_physics_3d_body_mode- 0=static, 1=kinematic, 2=rigid, 3=rigid_linear. Only rigid modes respond to forces and impulses.apply_physics_2d_body_force/apply_physics_3d_body_force(continuous) andapply_physics_2d_body_impulse/apply_physics_3d_body_impulse(instantaneous - jumps, hits); an optionalpositionapplies off-center, which adds rotation. 3D addsapply_physics_3d_body_torque(no 2D counterpart - 2D rotation is scalar).set_physics_2d_body_state/get_physics_2d_body_state(and the 3D pair) write and read fields by index: 0=transform, 1=linear_vel, 2=angular_vel, 3=sleeping, 4=can_sleep.- 3D extras:
set_physics_3d_body_transform(place/teleport),set_physics_3d_body_param(BodyParameter enum 0-9: bounce, friction, mass, inertia, center_of_mass, gravity_scale, damp modes and damps),set_physics_3d_body_axis_lock(bit flags 1=linear_x through 32=angular_z),add_physics_3d_body_shape(optionaltransform,disabled) and the collision exception add/remove pair.
Shapes: create_physics_2d_circle_shape / create_physics_3d_sphere_shape, sized
with set_physics_2d_shape_data / set_physics_3d_shape_data (data:
{"radius": ...}). Shape RIDs feed shape queries and add_physics_3d_body_shape.
Joints: create_physics_2d_joint with type "pin" (needs anchor), "groove" or
"damped_spring". create_physics_3d_joint with "pin", "hinge", "slider",
"cone_twist" or "generic_6dof" - body_a_rid required, type-specific transforms
optional. set_physics_3d_joint_param tunes solver_priority and disable_collision.
Areas: create_physics_2d_area / create_physics_3d_area detect overlaps and
apply effects such as gravity; set_physics_2d_area_monitorable /
set_physics_3d_area_monitorable control area-to-area monitoring. 3D adds
set_physics_3d_area_param (AreaParameter enum 0-9), set_physics_3d_area_transform
and set_physics_3d_area_space.
Spaces: set_physics_3d_space_solver_iterations, set_physics_3d_space_solver_params
and set_physics_3d_space_param (raw SpaceParameter enum 0-7) trade constraint
accuracy for CPU; solver settings do not change gravity - configure gravity through
set_physics_3d_area_param or project settings. Soft bodies: create_physics_3d_soft_body
deforms under forces; assign a mesh with set_physics_3d_soft_body_mesh. (4.8: physics
enums moved into scoped namespaces on the engine side; the tools keep the same numeric
values. TODO(verify))
Navigation maps, regions and paths
The navigation servers follow the same RID pattern: map -> region ->
(3D: navmesh) -> path query. Navigation RIDs come back as rid and are never
persisted to scene files.
create_nav_2d_map/create_nav_3d_map- passactive: true, maps default to inactive. 3D extras:cell_size,cell_height(meters) andup;set_nav_3d_map_cell_sizeadjusts granularity later - match the cell size baked into the region navmeshes.create_nav_2d_region/create_nav_3d_regionon the map (map_rid; optionalenabled,navigation_layersbitmask, default 1). Regions define the walkable area - a map with no region yields an empty path. For 3D, assign a navmesh withset_nav_3d_region_navigation_mesh:mesh_pathis ares://path to aNavigationMeshresource (.tresor.obj).- Query with
get_nav_2d_map_path/get_nav_3d_map_path(origin,destination; optionaloptimize,navigation_layers). Returnspathas an array of points - empty when the map has no baked regions or mesh.get_nav_3d_map_closest_point_to_segmentsnaps a position onto the navigation mesh (start,end, optionaluse_collision).
Navigation agents and obstacles
create_nav_2d_agent/create_nav_3d_agenton a map (map_rid,position; optionalradius,max_speed). Avoidance is off by default - passavoidance_enabled(2D) oruse_3d_avoidance(3D) true to enable it.- Drive the agent every frame with
set_nav_2d_agent_velocity/set_nav_3d_agent_velocity: the agent adjusts the desired velocity around obstacles before the value is used for movement. get_nav_3d_agent_statereads back the registeredpositionand the last suppliedvelocity- use it to verify the agent is registered.create_nav_3d_obstacleplaces an obstacle (radius,height) that avoidance-enabled agents steer around; plain agents ignore it.
Rendering: 2D canvas items
create_render_canvas_item returns the item RID. Draw commands (all take it):
add_render_canvas_item_rect (rect + color; optional antialiased),
add_render_canvas_item_circle, add_render_canvas_item_texture_rect (texture RID from
create_render_texture_from_image; optional tile, modulate, transpose) and
add_render_canvas_item_line. set_render_canvas_item_transform sets axis scaling plus
origin offset; set_render_canvas_item_visible is a hard on/off, not a toggle.
Rendering: scenario, camera, lights, meshes
create_render_scenariohosts cameras, lights, meshes and fog;set_render_scenario_environmentattaches an environment (external RID only - no create tool exists).create_render_camera+set_render_camera_transform(only the origin is applied - the camera always looks down -Z) +set_render_camera_perspective(fovy_degreesdefault 75,z_near0.01,z_far4000) orset_render_camera_orthogonal(uniformsize, default 10).create_render_light-type"directional" (default), "omni" or "spot";set_render_light_paramtakes 0=energy, 1=specular, 2=range, 3=size, 4=attenuation (rangeonly affects omni and spot);set_render_light_colortakes a color, alpha ignored.create_render_meshholds geometry;add_render_mesh_surfaceadds a surface from arrays (primitivedefaults to triangles; surfaces index from 0 in call order).create_render_material+set_render_material_paramset named shader parameters (type_hintcontrols Variant decoding);set_render_mesh_surface_materialassigns a material RID to one surface. Known gap: no tool attaches a shader to a material - materials only take effect with external shader setup such ascode_execute.
Rendering: viewports, particles, environment, shaders, textures
create_render_viewport+set_render_viewport_size(default 640x480) +set_render_viewport_clear_mode(0=always, 1=never, 2=only_next_frame). No tool can attach a camera or canvas to a viewport, so standalone viewports cannot be rendered on their own - mainly useful for external composition.create_render_particles(mode0=2D, 1=3D) +set_render_particles_emitting,set_render_particles_lifetime(seconds, default 1.0) andrestart_render_particles(fresh emission cycle for one-shot bursts). No tool instantiates particles into a scenario.- Environment tools all take an
environment_ridfrom an external source (no create tool exists):set_render_environment_bg_color,set_render_environment_ambient_light(source0=bg, 1=disabled, 2=color, 3=sky, plusenergy- fills shadows so unlit surfaces stay visible),set_render_environment_glow(bloom),set_render_environment_ssr,set_render_environment_tonemap,set_render_environment_sdfgi,set_render_environment_volumetric_fog.create_render_fog_volume+set_render_fog_volume_shapeadd localized fog volumes (visible when the environment has volumetric fog enabled). create_render_shader(optionalcodeat creation) andset_render_shader_codereplace the source (compilation happens server-side).set_render_shader_parameter_globalsets a global shader parameter - the shader must declare it with theglobalkeyword.create_render_texture_from_imageloads a texture RID fromres://,user://or absolute image paths; relative paths are not supported.create_render_sky+set_render_sky_material(material RID defines the appearance; no tool attaches a sky to an environment);create_render_decalandcreate_render_reflection_probehave no instantiation tools yet;set_render_instance_visible/set_render_instance_layer_maskcontrol server-side instances (instance RIDs must come from an external source).
TextServer: fonts and shaped text
create_text_fontreturns the font RID every font tool requires.set_text_font_dataloads a.ttf/.otf/.woff2file path;get_text_font_system_pathresolves an installed system font (font_name, optionalweightdefault 400,stretchdefault 100,italic) to an absolute path you can pass asdatadirectly.set_text_font_antialiasing(0=none, 1=gray, 2=grayscale, 3=subpixel; use 0 for pixel-art fonts) andset_text_font_hinting(0=none, 1=light, 2=normal - light is the typical UI default) apply afterset_text_font_dataso they affect the loaded font.has_text_featurechecks TextServer capabilities before relying on them: 1=simple_layout, 2=bidi_layout, 4=shaped, 8=kerning, 16=ligatures.- Shaped measurement:
create_shaped_text(direction0=auto, 1=ltr, 2=rtl;orientation0=horizontal, 1=vertical) ->add_shaped_text_string(font configured first,sizein pixels, optionallanguageimproves shaping) ->get_shaped_text_sizereturns the pixel dimensions - zero until strings are added; use it to size labels before creating them.is_text_locale_right_to_left(BCP-47 in, boolean out) picks alignment ordirectionbefore shaping RTL text.
Minimal workflows
2D ray query against the open scene (space auto-detected):
{"name": "intersect_physics_2d_ray", "arguments": {"from": {"x": 0, "y": 0}, "to": {"x": 100, "y": 200}}}Navigation setup and path query (run such sequences in order with batch_execute):
{"name": "create_nav_2d_map", "arguments": {"active": true}}
{"name": "create_nav_2d_region", "arguments": {"map_rid": 1}}
{"name": "get_nav_2d_map_path",
"arguments": {"map_rid": 1, "origin": {"x": 0, "y": 0},
"destination": {"x": 200, "y": 100}}}RID lifecycle and silent failure
- Invalid RIDs fail silently. Calling any tool - including
free- on a stale, already-freed or never-existing RID neither crashes nor returns an error: the server resolves the RID, gets nothing and drops the call. At the tool layer this looks like a successful call with no effect. There is no "RID not found" error to catch, so track which create call produced which id yourself. - Canvas teardown does not cascade. Freeing a canvas RID does not free the canvas items parented to it: their parent pointer is cleared and they become orphans that keep existing (and drawing) until freed one by one.
- Shapes detach automatically. Freeing a shape RID removes it from every body that references it; the bodies themselves are unaffected and stay alive - the opposite of the canvas behavior above.
- No leak reporting. RIDs leaked at editor exit produce no warning at the server layer (only lower-level native rendering-device RIDs get a leak warning). Repeatedly creating RIDs without freeing them accumulates silently across a long session; everything is reclaimed only when the editor process exits. Object creation is two-phase internally (allocate then initialize), invisible at the tool level.
Timing and threads
- Editor single-thread assumption. The editor forces single-threaded rendering (multi-threaded rendering would crash on startup), so RenderingServer calls made on the main thread execute synchronously and immediately. MCP tools can assume "the change is in effect by the next draw" - there is no worker thread to wait for.
- Physics tick order. Each physics tick runs: state sync -> flush of query
results (direct-state reads and integration callbacks see the previous step) ->
node
_physics_process-> navigation -> message queue flush -> integration step -> flush. Node physics callbacks therefore observe the previous step's state. - Direct state window and the space lock. In threaded physics, a direct state object
fetched outside the sync window returns null with an error, and while a space is
locked, intersection queries return empty results. Re-entering queries from inside a
physics callback silently gets nothing; querying from
_physics_processis safe. - Navigation setters are deferred. Every navigation setter goes through a command queue applied at the server's next sync; reading back immediately returns the old value, with no error for "not applied yet".
- Map rebuilds use double-buffered iteration slots. Region or navmesh changes rebuild
the map in the other slot at the next sync (possibly asynchronously); slots swap only
once the rebuild finishes, and if the old slot is still occupied the swap waits another
round. Poll
map_get_iteration_idto track rebuild progress (slots exist since 4.7). - First query returns an empty path. Before a map has been synced at least once, path queries silently return an empty path in release builds; after setting up regions, allow one sync (frame) before trusting an empty result.
- Nav sync runs twice per frame - once from process (sync only) and once from physics_process (sync + avoidance step + avoidance callbacks). Avoidance-adjusted velocities therefore only update on physics ticks.
- Same-frame ordering. Each frame runs: node
_process-> message queue flush -> navigation sync -> RenderingServer sync -> draw. A region changed from_process(e.g. viacode_execute) is picked up by the same frame's navigation sync, and rendering happens after that - friendly to "change it and screenshot immediately". - Forcing a RenderingServer sync every frame for more than 5 consecutive frames logs a persistent warning. Viewports with a dimension of 1px or less silently render nothing, and a viewport set to UPDATE_ONCE renders once and then flips to disabled.
See also
godot-autopilot-content- TileMap, animation, audio and UI theming workflows.godot-autopilot-scene-system- building and editing the scene nodes these RID tools bridge to.godot-autopilot-resources- saving shape resources as.tresforCollisionShapeassignment.godot-autopilot-scripting-code_executeusage for the external-RID setups.references/tool-reference-physics-nav.md- the full physics + navigation tool tables.references/tool-reference-rendering.md- the full render + text tool tables.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

