Setting a clear design goal for the demo projects

[NathanLovato]

The code and quality of the demos in this repository vary a lot. Some are done with quick and dirty code, some have nice graphics, some have programmer art, and a lot teach poor programming practices when working with Godot.

At the last GodotCon, we talked with @akien-mga and @reduz about setting a clear design target for these demos, in the hope to bring them to a higher quality standard. We'd like to contribute (or keep contributing) towards that with @johnnygossdev, @razcore-art, and @henriiquecampos

To me, the goals of the demos are to:

• Showcase engine features, that is to say, give a sense for what Godot can do. In that sense, the demos are a communication asset and may contribute to giving a positive or a negative image of the engine.
• Help people learn these features. So the demos have an educational purpose.

Users can get a feel for Godot's power with these demos. If an experienced developer may see the value of a feature showcased through code, a casual user or hobbyist may wrongly feel that Godot sucks because some of the demos are really bare-bones.

Teaching-wise, I'd argue that a lot of demos offer counter-productive examples of how you're meant to use Godot. That is due in particular to the fact that a lot of demos were coded to "just work".

Below is a proposal to set some guidelines for this repository, start to frame a target to collectively move towards, and help increase the quality of the demos here. We would also like to contribute demos as part of the GDQuest project, with the team.

Design proposal

The demos' design

Each demo should clearly focus on one feature. The scope of the feature can be one node, one game mechanic, or one system.

For example:

1. KinematicBody2D, make a simple game with a side-view platform character, and another scene with top-down movement, and obstacles, including moving ones.
2. Touch gestures, a demo that shows how to detect a gesture, generate an input event from that, and consume it in another node.
3. User interface anchors and margins, showing the effect of various layout and anchor menu options.

To make this clearer, the idea is to have a clearer scope for the demos. We could avoid having tiny demos with several lines of code, that leave some more insights to be desired, or entire game projects that should rather be in a dedicated repository.

The target

Update existing demos to:

• Show good practices when it comes to Godot and game creation. Starting with following the official GDScript guidelines
• Make the demos feel and look both better and more consistent.

Having an art direction, or a visual language

We'd like to suggest using a simple, yet consistent visual language for the demos that don't have a game world and art of their own. An art style that:

1. Make the visuals appealing, yet fast to make.
2. Make the art creation process accessible to non-artists or unexperienced artists who'd like to contribute.
3. Use vector whenever possible so the assets are git-friendly.

@henriiquecampos is working on a style guide for that, based on the work he did with @razcore-art on our beginner platformer course

Here is an example of how that could look:

Proof of concept

@johnnygossdev rewrote the 2D platformer demo, with @razcore-art and I as reviewers, as an example for the kind of programming practices we'd like to promote, and the kind of work we'd like to contribute. You can download and inspect it here: https://github.com/GDQuest/godot-demo-projects-remake

We're here to answer any questions you might have about this proposal, and we're leaving this for the community to review and to discuss.

I'll add a final precision: we're talking about setting a goal and guidelines, not hard rules. Like with the docs and programming guidelines before, we're making this proposal in the hope to be able to gradually remake or improve the demos, but also to help make reviews clearer and faster.

Without that, saying which contributions are wanted or not, or what code is good or not is up to the reviewer and can be arbitrary: we all have our own taste and experience as devs and designers, after all.

Discussion and critiques are more than welcome!

[NathanLovato]

Ping @johnnygossdev @razcore-art @henriiquecampos, if you want to join the discussion.

[aaronfranke]

See also: godotengine/godot-docs#3104

[eon-s]

I agree that the scope of the official demos must be focused on a particular need, maybe it can be 1-1 with tutorials shown on the documentation (which may need to separate basic from advanced/complete tutorials).

[eon-s]

And about demos to showcase features, these can be a bit more complete or cover many related aspects (like a demo for joints, for example), showcasing engine features will be mostly code-free so complexity will be reduced in that aspect (considering the simplicity of the node system).

On both cases (tutorials and showcase), adding comments as labels on a scene may be needed to explain what happens in the editor (particular resource/material or node settings, tree organization, etc.).

[fire]

I can help with demos that touch 3d.

[aaronfranke]

I've recently been working on improving code quality in the demos while I test and update them to 3.1, including conformity to the GDScript style guide. Hopefully we will have a much better starting point in terms of existing quality if/when we decide to refactor the demos to meet goals we decide upon here.

Agree completely with the goal of showcasing features and helping people learn these features. As part of this, I think #241 would be really useful. A few demos, but far from all, already have these.

Having an art direction, or a visual language

That art style is nice, and I think it would be useful in some places, but I personally would prefer for demo projects that are meant to act as "fully-featured" games to look "finished" (even if you'd get bored or beat the whole thing in under 1 minute). For example, I would consider the Platformer 2D demo to be "fully-featured", and I would not wish for it to have such a simplistic art style, the current one is great.

For things that do use this art style, I 100% agree about using SVG files where appropriate.

I took a look at the Platformer 2D demo remake, and overall it's great, though it's missing some things. The current demo has a section with four slopes of different angles right next to each other which showcases movement over slopes (as shown here), and this is not present in the remake. The remake has separate assets/src folders, either way is fine to me really but this certainly needs to be discussed (and why are files and folders capitalized inside src but not in assets?). The remake also lacks support for multiple resolutions and movement is way too fast in my opinion (though this is getting off-topic a bit, this kind of discussion can wait for later and be done in a PR).

@eon-s I think it's fine for demos to showcase multiple features at once. For example, when it comes to joints, Truck Town already has that, but it primarily showcases vehicle mechanics. So I think we don't need a dedicated demo for joints as long as we have Truck Town, etc.

[securas]

I argue for a pixel art demo... ;)

[Feniks-Gaming]

I think in addition to this once we have a demos done we should set up wiki page that can link each demo to feature shown. So when I look for "joints in godot demo" I can be linked to Truck town otherwise users must spend hours searching each demo project

[NathanLovato]

I personally would prefer for demo projects that are meant to act as "fully-featured" games to look "finished"

Yes, that's the idea. Having a consistent visual language for the simpler or more technical demos, the ones that focus on exploring and teaching one engine feature.

For complete games, it's a different story: each game can have its own concept, mechanic, art, game world, story... but in this repo, we're talking about 3 or maybe 4 demos out of dozens at the moment.

I'd also like to suggest having something like the 2D platformer, and generally, demos that grow into complete game projects some of these projects in dedicated repositories, where it can be easier for people to contribute, where we could have a dedicated issue tracker... it's a matter of size and scope. For now, I'm mainly thinking about the 2D and 3D platformers in that regard. It's just a suggestion.

On the Platformer 2D demo remake

We're going to make the changes. I'll open issues on our repo and we'll improve the demo before opening a PR.

The remake has separate assets/src folders, either way is fine to me really but this certainly needs to be discussed

Same for me. As I explained in the dedicated issue, we use that because it scales easily into larger projects, it's generic so you easily find files when exploring new projects. With that, we could also tell the last artist we hired they could work with the assets folder and ignore the rest.

why are files and folders capitalized inside src but not in assets?

It's source code vs assets. For files, we follow Godot's defaults: scenes and scripts are PascalCase by default, but not files like resources, that we put in the assets directory.

Regarding PascalCase in the src/ directory, it's that we treat this as part of our code structure and as class groups or categories in a sense. But again, I don't mind changing any of that. It's mostly conventions.

Even the split between assets and src is arbitrary at times. In an older discussion on folder and file structures, @cbscribe argued that the optimal structure depends on the project and its size. The larger it gets, the more assets may get disconnected from code files (e.g. in 3D, you may reuse props in completely unrelated scenes to save time), and so the more flexibility you gain from having that kind of directory structure.

Anyway, we can discuss that in details in the issue you opened: godotengine/godot-docs#3104

I'm personally open to about everything, as long as we piggyback on Godot's defaults when it comes to naming files - to save time, mostly.

[eon-s]

I don't agree with separating assets and source since Godot scene structure does not fit the system, and is easier to understand if you separate "physically" the components on the project by where are they used (is also better for teamwork organization on mid size projects).

Also it must be reflected on the documentation because is not the recommended project organization.

[henriiquecampos]

@aaronfranke

I personally would prefer for demo projects that are meant to act as "fully-featured" games to look "finished"

This takes a lot of time from who is creating the demo. And it can also shift the focus of the demo, finished looking assets have their own design which can be distracting.

I think we can use some art assets as defaults, not standards. What I mean is: to achieve fast prototyping demos that also look good you can use assets from this art repository. If you have finished looking assets you can use them subject to the reviewer's approval. The ones in the repository are pre-approved ones, and we can work with the community to improve this library so we always have a place to go for good looking, pre-approved assets, and take away the overhead of making or searching for "finished looking" assets from the contributor.

[cbscribe]

Maybe there could be a default asset set for demo writers to use, but this seems unmanageable. If I'm doing a demo on TileMap, for example, I may want a tile set that demonstrates a particular feature (simple tiles, autotile, iso, etc) and not one that has extra content that confuses the issue. I don't know how we'd cover all the possibilities.

Consistency is good, but I would not want to see demos that end up obscuring the intended subject by including a lot of extra code/objects/animations/etc. Demos should have very low levels of polish (unless it's a demo on polish) because they're trying to communicate a specific message, not emulate a completed game.

[nrcionline]

I agree (that projects should have a single focus) when the goal is to teach a specific skill. The exception for me would be having at least one project that demonstrates good practices for tying it all together (to see good practice for having various parts work together). Even better in this case would be to see the same/similar code from smaller projects reused into a comprehensive project.

I've used Godot for about a month now. I integrated the bomber demo (for its multiplayer code) with an online tutorial. I got it to work, but I'm not sure what best practices might be to keep the multiplayer (network) code separate from the game code. I suppose there is a learning curve for everything.

Maybe there could be a default asset set for demo writers to use, but this seems unmanageable. If I'm doing a demo on TileMap, for example, I may want a tile set that demonstrates a particular feature (simple tiles, autotile, iso, etc) and not one that has extra content that confuses the issue. I don't know how we'd cover all the possibilities.

Consistency is good, but I would not want to see demos that end up obscuring the intended subject by including a lot of extra code/objects/animations/etc. Demos should have very low levels of polish (unless it's a demo on polish) because they're trying to communicate a specific message, not emulate a completed game.

[aaronfranke]

@Feniks-Gaming I think in addition to this once we have a demos done we should set up wiki page that can link each demo to feature shown.

Here's an idea, what if we linked to the demos from the class reference, not just the tutorial docs? For example, Joint would link to the Truck Town demo.

[Feniks-Gaming]

I would like that I think it would work well.

[sarrowsmith]

Just asked about links between documentation and demos on the forums (https://godotforums.org/discussion/comment/44325) which ended up with me going through the issues in godot-docs, which lead me here. So thoughts on it from the perspective of an experienced software engineer trying to learn Godot:

1. The demos are very discoverable (eg from the asset library, or pre-installed if you use the Steam download), so the goals stated here of making them a showcase and teaching material is key. The fact that tutorials are being moved out of the main documentation (Proposal: redesigning the docs for Godot 4 godot-docs#3390) puts even more pressure on the demos as tutorial material.
2. Only a couple of the demos are currently linked from the main documentation, which is a missed opportunity. (See also @aaronfranke 's comment above.)
3. In many cases, it's difficult to work out what a demo is showcasing (unless it's a concept you're familiar with from another engine and just want to see how to implement it in Godot). Add descriptions to all projects with README files #449 is a big improvement, but apparently hasn't propagated widely. (And a README.md won't show up in the editor once you've got the project loaded.)
4. Although the READMEs link to the class reference, they don't (always) link to appropriate sections of the "main" documentation. Even when that documentation links to them: eg https://docs.godotengine.org/en/stable/tutorials/audio/recording_with_microphone.html links to https://github.com/godotengine/godot-demo-projects/tree/master/audio/mic_record, but https://github.com/godotengine/godot-demo-projects/blob/master/audio/mic_record/README.md doesn't link back.
5. In many cases, the code is not readily comprehensible. See Include Comments in Code examples #529
6. I completely agree with everyone saying that visual consistency across the demos is not that important, although reusing assets is definitely a Good Thing.

[aaronfranke]

2. I added a few hundred links in this PR, but more needs to be done: godotengine/godot#42486

3, 4, 5. You are welcome to contribute improvements in these areas. Some of the demos have really good READMEs that you can use for reference. Writing good comments is tedious to do, and hard to do in a concise yet comprehensive manner.

[sarrowsmith]

3, 4, 5. You are welcome to contribute improvements in these areas.

Heh. Learning by writing documentation is a new one on me. I'll see what I can do (but it may take a while).