Skip to main content

Game Folder Structure - WIP

This is the guide on how to name things, where to put them, and over-all how we intend to organize the project files.

Considerations

The game project's file structure should achieve several key things:

  • Organize multiple repositories into folder structures that can co-exist.
    • One directory for the Godot project, a separate directory for the art source files that are created outside of the engine.
    • These directories will each be a Git repository and should conform to the hyphenated naming convention.
    • These names should make sense in and out of context, the top-level folder name should make sense when viewed as a tab in a Git GUI e.g:
      • project-example-game 
    • example-art-source
    • project-example-audio-source
  • project-game
Splitting the repositories avoids having to sync large amounts of irrelevant content for your role on the project:
  • Programmers / Dev Ops / Build Bots should only need to sync the project-example-game repository.
  • Artists / Animators can sync project-example-art-source along side the project-example-game repository.
  • Musicians / Foley Artists can sync project-example-audio-source along side the project-example-game repository.
The folder structures should work without using Git sub-modules, since thissub-modules addsadd a lot of complexity and confusion without really adding value. The folder structures in these directories should mimic each other 1:1 Tools and pipelines should be able to export / import content by simply swapping the root, e.g:
  • project-example-art-source/art_assets/characters/bouncer/bouncer_diffuse.main_character/main_character_diffuse.png
  • |--->project-example-game/art_assets/characters/bouncer/bouncer_diffuse.main_character/main_character_diffuse.png
Art source content from tools like Blender, Gimp, Krita, etc... should be kept in the art-source repo Music production files for a DAW should be kept in the audio-source repo Ship-able game content should be the only thing going into the Godot project resource folder in the game repo. Art source content from tools like Blender, Gimp, Krita, etc... should be kept in the art-source repo. Music production files for a DAW should be kept in the audio-source repo.

Naming Conventions

    The repositories should use lowercase-hyphenated-case

    Files and folders should use snake_case unless otherwise required by third-party tools or conventions for the specific file e.g. README.md

    No spaces in file names.

    Compromises

    No folder structure is perfect, but this structure should lead to the fewest problems. Here is a list of known compromises we've decided to accept:

    Top level folder names repeat,repeat the game's name even though they are already inside of a top-level folder named after the game:

    example
    • project-example-game
    example-art-source project-example-audio-source project-game

     

    There'sWhile athis fairintroduces bitredundancy, of redundancy. Foldersfolders don't cost anything, so this is okay.

    Some intermediate sub-folders are empty and seem to be useless, but they keep the hierarchies between directories in perfect sync. For instance, project-example-art-source may never end up with content directly inside of it, most if not all content will be inside of its first sub-folder art_assets  i.e. project-example-art-source/art_assets/ This is on purpose, since it ensures the game content is at the same hierarchical indentation level to the source contentcontent, making pipelines and paths extremely easy to work with,with; just swap the root and you're done!

    You aught have a directory on your computer for "BUGJam" projects. You can place this anywhere on your computer with a few considerations:

      Do not sync this directory with OneDrive, iCloud, Google Drive, or any other backup tool, this will break the Git repositories inside the folder since these services interfere with Git. Don't nest the folder too deep so you avoid file name length issues:
        Good (Windows style path): C:\Users\xgreer\Projects\BUGJam Good (MacOS / Linux): /home/xgreer/Projects/BUGJam Bad: /home/xgreer/Projects/Extra Projects/Seattle Blender User Group/Game Projects/BUGJam

        Within thisthe BUGJam directory there will be folders for each BUGJam project. For a project called 'ProjectGenesis' we will have a project folder called 'project'genesis' that serves as the root for all content necessary to develop the game.

        File Tree Structure Example

        BUGJam <!-- Top-level folder for the entire studio. -->
├── logo <!-- Example of other stuff for the studio that is not directly related to the game. -->
└── projectgenesis <!-- Top-level folder for the game. -->
  ├── project-genesis-art-source <!-- Repository for large art content, stored outside of the Godot project. -->
  │ └── art_assets
  │   └── characters
  │     ├── bouncermain_character
  │     │ ├── animations
  │     │ │ └── idle.blend
  │     │ ├── bouncer_diffuse.main_character_diffuse.png
  │     │ └── bouncer_rig.main_character_rig.blend
  │     └── gentlemanmonster
  │       ├── animations
  │       │ └── walk.blend
  │       ├── gentleman_diffuse.monster_diffuse.png
  │       └── gentleman_rig.monster_rig.blend
  ├── project-genesis-audio-source <!-- Repository for large audio content, stored outside of the Godot project. -->
  │ └── audio_assets
  │   ├── dialogue
  │   ├── music
  │   └── sound_effects
  └── project-genesis-game <!-- This is the Godot root for resources: 'res://' -->
    ├── addons <!-- Godot plugins -->
    ├── art_assets <!-- A 1:1 mirrored file structure with the project-genesis-art-source repository. -->
    │ ├── characters
    │ │ ├── bouncer
    │ │ │ ├── bouncer.glb <!-- Model file -->
    │ │ │ ├── bouncer.glb.import <!-- Import settings and UID -->
    │ │ │ └── bouncer_diffuse.png
    │ │ └── gentleman
    │ │   ├── gentleman_0.glb <!-- Model file -->
    │ │   ├── gentleman_0.glb.import <!-- Import settings and UID -->
    │ │   ├── gentleman_1.glb
    │ │   ├── gentleman_1.glb.import
    │ │   ├── gentleman_2.glb
    │ │   ├── gentleman_2.glb.import
    │ │   ├── gentleman_3.glb
    │ │   ├── gentleman_3.glb.import
    │ │   ├── gentleman_color_mask.png
    │ │   ├── gentleman_color_mask.png.import
    │ │   ├── gentleman_diffuse.png <!-- Texture -->
    │ │   ├── gentleman_diffuse.png.import <!-- Import settings and UID -->
    │ │   └── m_gentleman.tres <!-- Material -->
    │ ├── common
    │ │ └── textures
    │ │   └── blue_noise_64.png
    │ ├── environment
    │ │ └── wall.glb
    │ └── puzzle_elements <!-- Core puzzle elements for designing levels. -->
    │   ├── cake
    │   │ └── [...]
    │   ├── door
    │   │ └── [...]
    │   └── door
    │     └── [...]
    ├── audio_assets
    │ ├── dialogue
    │ ├── music
    │ └── sound_effects
    ├── entities <!-- Complete assets that are ready to drag and drop into a level. -->
    │ ├── characters
    │ │ ├── bouncer.tscn
    │ │ └── gentleman.tscn
    │ ├── environment <!-- Stuff without direct gameplay mechanics. -->
    │ │ ├── lamp_post.tscn
    │ │ ├── rock.tscn
    │ │ └── wall.tscn
    │ ├── level_packs <!-- Data assets that organize levels into packs. -->
    │ │ ├── christmas_levels.gd
    │ │ ├── world1.gd
    │ │ └── world2.gd
    │ └── puzzle_elements <!-- Core puzzle elements for designing levels. -->
    │   ├── button.tscn
    │   ├── cake.tscn
    │   ├── exit_door.tscn
    │   ├── player_start.tscn
    │   └── pusher.tscn
    ├── levels <!-- Playable levels. -->
    │ ├── intro_stairs.tscn
    │ ├── intro_treadmill.tscn
    │ └── intro_welcome_to_the_club.tscn
    ├── scripts
    │ └── player.gd
    ├── shaders
    │ └── iris.gdshader
    ├── ui
    │ └── icons.png
    ├── .gitignore
    ├── icon.png
    ├── project.godot <!-- Main Godot project file -->
    └── README.md
        Back to top