harrison/documentation
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated filename

Browse Source
This commit is contained in:
harrison
2025-10-23 14:38:04 +00:00
parent 895cf0c008
commit da1ef266d7
1 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

768
VSCODE_INTEGRATION.md Normal file
View File

@@ -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.*