An Emacs package to get GDScript support and syntax highlighting.
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
This mode features all the essentials:
.tscn) and script (
.gd) files.
fill-paragraph.
gdscript-keywords.elfile.
Code folding in action.
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.shprovided with the repository:
./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
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)
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) ;; ... ))
dotspacemacs/user-configfunction, require the package.
(defun dotspacemacs/user-config () (require 'gdscript-mode))
Doom Emacs comes with a Godot GDScript module.
You just need to add the "lang: gdscript" keyword to your
.doom.d/init.elfile.
:lang (gdscript +lsp) ; the language you waited for
The
+lspflag adds language server support for game development with Godot.
To see the module's documentation in Emacs, place your cursor over the word
gdscriptand press k.
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 "GDQuest/emacs-gdscript-mode"))
(add-to-list 'load-path "/path/to/gdscript-mode") (require 'gdscript-mode)
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-modeon top of
gdscript-modeand configure it. To install and configure
lsp-mode, see the lsp-mode documentation.
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 notificationerrors 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)
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
godoton the system PATH environment variable.
If you don't have
godotavailable there, you can set a custom executable name or path to use instead:
(setq gdscript-godot-executable "/path/to/godot")
You can also use
customizeto change this path:
M-x customizeand search for "godot".
When running
gdscript-godot-run-project-debug, you can use the universal argument C-u to invoke a mini-buffer with extra options to pass to godot.
Here are the available options:
--debug-collisions
--debug-navigation
--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.
Running
gdscript-hydra-show(C-c r) 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.
You can call the
gdscript-formatfunction to format the current buffer with
gdformat. Alternatively,
gdscript-format-allwill reformat all GDScript files in the project. This feature requires the python package
gdtoolkitto 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
With the point on a built-in class, you can press
C-c C-b oto 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.
You can browse the API reference offline with
eww. To do so:
gdscript-docs-local-pathto the docs' directory, that contains the docs'
index.htmlfile.
For example:
(setq gdscript-docs-local-path "/home/gdquest/Documents/docs/godot")
The following shortcuts are available by default:
gdscript-completion-insert-file-path-at-point
gdscript-format-region
gdscript-format-buffer
gdscript-godot-open-project-in-editor
gdscript-godot-run-project
gdscript-godot-run-project-debug
gdscript-godot-run-current-scene
gdscript-godot-run-current-scene-debug
gdscript-godot-edit-current-scene
gdscript-godot-run-current-script
gdscript-docs-browse-api
gdscript-docs-browse-symbol-at-point
gdscript-hydra-show(require hydra package to be installed)
gdscript-debug-hydra(require hydra package to be installed)
To find all GDScript-mode settings, press
M-x customizeand 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.
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.
You can add a breakpoint on the current line with
gdscript-debug-add-breakpoint(C-c C-d b). A red dot should appear in the left fringe. Use
gdscript-debug-remove-breakpoint(C-c C-d r) to remove a breakpoint on the current line.
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 D on a breakpoint line deletes the breakpoint. Pressing RET opens the corresponding GDScript file in another buffer.
When any breakpoint exists, running the project with
gdscript-godot-run-projectwill automatically start the debugger's server if one isn't already running and connect to it.
The debugger's server runs on
localhostthrough port
6010by default. You can customize the port with the
gdscript-debug-portvariable.
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.
You can toggle between one-line and multi-line display for values of type
Dictionary,
PoolRealArray,
PoolStringArray,
PoolVector2Array,
PoolVector3Arrayand
PoolColorArray. To do so, press
TABon the corresponding line.
Pressing d 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:
KinematicBody2Dinstead of
ObjectId.
If
hydrais available, the debug hydra displays below
* Stack frame vars *and
* Inspector *buffers upon hitting a breakpoint.
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
* Stack dump *buffer.
* Stack frame vars *buffer.
* Inspector *buffer.
* Scene tree *buffer.
* Stack frame vars *and
* Inspector *buffers and redisplay the buffers.
selfin the
* Inspector *buffer. It stays displayed until Godot frees the instance or you unpin it.
* 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.
* Stack dump *buffer.
ObjectIdvariables.
* Inspector *buffer.
* Inspector *buffer
Contains information about inspected object. By default
selfvariable 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
selfis displayed instead.
Node/pathline (second line from the top) to show given object in
* Scene Tree *buffers.
lwhile on top-level object displays
* Stack frame vars *buffers.
* Inspector *buffers.
* Stack dump *buffer
Contains stack dump information.
* Stack frame vars *,
* Inspector *buffers, and a debug hydra.
* Stack frame vars *buffer.
* Breakpoints *buffer
Lists all existing breakpoints in the project.
* Stack dump *buffer.
* Scene tree *buffer
Contains a tree visualisation of all objects in the running program.
* Inspector *buffer.