Establish a consistent folder/file layout within demo project directories

[LikeLakers2]

Right now it seems like the demo projects are all over the place with how they're laid out, and what file types are used. As an example of some issues in layout I see:

• Some demos with relatively few files will store the files in the root of the project, which is okay. But others that also have relatively few files will sort them into directories. This also applies to projects who have large amounts of files.

• A couple demos appear to make directories specifically for one type of object, and will only store that object's *.gd and *.tscn file in there (they will over-categorize). Most others will generalize the content into one directory (i.e. graphics going into res://art/ instead of a subdirectory of res://art/; they will over-generalize).

• Some demos use *.scn instead of *.tscn. Some will use *.material or *.mesh instead of *.tres.

• Some demos will include the default_*.tres files, while others will not.

• The naming scheme of both folders and files is just not consistent at all. Some use snake_case, some use CamelCase, some opt not to use either and just put wordstogether. I notice that networking/multiplayer_bomber even seems to mix and match.

• To add to this, files that are used for non-engine purposes (such as 2d/dodge_the_creeps/attributions.txt) also don't seem to have a consistent naming scheme.

• The plugin demos should be a full project rather than just the project folder, in order to maintain consistency instead of arbitrarily requiring the user to have to figure out that there's a step 2 (Installing) to those plugin examples.

• And finally, I noticed that visual_script/multitouch_view uses a GDScript file in a project that, in my opinion, should be entirely VisualScript. Perhaps that's nitpicking, but I see it as an inconsistency I should note for the sake of this issue.

All of this, at least to me, adds up to a demo project repository that just seems harsh to navigate. For every new demo project I explore, I would have to figure out what sort of layout that demo project is using. And while it takes maybe two to three seconds for me, I imagine for beginners it might take even longer.

[pwab]

I totally agree with all your points.

Most others will generalize the content into one directory (i.e. graphics going into res://art/ instead of a subdirectory of res://art/).

And this is bad practise. We should really avoid this.

Some demos use *.scn instead of *.tscn. Some will use *.material or *.mesh instead of *.tres.

See also #10

If we decide on the reorganisation of the demo project structures we could do that in parallel to #251.

[LikeLakers2]

Most others will generalize the content into one directory (i.e. graphics going into res://art/ instead of a subdirectory of res://art/).

And this is bad practise. We should really avoid this.

I get the feeling that part was misunderstood. I suppose I should have been more specific: that part was highlighting the problem of over-generalization vs. over-categorization that seems to plague much of this repository. By that I mean, some really do just put all their assets in one folder (over-generalization; i.e. all sprites, regardless of meaning, go into res://sprites/), while others split down the project into too many folders (over-categorization; i.e. every object in a demo, with its corresponding *.gd and *.tscn files, has it's own folder dedicated to those files).

Over-generalization is bad in my eyes because it makes it hard to find many related assets (i.e. you have to go to res://scenes/ for the *.tscn file, and then to res://scripts/ for the *.gd file). Over-categorization, on the other hand, is also bad to me as it means having the object's name twice in the path. If you ever have to rename that object, you have to rename both the folder and the files inside for it to stay consistent -- not to mention having to change all the references to that object's path!

[NathanLovato]

Over-categorization, on the other hand, is also bad to me as it means having the object's name twice in the path.

It's not categorizing assets, it's just grouping related assets in a folder. Yes, when there's only two that's a bit of a pain. Built-in scripts can help there but they're less flexible than .gd files. At least in 3.0: you've got to close the script to save it, they have weird names, and you can't open or edit the script without opening the parent scene in the editor first.

Updating paths won't be as much of an issue from 3.1 with the class_name keyword. Aside from utility classes shared in your project and that you want to access by absolute path, you can already use relative paths to access resources, or export(PackedScene) - Godot update dependencies between scenes when you move or rename files in that case.

Different projects require different folder structures, so I don't think you should try to make all demos work the same. In general, I like to have related assets together in a folder, in a tree that reflects your project's architecture. And if at some point you realize you need to share assets between systems, move them to a shared folder up the tree.

I really like the clean structure you get with built-in script files, but again for now I'm not sure it's a good idea to use them: when something crashes in the game you can't jump to the line at fault straight away at the moment, etc.

[LikeLakers2]

It's not categorizing assets, it's just grouping related assets in a folder.

That's quite literally the definition of categorize, though: https://www.merriam-webster.com/dictionary/categorize

Yes, when there's only two that's a bit of a pain. Built-in scripts can help there but they're less flexible than .gd files.

Personally, I'm unsure where you got the idea that I was talking about using built-in scripts. Regardless, I'll try to reply to what I think you're meaning.

Utilizing built-in scripts isn't our only option. For example, you could simply move them up a folder. Imagine you had a object folder structure similar to this (excluding res:// here for simplicity):

entities/
  Enemy/
    Enemy.gd
    Enemy.tscn
  NPC/
    NPC.gd
    NPC.tscn
  Player/
    Player.gd
    Player.png
    Player.tscn

You could move all the files up a folder, and be left with this:

entities/
  Enemy.gd
  Enemy.tscn
  NPC.gd
  NPC.tscn
  Player.gd
  Player.png
  Player.tscn

The Godot source utilizes this structure all over its codebase, with two related .h and .cpp files in the same folder as many other .h and .cpp files of the same category. For example, all the editor code is contained neatly under editor/.

Updating paths won't be as much of an issue from 3.1 with the class_name keyword.

True, however that now makes me wonder... once class names get introduced into this demo repository, won't it be that much harder to figure out where a certain class is in the folder/file structure, since you won't have a path to look at anymore?

Different projects require different folder structures, so I don't think you should try to make all demos work the same.

Disagree. In non-demo projects, I don't think having a universally common structure is as necessary. However in this repository, which is (from what I can tell) designed to show new people what sort of things can be done in Godot, it's important that a common layout be considered. New users should be able to enter any project and, after the first project or two, be able to understand where a certain file for an object is most likely stored. That's what this issue is about.

Having a common layout also somewhat simplifies bug-fixing and updating efforts. Imagine if you were tasked with fixing someone else's code -- if their style or their folder structure was wildly different from yours, wouldn't that make it all the harder to fix? Referring back to Godot again: Godot's source code and documentation are two good examples of a common layout: PRs are all kept to a consistent coding style using clang-format, and documentation is kept to a (nearly) consistent writing style via the doc writing guidelines. Wouldn't that make maintaining the code and documentation all the easier, since they're in a consistent format?

Now I ask you, why can't we apply that same line of thinking (keep things consistent) to the demo projects repository?

[NathanLovato]

Now I ask you, why can't we apply that same line of thinking (keep things consistent) to the demo projects repository?

You got the wrong idea, I agree with the diagnostic 😄, I was just trying to steer the conversation towards solutions / how we could organize files. To me, to start with, it could be as simple as:

• group related scenes, scripts and resources in the same folder
• use simple names, and plain english
• snake_case for folders to avoid whitespace in the file paths, PascalCase for nodes and related scripts (as it's Godot's default behavior when you generate scripts and nodes)
• Try to follow a flat directory structure. I've definitely had a tendency to split things too much for a little while, something I'm trying to correct in more recent projects.

I suggested we could follow guidelines before 3.0. At the time Juan disagreed because he considered these demos to be quick (and dirty) examples of what you can do with Godot - not educational material. That's why I focused my work on new demos since then.

There's no guidelines as far as which demos should land here, no requirements in terms of quality... some show practices that will lead any programming beginner to produce a lot of bugs if they try to build their own projects with similar logic.

Regarding built-in scripts, I was just saying they could be nice, as they help make the directories really clean. And yeah sure, putting more files together in one folder is fine.

be able to understand where a certain file for an object is most likely stored

There might be a slight misunderstanding on what we mean by "same structure": to me "same structure" = standardized folder tree. It's what some web frameworks tend to do, inviting you to use starting templates. See how ruby on rails etc. work. If by "same structure" you just mean some simple guidelines about using clean, consistent names, a flat file structure when it makes sense, we're on the same page.

[LikeLakers2]

You got the wrong idea, I agree with the diagnostic 😄

Ah, my bad! The implication I got from your wording was that you disagreed with me, and thus I felt a need to defend my stance. Sorry if I seemed a little aggressive. 😅 Sometimes I'm just really bad with words, and it tends to show.

That being said, I reread your original reply. I think I agree with it wholeheartedly now. However, out of all the things I replied with, I am still curious about what introducing class_name stuff to this repository will do to the learning experience of a new user.

To me, to start with, it could be as simple as:

• group related scenes, scripts and resources in the same folder
• use simple names, and plain english
• snake_case for folders to avoid whitespace in the file paths, PascalCase for nodes and related scripts (as it's Godot's default behavior when you generate scripts and nodes)
• Try to follow a flat directory structure. I've definitely had a tendency to split things too much for a little while, something I'm trying to correct in more recent projects.

These are all very good starting points. Though personally I would go full snake_case for both folders and files, as godot uses snake_case for its own default files such as default_env.tres.

If by "same structure" you just mean some simple guidelines about using clean, consistent names, a flat file structure when it makes sense, we're on the same page.

That's actually exactly what I meant.

[NathanLovato]

However, out of all the things I replied with, I am still curious about what introducing class_name stuff to this repository will do to the learning experience of a new user.

Can't you Ctrl Click on the class name to jump to the file/definition? By the time people get to the demos, I think we should assume they went through the intro to gdscript - you need some background on nodes, signals, virtual methods like _ready or _process to make sense of them. And class_name is covered both in the getting started section and in the gdscript guide.

Now it's not available in stable yet and it's optional. The demos will likely need some changes after 3.1 comes out - to show new features instead of old workflows. We can think about it later.

[LikeLakers2]

Can't you Ctrl Click on the class name to jump to the file/definition?

Ctrl-clicking isn't exactly reliable in my eyes. When you hold Ctrl in the script editor, everything, including comments and variable names, all become clickable -- but only some of it will actually do anything when you ctrl-click on them. Additionally, there's nothing in the GUI that says "You can ctrl-click certain things to jump to their file/definition".

It's not that I disagree with the sentiment, but the way ctrl-clicking is (at least on my usual build, which is dated maybe about a month back; as well as on another build I occasionally test on dated about a week ago), I imagine it might come across as a useless function if a user doesn't already know you can only click on certain things.

Assuming they even know they can ctrl-click at all -- I searched in the docs, and I didn't find anything relating to ctrl-clicking: http://docs.godotengine.org/en/latest/search.html?q=ctrl+click&check_keywords=yes&area=default

That being said, yes, you can ctrl-click. But I wouldn't personally rely on people knowing about that. Not with how ctrl-clicking is right now, at least.

[LikeLakers2]

Though now that I know class_name is being shown off in the GDScript intro (I haven't looked at the GDScript intro in a long while, so forgive me for not knowing), I don't have as much of a concern about using class_name in the demo projects.

[fire]

If you guys like, I can do the grunt work of adapting the various projects to a standard.

I don't mind which one, but here's one I made for reference https://gist.github.com/fire/f3981ad4a48ccae08224d3b82b9f95bc Just decide on a structure.

[aaronfranke]

Thank you for writing this list of problems, I've been referencing it over time as I work on improving the demo projects repository. Here's all of the points and the current status.

• Some demos with relatively few files will store the files in the root of the project, which is okay. But others that also have relatively few files will sort them into directories. This also applies to projects who have large amounts of files.

Most of the demos which are big enough to need organizing are now organized.

• A couple demos appear to make directories specifically for one type of object, and will only store that object's *.gd and *.tscn file in there (they will over-categorize). Most others will generalize the content into one directory (i.e. graphics going into res://art/ instead of a subdirectory of res://art/; they will over-generalize).

This is tracked by godotengine/godot-docs#3104, but I've also made some changes already.

• Some demos use *.scn instead of *.tscn. Some will use *.material or *.mesh instead of *.tres.

As of #444, there are no more .scn or .material files in any of the demo projects! However, I haven't converted .mesh files because, when saved as .tres, these files are just a list of numbers and aren't actually meaningful to read or track changes in.

This was also partially tracked by #10.

• Some demos will include the default_*.tres files, while others will not.

Is it considered good practice to remove these files if you don't need them? EDIT: Fixed by #488

• The naming scheme of both folders and files is just not consistent at all. Some use snake_case, some use CamelCase, some opt not to use either and just put wordstogether. I notice that networking/multiplayer_bomber even seems to mix and match.

This is tracked by godotengine/godot-docs#3104

• To add to this, files that are used for non-engine purposes (such as 2d/dodge_the_creeps/attributions.txt) also don't seem to have a consistent naming scheme.

As of #446, 2d/dodge_the_creeps/attributions.txt has been replaced by a Licenses section at the bottom of the new README file (which most demos now have as of #432).

• The plugin demos should be a full project rather than just the project folder, in order to maintain consistency instead of arbitrarily requiring the user to have to figure out that there's a step 2 (Installing) to those plugin examples.

This has been changed as of #453.

• And finally, I noticed that visual_script/multitouch_view uses a GDScript file in a project that, in my opinion, should be entirely VisualScript. Perhaps that's nitpicking, but I see it as an inconsistency I should note for the sake of this issue.

I tried to convert it, but I ran into an issue. Dictionary.erase has no white arrows going in or out of it. How are you supposed to execute it and erase dictionary items in VisualScript?