Create a style guide for project organization

[aaronfranke]

Currently there is no style guide for how to structure Godot projects outside of the contents of the scripts. This should include what is encouraged, what is allowed, and what is discouraged (and most importantly, how should the demo projects be organized).

When created, this should probably be placed in project workflow.

Some topics that could be included:

Nodes:

• Casing of nodes. PascalCase? Something else? The current demo projects are fairly mixed EDIT: have all been refactored to PascalCase node names due to a general consensus below and also because that is how Godot cases newly created nodes by default.

• How often should nodes be grouped together? If there are 30 boxes in a scene, would it make sense to make all of them a child of "Boxes", or maybe group them like "Boxes/Group1" and include several boxes that are next to each other under the same parent?

• Should Node children be added with their own scripts to add behavior, like "components", or is this way of abstracting functionality discouraged?

Files/folders:

• Casing of folders. Most of the demo projects use snake_case for this.

• Casing of files. This one's a bit more tricky than the above:

  • What about for C# projects, where it is generally expected that the file name should match the class name? Should MyClass be in MyClass.cs or my_class.cs? If the former, should C# projects also use PascalCase for folders and other files to be consistent?

  • If the above, should GDScript files also be this way to be consistent with C# files?

• File hierarchy and organization.

  • I propose object-first, which would look like this:

    player/
        player.gd
        player.png
        player.tscn
    enemy/
        enemy.gd
        enemy.png
        enemy.tscn

• When should folders be used at all? Some demo projects have a completely flat directory structure, others (mostly the larger projects) have many subfolders.

  • How many related files should be allowed to sit next to each other without being in their own folder? If you only have player.tscn and player.gd, does that deserve a player folder?

  • If a project has assets from third-party sources, how should they be indicated to be so?

  • The project I am working on with my brother contains an "Assets" folder for all the stuff we make, and we still have around 30 items in the project's root folder including things like the icon, config files, helper scripts, git stuff, readme/license, C# stuff, translation files, and native libraries, most of which can't be moved to subfolders. Should an "assets" folder containing "as much user-created stuff as possible" be encouraged for large projects?

[Calinou]

Casing of nodes. PascalCase? Something else? The current demo projects are fairly mixed.

Definitely go for PascalCase, in my experience :slightly_smiling_face:

As for animation names, I use snake_case personally (just like file names).

[Shatur]

Casing of nodes. PascalCase? Something else? The current demo projects are fairly mixed.

Godot by default creates nodes in PascalCase, but when creating collisions, it creates a StaticBody called static_collision. It's confusing.

Casing of folders. Most of the demo projects use snake_case for this. Casing of files. This one's a bit more tricky than the above: What about for C# projects, where it is generally expected that the file name should match the class name? Should MyClass be in MyClass.cs or my_class.cs? If the former, should C# projects also use PascalCase for folders and other files to be consistent?

Godot creates snake_case files by default (default_env.tres, icon.png), but yes, it’s not very clear what to do with the classes.

[lboklin]

Over the years I've arrived at some patterns that are more common (or recommended) than others that I use myself:

• Directory names and resource file names in snake_case/snake_case.{tres,png}
• Script and scene file names in PascalCase.{tscn,gd} - these belong together so they should match style
• When it comes to directory hierarchies I haven't seen any consistency, and 2-dimensional categorisation of relational objects is kind of an unsolved problem.
  • Personally I try to categorise by relevancy and logical sub-typing: Player input-specific things go in character/player/ because a player will in most games always control a character but a character will not always be a player - this is not always based on actual inheritance (I use node dependencies myself). I also try to keep things tidy when there are lots of resource files by moving them into a local res subdirectory (character/res/{model.glb,decal.png,skin_mat.tres}).
  • I've seen/read that
  • some people separate resources from scenes and scripts
  • some keep scripts separate from everything else
  • some organise everything by file/resource type (scenes, src/scripts, textures, materials, etc)
  • some base their directory hierarchies entirely based on scenes with some common resources separated out.

I feel that the naming scheme has become rather clear to me (even though the official demos are very bad at consistency). What I miss the most is a the-one-true-hierarchy guideline. Making a mess for yourself is a serious bother and if you decide to rearrange things down the line it will cause headaches in the revision history like when you want to check out a certain file from a certain revision but it changed paths at some point.

[winston-yallow]

some people separate resources from scenes and scripts

I try to avoid this. In most projects I keep all necessary files for an object in a dedicated folder (for example a player folder containing Player.{gd,tscn,obj}). The only situation where I seperated resources was for audio files. I had a pool of 20 audio files that would be used by nearly every object. I put them into their own sounds directory. I only do this if the resources are shared by many objects (and if these objects should always use the same resource). Beside this exception I think placing them in the object folder is much better. It also allows for easier reuse of the object in other projects.

[Shatur]

Script and scene file names in PascalCase.{tscn,gd} - these belong together so they should match style

I agree with you about this, but in this case folders and resources in snake_case has no sense as for me. I would suggest using CamelCase for them too.

I propose object-first

Beside this exception I think placing them in the object folder is much better. It also allows for easier reuse of the object in other projects.

Personally I try to categorise by relevancy and logical sub-typing

I agree. I once tried to sort by type and it was a headache :)

[NathanLovato]

Creating a folder structure style guide is trickier than the GDScript one, to me. There's no one-size-fits-them-all approach, or general structure that would be inherently better than others. We've actually already had an issue and detailed conversation about that and couldn't reach a consensus.

For naming it's quite simple to me as Godot provides us with some defaults. Nodes, which are types, use PascalCase, so tscn and gdscript files should use PascalCase.

When it comes to the folder structure, the issue is that the larger the project, the more you end up reusing assets, and the more it makes sense to split data files (sprites, meshes, audio, text...) from your classes. It really depends on the game. And if possible, keeping related files and scripts together is nice as it makes your dependencies and code structure clearer.

I'm personally not leaning towards anything in particular. At GDQuest, we use assets/ and src/ mainly because our projects can scale. But I like the idea of trying to keep related files together.

When it comes to the official demos, the only thing I wouldn't do is keep all the files in the res:// directory, because a beginner learning from the demos may reproduce that, and get into a bad habit.

[NathanLovato]

Ah, I would also treat node structure inside a scene as a separate topic. With signals, nesting scenes, instancing scenes at runtime, patterns... there's quite a lot to say on the topic. It's a little more complex to have a strict style guide there again, and we already have some guides on the matter in the Best Practices section of the official docs.

See http://docs.godotengine.org/en/latest/getting_started/workflow/index.html, there's a lot of content there

[nathanfranke]

Resources should not be PascalCase. My project currently uses snake_case (which I prefer), but we could also use camelCase

• Godot projects come prepacked with defaultenv.tres and icon.png. We should change defaultenv.tres to default_environment.tres. (Thanks for the correction, Aaron)
• Godot projects come prepacked with default_env.tres and icon.png, which are already snake_case. I think we should still think about changing default_env.tres to environment.tres since the user is able (And probably should 😊) change it
• This can distinguish all these PascalCase things from resources, which should be kept separately anyway. The idea is
  • Player (folder)
  • Sprites (folder)
    • player_gun.png
    • player_sprite_sheet.png
    • player_death_effect.png
  • Player.tscn
  • Player.gd
• Even though .dae is recognized as a scene, it should still be snake_case because it is not meant to be edited within Godot

[Shatur]

@nathanwfranke, But why use snake_case? If the scripts and scenes are in PascalCase, then why not use it for all project files for consistency?

[aaronfranke]

@Shatur Because the default project files, as well as Godot's source code, use snake_case.

[Calinou]

@Shatur Godot's source code itself uses PascalCase for class names, yet all file names use snake_case.

[Shatur]

But does it make sense to use snake_case for other of game files too? Using PascalCase for some files and snake_case for others does not look consistent as for me :(

[aaronfranke]

@Shatur There are arguments for either case, which is why this issue is open - the argument in favor of PascalCase for scenes is because Godot's default name when saving a scene with Foo as a root node is Foo.tscn, and for scripts, C# generally expects class Player to be in Player.cs, so the same argument can be made for GDScript, or there can be an argument just for consistency's sake.

[Shatur]

@aaronfranke, sounds reasonable. What if use CamelCase for resources too? Yes, Godot creates project with the default files in snake_case but I do not see any reason for it.

[Duroxxigar]

My vote is for PascalCase for two reasons.

1. Because Nodes should be PascalCase.
2. C# script names should be PascalCase, so it is more consistent in that regard.

[fire]

Regarding your question of the "Assets" folder. It should be discouraged.

Reasoning is the same as in ue4.

2.6 Do Not Create Folders Called Assets or AssetTypes 2.6.1 Creating a folder named Assets is redundant. All assets are assets. 2.6.2 Creating a folder named Meshes, Textures, or Materials is redundant. # All asset names are named with their asset type in mind. These folders offer only redundant information and the use of these folders can easily be replaced with the robust and easy to use filtering system the Content Browser provides.

https://github.com/Allar/ue4-style-guide#262-creating-a-folder-named-meshes-textures-or-materials-is-redundant-

[fire]

If a project has assets from third-party sources, how should they be indicated to be so?

UE4 styleguide from Allar does it by having a top level folder. The third party resource path doesn't change. It keeps its own top level folder. The benefit is now you can compose different projects from the asset library and remove things, but the asset path doesn't need to change.

https://github.com/Allar/ue4-style-guide#22-use-a-top-level-folder-for-project-specific-assets-

The Allar guide has like 6 subsections on this topic.

[Shatur]

@fire, agree, I using something similar according to the UE4 guide. Except prefixes, because it not needed for Godot.