AgentSkillsCN

godot-lsp

连接 Godot 的语言服务器协议，为 GDScript 项目提供代码智能支持。适用于在 Godot 项目中使用时，获取符号定义、悬停文档、代码补全建议、工作区符号搜索，以及诊断信息。支持查询 GDScript 代码结构、查找函数与类的定义、获取内联文档，并对代码进行校验。

SKILL.md
--- frontmatter
name: godot-lsp
description: Connect to Godot's Language Server Protocol for code intelligence on GDScript projects. Use when working with Godot projects to get symbol definitions, hover documentation, code completion suggestions, workspace symbol search, and diagnostics. Supports querying GDScript code structure, finding function/class definitions, getting inline docs, and validating code.

Godot LSP Client

Query Godot's Language Server Protocol for code intelligence on GDScript projects.

Prerequisites

Godot must be running with LSP enabled:

bash
godot --path /path/to/project --lsp-port 6005 --headless &

Default port: 6005 (Godot 3.x and 4.x)

Commands

Find Definition

Locate where a symbol is defined:

bash
python scripts/godot_lsp.py --project-path <project> definition <file>:<line>:<char>
python scripts/godot_lsp.py --project-path <project> definition <symbol-name>

Example:

bash
python scripts/godot_lsp.py --project-path ~/Projects/metalball definition scripts/ball.gd:25:10
python scripts/godot_lsp.py --project-path ~/Projects/metalball definition BallPhysics

Get Hover Documentation

Retrieve inline documentation for symbol at cursor position:

bash
python scripts/godot_lsp.py --project-path <project> hover <file>:<line>:<char>

Example:

bash
python scripts/godot_lsp.py --project-path ~/Projects/metalball hover scripts/player.gd:15:8

Search Symbols

Find symbols (classes, functions, variables) across the entire workspace:

bash
python scripts/godot_lsp.py --project-path <project> symbols <query>

Example:

bash
python scripts/godot_lsp.py --project-path ~/Projects/metalball symbols Ball
python scripts/godot_lsp.py --project-path ~/Projects/metalball symbols "func _ready"

Code Completion

Get autocomplete suggestions at cursor position:

bash
python scripts/godot_lsp.py --project-path <project> completion <file>:<line>:<char>

Example:

bash
python scripts/godot_lsp.py --project-path ~/Projects/metalball completion scripts/ball.gd:30:12

Position Format

Use file:line:character where:

  • •file - path relative to project root (e.g., scripts/ball.gd)
  • •line - 1-indexed line number
  • •character - 0-indexed column offset

Workflow Examples

Find where a class is defined:

  1. •Search symbols: symbols BallPhysics
  2. •Parse location.uri and range from response

Get documentation for a method:

  1. •Position cursor at method call
  2. •Run: hover scripts/player.gd:20:15
  3. •Read contents.value markdown

Validate GDScript syntax:

  1. •Use diagnostics scripts/ball.gd
  2. •Check for errors/warnings in response

Troubleshooting

Connection refused:

  • •Ensure Godot is running with --lsp-port 6005
  • •Check port availability: lsof -i :6005

Empty responses:

  • •LSP server may still be indexing files (wait 2-3 seconds after starting)
  • •Verify file path is relative to project root
  • •Confirm symbol exists in codebase

For detailed protocol reference: See references/lsp_quick_reference.md