How to Give an AI Assistant Context From a Godot Project

Choose context by dependency, not project size

Start from the exact function, error, or behavior in question. Add a second script only when the first one calls it, depends on its state, or exchanges a signal with it. Add scene context when node paths, node types, or attached scripts affect the answer.

1. 1

   Begin with the active code

   Share the open script or selected lines that contain the question.

2. 2

   Follow direct dependencies

   Attach the scripts and scene nodes directly involved in the behavior, not unrelated project files.

3. 3

   State the expected result

   Explain what should happen, what happens instead, and any constraint the answer must preserve.

Use the context command that matches the evidence

1. 1

   @file

   Attach a file, a line range, or a named function.

   @file "res://scripts/player.gd":10-40
2. 2

   @scene

   Attach scene structure, focus on a node, or include attached scripts.

   @scene res://scenes/player.tscn --scripts
3. 3

   @openscript

   Attach the script currently open in the Godot script editor.

   @openscript
4. 4

   @selection

   Attach the highlighted code with its file path and line numbers.

   @selection
5. 5

   @node

   Attach information about a scene node and its attached script.

   @node Player/WeaponPivot

Keep project conventions in res://AGENTS.md

Place an optional AGENTS.md at the project root as res://AGENTS.md. Personal rules saved in GDSense Settings apply first; project rules from res://AGENTS.md apply second, so the project can add conventions while keeping your preferences.

Fresh Chat, Quick Edit, and Agent-start requests reread AGENTS.md, so saved edits apply without restarting Godot. Retry preserves the original rules and context instead of rereading the file, and autocomplete does not use AGENTS.md. Both rule sources have the same server-enforced safety and length limits. Validation screens known-dangerous and oversized rules, but you should still review AGENTS.md before using GDSense in an untrusted or newly cloned project. Normal Agent tool approvals still apply.

Agent Mode automatically shares a shallow tree of file and folder path names so it can navigate the project, but that tree does not include file contents. On fresh Chat, Quick Edit, and Agent-start requests, GDSense reads only res://AGENTS.md file content automatically; attach other code and scene contents explicitly.

Use typed GDScript for public methods.
Keep signals in past tense.
Prefer composition over deep inheritance.

• Keep every rule focused on a project convention.
• Keep rules concise; the same server-enforced safety and length limits apply to both sources.
• Review AGENTS.md before using GDSense in an untrusted or newly cloned project.
• Remember that normal Agent tool approvals still apply.
• Attach code and scenes explicitly when a task needs their contents.

Work across explicitly attached scripts and scenes

GDSense can use multiple relevant attachments in one request. This is useful when behavior crosses a player script, a weapon script, and the scene that connects them. Keep the request narrow enough that every attachment has a clear reason to be there.

@file res://scripts/player.gd
@file res://scripts/weapon.gd
@scene res://scenes/player.tscn --scripts
The fire input reaches player.gd, but weapon.gd never emits its fired signal. Trace only the attached path, identify the most likely disconnect, and propose a change for me to review.

• Each attachment is directly related to the question.
• The request says what should happen and what happens instead.
• The answer identifies assumptions when context is still missing.
• Any proposed file change is reviewed and tested in Godot.

Keep in mind: More context is not automatically better. Focused evidence makes assumptions easier to spot and proposed changes easier to verify.