Introduction

A file system manages how assets are stored and how they are accessed.A well-designed file system also allows multiple developers to edit thesame source files and assets while collaborating. Godot storesall assets as files in its file system.

Implementation

The file system stores resources on disk. Anything, from a script, to a scene or aPNG image is a resource to the engine. If a resource contains propertiesthat reference other resources on disk, the paths to those resources are alsoincluded. If a resource has sub-resources that are built-in, the resource issaved in a single file together with all the bundled sub-resources. Forexample, a font resource is often bundled together with the font textures.

The Godot file system avoids using metadata files. Existing asset managers and VCSsare better than anything we can implement, so Godot tries its best to play alongwith Subversion, Git, Mercurial, etc.

Example of file system contents:

/project.godot/enemy/enemy.tscn/enemy/enemy.gd/enemy/enemysprite.png/player/player.gd

project.godot

Theproject.godot file is the project description file, and it is always foundat the root of the project. In fact, its location defines where the root is. Thisis the first file that Godot looks for when opening a project.

This file contains the project configuration in plain text, using the win.iniformat. Even an emptyproject.godot can function as a basic definition ofa blank project.

Path delimiter

Godot only supports/ as a path delimiter. This is done forportability reasons. All operating systems support this, even Windows,so a path such asC:\project\project.godot needs to be typed asC:/project/project.godot.

Resource path

When accessing resources, using the host OS file system layout can becumbersome and non-portable. To solve this problem, the special pathres:// was created.

The pathres:// will always point at the project root (whereproject.godot is located, sores://project.godot is alwaysvalid).

This file system is read-write only when running the project locally fromthe editor. When exported or when running on different devices (such asphones or consoles, or running from DVD), the file system will becomeread-only and writing will no longer be permitted.

User path

Writing to disk is still needed for tasks such as saving game state ordownloading content packs. To this end, the engine ensures that there is aspecial pathuser:// that is always writable. This path resolvesdifferently depending on the OS the project is running on. Local pathresolution is further explained inFile paths in Godot projects.

Host file system

Alternatively host file system paths can also be used, but this is not recommendedfor a released product as these paths are not guaranteed to work on all platforms.However, using host file system paths can be useful when writing developmenttools in Godot.

Drawbacks

There are some drawbacks to this file system design. The first issue is thatmoving assets around (renaming them or moving them from one path to another insidethe project) will break existing references to these assets. These references willhave to be re-defined to point at the new asset location.

To avoid this, do all your move, delete and rename operations from within Godot, onthe FileSystem dock. Never move assets from outside Godot, or dependencies will haveto be fixed manually (Godot detects this and helps you fix them anyway, but whygo the hard route?).

The second is that, under Windows and macOS, file and path names are case insensitive.If a developer working in a case insensitive host file system saves an asset asmyfile.PNG,but then references it asmyfile.png, it will work fine on their platform, but noton other platforms, such as Linux, Android, etc. This may also apply to exported binaries,which use a compressed package to store all files.

It is recommended that your team clearly define a naming convention for files whenworking with Godot. One fool-proof convention is to only allow lowercasefile and path names.