diff --git a/docs/VSCODE_INTEGRATION.md b/docs/VSCODE_INTEGRATION.md index 3280f28..cf32158 100644 --- a/docs/VSCODE_INTEGRATION.md +++ b/docs/VSCODE_INTEGRATION.md @@ -1,261 +1,118 @@ -# VS Code Integration Guide for Godot Development +# VS Code Setup for Godot Development -## Overview +## Why VS Code? -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 +Better IntelliSense, Git integration, extensions, debugging, and multi-project support compared to Godot's built-in editor. ## Prerequisites -- Godot v4.5.1+ with C# support enabled -- .NET 8.0+ installed -- Visual Studio Code installed -- Basic familiarity with VS Code interface +- Godot v4.5.1+ (C# support) +- .NET 8.0+ +- Visual Studio Code -## Initial Setup and Configuration +## Setup -### Step 1: Install VS Code Extensions - -Install these essential extensions for optimal Godot development: - -#### Required Extensions +### 1. Install Extensions +**Required:** ```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 - +**Recommended:** ```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 +### 2. Configure Godot -```bash -# Visual enhancements -code --install-extension pkief.material-icon-theme -code --install-extension zhuangtongfa.material-theme +**Editor Settings:** +1. **Editor → Editor Settings → Network → Language Server** + - Enable **Use Language Server** -# 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** +2. **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 + - **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` -### Step 3: Fix Project Context Issue +### 3. Fix Project Context (Choose One) -The default setup opens individual files without project context. Here are several solutions: +**Option A - Simple Flags (Easiest):** +``` +{project} --goto {file}:{line}:{col} +``` -#### Solution A: Create Smart Wrapper Script (Recommended) +**Option B - Wrapper Script (Best):** -Create a script that ensures VS Code always opens with full project context: - -**For macOS/Linux:** +**macOS/Linux** (`~/GameDev/vscode-godot.sh`): ```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):** +**Windows** (`~/GameDev/vscode-godot.ps1`): ```powershell -# Create vscode-godot.ps1 in your GameDev directory -@' -param( - [string]$FilePath, - [string]$LineNumber = "1", - [string]$ColumnNumber = "1" -) +param($FilePath, $LineNumber = "1", $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 +Make script executable: `chmod +x ~/GameDev/vscode-godot.sh` -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}` +Set **Exec Flags**: `{file} {line} {col}` -#### Solution B: Simple Project Opening +## Project Configuration -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' +### .vscode/settings.json +```json { - // .NET and C# Configuration - "dotnet.defaultSolution": "TestGame.sln", - "omnisharp.enableEditorConfigSupport": true, - "omnisharp.enableImportCompletion": true, - "omnisharp.enableRoslynAnalyzers": true, + "dotnet.defaultSolution": "YourGame.sln", "omnisharp.useModernNet": true, + "godot_tools.editor_path": "/path/to/Godot", - // 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 + "window.openFilesInNewWindow": "off", "editor.formatOnSave": true, - "editor.formatOnType": true, - "csharp.format.enable": true, - - // Git Integration - "git.autoRepositoryDetection": "subFolders", - "git.detectSubmodules": true, - - // Terminal Configuration - "terminal.integrated.cwd": "${workspaceFolder}" + "git.detectSubmodules": true } -EOF ``` -### Step 2: Create Launch Configuration - -Set up debugging and task running with `.vscode/launch.json`: - -```bash -cat > .vscode/launch.json << 'EOF' +### .vscode/launch.json +```json { "version": "0.2.0", "configurations": [ @@ -264,505 +121,95 @@ cat > .vscode/launch.json << 'EOF' "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" - ] + "port": 6007 } ] } -EOF ``` -### Step 3: Configure Build Tasks - -Create `.vscode/tasks.json` for build automation: - -```bash -cat > .vscode/tasks.json << 'EOF' +### .vscode/tasks.json +```json { "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" - }, + "command": "dotnet", + "type": "process", + "args": ["build"], "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: +### .editorconfig (Optional) ```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`: +## Multi-Project Workspace +Create `your-workspace.code-workspace`: ```json -[ - { - "key": "cmd+shift+g", - "command": "godot.runProject", - "when": "resourceExtname == '.cs'" - }, - { - "key": "cmd+shift+b", - "command": "workbench.action.tasks.build" +{ + "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 -### Common Issues and Solutions +**IntelliSense not working:** +- Reload window: `Cmd/Ctrl + Shift + P` → "Developer: Reload Window" +- Rebuild: `dotnet build` -#### VS Code Opens Individual Files Instead of Project +**Project opens as single file:** +- Use wrapper script or set Exec Flags to `{project} --goto {file}:{line}:{col}` -**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 +**Submodules not recognized:** ```bash -# List installed extensions -code --list-extensions - -# Check if specific extensions are installed -code --list-extensions | grep -E "(csdevkit|godot-tools|csharp)" +git submodule update --init --recursive ``` +Add to settings: `"git.detectSubmodules": true` -#### 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 -``` +**Performance issues:** +- Exclude build folders in settings +- Disable unused extensions +- Run: `code --max-memory=8192` ## 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 +- 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