Repository files navigation

GodotEnv is a command-line tool that makes it easy to switch between Godot versions and manage addons in your projects.

GodotEnv can do the following:

• ✅ Download, extract, and install Godot 3.0/4.0+ versions from the command line on Windows, macOS, and Linux (similar to tools likeNVM,FVM,asdf, etc.
• ✅ Switch the active version of Godot by updating a symlink.
• ✅ Automatically setup a userGODOT environment variable that always points to the active version of Godot.
• ✅ Install addons in a Godot project from local paths, remote git repositories, or symlinks using an easy-to-understandaddons.json file. No more fighting with git submodules! Just rungodotenv addons install whenever youraddons.json file changes.
• ✅ Automatically create and configure a.gitignore,addons.json, andaddons/.editorconfig in your project to make it easy to manage addons.
• ✅ Allow addons to declare dependencies on other addons using a flat dependency graph.

GodotEnv is a .NET command line tool that runs on Windows, macOS, and Linux.

dotnet tool install --global Chickensoft.GodotEnv

If you encounter the errorNo NuGet sources are defined or enabled, add a Nuget source or enable one and try installing GodotEnv again.

List the current sources and see which are enabled.

dotnet nuget listsource

If no sources are listed,add a new one.

dotnet nuget addsource https://api.nuget.org/v3/index.json -n nuget.org

Otherwise, make sure one isenabled.

dotnet nugetenablesource<NAME>

GodotEnv uses the localgit installation and other processes available from the shell, so make sure you've installedgit andconfigured your local shell environment correctly.

We'll walk through the commands in depth below, but if you prefer to get started right away you can use the--help flag with any command to get more information.

# Overall helpgodotenv --help# Help for entire categories of commandsgodotenv godot --helpgodotenv addons --help# Help for a specific godot management commandgodotenv godot install --help# etc...

GodotEnv can automatically manage Godot versions on your local machine for you.

🙋‍♀️ Using GodotEnv to install Godot works best for local development. If you want to install Godot directly on a GitHub actions runner for CI/CD purposes, consider using Chickensoft'ssetup-godot action — it caches Godot installations between runs, installs the Godot export templates, and also works on Windows, macOS, and Ubuntu GitHub runners.

To get started managing Godot versions with GodotEnv, you'll need to first instruct GodotEnv to install a version of Godot.

godotenv godot install 4.0.1# or a non-stable version:godotenv godot install 4.1.1-rc.1

Versions should match the format of the versions shown on theGodotSharp nuget package. Downloads are made fromGitHub Release Builds.

By default, GodotEnv installs .NET-enabled versions of Godot.

If you really must install the boring, non-.NET version of Godot, you may do so 😢.

godotenv godot install 4.0.1 --no-dotnet

When installing a version of Godot, GodotEnv performs the following steps:

• 📦 Downloads Godot installation zip archive (if not already downloaded).
• 🤐 Extracts Godot installation zip archive.
• 📂 Activates the newly installed version by updating the symlink.
• 🏝 Makes sure the userGODOT environment variable points to the active Godot version symlink.

GodotEnv can show you a list of the Godot versions you have installed.

godotenv godot list

Which might produce something like the following, depending on what you have installed:

4.0.14.0.1 *dotnet4.1.1-rc.14.1.1-rc.1 *dotnet

GodotEnv also supports showing a list of remote Godot versions available to install using the-r option.

godotenv godot list -r

You can change the active version of Godot by instructing GodotEnv to update the symlink to one of the installed versions. By default, it only looks for the .NET-enabled version of Godot. To use a non-.NET version of Godot, specify--no-dotnet.

# uses dotnet versiongodotenv godot use 4.0.1# uses non-dotnet versiongodotenv godot use 4.0.1 --no-dotnet

You may want to install or use the version of Godot that is appropriate for the project you're currently working on. You can issue thegodotenv godot install andgodotenv godot use commandswithout providing a version parameter, and the commands can infer the correct version from files in your directory tree.

The command will walk up the directory tree and use the following files, in order of precedence:

• global.json specifying aGodot.NET.Sdk value inmsbuild-sdks.
• *.csproj specifying a versionedGodot.NET.Sdk as its Project SDK.
• .godotrc with a Godot version string as its first line.

Aglobal.json file at any directory level above the working directory will take precedence over allcsproj files, even those closer to the working directory; likewise, anycsproj file in the tree will take precedence over all.godotrc files. Files of the same type that are fewer steps up the directory tree will take precedence over ones that are further up the tree.

Versions fromglobal.json or acsproj file are assumed to be .NET-enabled. A.godotrc file may specify a non-.NET Godot by appending a space and the stringno-dotnet to the version string. For instance, a.godotrc file containing the value4.0.1 no-dotnet indicates the non-.NET version of Godot 4.0.1.

To enable the version-freegodotenv godot install andgodotenv godot use commands without hand-authoring a version-specifying file for your project, you can use thegodotenv godot pin command. This command will locate the top-level directory of your project and place a version-specifying file in it, indicating your active Godot version as the preferred version for the project.

• To find the top-level directory of your project, the command walks up the directory tree from the working directory.
  • If your project contains anysln files, the command will use the topmost directory containing asln file.
  • If your project does not contain anysln files, the command will use the topmost directory containing aproject.godot file.
• If your active Godot version is .NET-enabled, the command will add its version number as aGodot.NET.Sdk value in an existingglobal.json in the top-level project directory, or create a newglobal.json with the value if one does not exist.
• If your active Godot version is not .NET-enabled, the command will place its version number in a.godotrc file in the top-level project directory, overwriting any existing.godotrc file in that location.

Once the version-specifying file is created or updated with the preferred Godot version, you can commit it to source control for use by others on your team.

Uninstalling works the same way as installing and switching versions does.

# uninstalls .NET versiongodotenv godot uninstall 4.0.1# uninstalls non-dotnet versiongodotenv godot uninstall 4.0.1 --no-dotnet

GodotEnv can provide the path to the symlink that always points to the active version of Godot.

godotenv godot env path

GodotEnv will provide you with the path to the active version of Godot that the symlink it uses is currently pointing to.

godotenv godot env target

You can use GodotEnv to set theGODOT user environment variable to the symlink that always points to the active version of Godot.

# Set the GODOT environment variable to the symlink that GodotEnv maintains.godotenv godot env setup# Print the value of the GODOT environment variable.godotenv godot env get

On Windows, this adds theGODOT environment variable to the current user's environment variable config.

On macOS, this adds theGODOT environment variable to the current user's default shell configuration file. In case the user's shell isn't compatible, defaults tozsh.

On Linux, this adds theGODOT environment variable to the current user's default shell configuration file. In case the user's shell isn't compatible, defaults tobash.

After making changes to environment variables on any system, be sure to close any open terminals and open a new one to ensure the changes are picked up. If changes are not picked up across other applications, you may have to log out and log back in. Fortunately, since the environment variable points to a symlink which points to the active Godot version, you only have to do this once! Afterwards, you are free to switch Godot versions without any further headache as often as you like.

GodotEnv caches the Godot installation zip archives it downloads in a cache folder. You can ask GodotEnv to clear the cache folder for you.

godotenv godot cache clear

GodotEnv allows you to installGodot addons. A Godot addon is a collection of Godot assets and/or scripts that can be copied into a project.By convention, these are stored in a folder namedaddons relative to your Godot project. Check out theDialogue Manager addon to see how a Godot addon itself is structured.

Besides copying addons from remote git repositories or zip files, GodotEnv allows you to install addons from a local git repository or symlink to local directories on your machine so that you can use an addon across multiple Godot projects while it is still in development.

Using GodotEnv to manage addons can prevent some of the headaches that occur when using git submodules or manually managing symlinks.

Additionally, GodotEnv will check for accidental modifications made to addon content files before re-installing addons in your project to prevent overwriting changes you have made. It does this by turning non-symlinked addons into their own temporary git repositories and checking for changes before uninstalling them and reinstalling them.

If you're using C#, you have two ways of sharing code: Godot addons and nuget packages. Each should be used in different scenarios.

• 🔌Addons allow scenes, scripts, or any other Godot assets and files to be reused in multiple Godot projects.

• 📦Nuget packages only allow C# code to be bundled into a library which can be used across multiple Godot projects.

If you're just sharing C# code between projects, you should use a nuget package or reference another .csproj locally. If you need to share scenes, resources, or any other type of files, use a Godot addon.

Managing addons in Godot projects has historically been somewhat problematic:

• If you copy and paste an addon into multiple projects, and then modify the addon in one of the projects, the other projects won't get any updates you've made. Duplicated code across projects leads to code getting out of sync, developer frustration, and forgetting which one is most up-to-date.

• If you want to share addons between projects, you might be tempted to use git submodules. Unfortunately, git submodules can be very finnicky when switching branches, and you have to be mindful of which commit you've checked out. Submodules are not known for being friendly to use and can be extremely fragile, even when used by experienced developers.

• GodotEnv allows addons to declare dependencies on other addons. While this isn't a common use case, it will still check for various types of conflicts when resolving addons in a flat dependency graph and warn you if it detects any potential issues.

Using anaddons.json file allows developers to declare which addons their project needs, and then forget about how to get them. Whenever the addons.json file changes across branches, you can just simply reinstall the addons by runninggodotenv addons install and everything will "just work." Additionally, it's easy to see which addons have changed over time and across different branches — just check the git diff for theaddons.json file.

GodotEnv needs to tell git to ignore your addons directory so that it can manage addons instead. Additionally, it will place a.editorconfig in your addons directory that will suppress C# code analysis warnings, since C# styles tend to vary drastically.

godotenv addons init

This will add something like the following to your .gitignore file:

# Ignore all addons since they are managed by GodotEnv:addons/*# Don't ignore the editorconfig file in the addons directory.!addons/.editorconfig

Theaddons init command will also create a.editorconfig in youraddons directory with the following contents:

[*.cs]generated_code =true

Finally, GodotEnv will create an exampleaddons.jsonc file with the following contents to get you started:

// Godot addons configuration file for use with the GodotEnv tool.// See https://github.com/chickensoft-games/GodotEnv for more info.// -------------------------------------------------------------------- //// Note: this is a JSONC file, so you can use comments!// If using Rider, see https://youtrack.jetbrains.com/issue/RIDER-41716// for any issues with JSONC.// -------------------------------------------------------------------- //{"$schema":"https://chickensoft.games/schemas/addons.schema.json",// "path": "addons", // default// "cache": ".addons", // default"addons": {"imrp": {// name must match the folder name in the repository"url":"https://github.com/MakovWait/improved_resource_picker",// "source": "remote", // default// "checkout": "main", // default"subfolder":"addons/imrp"    }  }}

Here are some notes explaining the info fields within each addon:

• url : The link or file system path pointing to the addon source.
• source : The source type used by this addon, can beremote,local, orsymlink.
• checkout : The branch or tag to use when installing from a Git repository.
• subfolder : The folder path within the addon repository to install from. The default value is/ which installs all files from the source.

GodotEnv uses the system shell to install addons from symlinks, local paths, and remote git url's and zip files. Please make sure you've configuredgit in your shell environment to use any desired credentials so it can clone any local and remote repositories you reference.

godotenv addons install

When you run the addon installation command in GodotEnv, it looks in thecurrent working directory of your shell for anaddons.json oraddons.jsoncjsonc file. The addons file tells GodotEnv what addons should be installed in a project.

Here's an example addons file that installs 3 addons, each from a different source (remote git repository, local git repository, and symlink).

{"path":"addons",// optional — this is the default"cache":".addons",// optional — this is the default"addons":{"godot_dialogue_manager":{"url":"https://github.com/nathanhoad/godot_dialogue_manager.git","source":"remote",// optional — this is the default"checkout":"main",// optional — this is the default"subfolder":"addons/dialogue_manager"// optional — defaults to "/"},"my_local_addon_repo":{"url":"../my_addons/my_local_addon_repo","source":"local"},"my_symlinked_addon":{"url":"/drive/path/to/addon","source":"symlink"}}}

❗️ Each key in theaddons dictionary above must be the directory name of the installed addon inside the project addons path. That is, if an addon repository contains its addon contents insideaddons/my_addon, the name of the key for the addon in the addons file must bemy_addon.

If you want to install an addon from a local path on your machine, your local addon must be a git repository. You can specify theurl as a relative or absolute file path.

{"addons": {"local_addon": {"url":"../my_addons/local_addon","checkout":"main","subfolder":"/","source":"local"    },"other_local_addon": {"url":"/Users/me/my_addons/other_local_addon","source":"local"    },  }}

GodotEnv can install addons from remote git repositories. Below is the addon specification for an addon from a remote git repository. The url can be any valid git remote url, and the subfolder specifies which folder within the addon repository will be copied into your project.

{"addons": {"remote_addon": {"url":"git@github.com:user/remote_addon.git","subfolder":"addons/remote_addon"    }  }}

By default, GodotEnv assumes the addonsource isremote, thecheckout reference ismain, and thesubfolder to install is the root/ of the addon repository. If you need to customize any of those fields, you can override the default values:

{"addons": {"remote_addon": {"url":"git@github.com:user/remote_addon.git","source":"remote","checkout":"master","subfolder":"subfolder/inside/repo",    }  }}

GodotEnv can "install" addons using symlinks. Addons installed with symlinks do not need to point to git repositories — instead, GodotEnv will create a folder which "points" to another folder on your file system using symbolic linking.

"addons": {"my_symlink_addon": {"url":"/Users/myself/Desktop/folder","source":"symlink"    },"my_second_symlink_addon": {"url":"../../some/other/folder","source":"symlink","subfolder":"some_subfolder"    }  }

Note: Thecheckout reference is ignored when using symlinks.

Whenever a symlinked addon is modified, the changes will immediately appear in the project, unlike addons included with git repositories. Additionally, if you change the addon from your game project, it updates the addon source where the symbolic link is pointing.

Using symlinks is a great way to include addons that are still in development across one or more projects.

GodotEnv can install addons from remote zip files. Simply provide a url to a zip file and GodotEnv will download it, extract it, and copy its contents to the addons directory.

"addons": {"godot_jolt": {"url":"https://github.com/godot-jolt/godot-jolt/releases/download/v0.14.0-stable/godot-jolt_v0.14.0-stable.zip","source":"zip","subfolder":"addons/godot-jolt"    }  }

GodotEnv caches local and remote addons in the cache folder, configured above with thecache property in theaddons.json file (the default is.addons/, relative to your project). You can safely delete this folder and GodotEnv will recreate it the next time it installs addons. Deleting the cache forces GodotEnv to re-download or copy everything on the next install.

IMPORTANT: Be sure to add the.addons/ cache folder to your.gitignore file!

GodotEnv will install addons into the directory specified by thepath key in theaddons.json file (which defaults to justaddons/).

Addons should be omitted from source control. If you need to work on an addon at the same time you are working on your Godot project, use GodotEnv to symlink the addon. By omitting the addons folder from source control, you are able to effectively treat addons as immutable packages, like NPM does for JavaScript.

Just rungodotenv addons install after cloning your project or whenever youraddons.json file changes!

An addon can itself contain anaddons.json file that declares dependencies on other addons. When the addon is cached during addon resolution, GodotEnv checks to see if it also contains anaddons.json file. If it does, GodotEnv will add its dependencies to the queue and continue addon resolution. If GodotEnv detects a potential conflict, it will output warnings that explain any potential pitfalls that might occur with the current configuration.

GodotEnv uses a flat dependency graph that is reminiscent of tools likebower. In general, GodotEnv tries to be extremely forgiving and helpful, especially if you try to include addons in incompatible configurations. GodotEnv will display warnings and errors as clearly as possible to help you resolve any potential conflicting scenarios that may arise.

You can view and adjust GodotEnv's settings. Configuration settings are organized into sections and are accessed by keys of the form<SectionName>.<SettingName>.

To view all configuration settings:

godotenv config list

To view a particular configuration setting:

godotenv config list Terminal.DisplayEmoji

To specify a new value for a configuration setting:

godotenv configset Terminal.DisplayEmoji False

If you want to contribute, please check outCONTRIBUTING.md!

While the addons installation logic is well-tested, the Godot version management feature is new and still needs tests. Currently, a GitHub workflow tests it end-to-end. As I have time, I will add more unit tests.

🐣 Made with love by 🐤 Chickensoft —https://chickensoft.games