English | 简体中文
For projects involving multiple team collaborations, Godot does not have a complete project file specification. This guide aims to provide recommendations for organizing Godot projects to streamline multi-person collaboration processes.
All assets should have a base asset name, indicating the logical grouping of related assets. Any asset belonging to this logical group should follow:
base_asset_name_suffix.type_extension
For unique and specific variants of assets, the base asset name should either be a short and easily recognizable name that represents the logical grouping of the assets, or a subset of the base asset name. For example, if Bob has multiple skins, these skins should still use bob as the base asset name but include a recognizable variant. An Evil skin would be called bob_evil and a retro skin would be called bob_retro.
For unique assets with common variables, the base asset name should start with 01 and be two digits long. For example, if an environment artist produces unusual rocks, they would be named rock_01, rock_02, rock_03, etc. You should not require a three-digit variant number except for rare exceptions. If you have more than 100 assets, you should consider using different base names or multiple variant names to organize them.
wuling_01.gltf, wuling_01_albedo.png, wuling_01_normal.png
| Type | Name |
|---|---|
| Scene | bob.tscn |
| Skeletal Mesh | bob_skleton.gltf |
| Material | bob_material.tres |
| Texture | bob_albedo.png |
| Texture (Evil Albedo) | bob_albedo_evil.png |
| Type | Name |
|---|---|
| Static Mesh 01 (Static Mesh) | rock_01.gltf |
| Static Mesh 02 (Static Mesh) | rock_02.gltf |
| Static Mesh 03 (Static Mesh) | rock_03.gltf |
| Texture | rock_01_albedo.png |
| Material | rock_01_material.tres |
| Material (Snow) | rock_01_material_snow.tres |
| Type | Name |
|---|---|
| Texture (Albedo) | tank_01_albedo.png |
| Texture (Normal) | tank_01_normal.png |
| Texture (Roughness) | tank_01_rough.png |
| Texture (Alpha/Opacity) | tank_01_alpha.png |
| Texture (Ambient Occlusion) | tank_01_ao.png |
| Texture (Emissive) | tank_01_emissive.png |
| Texture (Specular) | tank_01_specular.png |
| Texture (Metallic) | tank_01_metallic.png |
| Texture (ORM) | tank_01_orm.png |
The project directory structure style should be treated as a rule, just as important as asset naming conventions. There are multiple ways to layout Godot project content.
This guide recommends a structure that relies more on the file system’s filtering and search capabilities to help users find specific types of assets, rather than a common structure that groups asset types by folder.
|-- res://
|
|-- addons
| |-- terrain_3d
| |-- ...
|-- waveshooter
| |-- meshes
| | |-- industrial
| | | |-- props
| | | | |-- standlight_01.gltf
| | | | |-- standlight_01_albedo.png
| | | | |-- ...
| | | |-- buildings
| | | |-- ...
| | |-- nature
| | |-- props
| | |-- foliage
| | |-- rocks
| | |-- trees
| |-- characters
| | |-- bob
| | |-- common
| | |-- animations
| | |-- audio
| |-- effects
| | |-- fire
| | |-- weather
| | |-- electrical
| | |-- spark_01
| | |-- spark_01_halo.png
| | |-- spark_01.tscn
| | |-- ...
| |-- maps
| |-- gameplay.tscn
|-- core
| |-- fonts
| |-- images
| |-- singletons
| |-- ui
| |-- menu
| |-- pause
|-- sandbox
The reasons for this structure are listed in the following sections:
These are the common rules for naming any folders in the content structure：
snake_case means starting a name with a lowercase letter, then using underscores instead of spaces, with each subsequent word also starting with a lowercase letter. For example, desert_eagle, rocket_pistol, and a_series_of_words.
As a supplement to 3.2.2: never use spaces. Spaces can cause various engineering tools and batch processing to error. Ideally, the root of your project also does not contain spaces and is located in such a position as D:\GodotProjects, NOT C:\Users\My Name\My Documents\Godot Projects.
If one of your game characters is named “Zoe”, its folder name should be zoe. For engineering tools, Unicode characters can be worse than spaces, and some parts of Godot may not support Unicode characters in paths.
Related to this, if your project has inexplicable issues and your computer’s username has Unicode characters (i.e., your name is Zoe), any projects in your “Documents” folder will be affected by this issue. Typically, simply moving your project to D:\Project will resolve these issues.
Using other characters beyond a-z and 0-9, such as @, -, *, and #, can also lead to unexpected and difficult-to-trace issues on other platforms, source control systems, and weaker engineering tools.
All assets of the project should exist within a folder named after the project. For example, if your project is named “shooter”, then all of its content should exist within res://shooter/.
There are several reasons for this practice:
If your project plans to release DLC, or has multiple related sub-projects, which may be moved out or not cooked with the main project, then the assets related to these projects should have their own separate top-level content folders. This makes it easier to separate cooking DLC from the main project content. Sub-projects can also be migrated in and out with minimal effort. If you need to change the materials of assets or add some very specific asset override behaviors in patches, you can easily put these changes in a patch folder and work safely without breaking the core project.
Example: res://dlc_01/
It is very common during project development for team members to have a “sandbox” where they can experiment freely without risking the core project. Since this work may be in progress, these team members may want to put their assets on the project’s source code management server. Not all teams need to use a sandbox folder, but teams that do often encounter common issues with assets being committed to source control. You should add the sandbox folder to the ignore list in your version control system, for example:
# .gitignore file
# Sandbox folder
[Ss]andbox/
Team members can easily accidentally use assets that are not yet ready for use, and once these assets are removed, it will cause issues. For example, an artist may be working on a set of modular static meshes and is still working to get their sizes and mesh grabbing correct. If a world builder sees these assets in the main project folder, they might use them on a level without knowing they may be subject to incredible changes and/or deletion. This leads to a lot of rework for everyone on the team.
If these modular assets were placed in the sandbox folder, the world builder would have no reason to use them, and the whole issue would never occur.
Once the assets are ready for use, the artist simply moves the assets to the project-specific folder and fixes the redirectors. This is essentially “promoting” the assets from experimental to production.
Example: res://sandbox/
Map scene files are very special, and it's common for each project to have its own map naming system, especially when they work with sub-levels or stream levels. Whatever map organization system is established for a specific project, all levels should belong to res://project_name/maps.
Being able to tell someone to open a specific map without having to explain where it is is a great time saver and a general QoL improvement. Levels are usually located in sub-folders of maps, such as maps/campaign1/ or maps/arenas, but the most important thing here is that they all exist within res://project_name/maps/.
This also simplifies the engineer's work. If you have to dig through arbitrary folders for the build process, the swinger level of the build process can be very frustrating. If a team's maps are all in one place, it is much more difficult to accidentally omit maps from the build. It also simplifies the QA process.
Example: res://project_name/maps/
Use a separate folder to handle assets that are absolutely critical to the project’s operation. For example, basic Singletons, UI/HUD, Audio Bus Layout, Event System, and Splash Images should reside here.
For UI, generally, the core folder should only store UIs such as the main menu, settings menu, etc., while the HUD within the game should be stored under the game project folder. It’s important to ensure that files within the core are not modified as much as possible during game updates (except for major version updates or DLC updates).
This creates a very clear “do not touch these” message for other team members. Non-engineers should have little reason to enter the core folder. Following good coding structure practices, designers should make game adjustments in subclasses that expose functionality. World builders should use Scenes in the specified maps folder, rather than potentially misusing base classes.
Example: res://core/