Skip to main content

Stan Godot Plugin User Guide (v1.0.4)

Welcome to the Stan Godot Plugin User Guide! This document provides detailed instructions on installing, authenticating, and effectively using Stan, your AI co-pilot, within the Godot Engine.

I. General & Overview​

Stan is an autonomous AI Godot developer that lives inside your editor. It's capable of reading your scenes and scripts to perform real-time code modifications and project planning without you leaving the workspace, significantly boosting your Godot game development workflow.

Compatibility​

  • Minimum Godot Version: Godot 4.0
  • Recommended Godot Version: Godot 4.2.x or 4.3.x (both Standard and .NET versions are supported).

Prerequisites​

  • An active internet connection (required for all AI processing and authentication).
  • A functional Godot Editor installation.
  • Important Note: The plugin uses standard GDScript and does not require external Node.js dependencies for v1.0.4+. All necessary components are self-contained.

II. Installation​

Stan's Godot plugin is designed for straightforward installation as a standard Godot addon.

Packaging​

The plugin is distributed as a .zip file containing the addons/stan_agent directory structure, ready to be extracted into your project.

Installation Steps​

  1. Download the Package: Download the stan-godot-plugin.zip from the official download page: https://stan.stanlink.online/#/download. The zip file has been downloaded to the local computer
  2. Extract to Project Root: Extract the contents of the .zip file directly into your Godot project's root directory.
    • Ensure that the resulting path is res://addons/stan_agent/. The zip file was extracted into the godot project root and in this image we have the addons folder in the root
  3. Enable Plugin in Godot:
    • Open your project in the Godot Editor.
    • Navigate to Project > Project Settings in the top menu.
    • Go to the Plugins tab.
    • Locate "Stan Agent" in the list and check the "Enable" box.

Folder Structure​

The plugin installs into res://addons/stan_agent/. This folder contains all the necessary GDScript logic, UI models, and assets (such as icons and banners) for Stan's operation.

Post-Installation Steps​

  • Once enabled in Project Settings, the Stan Agent dock will automatically appear within your Godot Editor workspace. No manual Autoload configuration or additional setup is required; the plugin handles its own initialization.

III. Authentication (Godot-Specific Device-Code Flow)​

Stan uses a secure, modern "Device Code" authentication flow to connect your Godot Editor to the StanLink services, ensuring your credentials never reside directly within the editor.

Initiating Login​

  1. Stan Agent Dock: The Stan Agent dock will appear after enabling the plugin. It typically shows an initial welcome screen. Initial view of Stan Agent dock in Godot
  2. Login with Browser: Click the prominent "Login with Browser" button located within the Stan Agent dock. Login with Browser button clicked in Stan Agent dock

UI Elements During Login​

After clicking "Login with Browser":

  • Godot displays a welcome screen with a banner, transitioning to a status text: [center]Please authorize in browser...[/center]. This indicates that Stan is awaiting external authorization.

Authentication URL​

The plugin will automatically open your default web browser to: https://stan.stanlink.online/#/auth?code={YOUR_DEVICE_CODE} (The {YOUR_DEVICE_CODE} part will be pre-filled with the unique code generated by the Godot Editor).

  1. Browser Authorization Request: Browser authentication request with account selection
  2. Grant Permissions: You will be prompted to authorize StanLink Extensions to access your account. Authorization screen showing access permissions
  3. Confirmation: After granting permissions, a confirmation pop-up will appear. Click "Continue to Dashboard" to finalize the login. Confirmation popup to continue to dashboard

Successful Feedback​

Upon successful authorization in the browser:

  • The Godot Editor's Stan Agent dock will automatically update.
  • A green status indicator [center][color=green]Connected![/color][/center] will briefly display.
  • The login screen will transition to the Stan Dashboard, showing the "Chat" and "Tasks" tabs, ready for interaction. Connected dashboard view in Godot

Session Management​

  • Logout: To sign out, click the Hamburger Menu (☰) in the top-right corner of the Stan Agent dashboard and select "Sign Out".

IV. Core Features & Usage (Godot-Specific)​

A. Deep Project Context (Godot's AI "Eyes")​

Stan's Deep Project Context in Godot provides the AI with a comprehensive understanding of your project, enabling highly accurate and relevant assistance.

  1. Context Gathering:

    • Context gathering is automatic and deep. Every time you send a message to Stan, it triggers a scan of:
      • Your visual folder structure (Project Tree).
      • The current scene hierarchy (Nodes and their Types).
      • Currently selected nodes in the editor.
      • Text content of relevant .gd (GDScript), .tscn (scene), .md (Markdown), .txt (text), and .json (JSON) files, with up to a 100-line preview for optimal token usage and accuracy.

  2. Feedback:

    • During context gathering, system messages will appear in the Stan Agent chat log, such as "🔍 Reading file: player.gd", "📁 Listing directory...", providing transparency into Stan's understanding process.

  3. Configuration:

    • The Godot plugin in v1.0.4+ is zero-config. Stan intelligently prioritizes files and information mentioned in your chat prompts, utilizing a "Pre-Read" heuristic. This maximizes accuracy while efficiently managing AI token usage, providing a seamless "it just works" experience.

  4. Example Prompt leveraging Deep Context:

    • Prompt: "Find the 'Credits' Label in my open scene and change its text to say 'Developed by MyStudio with Stan Agent'."
    • Stan's Understanding: Stan will automatically locate the 'Credits' Label node based on its name and modify its text property, demonstrating its ability to interact directly with your scene's nodes.

B. Task-Driven Workflow (Godot's Integrated Task Manager)​

The Task Manager in Godot provides a structured overview and control over Stan's actions, especially for multi-step operations.

  1. Accessing Task Manager:

    • Navigate to the "Tasks" tab at the top of the main Stan Agent panel.

  2. Task Stages: Tasks progress through clear stages, each with an intuitive icon:

    • Pending (⭕): The task is queued and awaiting execution.
    • In Progress (⏳): Stan is actively working on this task.
    • Completed (✅): The task has been successfully finished and applied.
    • Failed (❌): Stan encountered an error during execution.

  3. Task Information: The Task Manager displays:

    • Title: A bold summary of the task's objective.
    • Status & Icon: The current stage (Pending, In Progress, Completed, Failed) with its corresponding visual icon.
    • Note: The UI automatically switches to the "Tasks" tab whenever Stan generates a multi-step plan in response to a complex request.

  4. User Interaction:

    • Execute Next Task: For planned items, users can click "Execute Next Task" to trigger Stan's automated coding engine for the next step in the plan. This gives you control over the execution flow.

C. AI Interaction (How to ask Stan to do things in Godot)​

Interacting with Stan in Godot is primarily chat-based, using natural language prompts.

  1. Input Area:

    • You input your requests in a dedicated text box at the bottom of the "Chat" tab within the Stan Agent dock.

  2. Phrasing Best Practices:

    • Stan understands natural language, but precision improves results.
    • Node Names: Refer to Node names exactly as they appear in your Godot Scene Tree.
      • Example: Instead of "Add a cube," say "Add a Sprite2D child to the Player node." Stan can then precisely target the 'Player' node.

  3. Responses & Modifications: Stan communicates and acts dynamically:

    • Thought: Stan's internal reasoning or plan is often displayed (e.g., in gray italics) before an action.
    • Message: Stan provides natural language explanations for its actions or questions in the chat log.
    • Actions: Stan performs immediate, autonomous file and scene edits. You will observe these changes occurring directly in your Godot Editor workspace as Stan executes.

V. Troubleshooting & Support (Godot-Specific)​

Common Issues & Troubleshooting​

  • TLS Handshake Error: Ensure you are using Stan Godot plugin v1.0.4+ which utilizes the optimized plugin endpoint. If the issue persists, check system-wide TLS/SSL configurations or proxy settings.
  • "Nil" instance errors: These are usually resolved by a clean reinstall. Delete the addons/stan_agent folder from your Godot project and extract a fresh download of the plugin.
  • Editor Freezes/Performance: If the editor becomes unresponsive during complex AI operations, ensure your system meets minimum requirements and consider simplifying large scenes before initial context gathering.

Support Channels​

If you encounter issues not covered here, or require further assistance, please reach out to our support channels: