# 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

```bash
# 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

```bash
# 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

```bash
# 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:**
```bash
# 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):**
```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`:

```bash
# 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`:

```bash
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:

```bash
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:

```bash
# 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

```bash
# 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**
   ```bash
   # 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**:
   ```bash
   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**:
   ```bash
   git add .
   git commit -m "Add new utility function"
   git push origin main
   ```

#### Updating Libraries in Projects

1. **Update from VS Code terminal**:
   ```bash
   # 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:
```ini
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

```bash
# 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`:

```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**:
   ```bash
   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:
   ```json
   "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**:
   ```bash
   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**:
   ```bash
   code --max-memory=8192
   ```

### Diagnostic Commands

#### Check Extension Status
```bash
# List installed extensions
code --list-extensions

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

#### Verify Project Setup
```bash
# 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.*