The short answer
Use @scene with a res:// path for saved scene hierarchy, #Node/Path for a subtree, and --scripts for associated script context. Use @node for a node’s identity and attached script in the currently edited scene. These commands do not supply a full Inspector-property dump or serialized signal connections. When that evidence matters, attach the saved .tscn text with @file or paste the relevant settings. Neither command ingests the whole project.
Choose between @scene and @node
Type @ and choose @scene to search saved .tscn files. @node does not open a scene-file picker because it resolves a node path against the scene currently open in the editor.
| Command | Source | Included evidence |
|---|---|---|
| @scene | A saved res:// .tscn file | Parsed scene structure, optionally filtered to a subtree |
| @scene --scripts | A saved scene plus attached scripts | Scene structure and a bounded set of associated script contents |
| @node | A node in the currently edited scene | Node identity, type, path, parent, attached script, and scene context |
Use @scene for saved hierarchy and ownership
A plain @scene command attaches a formatted node hierarchy from the specified .tscn file, not the entire serialized file. Use a #node path to reduce the result to a relevant subtree. Add --scripts only when behavior depends on scripts attached within that scene; the plugin limits associated script expansion instead of sending an unbounded project set.
The formatted attachment does not include all saved Inspector properties or the scene’s serialized signal-connection records. For those details, use @file to attach the relevant saved .tscn text, paste the necessary property or connection lines, or ask Agent to read the relevant file through its supported tools. Review raw files for secrets before attaching them; a saved value is still not proof of current runtime state.
@scene res://scenes/door.tscn#InteractionArea --scripts
@file res://scenes/door.tscn
The interaction prompt appears, but the door never opens. Use the raw scene text to check saved signal connections and property values alongside the hierarchy and scripts. State any missing runtime evidence before proposing a change.@scene res://scenes/player.tscn@scene res://scenes/player.tscn#CameraRig/SpringArm3D@scene res://scenes/player.tscn --scripts@scene res://scenes/player.tscn#WeaponPivot --scripts@file res://scenes/door.tscnKeep in mind: @scene reads the saved .tscn file. Save relevant scene changes before sending when the request must reflect the latest editor state.
Use @node for a node in the current scene
@node resolves a slash-separated node path in the scene currently being edited. The context includes the node name, Godot type, full path, parent, and attached script when present, plus the scene root name and node count. It does not include every Inspector value or inspect the running game’s Remote scene tree. Paste the specific editor or runtime values needed to investigate a property-dependent failure.
@node HUD/PauseMenu/ResumeButton
Why can this button remain disabled after returning from settings? Explain which current-scene relationships are visible in the attached context and what runtime state I still need to inspect.@node Player/WeaponPivot@node HUD/PauseMenu/ResumeButtonKeep in mind: Node paths use letters, numbers, underscores, and forward slashes. Rename-sensitive or generated runtime nodes may not exist in the currently edited scene.
Attach scene evidence only when structure matters
Hierarchy and script context are useful for missing-node errors, attached-script relationships, and UI structure. Signal wiring and exported NodePath values may also require raw .tscn text or pasted settings because @scene does not include that complete serialized evidence. A pure calculation usually needs neither. Start from the failure and provide the specific evidence that can change the answer.
- The request names the expected runtime behavior.
- The chosen scene or node is on the failing path.
- Use a subtree instead of the complete scene when one branch is sufficient.
- Use --scripts only when script contents affect the question.
- Attach reviewed raw scene text with @file or paste settings when Inspector values or editor-created connections matter.
- Add the exact Godot error or reproduction steps when the issue appears only at runtime.
Understand Agent Mode scene references
In Chat, @scene and @node are expanded into structured context before sending. In Agent Mode, they become scene or node hints and the Agent uses supported tools to inspect the relevant project data. The automatically supplied Agent tree contains path names only, not scene contents.
A scene or node attachment can contain project code and structure. It is transmitted with the prompt to GDSense and the server-routed AI provider for processing. Do not put secrets in scene metadata, scripts, project rules, or prompts.