Godot Files

[][public domain] [][donate]

Additional features for some Godot files, better syntax-coloring and very basic GDShader support.
Godot Editor does NOT need to be running for any features here.

🔑 With a [donation][donate], you can unlock early access and other rewards! More info below.

Screenshots use the [Semanticolors Dark][donate] theme, available for both VSCode and Godot for a consistent experience.

This is not meant to fully replace the official godot-tools extension, but to improve on its supported files. This plugin is designed so it can work alongside it, but it's completely independent. If you're using GDScript, you'll likely want to install godot-tools too; if not, just this one may be enough.
🔧 The setting files.associations can change your preferred extension to handle *.tscn, *.tres, etc.

Compatibility:

• Godot: 3.x LTS and 4.0 to 4.x; official and flathub builds
• godot-tools: v2.6.x; ("view documentation" feature can use godot-tools)

🌐 This extension also works on browser IDEs (vscode.dev and github.dev), with minor limitations.

Special Thanks

❤️ Huge thanks to everyone who has donated so far!
There are special donation tiers if you also want to [get your profile picture listed][rewards] right here:

Features

Features are supported on these languages: - GDShader files: *.gdshader, *.gdshaderinc.
> 🔒 Very basic GDShader Language features are available on [early access][donate]. See below. - "GDAsset" files (this term is used here to describe all INI-like files used by Godot):
project.godot, *.tscn, *.escn, *.tres, *.gdns, *.gdnlib, *.import, *.tet, *.remap. - "Configuration Properties" (config-definition), used for other specific non-Godot INI-like files:
*.cfg, Git config files (.gitconfig, .git/config) and XDG Desktop Entry files (.desktop, .directory).

Webview features: - Godot Documentation Viewer

Syntax Highlighting

Includes better (more specific) grammars for syntax-coloring on all supported textual languages above.

"Configuration Properties" reuses the "GDAsset" grammar. It fits better than "INI" and "Properties" because it's "smarter" than regular INI. It supports sub-properties, literals (booleans, numbers, strings), quoted strings in section headers, ;-separated lists, apostrophe (single quote) inside unquoted strings like don't, etc. You might want to associate this language with any other INI-like formats as well if you notice it fits better.

Embedded Code

Syntax-coloring of valid embedded code is supported. - GDAsset: in asset strings for GDScript and GDShader resources.
😎 It handles inner and outer languages' escape sequences gracefully, and colors them differently:
- GDShader: in codeblock BBCode tags in docs comments (including [gdscript] and [csharp] tags).
✳️ Always put the inner code in its own lines verbatim, without a leading * or extra leading indentation.

The inner code doesn't break the container code syntax, as long as it's valid code (without partial constructs like unterminated strings/comments, mismatched brackets, etc). Some cases are being handled, but it's not viable to try to safeguard against every possible case of invalid code; this is a limitation of the IDE.

Document Symbols

Symbol definitions are provided for: - 🔒 GDShader files (only in [early access][donate], see below). - GDAsset files, as per their INI-like structure. - Configuration Properties (non-Godot INI-like) files.

The IDE uses this in many places, like the Outline view, in Breadcrumbs and in the "Go to Symbol in Editor" feature (typing @ in the command palette).

Features in GDAsset files

These features are supported in textual Scene and Resource files.

Automatically shown

• See inferred class and path of resource references in inlay hints. You can Ctrl+Click them to navigate. You can also hover paths.
  ✳️ Paths are only shown at the end of a line (so not within arrays, but you can still hover the id to see the path in this case).
  🔧 You can control this feature in the settings under godotFiles.clarifyReferences (.filePath, .class and .asOperator). By default, .filePath shows the minimal unique subpath (usually just the file name; folders are only shown to differentiate files with the same name). The class is not hinted where it can be inferred from the context, so in Godot 4 it won't be shown for SubResource, as it's already in the id (unless you set .class to always).
  

• See implied parentheses in packed arrays of vectors or colors that surround items, similar to inlay hints.
  🔧 You can toggle this feature with the settings under godotFiles.clarifyArrays (.vector and .color).
  ✳️ This feature respects editor.maxTokenizationLineLength to avoid potential performance issues on very long lines.
  

Hovering

• Preview images and fonts by hovering their resource paths or ExtResource references.
  🔧 You can disable resource previews when hovering at godotFiles.hover.previewResource.
  💻 On browser IDEs, this may only work for small files (approx. 74kB or less).

  
  ✳️ Images supported: SVG, PNG, WebP, JPEG, BMP, GIF.

  The font preview shows all ASCII letters and helps testing if they're too similar to numbers:
  
  ✳️ Fonts supported: TTF, OTF, WOFF, WOFF2.

• Preview a resource file thumbnail (from the Godot Editor cache) by hovering its external reference.
  🔧 The setting godotFiles.hover.previewResource also applies here.
  💻 Unavailable on browser IDEs, as this depends on the thumbnail cache that Godot writes on your PC.
  ⚠️ If you're using Godot in self-contained mode, this requires adding the cache path with the setting godotFiles.godotCachePath.

  It works for scenes:
  

  As well as any other resource files that have a thumbnail in Godot Editor:
  

• See GDScript code for loading a resource or path (preload(…), load(…) or FileAccess.open(…)).
  

• Edit a color in its inline decorator on Color(…) values or within an array. You can also see its hex value.
  🔧 You can disable this feature with the settings under godotFiles.inlineColors (.single and .array).
  
  ✳️ The displayed color (and its hex value) can't consider advanced cases like HDR and color space changes (e.g. between sRGB and linear).

Commands

• Navigate to the definition of SubResource and ExtResource references, and to resource paths (Ctrl Click or F12 by default).
  
  ✳️ Going to the definition of a built-in engine type (on type="SomeType", some_field = SomeType(...) or in inlay hints) will open its Godot API Documentation using the configured viewer (see below). But note that GDScript is entirely handled by godot-tools (not by this extension), so when using "Go to Definition" on a .gd file, they'll always use their own implementation to show the documentation.

Features viewed in special tabs

These features are supported as special (non-text editor) tabs.

Godot Documentation Viewer

Browse the online Godot Documentation directly from the IDE.
⚙️ Use the command Godot Files: Open Godot API Documentation (default: Ctrl F1; macOS: ⌥ ⌘ D) to show the page listing all classes, find a specific class under the text cursor, or search the selected text.
🔧 The setting godotFiles.documentation.viewer lets you choose your preferred viewer for when you're online (the features supporte