How to apply standard code order in one click - Automatic GDScript formatting

Resources Tips & Tricks
,
1

If you’re tired of manually reordering your GDScript code to match the official style guide, I’ve got something for you.

Why code order matters?

A code with standard order is more easier to read, specially when you read it from top to bottom. Also, it helps developers reading the code for the first time to understand how it works.

Manual way

You can reorder your code manually with this guide, but

  • It takes a lot of time for each script
  • You have to go back to the help page many times
  • You might forget something

And you have to repeat it over and over, there’s even a joke about it here (I had pinned this help page in my browser before this guide😅)

Automatic way

So let’s start real solution. For this you need a simple setup:

  1. Text Forge v0.1+ (it’s available for download for Windows and Linux here) ~30MB
  2. Text Forge GDScript Mode v1.1+ (direct link to mode file) ~5KB

First step is installing mode, for this run Text Forge (you can find full setup guide here) and go to Settings > Mode Manager…, then click on Import Mode / Mode Kit and select .tfmode file you was downloaded. Now, close Mode Manager window and just open your .gd file (you can use Ctrl + O as shortcut) and press Ctrl + Shift + F or use Format > Auto Format option, editor will use GDScript mode to:

  • Move each block extedns, class, func, static func, var, @onready var, etc to correct place
  • Cleanup whitespaces
  • Sort each block type in public-private and alphabetical order
  • Move comments to correct place

Now you can save your script to apply changes.

Some details

How does it work?
Breaks the code into blocks, categorizes the blocks, sorts each category, and arranges the categories sequentially to form the complete code.

Is it possible for the code’s functionality to change?
Generally, no, because it doesn’t change the logic or remove any blocks.

Limitations:

  • Does not support regions; it moves them all to the top of the code for you to remove yourself.
  • Does not support nested sorting to prevent changes in code behavior.
  • Treats standalone comments (not attached to any code) as notes and moves them to the top of the code.
  • Does not sort export variables precisely.

Directly in Godot?

Unfortunately, I don’t have a plugin to do this directly in Godot, but since Text Forge and all its modes (including the GDScript mode which has this capability) are written in GDScript, it’s not too difficult to implement. This mode is available under the MIT license in this GitHub repository:

If you develop a plugin with the Auto Format section of this code, please comment it here so that others can use it as well.

Thanks,
– Mahan

1 Like
2

Is there a command line option for this so it can be added into a git hook?

3

Right now no, the CLI doesn’t have a very good look, and the only way to implement it is to run something like this through a plugin:

  • Send open command
  • Send auto format command
  • Send save command (or get formatted code)

Of course, this requires more preparation. Without the user interface, you need to run and close the editor for the initial preparation once, extract the mode and install it manually, create a plugin that does the above steps and install it manually, then run the editor to get everything going. All of this is possible with the command line, but it will definitely be more complicated than running something like one or more command line commands.

1 Like
4

Still very cool. I’d love to see this integrated into the Godot Editor. I wonder if there’s a feature request for it?

5

It doesn’t exist, but I’m not saying it’s impossible. Of course, it still has limitations, the most important of which is that it does not correctly identify virtual functions and considers them private, which go to the end (I have already tried identifying default signals in Settings handling (complete) by mkh-user · Pull Request #39 · yannlemos/Signal-Lens · GitHub, it is probably possible to do the same for functions), another issue is the detection of signal callbacks, they should basically be after other functions but remain next to the private functions. To prevent this from being a big problem, I wrote it in such a way that it sorts each type of block as public-private and then alphabetically (so if the default prefix _on_ is used, all these functions will be close together).

Of course, these are not much of an obstacle, although the Official Style Guide has its own advantages, this current performance has a similar result: all codes have the same order and follow a rule that is almost the same as the official version.

We have a formatter in GDScript ToolKit (here) that fixes whitespaces a bit. This one is suitable for git hook and I think it also has a ready-made action, however it is not yet a built-in feature.

Maybe later I will translate it to C++ and submit a suggestion, but now I can’t do anything except what exists.

1 Like