Godot LSP Bridge

A high-performance TCP-to-stdio bridge that enables AI IDEs to communicate with Godot's native LSP servers for full GDScript language support.

Features

✅ Multi-Project Support - Work on multiple Godot projects simultaneously
✅ Auto-Start Godot Instances - Automatically launches Godot when needed
✅ Dynamic Port Allocation - Prevents port conflicts (6005+)
✅ Smart Project Detection - Finds closest project.godot (root first, then nested)
✅ Full LSP Features - Syntax errors, completion, navigation, hover
✅ Performance Optimized - Connection pooling, caching, memory management
✅ Robust Startup - Retry logic ensures Godot starts reliably
✅ Completion Caching - 78% faster completions with intelligent caching

Performance Highlights

• Cold completion: ~310ms (limited by Godot)
• Warm completions: ~110ms (78% improvement with caching)
• Godot startup: <5s with retry logic
• Connection reuse: Persistent connections reduce overhead
• Memory efficient: Automatic cleanup and monitoring

Quick Start

1. Install dependencies:

   bun install
   

2. Configure your IDE (example for MCP-compatible IDEs):

   {
     "lsp": {
       "gdscript": {
         "command": ["bun", "/path/to/godot-lsp-bridge/src/index.js"],
         "extensions": [".gd", ".gdshader"],
         "initializationOptions": {
           "godotPath": "/path/to/godot.exe",
           "basePort": 6005,
           "maxInstances": 10,
           "autoStart": true,
           "logLevel": "info"
         }
       }
     }
   }
   

3. Test the bridge:

   bun run test
   

4. Run performance benchmarks:

   bun run benchmark
   

Architecture

IDE (stdio) ↔ Bridge (stdio) ↔ Godot Instance (TCP:6005+)

• Bridge: Node.js process that translates between stdio and TCP
• Smart Project Detection: Finds closest project.godot (workspace root first, then nested projects)
• Instance Manager: Manages multiple Godot processes on unique ports
• Protocol Translator: Handles LSP message format conversion

Project Detection Strategy

The bridge uses an intelligent project detection strategy:

1. Root First: Checks workspace root for project.godot
2. Nested Search: Walks up from file location to find closest project
3. Closest Wins: Chooses the project closest to the file being edited
4. Caching: Results are cached for performance

Example Structures:

With project.godot:

workspace/
├── project.godot          # Root project
├── scripts/
│   └── Player.gd         # → Uses root project
└── addons/
    └── my_addon/
        ├── project.godot  # Nested project
        └── addon.gd      # → Uses nested project

This ensures files are associated with the correct project, whether you have a single project or multiple nested projects.

Files Structure

godot-lsp-bridge/
├── src/
│   ├── index.js              # Main entry point
│   ├── bridge.js             # Core LSP bridge logic
│   ├── project-detector.js   # Project.godot detection
│   ├── godot-instance-manager.js  # Godot process management
│   ├── protocol-translator.js     # TCP-stdio translation
│   └── utils/
│       ├── config.js         # Configuration management
│       ├── logger.js         # Logging utilities
│       └── errors.js         # Custom error types
├── test/
│   └── test.js               # Basic test script
└── package.json

Configuration Options

Option	Default	Description
godotPath	Required	Path to Godot executable
basePort	6005	Starting port for Godot instances
maxInstances	10	Maximum concurrent Godot instances
autoStart	true	Automatically start Godot when needed
logLevel	"info"	Logging level (debug, info, warn, error)

Environment Variables

• GODOT_PATH - Path to Godot executable
• GODOT_LSP_BASE_PORT - Starting port number (default: 6005)
• GODOT_LSP_MAX_INSTANCES - Maximum concurrent instances (default: 10)
• GODOT_LSP_LOG_LEVEL - Logging level (debug, info, warn, error)

Testing

Run the test script:

bun test/test.js

This will:

1. Start the bridge process
2. Send an initialize message
3. Send a shutdown message
4. Clean up

Usage

1. Open a GDScript file in your Godot project
2. The bridge will automatically:
   • Detect the project from project.godot
   • Start a Godot instance on an available port
   • Begin translating LSP messages
3. Full LSP features will be available:
   • Syntax error detection ✅
   • Code completion ✅
   • Go to definition ✅
   • Hover information ✅
   • Symbol navigation ✅

Performance Testing

The bridge includes comprehensive performance tests:

# Run all performance tests
bun run test:performance

# Test completion optimization specifically
bun run test:completion

# Run full benchmark suite
bun run benchmark

Expected Performance Scores:

• 7-8/8: Excellent performance
• 5-6/8: Good performance
• 3-4/8: Needs improvement
• 0-2/8: Poor performance

Troubleshooting

Bridge doesn't start:

• Verify dependencies are installed
• Check the path in OpenCode configuration

Godot instances not starting:

• Verify Godot executable path is correct
• Check that Godot 4.5+ is installed
• Look for permission issues

No LSP features:

• Ensure project.godot file exists
• Check bridge logs for errors
• Verify file extensions (.gd, .gdshader) are configured

Port conflicts:

• Bridge automatically handles port allocation
• Conflicts are resolved by using higher ports
• Set GODOT_LSP_BASE_PORT if needed

Troubleshooting

Bridge doesn't start

• Verify dependencies are installed (bun install)
• Check the path in your IDE configuration

Godot instances not starting

• Verify Godot executable path is correct
• Check that Godot 4.5+ is installed
• Look for permission issues
• Check logs with GODOT_LSP_LOG_LEVEL=debug

No LSP features

• Ensure project.godot file exists in your project root
• Check bridge logs for errors
• Verify file extensions (.gd, .gdshader) are configured
• First startup takes 5-10 seconds (Godot initialization)

Port conflicts

• Bridge automatically handles port allocation
• Conflicts are resolved by using higher ports (6005+)
• Set GODOT_LSP_BASE_PORT environment variable if needed

Performance issues

• First completion request takes ~310ms (Godot cold start)
• Subsequent requests should be ~110ms (cached)
• Run bun run benchmark to verify performance
• Check memory usage with debug logging

Logging

Enable debug logging to troubleshoot issues:

# Environment variable
export GODOT_LSP_LOG_LEVEL=debug

# Or in configuration
"initializationOptions": {
  "logLevel": "debug"
}

Debug logs show:

• LSP message traffic
• Godot instance lifecycle
• Port allocation details
• Performance metrics
• Error stack traces

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: bun run test && bun run benchmark
5. Submit a pull request

License

MIT License - see LICENSE file for details.