From 895cf0c0083201a5e80d78bde554d4b3415651a4 Mon Sep 17 00:00:00 2001
From: harrison <harrisonstuckey1@gmail.com>
Date: Thu, 23 Oct 2025 14:37:27 +0000
Subject: [PATCH] added GODOT_VSCODE_INTEGRATION.md

---
 GODOT_VSCODE_INTEGRATION.md | 768 ++++++++++++++++++++++++++++++++++++
 1 file changed, 768 insertions(+)
 create mode 100644 GODOT_VSCODE_INTEGRATION.md

diff --git a/GODOT_VSCODE_INTEGRATION.md b/GODOT_VSCODE_INTEGRATION.md
new file mode 100644
index 0000000..3280f28
--- /dev/null
+++ b/GODOT_VSCODE_INTEGRATION.md
@@ -0,0 +1,768 @@
+# 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.*
\ No newline at end of file