contexture godot.instructions.md

godot rules

Auto-loaded by Copilot when editing files matching **. Generated from architectural-rules/godot/ — do not hand-edit.

C# in Godot

Expose inspector-editable fields with [Export] on a C# property/field, the binding equivalent of GDScript's @export. Plain C# fields are invisible to the editor. (Godot docs — C# basics) Declare signals as [Signal] public delegate void NameEventHandler(...). The generated event is the typed, editor-visible signal; ad-hoc C# events are not Godot signals. (Godot docs — C# basics) Every C#↔engine call crosses a marshalling boundary with real per-call cost. Do not make many small cross-language calls per frame — batch work and cache values on the C# side. (Godot docs — C# API differences) A GodotObject (Node, Resource) has engine-owned native lifetime that is independent of the C# GC. Free engine objects explicitly (QueueFree/Free); never assume the GC reclaims them, and never touch a C# wrapper after the native object is freed. (Godot docs — C# API differences) Connect signals in C# with a Callable (e.g. Connect(SignalName.X, Callable.From(handler))), not a raw string method name. Callable-based connection is type-checked and refactor-safe. (Godot docs — C# basics)

Cross-reference: the universal C# rules under csharp/ still apply — these add only the Godot-binding specifics on top of them.

Why: The C# binding sits over a native engine: the marshalling boundary and the GodotObject/GC lifetime split are the two seams where idiomatic C# assumptions break. Treating engine objects as GC-managed, or chattering across the boundary each frame, produces both correctness bugs (use-after-free) and frame-time regressions. Source: Godot docs — C# basics / C# API differences.

Editor plugins

A socket/server polled inside a Node's _process() runs on the editor MAIN thread (Thread.is_main_thread() is true). EditorInterface calls from there need NO call_deferred or cross-thread marshalling. Poll editor-facing work on _process to stay main-thread-safe by construction. Do NOT await RenderingServer.frame_post_draw to force a frame before capturing an EDITOR viewport — that signal does not fire predictably for the editor's own viewports and the coroutine hangs. Read viewport.get_texture().get_image() directly; editor viewports render continuously, so the latest frame is already available. Set WebSocketPeer.inbound_buffer_size and outbound_buffer_size large (e.g. 16 MB) BEFORE calling accept_stream(). The default (~64 KB) is too small for large payloads (e.g. base64 viewport PNGs); a big send fails with ERR_OUT_OF_MEMORY. Buffer sizing after accept_stream is too late. Validate editor-plugin tools that render or push large payloads in a WINDOWED editor, not --headless. Headless has no render surface (cannot verify viewport capture) and masks WebSocket buffer limits (there is no large payload to send). Headless is fine ONLY for parse-checks, registry writes, and socket round-trips. Keep any plugin backup/old copy OUTSIDE res://. An in-tree backup collides class_name with the live copy ("Class X hides a global script class") and breaks the entire plugin load; it also pollutes .godot/global_script_class_cache.cfg and uid_cache.bin, which survive restart. If already hit, move the backup out and clear those caches.