Godot Project Structure Guideline

project_structure.md

Godot Project Structure Guideline

This is an explaination of my project layout for Godot games and other projects. Each folder is visualised in a code block and explained below. Names written in cursive are arbitrary and can be changed.

Table of contents

• Godot Project Structure Guideline
  • Addons
    • GDScript Addons
    • GDNative Addons
    • Small Utility Addons
  • Autoloads
  • Entry Scenes
  • 3D Specific Folders
    • Materials
    • 3D Models
  • Generic Game Objects
  • Utils
  • Godot-Specific
  • Final Structure

Table of contents generated with markdown-toc

Addons

addon_repos

Addons should be git repositories and added to the addon_repos folder as git submodules. The repo should contain a readme, license, the addon in an addons folder and optionally a demo. This way it can be put on the asset library and easily viewed on github. The addon should be added to the project addons via a symbolic link.

GDScript Addons

└── *gdscript_addon*
    ├── addons
    │   └── *gdscript_addon*
    │       ├── *generator*.gd
    │       ├── plugin.cfg
    │       └── plugin.gd
    ├── LICENSE
    └── README.md

The main script of addons written in GDScript that have a plugin.cfg should be named plugin.gd.

└── *gdnative_addon*
    ├── demo
    │   └── addons
    │       └── *generator*
    │           ├── bin
    │           │   ├── *generator*.gdnlib
    │           │   └── *generator*.gdns
    │           ├── plugin.cfg
    │           └── plugin.gd
    ├── godot_cpp
    ├── src
    │   ├── gdlibrary.cpp
    │   ├── *generator*.cpp
    │   └── *generator*.h
    └── SConstruct

GDNative Addons

GDNative addons should follow a structure layed out in the official documentation. godot_cpp is a git submodule.

addons
├── *generator* -> addon_repos/gdnative_addon/demo/addons/generator
├── *gdscript_addon* -> addon_repos/gdscript_addon/addons/gdscript_addon

Small Utility Addons

└── *util_addon*
    ├── LICENSE
    ├── *util*.gd
    └── README.md

For small addons that don't have a plugin.cfg, the files can be put at the root of the addon's git repo. They can be added to the addons folder directly.

Autoloads

autoloads
└── game_state.gd

Autoload scenes or scripts should be put in the autoloads folder if they don't fit anywhere else.

Entry Scenes

game
├── game.gd
└── game.tscn

The game scene is the scene the player will spend most of his time in. It contains the gameplay section of the project.

main_menu
├── main_menu.gd
└── main_menu.tscn

The main menu is put into a folder. More menus like settings, credits and more can be added as well.

3D Specific Folders

Materials

materials
└── *stone*
    ├── albedo.png
    ├── normal.png
    ├── orm.png
    └── *stone*.material

In a 3D game the shared materials should be stored in sub-folders inside the materials folder. The textures should be named after the channels.

3D Models

models
└── *model*
    ├── *model*.blend
    ├── *model*.glb
    └── *model*.tscn

Models should have the native file made in a 3D modeling program and the exported Gltf2 file inside a sub-folder inside the models folder. The gltf file shoulb be used directly, but an inherited scene can be made if modifications are necessary.

Generic Game Objects

*object*
├── *special_object*
│   ├── *special_object*.tscn
│   ├── *special_object*.gd
│   ├── *sound*.ogg
│   └── *sprite*.png
├── *object*.tscn
├── *object*.gd
└── *objects*.gd

In most games there will be base game objects that are inherited to create more specialized ones. They should be put inside a folder with the base class at the root. Scenes inheriting that base should be put inside their own folders.

Assets like sounds, textures and scripts should be placed next to the scene file.

Often these objects will also need to be managed. The script responsible for that is put at the root of the objects folder.

Utils

utils
└── *texture_utils*.gd

Small utilities should be placed in the utils folder.

Godot-Specific

default_env.tres
icon.png
project.godot

Final Structure

addon_repos
├── *gdscript_addon*
│   ├── addons
│   │   └── *gdscript_addon*
│   │       ├── *generator*.gd
│   │       ├── plugin.cfg
│   │       └── plugin.gd
│   ├── LICENSE
│   └── README.md
└── *gdnative_addon*
    ├── demo
    │   └── addons
    │       └── *generator*
    │           ├── bin
    │           │   ├── *generator*.gdnlib
    │           │   └── *generator*.gdns
    │           ├── plugin.cfg
    │           └── plugin.gd
    ├── godot_cpp
    ├── src
    │   ├── gdlibrary.cpp
    │   ├── *generator*.cpp
    │   └── *generator*.h
    └── SConstruct
addons
├── *generator* -> addon_repos/gdnative_addon/demo/addons/generator
├── *gdscript_addon* -> addon_repos/gdscript_addon/addons/gdscript_addon
└── *util_addon*
    ├── LICENSE
    ├── *util*.gd
    └── README.md
autoloads
└── game_state.gd
game
├── game.gd
└── game.tscn
main_menu
├── main_menu.gd
└── main_menu.tscn
materials
└── *stone*
    ├── albedo.png
    ├── normal.png
    ├── orm.png
    └── *stone*.material
models
└── *model*
    ├── *model*.blend
    ├── *model*.glb
    └── *model*.tscn
*object*
├── *special_object*
│   ├── *special_object*.tscn
│   ├── *special_object*.gd
│   ├── *sound*.ogg
│   └── *sprite*.png
├── *object*.tscn
├── *object*.gd
└── *objects*.gd
utils
└── *texture_utils*.gd
default_env.tres
icon.png
project.godot