Godot Files
Better syntax-coloring and additional features for some files supported by Godot Editor.
This is not meant to 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.
Compatibility: Godot 3.x LTS and 4.0 to 4.x
This extension also works on browser IDEs (vscode.dev and github.dev), with limited functionality.
Features
Includes syntax-coloring for these languages:
- Godot Shader files:
*.gdshader
, *.gdshaderinc
.
- Better (more specific) grammar for the INI-like files used by Godot (called "GDAsset" here):
project.godot
, *.tscn
, *.escn
, *.tres
, *.gdns
, *.gdnlib
, *.import
, *.tet
, *.remap
.
- The same grammar is reused for other INI-like files:
*.cfg
, Git config files (.gitconfig
, .git/config
) and XDG Desktop Entry files (.desktop
, .directory
).
It fits better than INI and Properties because this grammar is "smarter" than regular INI. E.g., 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 (config-definition
/ Configuration Properties) with any other (non-Godot) INI-like formats as well if you notice it fits better.
INI-like files (including GDAsset) also support:
- Outline and breadcrumb items.
GDAsset files also support:
Syntax-coloring of embedded code in asset strings for GDScript and Godot Shader resources (see image above).
😎 It even handles both inner and outer languages' escape sequences gracefully, and colors them differently:
Navigate to definition of SubResource
and ExtResource
references, and to resource paths.
🌟 NEW: Going to the definition of a built-in engine type (on type="SomeType"
or some_field = SomeType(...)
) will open its Godot API Documentation. This will be handled by the godot-tools extension, unless you're online and enabled early access (see below).
Hover resource references or paths to show code for loading in GDScript (preload(…)
, load(…)
or FileAccess.open(…)
).
Hover image and font resource paths or their ExtResource
references to preview them directly.
🔧 You can disable resource previews when hovering with the setting godotFiles.hover.previewResource
.
✳️ Images supported: SVG, PNG, WebP, JPEG, BMP, GIF.
The font preview shows all uppercase and lowercase ASCII letters and helps testing if they're too similar to numbers:
✳️ Fonts supported: TTF, OTF, WOFF, WOFF2.
Hover any resource (except sub-resources) to preview its thumbnail as generated by the Godot Editor.
Godot doesn't need to be running because it updates thumbnail files into the cache whenever a resource is saved.
🔧 The setting godotFiles.hover.previewResource
also applies here.
⚠️ 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:
🌟 NEW FEATURE (NO LONGER RESTRICTED): 🌟
Inline color decorators on Color(…)
values and within arrays. Hover to edit the color or 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).
If you want more features, check the next section and potential future development below.
Early Access
Features in early access are ready for use, but restricted to supporters at first.
Each feature will usually stay restricted until the next new feature takes its place in a future version.
🔑 To unlock all features as soon as they arrive, please donate and copy the password, then use the Unlock features in early access command (right-click this extension in the panel) and paste it in the prompt. Doing this just once will permanently unlock everything in early access, even across updates.
🔒 GDAsset features currently restricted:
Inlay hints surrounding items with implied parentheses in packed arrays of vectors or colors.
✳️ This is not supported syntax in asset files! These parentheses are only shown for clarity.
🔧 You can toggle this feature with the settings under godotFiles.clarifyArrays
(.vector
and .color
).
Browse the online Godot Documentation directly from the IDE.
⚙️ You can use the command Godot Files: Open Godot API Documentation to show the page listing all classes.
🔧 The setting godotFiles.documentation.viewer
lets you choose your preferred viewer for when you're online:
godot-tools
: Use the godot-tools extension to open API docs (offline; requires Godot to be running and connected).
browser
: Open online documentation URLs in the external browser. Also supports going to the specific Godot version.
webview
: Load online documentation pages internally within IDE tabs (including tutorials). Searches and external links are opened in your browser. This advanced viewer supports going to the specific Godot version, and redirecting inherited members to locate their definition in a parent class. There's a few settings for it too.
Known Limitations
Parsing of INI-like files is very simplistic (line-based; doesn't use a robust parser library), but should work well for almost all cases where files were generated by Godot. A few corner cases might not match, specially if you manually edit files (e.g., a line with an array value like [null]
may be interpreted as a section). Also, ext_resource
paths containing comment chars (#
or ;
) are not parsed properly in outline; this causes issues in hover too.
VSCode only recognizes a word token properly when hovering or placing the cursor within its first 32 characters. So, for long paths, you only get the tooltip when hovering this initial part of the path.
VSCode is not recognizing "embeddedLanguages" as expected for some reason, so, if you edit code inside GDAsset strings, then things like toggling comments, snippets, etc. won't consider the embedded language's context.
Support
This software is free and in the public domain. It respects your privacy by not collecting any data.
👍 If you think this is useful, please star the GitHub repo and give it a rating on VS Marketplace or Open-VSX.
❤️ Itch Store | ArtStation | Unity Assets
🌐 GitHub | Bitbucket | Reddit | YouTube
Potential Future Development
You can fund development of a specific feature that you want, contributing for the benefit of the community.
When you donate, you get not only the password to unlock early access explained above, but also the right to optionally vote on a new feature. If there's enough funding from the community, development will progress, prioritizing the most voted feature. Any amount helps a lot!
The features below are theoretically feasible.
Each $ means about a week of work needed to implement it. These are very rough estimates, and this list may change.
Textual GDAsset
Id |
Weeks |
Possible Feature |
aArrayCount |
$ |
Show array size and element indices |
aHoverCartesian |
$$$$$ |
Cartesian hover previews for some coordinate values like vector, quat, basis, etc |
Binary Godot Asset
Id |
Weeks |
Possible Feature |
bDecode |
$$ |
Read-only textual GDAsset code (tres, tscn) for binary resource files (res, scn, etc.) |
bTexView |
$$ |
Open .stex and .ctex texture files like images |
Godot Shader
Id |
Depends on |
Weeks |
Possible Feature |
sParser |
|
$$$$$$$$ |
Preprocessor + Parser, independent of Godot Editor |
sSyntaxErr |
sParser |
$ |
Report Syntactical Errors |
sOutline |
sParser |
$ |
Outline / Breadcrumbs + Go to Workspace Symbol |
sGotoDef |
sParser |
$ |
Go to Definition in User Code |
sHighlight |
sGotoDef |
$ |
Highlight Occurrences |
sSemantic |
sParser |
$ |
Semantic Coloring |
sLangCompl |
sParser |
$ |
Basic Completions (Keywords, Snippets) |
sUserDocs |
sParser |
$$ |
User API Documentation |
sUserCompl |
sParser |
$$ |
User API Completions |
sUserSign |
sParser |
$$ |
User API Signature Help |
sCoreApi |
|
$$$ |
Structured Built-in API + Docs (fetch online) |
sGotoDocs |
sCoreApi, sParser |
$ |
Go to Online Documentation |
sFindRef |
sCoreApi, sHighlight |
$ |
Find References |
sRename |
sCoreApi, sFindRef |
$ |
Rename Refactoring |
sCoreDocs |
sCoreApi, sParser |
$$$ |
Built-in API Documentation |
sCoreCompl |
sCoreApi, sParser |
$$$ |
Built-in API Completions |
sCoreSign |
sCoreApi, sParser |
$$$ |
Built-in API Signature Help |
sSemErr |
sCoreApi, sSyntaxErr |
$$$$ |
Report Some Semantic Errors |