GDScript Formatter: Godot 4 User Manual

This user manual covers how to install and use the GDScript Formatter directly from within Godot 4. The formatter helps you keep your code clean and consistent by automatically fixing spacing, indentation, and code order, while the linter catches common style issues (all according to the official GDScript style guide).

This documentation guides you through everything you need to know to improve your code quality and save time on manual formatting.

In this guide, you'll learn how to:

• Install the add-on and formatter
• Format your scripts manually or automatically on save
• Lint your code to catch style issues
• Configure the formatter
• Update or uninstall the formatter

Installation and setup

The formatter comes in two parts: the Godot add-on and the formatter binary. The add-on adds menus and commands to Godot, while the binary does the actual formatting work. You need both to use the formatter.

Installing the add-on

First, you need to add the add-on to your Godot project:

1. Download the Godot addon in the Download Files section below
2. Extract the folder from the zip and copy it into your project to add the addon at res://addons/gdscript_formatter/
3. In Godot, go to ProjectProject SettingsPlugins
4. Find "GDQuest GDScript Formatter" in the list and turn on the checkbox to enable it

The add-on is now active and will add a "Format" menu to the script editor.

NOTE:

Godot 4.5 currently only supports per-project plugins, so you need to install the add-on in each project where you want to use it.

Installing the formatter binary through the add-on

The GDScript formatter is a native computer program written in Rust, so just like Godot, it needs a different executable on Windows, macOS and Linux to work.

The add-on can download and install the correct version for your system automatically:

1. Open the Format menu in the script editor (or press Ctrl+Shift+P to open the command palette)
2. Choose Install or Update Formatter

Then, wait for the small download to complete. You'll see messages in the Output bottom panel to show the progress.

The add-on downloads the formatter and puts it in Godot's cache folder. You only need to do this once per computer. If you see an error, check your internet connection and try again.

Can I use my own formatter binary?

Yes! If you already have the formatter installed on your system, you can tell the add-on where to find it:

1. Go to EditorEditor Settings...
2. Scroll down to the GDQuest GDScript Formatter section
3. Change the Formatter Path setting to point to your formatter binary

For example, if you installed the formatter globally on your computer, you might set this to just gdscript-formatter.

Using the formatter

Once the formatter is installed, you can use it to clean up your code whenever you need. You have several ways to run the formatter depending on your workflow.

Quick start: enable format on save

The most common way to use the formatter is to have it automatically format your code every time you save:

1. Go to EditorEditor Settings...
2. Scroll down to the GDQuest GDScript Formatter section
3. Enable the Format On Save checkbox

Now, every time you save a GDScript file with , the formatter will format your code.

Formatting a script manually

You can format your current script manually in three ways:

• Press ctrl+alt+i on Windows/Linux or cmd+alt+i on macOS
• Use the Format menu in the script editor and choose Format Current Script
• Press Ctrl+Shift+P to open the command palette, then type "format" and choose Format GDScript

Reordering code elements

The formatter can also reorder the elements in your script to follow the GDScript style guide.

To reorder your current script:

1. Open the Format menu
2. Choose Reorder Code

Your code elements will be rearranged to follow the official style guide order. This is a separate command from regular formatting because it changes more of your code's structure. You may want to use the command to do a big cleanup in a large script, and then reorder a few elements manually to fine-tune it.

You can also enable automatic reordering in EditorEditor Settings... under GDQuest GDScript Formatter by turning on the Reorder Code setting. When enabled, the formatter will reorder your code every time it formats.

Important: Code reordering cannot always perfectly reorder your code while preserving your intentions. We favor following the official style guide. So if you want to make code regions that group certain elements together, you may need to reorder those manually after running the command. I recommend using the reorder command manually for this reason, rather than enabling automatic reordering on save.

The formatter changed my code in a way I don't like. Can I undo it?

Yes! You can press ctrlz (on Mac: ⌘z) immediately after formatting to restore your code to how it was before.

The formatter follows the official GDScript style guide, so most changes are intentional to keep your code consistent with Godot's standards.

If you find a change that is not part of the style guide or that breaks your code, please report it as an issue on the formatter's GitHub repository (this link lists existing issues to avoid duplicates). Please include a code snippet showing the before and after so we can investigate and fix it.

Using the linter

The linter checks your code for style issues without changing anything. It highlights style problems in your script and shows you detailed messages about what needs fixing in the Output bottom panel.

Running the linter manually

To check your current script for linting issues:

1. Open the GDScript file you want to lint
2. Open the Format menu or press Ctrl+Shift+P for the command palette
3. Choose Lint Current Script (or Lint GDScript in the command palette)

The linter runs and shows results in two places:

• In the script editor: you'll see colored icons in the gutter (left margin) and colored highlighting on problem lines
• In the Output panel: you'll see a detailed list of all issues with line numbers and descriptions

Red markers mean errors, yellow markers mean warnings.

Using lint on save

Just like formatting, you can have the linter check your code automatically every time you save:

1. Go to EditorEditor Settings...
2. Find the GDQuest GDScript Formatter section
3. Enable Lint On Save

Now, every time you save a GDScript file, the linter highlights any issues in your editor and prints a summary in the Output panel. This helps you catch problems as you work without having to remember to run the linter manually.

Clearing lint highlights

The lint highlights stay in your editor until you run the linter again or format the code. To clear them:

• Run the linter again on code with no issues
• Format the code (which removes the highlights automatically)
• Close and reopen the file

Can I use both format on save and lint on save together?

Yes! You can enable both settings. When you save a file:

1. First, the formatter runs and cleans up your code
2. Then, the linter checks the formatted code for any remaining issues

This combination gives you automatically clean code that also passes style checks. Formatting happens first, so the linter sees and checks the formatted version of your code.

Configuration and settings

All formatter settings are in EditorEditor Settings... under the GDQuest GDScript Formatter section. You can customize how the formatter works to match your preferences or your team's coding standards.

Changing the formatter path

The Formatter Path setting tells the add-on where to find the formatter binary.

By default, after auto-installation, this points to the formatter in Godot's cache folder. You might want to change this if you installed the formatter globally on your computer.

To change it:

1. Go to EditorEditor Settings...
2. Find GDQuest GDScript FormatterFormatter Path
3. Enter the path to your formatter binary

Use just gdscript-formatter if it's in your system's PATH, or use the full path to the executable otherwise.

Configuring indentation

By default, the formatter uses tabs for indentation. You can change this to use spaces instead:

1. Go to EditorEditor Settings...
2. Find GDQuest GDScript FormatterUse Spaces
3. Enable the checkbox to use spaces instead of tabs
4. Set Indent Size to the number of spaces you want (usually 4)

Enabling automatic code reordering

If you want the formatter to always reorder your code elements:

1. Go to EditorEditor Settings...
2. Find GDQuest GDScript FormatterReorder Code
3. Enable the checkbox

Now, every time you format (including format on save), the formatter will rearrange your code to follow the GDScript style guide order.

Important: You cannot use both Reorder Code and Safe Mode at the same time. If you enable both, you'll get an error message. Safe mode is more conservative and doesn't support reordering yet.

Using safe mode

Safe mode makes the formatter more conservative. It verifies that the code is valid before making changes, which can prevent some issues in complex scripts. To activate safe mode:

1. Go to EditorEditor Settings...
2. Find GDQuest GDScript FormatterSafe Mode
3. Enable the checkbox

Important: Safe mode is not 100% fail-proof. It greatly reduces the risk of errors, but cannot guarantee that no issues will ever occur. It should however work reliably on the majority of Godot projects (the risks are mainly with rarely used or newer syntax that the Rust GDScript parser does not support yet).

NOTE:

Safe mode is currently not compatible with automatic code reordering. If you enable both, you won't be able to format until you disable one of them.

Configuring the linter line length

The linter can check if your lines are too long. By default, it warns about lines longer than 100 characters:

1. Go to EditorEditor Settings...
2. Find GDQuest GDScript FormatterLint Line Length
3. Set the maximum line length you want

The GDScript style guide recommends keeping lines under 100 characters for readability. Feel free to increase this if you work on a large monitor.

Ignoring specific lint rules

If you want the linter to skip certain rules, you can add them to the ignore list:

1. Go to EditorEditor Settings...
2. Find GDQuest GDScript FormatterLint Ignored Rules
3. Enter the rule names you want to ignore, separated by commas

For example, if you don't want to see warnings about line length, you could enter line-too-long. If you want to ignore multiple rules, use commas: line-too-long,another-rule.

The linter will skip any rules you list here when checking your code.

Customizing the keyboard shortcut

You can change the format shortcut to whatever you prefer. It uses the same ShortCut resource used by UI nodes in your Godot projects:

1. Go to EditorEditor Settings...
2. Find GDQuest GDScript FormatterShortcut
3. Click on the shortcut field to expand the shortcut resource
4. Click the Events array to open the list of key events
5. Click the InputEventKeyInputEventKey item to edit it
6. Click the EditConfigure button to input a new key combination intera

The default is Ctrl+Alt+I (or Cmd+Alt+I on Mac), but you can change this to any key combination that doesn't conflict with other Godot shortcuts.

Maintenance

The formatter binary gets updated regularly with bug fixes and improvements. You can update it anytime or uninstall it if you no longer need it.

Updating the formatter

To get the latest version of the formatter binary:

1. Open the Format menu or press Ctrl+Shift+P for the command palette
2. Choose Install or Update Formatter
3. Wait for the download to complete

The add-on downloads the newest version and replaces your current one. You'll see messages in the Output panel confirming when the download is complete.

Uninstalling the formatter binary

If you want to remove the formatter binary that the add-on installed:

1. Open the Format menu or press Ctrl+Shift+P for the command palette
2. Choose Uninstall Formatter

This removes only the binary from Godot's cache folder. The add-on itself stays installed and active in your project, it just won't be able to format code until you install the formatter again.

Download files

• Godot addon

Updates / Code patches

• This user manual was created with Godot 4.5
• No errors have been reported. REPORT AN ERROR