File system

Introduction

File systems are another hot topic in engine development. The file system manages how assets are stored and how they are accessed. A well-designed file system allows multiple developers to edit similar source files and assets while collaborating.

Early versions of the Godot engine (and previous iterations before Godot was named) used a database. It stored assets and assigned an ID. Other approaches were also tried, such as local databases, files with metadata, etc. In the end, the simplex method won out, and Godot stores all assets in the file system as files.

Implementation

The file system stores resources on disk. Anything, from script to scene or PNG image, is a resource for the engine. If a resource has properties that refer to other resources on the disk, then the path to those resources is also included. If a resource has sub-resources that are built-in, the resource is saved in a single file with all the bundled sub-resources. For example, font processing is often combined with font design.

In general, the Godot file system avoids using metadata files. The reason for this is simple, the current asset manager and VCS are much better than anything we implement, so Godot tries its best to play with SVN, Git, Mercurial, perforce, and more.

Example of a file system contents:

Project.godot

The project.godot file is the project description file and is always found at the root of the project. Its location defines where the root is. This is the first file Godot sees when opening for a project.

The file has a project configuration in plain text, using the win.ini format. Even an empty project .godot can serve as the basic definition of a new project.

Path delimiter

Godot only supports / as a limitation. This is done for portability reasons. All operating systems support Windows, even a path, such as c: \ project \ Project. Godot must type c: /project/project.godot.

Resource path

Access to resources can be cumbersome and non-portable when using a host OS file system layout. To solve this problem, the individual path res: // was created.

The path Res: // will always point to the project root (where project.godot is located, so in fact, Res: //project.godot is still valid).

This file system is read-only from the editor while running the project locally. When exported or running on different devices (such as from a phone or console, or DVD), the file system will become read-only, and no write permissions will be allowed.

User path

Writing to disk is still required for various tasks such as saving game state or downloading content packs. To this end, the engine ensures that a particular path is a user: //, which is always writable.

Host file system

Alternatively, the host file system path can also be used, but is not recommended for a released product as these paths are not guaranteed to work on all platforms. However, it can be useful to use the host file system path when writing development tools in Godot!

Drawbacks

This simple file system design has some drawbacks. The first issue is that the surrounding assets (renaming them or moving from one path to another within the project) will break existing references to these assets. These references have to be redefined to point to the new asset location.

Another is that Windows and macOS file and path names are case insensitive. If there is a case the developer working in the insensitive host file system saves the property as"myfile.PNG", but then refers to it as "myfile.png", it will work fine on their platform, but Linux Like not on other platforms. Android, etc.

The second is that Windows and macOS file and path names are case insensitive. If a developer working in a case insensitive host file system saves property as "myfile.PNG" but then refers to it as "myfile.png," it will work fine on their platform, but not on other platforms like Linux. Android, etc. This can also apply to exported binaries, which use a compressed package to store all files.

It is recommended that our team clearly defines a naming convention for files when working with Godot! One simple fool-proof agreement is only to allow lowercase file and path names.