Product Documentation

Everything you need to get started with GDSense

Documentation Library

Start with the answer you need. Every article is a crawlable, standalone page with focused steps, examples, and links to the next relevant topic.

3 articles

Getting started

Install GDSense, connect your account, and complete a useful first request.

Install GDSense in Godot 4.7Download the current GDSense plugin, place it at res://addons/gdsense, enable it in Godot, and confirm the right-side dock appears.GDSense quick startGo from an enabled plugin to a focused first GDScript question with explicit project context and a result you can verify.Connect your account and API keyGenerate the account key shown once, save it in the plugin Settings tab, and verify the connection status.

9 articles

Guides

Task-focused workflows for debugging, refactoring, and sharing project context.

Debug GDScript errorsTurn an error message, the relevant script, and scene context into a focused debugging plan you can verify in Godot.Refactor GDScript safelyImprove GDScript structure while preserving behavior through small changes, a visible diff, and repeatable verification.Share useful project contextAttach only the scripts, selections, scenes, and nodes that matter so an AI assistant can answer a specific Godot question.Choose AI reasoning for GDScriptMatch GDScript tasks to reasoning depth and evaluate answers with scene-aware checks, API verification, and a small repeatable test set.Export and verify a Godot projectPrepare an export preset, include the required resources, diagnose export-only failures, and smoke-test the actual Godot build before sharing it.Connect and debug Godot signalsConnect a typed health signal to a HUD, handle the initial state, and trace missing or duplicate callbacks with a practical Godot example.Build a GDScript state machineReplace conflicting enemy flags with explicit idle, chase, and disabled states, one transition function, and repeatable boundary checks.Use Godot TileMapLayerSet up a TileMapLayer, convert mouse positions to map cells correctly, place known atlas tiles, and separate collision problems from coordinate mistakes.Use AI in GodotTake one Godot task from a clear prompt and focused scene context to a reviewed GDScript change and a repeatable gameplay check.

5 articles

Features

Learn the editor surfaces and choose the GDSense workflow that fits your task.

GDSense dock overviewUnderstand the Chat, History, and Settings tabs and the controls you will use most often inside Godot.Use Chat ModeAsk focused Godot questions, attach only relevant project context, continue useful follow-ups, and verify every suggested change.Use Agent ModeGive GDSense a bounded multi-step task, follow its tool activity, control protected actions, and verify the finished Godot project.Use editor code actionsChoose Explain, Quick Edit, whole-function Refactor, or ghost-text autocomplete from the Godot script editor.Manage history and sessionsLoad, continue, favorite, rename, export, import, or delete Chat and Agent conversations stored by the Godot plugin.

4 articles

Reference

Precise command, setting, and behavior reference for day-to-day use.

Credits, usage, and plansUnderstand what uses credits, where to check usage, how plan capabilities differ, and what renewal or cancellation changes.File and script context commandsUse @file, @openscript, and @selection to attach the smallest useful GDScript or project-file context to a request.Choose a reasoning modeMatch Standard, Thinking, or Max to task difficulty, plan access, response time, and credit use in Chat, Agent, and edits.Scene and node context commandsUse @scene and @node for Godot hierarchy, node identity, and script context; provide raw scene text separately when saved properties or connections matter.

2 articles

Troubleshooting

Diagnose setup, connection, and workflow problems without guesswork.

Fix API key and connection errorsSeparate local key loading from authentication, then diagnose revoked credentials, account access, rate limits, and network failures.Restore a missing GDSense dockCheck the Godot version, addon path, plugin status, editor output, and installed files when the GDSense dock does not appear.

1 article

Comparisons

Understand when different GDSense modes and workflows are the right fit.

Compare Chat and Agent ModeChoose the right GDSense workflow by task shape, context behavior, tool access, approvals, plan access, and credit billing.

Getting Started

Installation

Step 1: Create an Account

Visit gdsense.com/register to create your account. Free access activates after you verify your email. You can upgrade to Starter, Pro, or Ultra for more credits and additional modes.

You'll receive a verification email to activate your account.

Step 2: Generate an API Key

Log in to your Dashboard
After email verification or subscription confirmation, click "Generate API Key"
Give your key a descriptive name (e.g., "My Godot Project")
Copy the API key immediately - you won't be able to see it again!

⚠️Keep your API key secure and never share it publicly or commit it to version control.

Step 3: Install the Godot Plugin

Requires Godot Engine 4.7

Download the GDSense plugin from your user dashboard
Extract the plugin to your Godot project's addons/ folder
Enable the plugin in Project → Project Settings → Plugins
Restart Godot Editor to complete installation

GDSense plugin folder structure in res://addons/gdsense

Proper folder structure: res://addons/gdsense

Step 4: Configure Your API Key

Open Godot and ensure GDSense plugin is enabled
Click the "GDSense" tab in the right dock
Click the "GDSense Settings" tab in the GDSense panel
Paste your API key in the "API Key" field
Click the "Save" button
Start using GDSense!

GDSense Settings tab showing API key configuration

Configure your API key in the GDSense Settings tab

Core Features

AI Chat Assistant

Talk to your AI coding partner directly in the Godot editor. Ask questions about your code, get help debugging issues, or brainstorm solutions to problems. The AI understands Godot and GDScript, so you can have natural conversations about your game development challenges.

Example questions:

"How do I make my player character jump?"
"Why is my enemy not following the player?"
"What's the best way to organize my game's inventory system?"
"How can I optimize this script for better performance?"

GDSense chat interface showing AI conversation

Chat with the AI assistant directly in the Godot editor

Failed Requests and Retry

A failed Chat or Agent-start request keeps your full prompt on the failed turn. Choose Retry to send the same prompt again with the same mode and attached context. A request that fails before the AI service creates a response is refunded, so it is not billed. If a response was already created—or an Agent turn completed—the work can remain billed even if delivery later fails.

Explain Code

Use a function's Explain button in the editor gutter for an explanation of that function. To ask about a selected block instead, attach it with @selection in Chat and ask how it works. Check the explanation against the code and the running project.

Pro Tip: Use Explain when you're learning new Godot concepts or debugging tricky code - it's like having an experienced game developer looking over your shoulder.

Click the Explain button beside a function in the editor gutter

Code explanation displayed in GDSense chat

AI explanation appears in the chat panel

Code Refactoring

Highlight any code and open Quick Edit with its shortcut or from the script-editor context menu. For a complete function, you can keep using the Refactor gutter icon. Every entry point opens the same prompt, mode picker, and reviewable diff so you can apply or reject the proposed change.

The AI can help you:

Clean up messy or complex code
Make your game run faster
Add helpful comments to your code
Reorganize code to be more logical

The Refactor button in the editor gutter remains available for whole functions

Review and apply AI-suggested refactoring improvements

Side-by-side comparison of original and refactored GDScript

Compare the original and refactored code before applying changes

Context Commands

Give the AI more information about your project by attaching files to your chat. This helps the AI give you better, more specific answers. Type these commands in the chat:

@file

Share a specific file with the AI

@file res://scripts/player.gd

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

@file res://scripts/player.gd#jump

Include entire files, specific line ranges, or individual functions by name

@scene

Share saved Godot scene hierarchy

@scene res://scenes/main.tscn

@scene res://scenes/main.tscn#Player

@scene res://scenes/main.tscn --scripts

Share hierarchy, focus on a subtree, or include a bounded set of attached scripts. This is not a full Inspector-property dump and does not include serialized signal connections. Use @file for reviewed raw .tscn text or paste the relevant settings when those details matter.

@openscript

Share your currently open script

@openscript

Quick way to get help with what you're working on

@selection

Share your currently selected code

@selection

Automatically shares the text you've highlighted in the script editor, including file path and line numbers

@node

Share information about a scene node

@node Player

@node Player/Sprite2D

Includes node identity, type, parent, full path, and attached script content from the currently edited scene, not a full Inspector-property dump or the running game's Remote scene tree. Paste relevant property values or use @file for reviewed saved scene text when needed.

💡 How to Use Context Commands

Ask about your current code:

@openscript Why is my player not moving when I press the arrow keys?

Get help with selected code:

@selection Can you optimize this function for better performance?

Understand scene nodes:

@node Player How should I add a health system to this character?

Combine multiple contexts:

@scene res://scenes/game.tscn#Player @file res://scripts/enemy.gd How can I make the enemy chase the player?

Tip: You can use multiple context commands in one message to give the AI a complete picture of your problem.

Project Rules from res://AGENTS.md

Add an optional res://AGENTS.md file to keep project conventions with the project. Personal rules saved in GDSense Settings apply first; project rules from AGENTS.md apply second.

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. The server validates both rule sources separately before the request runs, with the same server-enforced safety and length limits for Settings and project rules. 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 your project, but that tree does not include file contents. On fresh Chat, Quick Edit, and Agent-start requests, AGENTS.md is the only project file whose contents GDSense reads automatically; attach other code and scene contents explicitly when you want GDSense to use them.

Chat History Management

The History tab in the GDSense plugin helps you manage your AI conversation sessions. Keep track of your past conversations, mark important chats as favorites, and share sessions with your team.

GDSense history tab showing saved conversations

Manage your chat history, favorites, and saved sessions

💡 Why Use Chat History?

•Continue conversations exactly where you left off without losing context
•Save important problem-solving sessions for future reference
•Share complex debugging sessions with teammates via JSON export
•Organize sessions with custom names for easy retrieval

View & Load Sessions

See your 15 most recent chat sessions with preview details including Session ID, timestamp, and conversation snippet. Click any session to load it and continue the conversation exactly where you left off.

Pro Tip: Recent sessions show the last 15 chats. Mark important ones as favorites to keep them permanently accessible.

Favorites System

Star your most important conversations for unlimited storage. Favorite chats are not subject to the 15-session limit and remain accessible indefinitely. Perfect for reference implementations or complex problem-solving sessions.

Team Use: Export favorites to share proven solutions across your development team.

Export Sessions

Save any chat session as a JSON file. This is invaluable for sharing debugging sessions with teammates, documenting AI-assisted problem-solving processes, or creating a knowledge base of solved issues.

Export location: Choose your preferred folder via file dialog

JSON format includes full conversation history and metadata

Import Sessions

Load shared chat sessions from JSON files. When a teammate sends you an exported session, import it to see their entire conversation history with the AI, including all context and code examples.

Import from: Any JSON file path in your project

Rename & Organize

Give your chat sessions descriptive names instead of using default Session IDs. Organize by project, feature, or problem type for easy retrieval. Renamed sessions are easier to identify when browsing your history.

Player Movement Bug FixInventory System ImplementationPerformance Optimization Session

Delete & Clear

Remove individual sessions or clear all recent chats at once. You can also clear all favorites if you need a fresh start. Deleted sessions are permanently removed and cannot be recovered.

Warning: Deletion is permanent. Export important sessions before clearing.

🚀 Best Practices for Team Collaboration

Share Debugging Sessions

When you solve a tricky bug with AI assistance, export the session and share it with your team. This preserves the entire problem-solving process, including dead ends and the final solution.

Create Knowledge Base

Build a team library of exported sessions organized by topic. Use favorites for commonly referenced sessions like "Setting Up Multiplayer" or "Implementing Save Systems."

Onboarding New Developers

Give new team members imported sessions showing how to work with your project's architecture. They can see real examples of how experienced developers ask questions and implement features.

Document AI-Assisted Development

Keep exported sessions as documentation of how AI tools were used in your project. This helps with code reviews and understanding architectural decisions made with AI assistance.

Workflow Tip: Use Recent Chats for daily work, Favorites for long-term reference, and Export/Import for team knowledge sharing.

Modes

GDSense lets you choose how much reasoning to apply to each request. Pick Standard, Thinking, or Max in the plugin based on the depth your task needs.

Balance and Actual Billed Cost

Your remaining credit balance stays visible in the plugin dock and refreshes after each completed turn. Every completed Chat turn shows the credits actually billed for that turn, so the cost stamp matches your account history. A request that fails before the AI service creates a response is refunded; an already-created response can remain billed if delivery fails later.

Standard — Fast & Everyday

Quick, responsive answers for the work you do all day: GDScript syntax, small snippets, node and signal questions, and routine refactors. Standard is your default and is available on every plan. The function Explain button uses a separately configured path; do not infer its routing from the selected Chat mode.

Thinking — Reasons It Through

When a problem has a few moving parts, Thinking takes a beat to reason through it before answering. Great for multi-step bugs, gameplay and state-machine logic, and refactors that touch more than one script. Available on Starter and above.

Max — Deepest Reasoning

For your hardest, highest-stakes work: whole-system architecture, tricky performance problems, and large multi-step Agent tasks. Max applies the most capable engine your plan offers. Available on Ultra.

Modes work in both Chat and Agent

Your chosen mode applies whether you're chatting or running an Agent task. Standard costs 1 credit per request or turn, Thinking costs 5, and Max costs 10. Agent Mode adds no multiplier; each Agent turn costs the selected mode.

Agent Mode

What is Agent Mode?

Agent Mode helps with multi-step tasks that need more than a single answer. It can plan a sequence, use supported tools, and work through each step while you stay in control of protected changes.

Describe what you want to build or fix and attach the relevant context. GDSense shows visible progress, tool actions, and approval requests as it works. It may ask for clarification when a decision needs your input, and you should review and test the result in Godot.

Agent Mode is available on the Pro and Ultra plans.

Credit Cost

Standard costs 1 credit per request or turn, Thinking costs 5, and Max costs 10. Agent Mode adds no multiplier; each Agent turn costs the selected mode.

While Agent Mode works, its live counter shows completed turns and actual billed credits so far. When the run ends, the final turn-and-credit total remains on the run. The total is the sum of completed billed turns; a completed Agent turn can remain billed even if the run later fails. Work that fails before the AI service creates a response is refunded.

Example: A Standard turn costs 1 credit in both Chat and Agent Mode.

Agent Mode runs in any mode your plan includes:

Standard — 1 credit per turn
Thinking — 5 credits per turn
Max — 10 credits per turn

Best Tasks for Agent Mode

✓
Setting up player controllers
Let the agent create movement, input handling, and state management in one session
✓
Implementing game mechanics
Health systems, inventory management, save/load systems, and more
✓
Debugging complex issues
Agent Mode can investigate, hypothesize, and iterate to find root causes
✓
Refactoring across multiple files
Reorganize code, rename variables, and update dependencies systematically

When to Use Regular Chat Instead

For quick one-off questions, regular chat mode is still faster and more efficient:

•"What does this error mean?"
•"How do I use the AnimationPlayer node?"
•"What's the syntax for connecting signals in GDScript?"
•Simple code explanations or quick fixes

Tips for Better Agent Results

1.
Be specific about what you want
Instead of "make a player", try: "I want a player character that can walk left/right, jump, and double jump. It should have a sprite that flips when changing direction. The player should fall back down after jumping."
2.
Explain what you already have
Tell the agent about your existing work. Example: "I already have a player scene with a sprite, but it doesn't move yet. I want to add movement to it."
3.
Let the agent ask questions
Don't rush—the agent may need clarification to produce the best results
4.
Review intermediate steps
Review visible progress and tool actions, then provide feedback if the agent goes off track

Best Practices

Getting Better Answers

✓
Be specific about what you need
Instead of "help with movement", try "my player character moves too slowly and I want to add a sprint feature"
✓
Share your code using @commands
Use @openscript or @file to show the AI what you're working on
✓
Godot version sent automatically
The plugin automatically includes your Godot version with every request, so the AI knows which version you're using
✓
Ask follow-up questions
The AI remembers your conversation within the same chat session - build on previous answers to dive deeper

Keeping Your API Key Safe

•Don't share your API key with anyone
•Never upload it to GitHub or other public places
•If you think someone got your key, generate a new one in your dashboard

Making the Most of GDSense

💡
Start conversations when you're stuck
Don't waste hours being confused - ask the AI and keep making progress
💡
Use it to learn, not just copy code
Ask "why does this work?" to understand the code, not just paste it
💡
Check your usage dashboard
See what you're using and plan upgrades if you need more requests

Need More Help?

Check out our FAQ, join our Discord community, or view your usage in the dashboard

View FAQ Join Discord Go to Dashboard