GDScript mode for Emacs

This package adds support for the GDScript programming language from the Godot game engine in Emacs. It gives syntax highlighting and indentations. Contributors are welcome!

Table of Contents

• Features
• Contributing
• How to install
  • Installing in Spacemacs
  • Installing in Doom Emacs
  • Installing with

    use-package

    +

    straight.el

  • Installing manually
• Auto-completion with the Language Server Protocol (LSP)
• How to use
  • Opening the project in the editor
  • Running Godot with visual debug options
  • Using Hydra
  • Formatting code with gdformat
  • Browsing the Godot API with eww
• Keyboard shortcuts
• Customization
• Using the debugger
  • Adding and removing breakpoints
  • Running the project with the debugger active
  • Fetching an object's details
  • Debug Hydra
  • The

    * Stack frame vars *

    buffer

  • * Inspector *

    buffer

  • * Stack dump *

    buffer

  • * Breakpoints *

    buffer

  • * Scene tree *

    buffer

Features

This mode features all the essentials:

• Syntax highlighting.
• Code folding.
• Debugger support.
• Imenu.
• Support for scenes (

  .tscn

  ) and script (

  .gd

  ) files.
• Comment wrapping when using

  fill-paragraph

  .
• Indentation and auto-indentation: tab-based (default) and space-based.
• Automatic pairing of parentheses, brackets, etc.
• Code formatting using gdformat.
• Auto-completion for all the keywords in the

  gdscript-keywords.el

  file.
• Run or open the project and files with Godot.
• Browsing the API reference in Emacs.

Code folding in action.

Contributing

Contributors are welcome! Check the issues tab for tasks to work on and open a PR anytime.

If you find a bug or would like to suggest an improvement, open a new issue.

For code style, we follow the Emacs lisp style guide by Bozhidar Batsov, and the tips and conventions from the Emacs manual.

You should also check for errors and linter warnings in your code. You can do so in Emacs with flymake or flycheck, but we recommend running the tool

makem.sh

./makem.sh lint-compile

This program will tell you if there is any problem with your code. If there's no output, everything is fine. You can run all tests like so, but note it might give you spelling errors that aren't relevant in this project:

./makem.sh all

How to install

The package is available in the MELPA package archive. Once you set up MELPA you can install the package from Emacs:

M-x package-install gdscript-mode

Then, in your init.el file, you can require the package:

(require 'gdscript-mode)

Installing in Spacemacs

1. Add the package to the

   dotspacemacs-additional-packages

   . You can find it under the dotspacemacs/layers function:

(defun dotspacemacs/layers ()
  "Configuration Layers declaration..."
  (setq-default
   ;; ...
   dotspacemacs-additional-packages '(gdscript-mode)
   ;; ...
   ))

1. In your

   dotspacemacs/user-config

   function, require the package.

(defun dotspacemacs/user-config ()
  (require 'gdscript-mode))

Installing in Doom Emacs

Doom Emacs comes with a Godot GDScript module.

You just need to add the "lang: gdscript" keyword to your

.doom.d/init.el

:lang
(gdscript +lsp)          ; the language you waited for

The

+lsp

To see the module's documentation in Emacs, place your cursor over the word

gdscript

Installing with

use-package

+

straight.el

Add the call to use-package to your Emacs configuration:

(use-package gdscript-mode
    :straight (gdscript-mode
               :type git
               :host github
               :repo "godotengine/emacs-gdscript-mode"))

Installing manually

1. Clone the repository or download a stable release to your computer.
2. In your init.el file, add a call to load and require the package.

(add-to-list 'load-path "/path/to/gdscript-mode")
(require 'gdscript-mode)

Auto-completion with the Language Server Protocol (LSP)

For auto-completion, we rely on the lsp-mode package and the GDScript language server, which is built into Godot.

The GDScript LSP support is part of the LSP mode. To use it, you need to install

lsp-mode

gdscript-mode

lsp-mode

Known issues

There are some known issues with the GDScript language server in Godot 3.2 due to the server being a bit young and not following the specification strictly. This mainly causes some

unknown notification

(defun lsp--gdscript-ignore-errors (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)))
;; Runs the function `lsp--gdscript-ignore-errors` around `lsp--get-message-type` to suppress unknown notification errors.
(advice-add #'lsp--get-message-type :around #'lsp--gdscript-ignore-errors)

How to use

Opening the project in the editor

You can open the Godot editor with

M-x gdscript-godot-open-project-in-editor

M-x gdscript-godot-*

By default, these commands try to use an executable named

godot

If you don't have

godot

(setq gdscript-godot-executable "/path/to/godot")

You can also use

customize

M-x customize

Running Godot with visual debug options

When running

gdscript-godot-run-project-debug

Here are the available options:

1. (default)

2. --debug-collisions

3. --debug-navigation

4. --debug-collisions --debug-navigation

The last selected option is saved for the next time you call

gdscript-godot-run-project-debug

Using Hydra

Running

gdscript-hydra-show

Hydra interactive menu to run the project and set debug options on the fly.

Formatting code with gdformat

You can call the

gdscript-format

gdformat

gdscript-format-all

gdtoolkit

You can install gdtoolkit using the pip package manager from Python 3. Run this command in your shell to install it:

pip3 install gdtoolkit

Browsing the Godot API with eww

With the point on a built-in class, you can press

C-c C-b o

To open the main API reference page and browse it, press

C-c C-b a

Using a local copy of the Godot docs

You can browse the API reference offline with

eww

1. Get a build of the official documentation. You can build it from the godot docs repository or download a build from Hugo Lourcio's website.
2. Set

   gdscript-docs-local-path

   to the docs' directory, that contains the docs'

   index.html

   file.

For example:

(setq gdscript-docs-local-path "/home/gdquest/Documents/docs/godot")

Keyboard shortcuts

The following shortcuts are available by default:

• Inserting:
  • C-c i

    gdscript-completion-insert-file-path-at-point

• Formatting:
  • C-c C-f r

    gdscript-format-region

  • C-c C-f b

    gdscript-format-buffer

• Running the project and scenes in Godot:
  • C-c C-r p

    gdscript-godot-open-project-in-editor

  • C-c C-r r

    gdscript-godot-run-project

  • C-c C-r d

    gdscript-godot-run-project-debug

  • C-c C-r s

    gdscript-godot-run-current-scene

  • C-c C-r q

    gdscript-godot-run-current-scene-debug

  • C-c C-r e

    gdscript-godot-edit-current-scene

  • C-c C-r x

    gdscript-godot-run-current-script

• Browsing the code reference:
  • C-c C-b a

    gdscript-docs-browse-api

  • C-c C-b o

    gdscript-docs-browse-symbol-at-point

• Open hydra:
  • C-c r

    gdscript-hydra-show

    (require hydra package to be installed)
  • C-c n

    gdscript-debug-hydra

    (require hydra package to be installed)

Customization

To find all GDScript-mode settings, press

M-x customize

Code example:

(setq gdscript-use-tab-indents t) ;; If true, use tabs for indents. Default: t
(setq gdscript-indent-offset 4) ;; Controls the width of tab-based indents
(setq gdscript-godot-executable "/path/to/godot") ;; Use this executable instead of 'godot' to open the Godot editor.
(setq gdscript-gdformat-save-and-format t) ;; Save all buffers and format them with gdformat anytime Godot executable is run.

Using the debugger

Emacs GDScript mode includes support for the GDScript debugger. You can use breakpoints, use code stepping functions, see your nodes' state at runtime, and more.

To get started with this feature, you need to add a least one breakpoint.

Adding and removing breakpoints

Like in Godot's editor, you can toggle a breakpoint on the current line with

gdscript-debug-toggle-breakpoint

After adding at least one breakpoint to the project, a buffer named

* Breakpoints *

Running the project with the debugger active

When any breakpoint exists, running the project with

gdscript-godot-run-project

The debugger's server runs on

localhost

6010

gdscript-debug-port

Once Godot hits a breakpoint, Emacs displays two new buffers:

• * Stack frame vars *

  displays the locals, members, and globals variables for the current stack point. It shows the variable name, its type, and its value.

• * Inspector *

  displays detailed information about the selected object. By default, it shows the properties of

  self

  .

You can inspect any object in those two buffers by pressing RET on the corresponding line.

Multi-line display

You can toggle between one-line and multi-line display for values of type

Dictionary

PoolRealArray

PoolStringArray

PoolVector2Array

PoolVector3Array

PoolColorArray

TAB

Fetching an object's details

Pressing d in

* Stack frame vars *

* Inspector *

• Their real type, for example,

  KinematicBody2D

  instead of

  ObjectId

  .
• Their node path.

Debug Hydra

If

hydra

* Stack frame vars *

* Inspector *

You can also call it by pressing C-c n.

n next  c continue  m step  b breakpoints  s stack  v vars  i inspector  t scene-tree  d details
o pin   u unpin     q quit

• n - Steps to the next line of code.
• c - Continue program execution until the next breakpoint.
• m - Steps into the code.
• s - Shows the

  * Stack dump *

  buffer.
• v - Shows the

  * Stack frame vars *

  buffer.
• i - Shows the

  * Inspector *

  buffer.
• t - Shows the

  * Scene tree *

  buffer.
• d - Fetches details for all object present in the

  * Stack frame vars *

  and

  * Inspector *

  buffers and redisplay the buffers.
• o - Pins

  self

  in the

  * Inspector *

  buffer. It stays displayed until Godot frees the instance or you unpin it.
• u - Unpins the currently pinned object.
• q - Closes the debug hydra.

The

* Stack frame vars *

buffer

The stack frame buffer displays the locals, members, and global variables for the current stack point. Here are available keyboard shortcuts:

• TAB toggles multi-line display for selected types.
• RET on an object line to display its details in the

  * Inspector *

  buffer.
• l displays the

  * Stack dump *

  buffer.
• d displays additional details for

  ObjectId

  variables.
• p goes to the previous line.
• n goes to the next line.
• o pins the current object in the

  * Inspector *

  buffer.
• u unpins the currently pinned object.
• q closes the buffer.

* Inspector *

buffer

Contains information about inspected object. By default

self

* Stack frame vars *

self

• Press TAB to toggle multi-line display for selected typess.
• Press RET on object line to display its detailss.
• Press RET on

  Node/path

  line (second line from the top) to show given object in

  * Scene Tree *

  buffers.
• Press l deep in nested object to navigate one level up in the structure (ie. back). Pressing

  l

  while on top-level object displays

  * Stack frame vars *

  buffers.
• Press d to display additional details for object variabless.
• Press p to go to the previous lines.
• Press n to go to the next lines.
• Press o to pin current object in

  * Inspector *

  buffers.
• Press u to unpin currently pinned objects.
• Press q to close the buffers.

* Stack dump *

buffer

Contains stack dump information.

• Press SPC to jump to gdscript file where stack frame points to.
• Press RET to jump to the gdscript file and show

  * Stack frame vars *

  ,

  * Inspector *

  buffers, and a debug hydra.
• Press l to display the

  * Stack frame vars *

  buffer.
• Press p to go to the previous line.
• Press n to go to the next line.
• Press q to close the buffer.

* Breakpoints *

buffer

Lists all existing breakpoints in the project.

• Press SPC to enable or disable all breakpoints.
• Press RET to jump to the file and line corresponding to the breakpoint..
• Press TAB to display the

  * Stack dump *

  buffer.
• Press D to delete the breakpoint.
• Press q to close the buffer.

* Scene tree *

buffer

Contains a tree visualisation of all objects in the running program.

• Press RET to open the corresponding object in the

  * Inspector *

  buffer.
• Press p to go to the previous line.
• Press n to go to the next line.
• Press q to close the buffer.