Repository files navigation

This package adds support for the GDScript programming language from the Godotgame 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 withuse-package +straight.el
  • Installing manually
• Auto-completion with the Language Server Protocol (LSP)
  • Known issues
• Major mode with Treesit
  • Install treesit
  • Install grammar
• 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
    • Using a local copy of the Godot docs
• Keyboard shortcuts
• Customization
• Using the debugger
  • Adding and removing breakpoints
  • Running the project with the debugger active
    • Multi-line display
  • Fetching an object's details
  • Debug Hydra
  • The* Stack frame vars * buffer
  • * Inspector * buffer
  • * Stack dump * buffer
  • * Breakpoints * buffer
  • * Scene tree * buffer

This mode features all the essentials:

• Syntax highlighting.
• Code folding.
• Debugger support.
• Imenu.
• Support for scenes (.tscn) and script (.gd) files.
• Comment wrapping when usingfill-paragraph.
• Indentation and auto-indentation: tab-based (default) and space-based.
• Automatic pairing of parentheses, brackets, etc.
• Code formatting usinggdformat.
• Auto-completion for all the keywords in thegdscript-keywords.el file.
• Run or open the project and files with Godot.
• Browsing the API reference in Emacs.
• Add treesit major mode supportgdscript-ts-mode .

Code folding in action.

Contributors are welcome! Check theissues 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 newissue.

For code style, we follow theEmacs lisp styleguide by Bozhidar Batsov,and thetips andconventionsfrom 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 toolEask provided with the repository:

This assumes you haveEask 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

The package is available in theMELPA package archive. Once youset 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)

1. Add the package to thedotspacemacs-additional-packages. You can find it under the dotspacemacs/layers function:

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

2. In yourdotspacemacs/user-config function, require the package.

(defundotspacemacs/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.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 wordgdscript and pressk.

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

1. Clone the repository or download astable 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)

For auto-completion, we rely on either theeglot orlsp-mode packages, and the GDScript language server which is built into Godot.

To use the LSP witheglot, you need to installeglot on top ofgdscript-mode, if using an Emacs version earlier than 29.After installation,eglot can be connected on startup by addingeglot-ensure as a hook ongdscript-mode-hook.

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

An example configuration for Godot 3 usage withuse-package:

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

To use the LSP withlsp-mode, you need to installlsp-mode on top ofgdscript-mode and configure it. To install and configurelsp-mode, see thelsp-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 someunknown 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):

(defunlsp--gdscript-ignore-errors (original-function&restargs)"Ignore the error message resulting from Godot not replying to the`JSONRPC' request."  (if (string-equal major-mode"gdscript-mode")      (let ((json-data (nth0 args)))        (if (and (string= (gethash"jsonrpc" json-data"")"2.0")                 (not (gethash"id" json-datanil))                 (not (gethash"method" json-datanil)))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)

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 ofgdscript files.

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

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

sudo pacman -S tree-sitter

To support Gdscript, we must installgdscript-grammar:

git clone https://github.com/PrestonKnopp/tree-sitter-gdscript.gitcd tree-sitter-gdscript/srccc -std=c99 -c parser.ccc -c scanner.c -I./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.

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

By default, these commands try to use an executable namedgodot on the systemPATH environment variable.

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

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

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

When runninggdscript-godot-run-project-debug, you can use the universal argumentC-u 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 callgdscript-godot-run-project-debug. To turn off debug options, you need to call the command with the universal argument again.

Runninggdscript-hydra-show (C-c r) opens ahydra 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 thegdscript-format function to format the current buffer withgdformat. Alternatively,gdscript-format-all will reformat all GDScript files inthe project. This feature requires the python packagegdtoolkit to be installedand available on the system's PATH variable.

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

pip3 install gdtoolkit

With the point on a built-in class, you can pressC-c C-b o to open the code reference for that class in the text browsereww.

To open the main API reference page and browse it, pressC-c C-b a.

You can browse the API reference offline witheww. To do so:

1. Get a build of the official documentation. You can build it from thegodot docs repository ordownload a build from Hugo Lourcio's website.
2. Setgdscript-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")

The following shortcuts are available by default:

• Inserting:
  • C-c igdscript-completion-insert-file-path-at-point
• Formatting:
  • C-c C-f rgdscript-format-region
  • C-c C-f bgdscript-format-buffer
• Running the project and scenes in Godot:
  • C-c C-r pgdscript-godot-open-project-in-editor
  • C-c C-r rgdscript-godot-run-project
  • C-c C-r dgdscript-godot-run-project-debug
  • C-c C-r sgdscript-godot-run-current-scene
  • C-c C-r qgdscript-godot-run-current-scene-debug
  • C-c C-r egdscript-godot-edit-current-scene
  • C-c C-r xgdscript-godot-run-current-script
• Browsing the code reference:
  • C-c C-b agdscript-docs-browse-api
  • C-c C-b ogdscript-docs-browse-symbol-at-point
• Open hydra:
  • C-c rgdscript-hydra-show (require hydra package to be installed)
  • C-c ngdscript-debug-hydra (require hydra package to be installed)

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

Code example:

(setq gdscript-use-tab-indentst);; If true, use tabs for indents. Default: t(setq gdscript-indent-offset4);; 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-formatt);; Save all buffers and format them with gdformat anytime Godot executable is run.

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

Like in Godot's editor, you can toggle a breakpoint on the current line withgdscript-debug-toggle-breakpoint (F9).

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, pressingD on a breakpoint line deletes the breakpoint. PressingRET opens the corresponding GDScript file in another buffer.

When any breakpoint exists, running the project withgdscript-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 onlocalhost through port6010 by default. You can customize the port with thegdscript-debug-port variable.

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

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

You can toggle between one-line and multi-line display for values of typeDictionary,PoolRealArray,PoolStringArray,PoolVector2Array,PoolVector3Array andPoolColorArray. To do so, pressTAB on the corresponding line.

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

• Their real type, for example,KinematicBody2D instead ofObjectId.
• Their node path.

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

You can also call it by pressingC-c n.

n next  c continue  m step  b breakpoints  s stack  v vars  i inspector  t scene-tree  d detailso 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 - Pinsself 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 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 forObjectId 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.

Contains information about inspected object. By defaultself 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 currentself is displayed instead.

• PressTAB to toggle multi-line display for selected typess.
• PressRET on object line to display its detailss.
• PressRET onNode/path line (second line from the top) to show given object in* Scene Tree * buffers.
• Pressl deep in nested object to navigate one level up in the structure (ie. back). Pressingl while on top-level object displays* Stack frame vars * buffers.
• Pressd to display additional details for object variabless.
• Pressp to go to the previous lines.
• Pressn to go to the next lines.
• Presso to pin current object in* Inspector * buffers.
• Pressu to unpin currently pinned objects.
• Pressq to close the buffers.

Contains stack dump information.

• PressSPC to jump to gdscript file where stack frame points to.
• PressRET to jump to the gdscript file and show* Stack frame vars *,* Inspector * buffers, and a debug hydra.
• Pressl to display the* Stack frame vars * buffer.
• Pressp to go to the previous line.
• Pressn to go to the next line.
• Pressq to close the buffer.

Lists all existing breakpoints in the project.

• PressSPC to enable or disable all breakpoints.
• PressRET to jump to the file and line corresponding to the breakpoint..
• PressTAB to display the* Stack dump * buffer.
• PressD to delete the breakpoint.
• Pressq to close the buffer.

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

• PressRET to open the corresponding object in the* Inspector * buffer.
• Pressp to go to the previous line.
• Pressn to go to the next line.
• Pressq to close the buffer.