Add a guide on using the language server protocol

[NathanLovato]

While now the lsp packages supports Godot and GDScript, you still need to set it up. We should provide a guide for that so people know how to get full autocompletion.

[grahnen]

With built in support for gdscript in lsp-mode, shouldn't that be as simple as installing lsp-mode following the instructions on their readme
followed by installing gdscript-mode as described in the README

(use-package gdscript-mode
  :straight (gdscript-mode
                  :type git
                  :host github
                  :repo "GDQuest/emacs-gdscript-mode")
  :hook (gdscript-mode . lsp))

i.e. using a use-package hook to start lsp? (or running M-x lsp from a gdscript buffer)
This is how I setup LSP in Rust and Haskell, so it should be possible to have this be the entire required configuration.

I'd be happy to update the README, but there seems to be something wrong here because I keep getting error messages stating

Error processing message (lsp-unknown-message-type #s(hash-table size 3 test equal rehash-size 1.5 rehash-threshold 0.8125 data ("error" #s(hash-table size 2 test equal rehash-size 1.5 rehash-threshold 0.8125 data ("code" -32601 "message" "Method not found")) "id" nil "jsonrpc" "2.0")))

This makes me think I'm doing something stupid. I'd be happy to help if I can get it to work.

I'm using

• Emacs 27
• Godot built from branch 3.2 (commit e707b71)
• Empty project -> Create Script extending Spatial

[NathanLovato]

It is that simple, yes, although right now you also need a nightly build, and the support in a stable version of Godot will come with 3.2.2.

Even after 3.2.2 is out, I'd like us to mention lsp in the readme to raise awareness about the language server and completion support.

[francogarcia]

Hello, @grahnen and @NathanLovato ,
How are you?

I am also using a custom compiled version of the 3.2 branch and receiving the
same error.

If debug-on-error is disabled, the mode is usable (albeit the errors slow down
the completion and the pop-ups interrupt the workflow). The message keeps
spawning in the modeline, but the features (completion candidates, warnings,
etc.) work.

I have not tried using LSP in the master branch of Godot, as it is unstable at
the moment. As the commits relevant to LSP were recently cherry-picked from the
master to the 3.2 branch (for instance, in
godotengine/godot@ecfe9c2,
godotengine/godot@4150024,
godotengine/godot@511105b),
perhaps other parts of the master branch may differ and it works there.

Otherwise, there is probably a bug in the implementation (either of Godot's LSP
server or of Emacs' LSP client). I have not further investigated it at this
time, though. The error is likely client-side, related to the warning message
received upon initialization ("Warning (lsp-mode): Unknown notification: gdscript/capabilities"): Godot is sending a message specified in those
capabilities that the LSP client implementation is not handling.

A second issue is trying to close an active buffer when the mode is running.
Sometimes, it results into the following error:

LSP :: Timeout while sending shutdown request
lsp--uninitialize-workspace: Process gdscript::tcp is not a subprocess
Error processing message (lsp-unknown-message-type #s(hash-table size 65 test equal rehash-size 1.5 rehash-threshold 0.8125 data ("error" #s(hash-table size 65 test equal rehash-size 1.5 rehash-threshold 0.8125 data ("code" -32601 "message" "Method not found")) "id" nil "jsonrpc" "2.0"))). [2 times]

Best regards,
Franco

[NathanLovato]

Here is the explanation by @ofrank123, who's worked on the language server:

I get this as well, it's due to the saving JSONRPC method not being recognized by godot, and then the language server getting an error message back, the two options are to either implement the method in the language server or to find a way to ignore the error messages on the emacs side.

[francogarcia]

Hello, all,
How are you?

As a temporary workaround to avoid disruptions and improve usability, an advice
can be added around the function to ignore the error message:

(defun franco/godot-gdscript-lsp-ignore-error (original-function &rest args)
  "Ignore the error message resulting from Godot not replying to the `JSONRPC' request."
  (if (string-equal major-mode "gdscript-mode")
      (let ((json-data (nth 0 args)))
        (if (and (string= (gethash "jsonrpc" json-data "") "2.0")
                 (not (gethash "id" json-data nil))
                 (not (gethash "method" json-data nil)))
            nil ; (message "Method not found")
          (apply original-function args)))
    (apply original-function args)))
(advice-add #'lsp--get-message-type :around #'franco/godot-gdscript-lsp-ignore-error)

@ofrank123, thank you for your work! Also thank you for the hint about saving,
as it helps narrowing the problem.

As it is related to saving, the functions lsp--send-will-save-p,
lsp--send-will-save-wait-until-p, lsp--send-did-save-p, and
lsp--save-include-text-p from lsp-mode should be related solution. By
reading their definitions, it seems to be a matter of setting the
lsp--server-capabilities at the LSP client implementation:

  ;; Provides support for registering LSP Server specific capabilities.
  custom-capabilities

Inspecting lsp--client-capabilities leads to:

(synchronization . ((willSave . t) (didSave . t) (willSaveWaitUntil . t)))

which are probably related to the issue (for a more robust solution, perhaps the
gdscript/capabilities do tell Godot's capabilities and could be used to toggle
them).

If this does not work, perhaps that an alternative could be to implement a
custom handler for the message. Inspecting the source code of lsp-mode, there
may be some possibilities:

  ;; 'ignore-regexps' is a list of regexps.  When a data packet from the
  ;; language server matches any of these regexps, it will be ignored.  This is
  ;; intended for dealing with language servers that output non-protocol data.
  (ignore-regexps nil)

  ;; 'ignore-messages' is a list of regexps.  When a message from the language
  ;; server matches any of these regexps, it will be ignored.  This is useful
  ;; for filtering out unwanted messages; such as servers that send nonstandard
  ;; message types, or extraneous log messages.
  (ignore-messages nil)

  ;; 'notification-handlers' is a hash table mapping notification method names
  ;; (strings) to functions handling the respective notifications.  Upon
  ;; receiving a notification, 'lsp-mode' will call the associated handler
  ;; function passing two arguments, the 'lsp--workspace' object and the
  ;; deserialized notification parameters.
  (notification-handlers (make-hash-table :test 'equal))

  ;; 'request-handlers' is a hash table mapping request method names
  ;; (strings) to functions handling the respective notifications.  Upon
  ;; receiving a request, 'lsp-mode' will call the associated handler function
  ;; passing two arguments, the 'lsp--workspace' object and the deserialized
  ;; request parameters.
  (request-handlers (make-hash-table :test 'equal))

  ;; 'response-handlers' is a hash table mapping integral JSON-RPC request
  ;; identifiers for pending asynchronous requests to functions handling the
  ;; respective responses.  Upon receiving a response from the language server,
  ;; 'lsp-mode' will call the associated response handler function with a
  ;; single argument, the deserialized response parameters.
  (response-handlers (make-hash-table :test 'eql))

I will check it when I have time, as I have not read LSP specifications yet.

Best regards,
Franco

[NathanLovato]

@ofrank123 told me the issue had to do with the language server implementation in the Godot engine, that the capabilities function didn't follow the specification. So the fix should go there. Oliver already made the language server compatible with Emacs (and many other text editors), and fixed some bugs, but there's a bit more left to do it seems.

Thank you very much for the workaround @francogarcia :) ! I'll test this out a bit later.

[francogarcia]

Hello again,
How are you?

Oliver already made the language server compatible with Emacs (and many other
text editors), and fixed some bugs, but there's a bit more left to do it
seems.

@ofrank123, thank you again! You have helped people to use their favorite text
editors and benefit from awesome features.

I had an old auto-completion package
(https://github.com/francogarcia/company-godot-gdscript.el). It required to
compile a custom module within the engine to work; this was a major barrier for
use.

It is fantastic that custom modules (and engine compilation) are not required
anymore. Your work is greatly appreciated, as it made autocompletion, linting,
documentation, etc. nearly plug-and-play for many people.

(...) language server implementation in the Godot engine, that the
capabilities function didn't follow the specification. So the fix should go
there.

I agree. Although we could set the capabilities that are working manually (or
advise the initialization function), I guess it would require almost the same
effort to look at Godot's server implementation and fix it to benefit everyone.

the issue had to do with the language server implementation in the Godot
engine, that the capabilities function didn't follow the specification

Upon inspection, the gdscript/capabilities is not relevant, as it describes
language and class features instead of LSP capabilities. LSP capabilities are
provided by capabilities sent by Godot during initialization. However, even
assuming that the list of capabilities is correct, it seems that they values are
not being set by lsp-mode (as shown by (lsp-describe-session), everything is
red).

As you commented, I have done some tests: besides saving requests, there seems
requiring fixes. This can be shown as follows:

1. Saving features can be disabled manually:

(lsp-register-client
 (make-lsp-client :new-connection (lsp-gdscript-tcp-connect-to-port)
                  :major-modes '(gdscript-mode)
                  :server-id 'gdscript
                  :initialized-fn (lambda (w)
                                    (with-lsp-workspace w
                                      (lsp--set-configuration
                                       (lsp-configuration-section "gdscript/capabilities")))
                                    (let ((caps (lsp--workspace-server-capabilities w)))
                                      (ht-set caps "textDocumentSync" nil)))))

2. The following snippet can used for evaluation:

extends Node


# Provide the *lsp-log: gdscript:nil* buffer describing the communication.
# ; (setq lsp-log-io t) ; Should be set before initialization.
# Useful for inspection (`eval-last-sexp`):
# ; (lsp--send-will-save-p)
# ; (lsp--send-will-save-wait-until-p)
# ; (lsp--send-did-save-p)
# ; (lsp--save-include-text-p )
# ; (pp (lsp--server-capabilities))
# ; (lsp-describe-session)
func do_something():
    var x = 0
    var y = 1
    var z = 2

    x = x + y
    x = y + z

    print("hello")

3. Although saving features are never called (they do not appear at lsp-log: gdscript:nil), errors will happen eventually. For instance, when editing
   do_something().

A potential heuristic to identify remaining bugs could be investigating the
lsp-log: gdscript:nil buffer for messages sent by lsp-mode without a
response from Godot's LSP server.

For instance, the textDocument/didOpen message has not received a response
from the server. This suggests that an error will occur after a buffer is
opened.

From Godot's headers (modules/gdscript/language_server/lsp.{hpp,cpp}),
unrelated LSP capabilities can be manually disabled by name at lsp-gdscript.el
to ease debugging:

(lsp-register-client
 (make-lsp-client :new-connection (lsp-gdscript-tcp-connect-to-port)
                  :major-modes '(gdscript-mode)
                  :server-id 'gdscript
                  :initialized-fn (lambda (w)
                                    (with-lsp-workspace w
                                      (lsp--set-configuration
                                       (lsp-configuration-section "gdscript/capabilities")))
                                    (let ((caps (lsp--workspace-server-capabilities w)))
                                      ;; See real values at <https://github.com/godotengine/godot/blob/3.2/modules/gdscript/language_server/lsp.hpp>
                                      ;; (ht-set caps "gdscript/capabilities" nil)
                                      (ht-set caps "textDocumentSync" nil)
                                      (ht-set caps "completionProvider" nil)
                                      (ht-set caps "signatureHelpProvider" nil)
                                      (ht-set caps "codeLensProvider" nil)
                                      (ht-set caps "documentOnTypeFormattingProvider" nil)
                                      (ht-set caps "renameProvider" nil)
                                      (ht-set caps "documentLinkProvider" nil)
                                      (ht-set caps "colorProvider" nil)
                                      (ht-set caps "foldingRangeProvider" nil)
                                      (ht-set caps "executeCommandProvider" nil)
                                      (ht-set caps "hoverProvider" nil)
                                      (ht-set caps "definitionProvider" nil)
                                      (ht-set caps "typeDefinitionProvider" nil)
                                      (ht-set caps "implementationProvider" nil)
                                      (ht-set caps "referencesProvider" nil)
                                      (ht-set caps "documentHighlightProvider" nil)
                                      (ht-set caps "documentSymbolProvider" nil)
                                      (ht-set caps "workspaceSymbolProvider" nil)
                                      (ht-set caps "codeActionProvider" nil)
                                      (ht-set caps "documentFormattingProvider" nil)
                                      (ht-set caps "documentRangeFormattingProvider" nil)
                                      (ht-set caps "declarationProvider" nil)))))

Even with everything disabled, an error occurs once buffer is opened. The
message textDocument/didOpen was sent, but an error was received afterwards:

[Trace - 02:58:29 ] Sending notification 'textDocument/didOpen'.
Params: {
  "textDocument": {
    "uri": "file:///tmp/Character.gd",
    "languageId": "gdscript",
    "version": 0,
    "text": "..."
  }
}

LSP :: Connected to [gdscript:nil status:starting].
LSP :: gdscript:nil initialized successfully
Error processing message (lsp-unknown-message-type #s(hash-table size 65 test
equal rehash-size 1.5 rehash-threshold 0.8125 data ("error" #s(hash-table size
65 test equal rehash-size 1.5 rehash-threshold 0.8125 data ("code" -32601
"message" "Method not found")) "id" nil "jsonrpc" "2.0"))).

(print (json-encode #s(hash-table size 65 test equal rehash-size 1.5 rehash-threshold 0.8125 data ("error" #s(hash-table size 65 test equal rehash-size 1.5 rehash-threshold 0.8125 data ("code" -32601 "message" "Method not found")) "id" nil "jsonrpc" "2.0"))))

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "message": "Method not found",
    "code": -32601
  }
}

No other errors follow in this case, as everything was indeed disabled and the
lsp-mode do not send any further requests to the server. Thus, it is likely
that there is a bug related to textDocument/didOpen's implementation in
Godot's LSP server (or it does not provide the capability at all).

The same thing happens when the buffer does not close: textDocument/didClose
is sent; an error is received instead of the response.

Best regards,
Franco

[NathanLovato]

Thanks for the detailed report, I'll let @ofrank123 take a look at it.

Note that there is a known issue with capabilities in the GDScript language server: it does not provides its capabilities following the LSP specification, so lsp-mode in emacs, and certainly other editors don't get the capabilities as they should. This is certainly a source of errors, and this needs to be fixed upstream, in Godot itself.

[shackra]

I just fired gdscript-mode in Emacs out of curiosity and with the recent version of LSP (7.0) I got this:

Warning (lsp-mode): Unknown notification: gdscript_client/changeWorkspace
Warning (lsp-mode): Unknown notification: gdscript/capabilities

and my mode-line indicates LSP[gdscript:nil] so, it seems that the language server for GDScript failed to start

EDIT:

Ah, didn't notice this: I get errors/warnings from lsp-mode 🤔

[NathanLovato]

The unknown notifications are known issues, they're unfortunately parts of the GDScript language server that don't follow the specification. This has to be addressed in the engine.

Aside from that, it should work ok.

Hola de Tres Ríos!

[shackra]

offtopic:

Hola de Tres Ríos!

@NathanLovato !!!!! Why are you here, bruuuuuh. When will you move out of Costa Rica? I would like to shake your hand and tell you I haven't finish your course [PRO] Make Professional 2d Games with the Godot Game Engine jaja.

how the heck didn't I see any of your videos stating you were moving here? jaja, you cannot measure my surprise xD