documentation/setup/VSCODE_INTEGRATION.md

# VS Code Setup for Godot Development

## Why VS Code?

Better IntelliSense, Git integration, extensions, debugging, and multi-project support compared to Godot's built-in editor.

## Prerequisites

- Godot v4.5.1+ (C# support)
- .NET 8.0+
- Visual Studio Code

## Setup

### 1. Install Extensions

**Required:**
```bash
code --install-extension ms-dotnettools.csdevkit
code --install-extension ms-dotnettools.csharp
code --install-extension geequlim.godot-tools
```

**Recommended:**
```bash
code --install-extension visualstudioexptteam.vscodeintellicode
code --install-extension eamodio.gitlens
code --install-extension streetsidesoftware.code-spell-checker
```

### 2. Configure Godot

**Editor Settings:**
1. **Editor → Editor Settings → Network → Language Server**
   - Enable **Use Language Server**

2. **Text Editor → External**
   - Check **Use External Editor**
   - **Exec Path:**
     - 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 just `code`

### 3. Fix Project Context (Choose One)

**Option A - Simple Flags (Easiest):**
```
{project} --goto {file}:{line}:{col}
```

**Option B - Wrapper Script (Best):**

**macOS/Linux** (`~/GameDev/vscode-godot.sh`):
```bash
#!/bin/bash
FILE_PATH="$1"
LINE_NUMBER="$2"
COLUMN_NUMBER="$3"

PROJECT_DIR=$(dirname "$FILE_PATH")
while [[ "$PROJECT_DIR" != "/" && ! -f "$PROJECT_DIR/project.godot" ]]; do
    PROJECT_DIR=$(dirname "$PROJECT_DIR")
done

if [[ -f "$PROJECT_DIR/project.godot" ]]; then
    code "$PROJECT_DIR" --goto "$FILE_PATH:$LINE_NUMBER:$COLUMN_NUMBER"
else
    code "$(dirname "$FILE_PATH")" --goto "$FILE_PATH:$LINE_NUMBER:$COLUMN_NUMBER"
fi
```

**Windows** (`~/GameDev/vscode-godot.ps1`):
```powershell
param($FilePath, $LineNumber = "1", $ColumnNumber = "1")

$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
}

if (Test-Path (Join-Path $ProjectDir "project.godot")) {
    & code $ProjectDir --goto "$FilePath`:$LineNumber`:$ColumnNumber"
} else {
    & code (Split-Path $FilePath -Parent) --goto "$FilePath`:$LineNumber`:$ColumnNumber"
}
```

Make script executable: `chmod +x ~/GameDev/vscode-godot.sh`

Set **Exec Flags**: `{file} {line} {col}`

## Project Configuration

### .vscode/settings.json
```json
{
    "dotnet.defaultSolution": "YourGame.sln",
    "omnisharp.useModernNet": true,
    "godot_tools.editor_path": "/path/to/Godot",
    
    "files.exclude": {
        "**/.godot": true,
        "**/bin": true,
        "**/obj": true
    },
    
    "window.openFilesInNewWindow": "off",
    "editor.formatOnSave": true,
    "git.detectSubmodules": true
}
```

### .vscode/launch.json
```json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Play in Editor",
            "type": "godot",
            "request": "launch",
            "project": "${workspaceFolder}",
            "port": 6007
        }
    ]
}
```

### .vscode/tasks.json
```json
{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build",
            "command": "dotnet",
            "type": "process",
            "args": ["build"],
            "problemMatcher": "$msCompile"
        }
    ]
}
```

### .editorconfig (Optional)
```ini
root = true

[*]
charset = utf-8
insert_final_newline = true

[*.cs]
indent_style = space
indent_size = 4
```

## Multi-Project Workspace

Create `your-workspace.code-workspace`:
```json
{
    "folders": [
        {"path": "projects/main-game"},
        {"path": "libraries/utilities"},
        {"path": "libraries/extensions"}
    ],
    "settings": {
        "omnisharp.useModernNet": true,
        "files.exclude": {
            "**/.godot": true,
            "**/bin": true,
            "**/obj": true
        }
    }
}
```

## Shortcuts

- **Go to Definition**: `F12`
- **Find References**: `Shift + F12`
- **Go to Symbol**: `Cmd/Ctrl + Shift + O`
- **Command Palette**: `Cmd/Ctrl + Shift + P`
- **Search Files**: `Cmd/Ctrl + P`

## Troubleshooting

**IntelliSense not working:**
- Reload window: `Cmd/Ctrl + Shift + P` → "Developer: Reload Window"
- Rebuild: `dotnet build`

**Project opens as single file:**
- Use wrapper script or set Exec Flags to `{project} --goto {file}:{line}:{col}`

**Submodules not recognized:**
```bash
git submodule update --init --recursive
```
Add to settings: `"git.detectSubmodules": true`

**Performance issues:**
- Exclude build folders in settings
- Disable unused extensions
- Run: `code --max-memory=8192`

## Best Practices

- Keep consistent project structure
- Commit often with clear messages
- Use feature branches
- Exclude build folders (.godot, bin, obj)
- Enable format on save
- Document public APIs