documentation/VSCODE_INTEGRATION.md

VS Code Integration Guide for Godot Development

Overview

This guide provides comprehensive instructions for setting up Visual Studio Code as your primary editor for Godot game development. VS Code offers superior C# support, excellent Git integration, and powerful extensions that significantly enhance the Godot development experience compared to the built-in editor.

Why Use VS Code with Godot?

Advantages of VS Code

• Superior IntelliSense: Advanced code completion, error detection, and refactoring tools
• Powerful Extensions: Rich ecosystem of extensions for C#, Git, and game development
• Better Git Integration: Built-in Git support with visual diff tools and GitLens integration
• Multi-Project Support: Work with multiple libraries and projects simultaneously
• Debugging Support: Integrated debugging capabilities for C# code
• Customizable Interface: Themes, layouts, and keyboard shortcuts
• Fast Performance: Lightweight and responsive compared to full IDEs

What You'll Get

• Full project context when opening files from Godot
• IntelliSense for your custom libraries and Godot APIs
• Seamless navigation between files and projects
• Integrated terminal for Git operations
• Side-by-side editing of multiple files
• Advanced search and replace across entire projects

Prerequisites

• Godot v4.5.1+ with C# support enabled
• .NET 8.0+ installed
• Visual Studio Code installed
• Basic familiarity with VS Code interface

Initial Setup and Configuration

Step 1: Install VS Code Extensions

Install these essential extensions for optimal Godot development:

Required Extensions

# Core C# support
code --install-extension ms-dotnettools.csdevkit
code --install-extension ms-dotnettools.csharp

# Godot integration
code --install-extension geequlim.godot-tools

Highly Recommended Extensions

# Enhanced development experience
code --install-extension visualstudioexptteam.vscodeintellicode
code --install-extension eamodio.gitlens
code --install-extension ms-vscode.vscode-json

# Code quality and formatting
code --install-extension ms-dotnettools.vscode-dotnet-runtime
code --install-extension streetsidesoftware.code-spell-checker

# Productivity enhancements
code --install-extension ms-vscode.powershell
code --install-extension ms-vscode-remote.remote-repositories

Optional but Useful Extensions

# Visual enhancements
code --install-extension pkief.material-icon-theme
code --install-extension zhuangtongfa.material-theme

# Additional tools
code --install-extension formulahendry.auto-rename-tag
code --install-extension ms-vscode.hexeditor
code --install-extension redhat.vscode-yaml

Step 2: Configure Godot to Use VS Code

Basic External Editor Setup

1. Open Godot Editor Settings

   • Go to Editor → Editor Settings
   • Navigate to Network → Language Server
   • Set Use Language Server to On

2. Configure External Editor

   • Navigate to Text Editor → External
   • Check Use External Editor
   • Set Exec Path to VS Code installation:
     • macOS: /Applications/Visual Studio Code.app/Contents/Resources/app/bin/code
     • Windows: C:\Users\[Username]\AppData\Local\Programs\Microsoft VS Code\Code.exe
     • Linux: /usr/bin/code or /snap/bin/code
     • Alternative: Just code if you have the command in your PATH

Step 3: Fix Project Context Issue

The default setup opens individual files without project context. Here are several solutions:

Solution A: Create Smart Wrapper Script (Recommended)

Create a script that ensures VS Code always opens with full project context:

For macOS/Linux:

# Create the wrapper script
cat > ~/GameDev/vscode-godot.sh << 'EOF'
#!/bin/bash

# Get the file path passed by Godot
FILE_PATH="$1"
LINE_NUMBER="$2"
COLUMN_NUMBER="$3"

# Find the project directory by looking for project.godot
PROJECT_DIR=$(dirname "$FILE_PATH")
while [[ "$PROJECT_DIR" != "/" && ! -f "$PROJECT_DIR/project.godot" ]]; do
    PROJECT_DIR=$(dirname "$PROJECT_DIR")
done

# If we found a project.godot, open that directory with the file
if [[ -f "$PROJECT_DIR/project.godot" ]]; then
    echo "Opening project: $PROJECT_DIR"
    code "$PROJECT_DIR" --goto "$FILE_PATH:$LINE_NUMBER:$COLUMN_NUMBER"
else
    echo "No project.godot found, opening file directory"
    code "$(dirname "$FILE_PATH")" --goto "$FILE_PATH:$LINE_NUMBER:$COLUMN_NUMBER"
fi
EOF

# Make it executable
chmod +x ~/GameDev/vscode-godot.sh

For Windows (PowerShell):

# Create vscode-godot.ps1 in your GameDev directory
@'
param(
    [string]$FilePath,
    [string]$LineNumber = "1",
    [string]$ColumnNumber = "1"
)

# Find project directory
$ProjectDir = Split-Path $FilePath -Parent
while (($ProjectDir -ne [System.IO.Path]::GetPathRoot($ProjectDir)) -and 
       (-not (Test-Path (Join-Path $ProjectDir "project.godot")))) {
    $ProjectDir = Split-Path $ProjectDir -Parent
}

# Open VS Code with project context
if (Test-Path (Join-Path $ProjectDir "project.godot")) {
    Write-Host "Opening project: $ProjectDir"
    & code $ProjectDir --goto "$FilePath`:$LineNumber`:$ColumnNumber"
} else {
    Write-Host "No project.godot found, opening file directory"
    & code (Split-Path $FilePath -Parent) --goto "$FilePath`:$LineNumber`:$ColumnNumber"
}
'@ | Out-File -FilePath "~/GameDev/vscode-godot.ps1" -Encoding UTF8

Configure Godot to Use the Wrapper Script

In Godot's Editor Settings → Text Editor → External:

• Exec Path: /Users/[your-username]/GameDev/vscode-godot.sh (or path to .ps1 on Windows)
• Exec Flags: {file} {line} {col}

Solution B: Simple Project Opening

Alternative simpler approach in Exec Flags:

{project} --goto {file}:{line}:{col}

This opens the project directory and navigates to the specific file.

Project-Specific VS Code Configuration

Step 1: Create Workspace Settings

For each Godot project, create .vscode/settings.json:

# Navigate to your project
cd ~/GameDev/projects/test-game

# Create .vscode directory
mkdir -p .vscode

# Create comprehensive settings
cat > .vscode/settings.json << 'EOF'
{
    // .NET and C# Configuration
    "dotnet.defaultSolution": "TestGame.sln",
    "omnisharp.enableEditorConfigSupport": true,
    "omnisharp.enableImportCompletion": true,
    "omnisharp.enableRoslynAnalyzers": true,
    "omnisharp.useModernNet": true,
    
    // Godot Integration
    "godot_tools.editor_path": "~/GameDev/Godot/Godot.app/Contents/MacOS/Godot",
    "godot_tools.gdscript_lsp_server_port": 6005,
    
    // File Management
    "files.exclude": {
        "**/.godot": true,
        "**/.import": true,
        "**/bin": true,
        "**/obj": true,
        "**/*.tmp": true
    },
    
    // Window Behavior
    "window.openFilesInNewWindow": "off",
    "window.openFoldersInNewWindow": "off",
    "workbench.editor.revealIfOpen": true,
    
    // Search Configuration
    "search.exclude": {
        "**/.godot": true,
        "**/bin": true,
        "**/obj": true
    },
    
    // File Associations
    "files.associations": {
        "*.cs": "csharp",
        "*.tscn": "godot-scene",
        "*.tres": "godot-resource",
        "*.gd": "gdscript"
    },
    
    // Code Formatting
    "editor.formatOnSave": true,
    "editor.formatOnType": true,
    "csharp.format.enable": true,
    
    // Git Integration
    "git.autoRepositoryDetection": "subFolders",
    "git.detectSubmodules": true,
    
    // Terminal Configuration
    "terminal.integrated.cwd": "${workspaceFolder}"
}
EOF

Step 2: Create Launch Configuration

Set up debugging and task running with .vscode/launch.json:

cat > .vscode/launch.json << 'EOF'
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Play in Editor",
            "type": "godot",
            "request": "launch",
            "project": "${workspaceFolder}",
            "port": 6007,
            "debugServer": 6008,
            "preLaunchTask": "build"
        },
        {
            "name": "Launch Game",
            "type": "godot",
            "request": "launch",
            "project": "${workspaceFolder}",
            "port": 6007,
            "debugServer": 6008,
            "executable": "~/GameDev/Godot/Godot.app/Contents/MacOS/Godot",
            "executableArguments": [
                "--path",
                "${workspaceFolder}"
            ]
        },
        {
            "name": "Launch Main Scene",
            "type": "godot",
            "request": "launch",
            "project": "${workspaceFolder}",
            "port": 6007,
            "debugServer": 6008,
            "executable": "~/GameDev/Godot/Godot.app/Contents/MacOS/Godot",
            "executableArguments": [
                "--path",
                "${workspaceFolder}",
                "Scenes/Main.tscn"
            ]
        }
    ]
}
EOF

Step 3: Configure Build Tasks

Create .vscode/tasks.json for build automation:

cat > .vscode/tasks.json << 'EOF'
{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build",
            "type": "dotnet",
            "task": "build",
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "presentation": {
                "echo": true,
                "reveal": "silent",
                "focus": false,
                "panel": "shared"
            },
            "problemMatcher": "$msCompile"
        },
        {
            "label": "clean",
            "type": "dotnet",
            "task": "clean",
            "group": "build",
            "presentation": {
                "echo": true,
                "reveal": "always",
                "focus": false,
                "panel": "shared"
            },
            "problemMatcher": "$msCompile"
        },
        {
            "label": "restore",
            "type": "dotnet",
            "task": "restore",
            "group": "build",
            "presentation": {
                "echo": true,
                "reveal": "silent",
                "focus": false,
                "panel": "shared"
            },
            "problemMatcher": []
        }
    ]
}
EOF

Multi-Project Workspace Setup

Creating a Master Workspace

For working with multiple projects and libraries simultaneously:

# Create a master workspace file
cat > ~/GameDev/godot-development.code-workspace << 'EOF'
{
    "folders": [
        {
            "name": "🎮 Test Game",
            "path": "./projects/test-game"
        },
        {
            "name": "🎮 Puzzle Game", 
            "path": "./projects/puzzle-game"
        },
        {
            "name": "📚 Utilities Library",
            "path": "./libraries/utilities"
        },
        {
            "name": "📚 Audio Manager Library",
            "path": "./libraries/audio-manager"
        }
    ],
    "settings": {
        // Global workspace settings
        "files.exclude": {
            "**/.godot": true,
            "**/.import": true,
            "**/bin": true,
            "**/obj": true
        },
        "search.exclude": {
            "**/.godot": true,
            "**/bin": true,
            "**/obj": true
        },
        "git.detectSubmodules": true,
        "git.autoRepositoryDetection": "subFolders",
        
        // Default to first project's solution
        "dotnet.defaultSolution": "./projects/test-game/TestGame.sln"
    },
    "extensions": {
        "recommendations": [
            "ms-dotnettools.csdevkit",
            "ms-dotnettools.csharp",
            "geequlim.godot-tools",
            "eamodio.gitlens",
            "visualstudioexptteam.vscodeintellicode"
        ]
    }
}
EOF

Opening the Workspace

# Open the master workspace
code ~/GameDev/godot-development.code-workspace

# Or open individual projects
cd ~/GameDev/projects/test-game
code .

Development Workflows

Daily Development Routine

1. Start Your Day

   # Open your workspace
   code ~/GameDev/godot-development.code-workspace
   
   # Or open specific project
   cd ~/GameDev/projects/test-game
   code .
   

2. Working with Files

   • From Godot: Double-click scripts → Opens in VS Code with full project context
   • From VS Code: Use Cmd/Ctrl + P to quickly open files
   • Navigation: Use Cmd/Ctrl + Click on symbols to jump to definitions

3. Building and Testing

   • Quick Build: Cmd/Ctrl + Shift + P → "Tasks: Run Build Task"
   • From Godot: Use Godot's Build button (recommended for final builds)
   • Debug: Use F5 in VS Code (if debugging is set up)

Working with Libraries

Editing Library Code

1. Navigate to library:

   cd ~/GameDev/libraries/utilities
   code .
   

2. Make changes with full IntelliSense support

3. Test changes:

   • Open the library project in Godot
   • Or test within a game project that uses the library

4. Commit and push changes:

   git add .
   git commit -m "Add new utility function"
   git push origin main
   

Updating Libraries in Projects

1. Update from VS Code terminal:

   # In your game project
   git submodule update --remote Libraries/utilities
   git add Libraries/utilities
   git commit -m "Update utilities library"
   

2. Reload project in Godot to pick up changes

Git Integration Workflows

Using VS Code's Built-in Git

1. Source Control Panel (Cmd/Ctrl + Shift + G):

   • View changes across all repositories
   • Stage and commit changes
   • See submodule status

2. Git Commands:

   • Cmd/Ctrl + Shift + P → "Git: " for all Git commands
   • Built-in diff viewer for file changes
   • Integrated merge conflict resolution

Advanced Git with GitLens

1. Blame Information: See who changed each line of code
2. File History: View complete file change history
3. Repository Insights: Visualize branch structure and commits
4. Interactive Rebase: Advanced Git operations through UI

Advanced Features and Tips

IntelliSense and Code Navigation

Maximizing IntelliSense Performance

1. Ensure proper project references in .csproj files
2. Build solution regularly to update IntelliSense cache
3. Use "Reload Window" if IntelliSense stops working:
   • Cmd/Ctrl + Shift + P → "Developer: Reload Window"

Navigation Shortcuts

• Go to Definition: F12 or Cmd/Ctrl + Click
• Go to References: Shift + F12
• Go to Symbol: Cmd/Ctrl + Shift + O
• Go to File: Cmd/Ctrl + P
• Command Palette: Cmd/Ctrl + Shift + P

Code Formatting and Quality

Auto-Formatting Setup

1. Install C# extension with formatting support
2. Configure format on save in settings.json
3. Use EditorConfig for consistent formatting across team

Create .editorconfig in project root:

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.cs]
indent_style = space
indent_size = 4

[*.{csproj,props,targets}]
indent_style = space
indent_size = 2

Code Quality Tools

1. Enable Roslyn Analyzers in settings.json
2. Use SonarLint extension for additional code quality checks
3. Configure spell checking for comments and strings

Debugging Setup

Enable Debugging in Godot

1. In Godot Project Settings:

   • Go to Debug → Settings
   • Enable Remote Port (usually 6007)
   • Enable Remote Host (usually 127.0.0.1)

2. In VS Code:

   • Set breakpoints in your C# code
   • Press F5 to start debugging
   • Godot will connect to VS Code debugger

Debugging Workflow

1. Set breakpoints in VS Code
2. Start debugging with F5
3. Play scene in Godot
4. Debug in VS Code when breakpoints hit

Customization and Themes

Recommended Themes for Game Development

# Dark themes optimized for long coding sessions
code --install-extension zhuangtongfa.material-theme
code --install-extension github.github-vscode-theme
code --install-extension dracula-theme.theme-dracula

# Icon themes for better file recognition
code --install-extension pkief.material-icon-theme
code --install-extension vscode-icons-team.vscode-icons

Custom Keybindings

Create custom keybindings for Godot workflows in keybindings.json:

[
    {
        "key": "cmd+shift+g",
        "command": "godot.runProject",
        "when": "resourceExtname == '.cs'"
    },
    {
        "key": "cmd+shift+b",
        "command": "workbench.action.tasks.build"
    }
]

Troubleshooting

Common Issues and Solutions

VS Code Opens Individual Files Instead of Project

Problem: Clicking scripts in Godot opens single files without project context.

Solutions:

1. Use the wrapper script (recommended approach above)
2. Keep project always open in VS Code
3. Modify Exec Flags to {project} --goto {file}:{line}:{col}

IntelliSense Not Working

Problem: No code completion or error detection.

Solutions:

1. Check C# extension is installed and enabled
2. Verify .csproj references are correct
3. Reload VS Code window: Cmd/Ctrl + Shift + P → "Developer: Reload Window"
4. Rebuild solution: Cmd/Ctrl + Shift + P → "Tasks: Run Build Task"
5. Check OmniSharp output in Output panel

Submodule Libraries Not Recognized

Problem: Libraries in submodules don't have IntelliSense.

Solutions:

1. Verify submodules are initialized:

   git submodule update --init --recursive
   

2. Check project references in .csproj
3. Rebuild solution after submodule updates

Git Integration Issues

Problem: Git operations not working correctly with submodules.

Solutions:

1. Enable submodule detection in settings:

   "git.detectSubmodules": true
   

2. Use terminal for complex Git operations
3. Check repository status in each submodule directory

Build Errors in VS Code

Problem: Build fails in VS Code but works in Godot.

Solutions:

1. Check .NET SDK version matches Godot requirements
2. Use Godot's build system as authoritative
3. Clean and rebuild:

   dotnet clean
   dotnet restore
   dotnet build
   

Performance Issues

Problem: VS Code becomes slow with large projects.

Solutions:

1. Exclude build directories in settings.json
2. Disable unnecessary extensions
3. Increase VS Code memory limit:

   code --max-memory=8192
   

Diagnostic Commands

Check Extension Status

# List installed extensions
code --list-extensions

# Check if specific extensions are installed
code --list-extensions | grep -E "(csdevkit|godot-tools|csharp)"

Verify Project Setup

# Check submodule status
git submodule status

# Verify project can build
dotnet build

# Check Godot project configuration
grep -A 5 "\[dotnet\]" project.godot

Best Practices

Project Organization

1. Consistent Structure: Use the same folder layout across all projects
2. Clear Naming: Use descriptive names for files and folders
3. Separate Concerns: Keep game logic, UI, and utilities in separate folders
4. Document Code: Use XML documentation comments for public APIs

Code Quality

1. Follow C# Conventions: Use PascalCase for classes, camelCase for methods
2. Use Meaningful Names: Avoid abbreviations and unclear variable names
3. Keep Methods Small: Single responsibility principle
4. Comment Complex Logic: Explain why, not what

Git Workflow

1. Commit Often: Small, focused commits are easier to review
2. Descriptive Messages: Use clear commit messages
3. Branch Strategy: Use feature branches for new development
4. Test Before Pushing: Ensure code builds and runs before pushing

Performance

1. Exclude Build Folders: Keep VS Code fast by excluding unnecessary directories
2. Regular Cleanup: Clean build artifacts regularly
3. Monitor Extensions: Disable unused extensions
4. Use Workspace Settings: Project-specific settings improve performance

Conclusion

This setup provides a powerful, integrated development environment for Godot game development with C#. The combination of VS Code's advanced editing capabilities with Godot's excellent game engine creates an optimal workflow for both solo developers and teams.

Key Benefits Achieved

• Full Project Context: No more single-file editing
• Superior IntelliSense: Complete code completion and error detection
• Seamless Git Integration: Visual diff tools and submodule support
• Multi-Project Support: Work with libraries and games simultaneously
• Professional Debugging: Set breakpoints and inspect variables
• Extensible Environment: Customize with thousands of available extensions

Next Steps

1. Implement the wrapper script for proper project opening
2. Configure your first project with the provided settings
3. Install recommended extensions
4. Create a multi-project workspace for library development
5. Customize themes and keybindings to your preferences

Remember to update this documentation as your workflow evolves and new VS Code features become available!

---

Keep this documentation updated as VS Code and Godot continue to evolve.