Home

Awesome

GDScript mode for Emacs

banner showing the "GDScript mode" title with GDScript code in the background

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!

<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->

Table of Contents

<!-- markdown-toc end -->

Features

This mode features all the essentials:

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 Eask provided with the repository:

This assumes you have Eask installed.

eask 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:

eask lint checkdoc && eask lint package

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 file.

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

The +lsp flag adds language server support for game development with Godot.

To see the module's documentation in Emacs, place your cursor over the word gdscript and press <kbd>k</kbd>.

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 either the eglot or lsp-mode packages, and the GDScript language server which is built into Godot.

To use the LSP with eglot, you need to install eglot on top of gdscript-mode, if using an Emacs version earlier than 29. After installation, eglot can be connected on startup by adding eglot-ensure as a hook on gdscript-mode-hook.

Note that, due to language server changes made in Godot 4, usage with Godot 3 requires gdscript-eglot-version to be customized to 3.

An example configuration for Godot 3 usage with use-package:

(use-package gdscript-mode
  :hook (gdscript-mode . eglot-ensure)
  :custom (gdscript-eglot-version 3))

To use the LSP with lsp-mode, you need to install lsp-mode on top of gdscript-mode and configure it. To install and configure lsp-mode, see the lsp-mode documentation.

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 errors in lsp-mode at the moment. You can suppress them by adding the following code to your Emacs configuration (thanks to Franco Garcia for sharing this workaround):

(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)

Major mode with Treesit

Treesit is an incremental parsing system for programming tools.

This package has a major mode (gdscript-ts-mode). That supports the use tree-sitter for font-lock, imenu, indentation, and navigation of gdscript files.

Emacs version 29 or higher is required to use this mode.

Install treesit

We need to install tree-sitter library, When under Arch Linux :

sudo pacman -S tree-sitter

Install grammar

To support Gdscript, we must install gdscript-grammar:

git clone https://github.com/PrestonKnopp/tree-sitter-gdscript.git
cd tree-sitter-gdscript/src
cc -std=c99 -c parser.c
cc -c scanner.cc
cc -shared parser.o scanner.o -o libtree-sitter-gdscript.so

Additional directories to look for tree-sitter language definitions. ( DIR is your working path )

(setq treesit-extra-load-path '("DIR/tree-sitter-gdscript/src/"))

enjoy.

How to use

Opening the project in the editor

You can open the Godot editor with M-x gdscript-godot-open-project-in-editor, or open files and more in Godot with the M-x gdscript-godot-* commands.

By default, these commands try to use an executable named godot on the system PATH environment variable.

If you don't have godot available there, you can set a custom executable name or path to use instead:

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

You can also use customize to change this path: M-x customize and search for "godot".

Running Godot with visual debug options

When running gdscript-godot-run-project-debug, you can use the universal argument <kbd>C-u</kbd> to invoke a mini-buffer with extra options to pass to godot.

Here are the available options:

  1. <no options> (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. To turn off debug options, you need to call the command with the universal argument again.

Using Hydra

Running gdscript-hydra-show (<kbd>C-c r</kbd>) opens a hydra popup with options to open the editor or run the project, a scene, or a script, including with visual debug options.

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

Formatting code with gdformat

You can call the gdscript-format function to format the current buffer with gdformat. Alternatively, gdscript-format-all will reformat all GDScript files in the project. This feature requires the python package gdtoolkit to be installed and available on the system's PATH variable.

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 code reference for that class in the text browser eww.

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. To do so:

  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:

Customization

To find all GDScript-mode settings, press M-x customize and search for "gdscript".

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.

The debugger in this package is only for Godot 3. Godot 4 supports the Debugger Adapter Procol (DAP), which you can use with the dap-mode package.

You can use the debugger tools to manage breakpoints, step through code, 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 (<kbd>F9</kbd>).

After adding at least one breakpoint to the project, a buffer named * Breakpoints * is created. This buffer displays all existing breakpoints in a project. In that buffer, pressing <kbd>D</kbd> on a breakpoint line deletes the breakpoint. Pressing <kbd>RET</kbd> opens the corresponding GDScript file in another buffer.

Running the project with the debugger active

When any breakpoint exists, running the project with gdscript-godot-run-project will automatically start the debugger's server if one isn't already running and connect to it.

The debugger's server runs on localhost through port 6010 by default. You can customize the port with the gdscript-debug-port variable.

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

You can inspect any object in those two buffers by pressing <kbd>RET</kbd> 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 and PoolColorArray. To do so, press TAB on the corresponding line.

Fetching an object's details

Pressing <kbd>d</kbd> in * Stack frame vars * or * Inspector * buffers (or in the debug hydra) will fetch on the background data for all objects present in those two buffers and redisplay once done. Doing that adds two extra bits of information about the objects:

Debug Hydra

If hydra is available, the debug hydra displays below * Stack frame vars * and * Inspector * buffers upon hitting a breakpoint.

You can also call it by pressing <kbd>C-c n</kbd>.

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

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:

* Inspector * buffer

Contains information about inspected object. By default self variable from * Stack frame vars * is displayed. The inspected object is kept in focus until you inspect another object or until the active object ceases to exists, in which case the current self is displayed instead.

* Stack dump * buffer

Contains stack dump information.

* Breakpoints * buffer

Lists all existing breakpoints in the project.

* Scene tree * buffer

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