📚 Missing/outdated Wiki Pages Task Force

[4ian]

👉 Welcome to the Wiki Task Force!

GDevelop’s Wiki teaches beginners and advanced users how to approach and use GDevelop’s features.
Since the product is constantly evolving, some pages might be missing or needing an update.
This is why we’ve created a new way to contribute to the community as a wiki writer: The Wiki Task Force.

To make sure that everyone's Wiki contributions are consistent and useful, we've created this issue to list and keep track of needed articles.

Please take a moment to read through these general guidelines before you start editing.

1. KISS: Keep It Simple, Stupid!
 Use simple language, short sentences, and fewer words. Write for readers whose 1st language is not English and have no coding or technical experience. If you're not sure if your writing is too wordy, use a tool like Hemingway or Grammarly.
2. Be consistent
. Look at the existing documentation and follow the established patterns. Don't try to reinvent the wheel in terms of how the content is structured, formatted, and written.
3. Be clear and professional. 
Write with a friendly tone, but don't go overboard. If you're too casual, readers may find the writing difficult to read or trust.
4. Write clear, action-oriented headings
. Readers tend to scan pages, so clear headings are essential. Readers also tend to care about accomplishing a specific task, so headings should focus on an action.

Go to “Contributing to the documentation” for better guidance on how to create pages, use markdown and how to refer to GDevelop’s concepts.

If you’ve decided to work on a Wiki page:

1. Make sure to have a Wiki account to be able to edit
2. Choose the Theme that you’d like to address and let us know that you’re working on it by replying to the comment that contains the article. This way other contributors will know what you’re working on and might offer a hand.

Thanks for your help in making this a valuable resource for everyone!

[4ian]

Keeping this space as a buffer for future listing of pages.

[LuniMoon]

Placeholder message

[Silver-Streak]

High level items that are currently missing on the wiki, or are very briefly mentioned but could be expanded. These are things that have been on my personal task list for a long time to see about building out, but I've not had time.

1. Framerate, Vsync, Chromium, and Electron:
   - Not currently mentioned anywhere in the wiki, could probably be enough detail to be it's entire own page. Right now GDevelop's implementation of Electron is locked to Vsync, and this causes confusion because users don't understand why their game is set to max out at 60 fps, but drops down to 30 fps (When they have a 75 hz monitor or another weird refresh rate). Adding detail about vsync and how it does steps could be very useful. (Alternatively, a project setting that turns on the disable vsync flag in electron could also be useful: Unable to Disable vsync with argument on Electron 4.x.x electron/electron#16806)

2. Trigger Once best practices:
   - There's no best practices around Trigger Once anywhere in the wiki, and only a single sentence around how it interacts with "For Each Object" or Repeat events. I'd probably be beneficial to build out more details about when and how to use it: https://wiki.gdevelop.io/gdevelop5/all-features/advanced-conditions#trigger_once

3. Rotation vs Angle vs direction: Conditions, actions, and expressions dealing with Rotation/Angle/Direction all seem to use different nomenclature for listing the degree. Some use -180 to 180, some use 0 to 360, some seem to even use radians? This probably needs to either be standardized across all of these expressions/conditions/etc, or documentation needs to be given for all of these on what their ranges are (this is probably best for in the specific item's descriptions/fields/etc, but documentation in the wiki would be great)

4. Optimization documentation. I know Arthuro and Bouh have both taking stabs at some draft optimization pages, but this probably should be fleshed out much more to help people start out the right way rather than having to go back a bunch. (The trigger once info above will help a bit, but things like resource sizes, not having too many global objects, etc, will be hlpeful).

5. Resolution and scaling. This is one that's been on my task list the longest, but there probably needs to be some very detailed discussions around resolution, scaling, etc. Going far more into detail about how scaling options impact rendering would be helpful. The current project properties page doesn't seem to cut it for newer users, and a very common question on the forums and the discord is "What is the best resolution for X?".

[LuniMoon]

[UPDATE NEEDED]
How to make a platform game - Beginner level

Context:
Beginners reported the need of having a tutorial on how to make a type of game from A to Z instead of scattered information about GDevelop's concepts. Indeed, learning the basics of Game Design with a project improves concept retention and new creators can come to GDevelop if they find these tutorials online.
To solve this, we're centralising on the Wiki the official tutorials on "How to make a Platformer" (indeed, a template already exists for those who want to observe Event's logic, but it will not appear on Google Search).

Existent Input:

• Please consider watching and including Weasley's existent video "How To Make A Game Without Coding - Platformer" to your explanation (so there's a unified explanation).
• Keep in mind that the tutorial is separated in several sections (starting with the 1st Chapter)
• Feel free to use screen captures using GDevelop's Red Hero asset pack

[LuniMoon]

[CLUSTER NEEDED]
Using Javascript - Advanced Level

Context:
Users wanting to code faster using mostly Javascript lack documentation on what the possibilities and known limits are.
Interviewed users migrating from other engines or starting GameDev with GDevelop said that the only information they've found so far is a YouTube tutorial in German -without English subtitles- that explains how to do so.

Existent Input:

• Users on the forum asking related Javascript questions
• GDevelop's wiki on Javascript events which scope is on the Event sheet.
• The "Javascript" channel on Discord where users ask for help

Note: This comment mentions a Cluster (a family of related articles addressing a commun theme). Since this kind of documentation takes time, reply with the JavaScript scope that you're willing to address.

[LuniMoon]

[EXTENSION MAINTENANCE NEEDED] - Mid Level
Draggable (for physics object)
Wiki link to update: https://wiki.gdevelop.io/gdevelop5/extensions/draggable-physics/reference

Context:
Extensions are a powerful way for creators to achieve advanced mechanics without having to write longer lines on the event sheet. After research we noticed that users who consider migrating to GDevelop can get nervous because they fear extensions will no longer be maintained

[...] as long as the plug-ins are first-party that's fine, it's when there is a reliance on third-party plugins for functionality that devs get nervous because there's no guarantee they will continue to be maintained.

As for GDevelop users who are considering using an extension, some of them reported that it would be nice to have an example that they could test to see if the extension is what they need.

How we're addressing this:
We're simplifying the copy inside Extension's description (Rule no.1: KISS- Keep It Simple, Stupid) and assigning an owner to the Extension's wiki.

The new rules for extension publication are as follows:

1. Extension's short description -which appears on the search list- has to explain in less than 70 characters what the extension does.
2. Extension's long description, has to be the introduction on GDevelop's Wiki article
3. A link to test the extension has to be included
4. Owners should be able to be contacted for bug report

[Silver-Streak]

Some minor input on these

To solve this, we're centralising on the Wiki the official tutorials on "How to make a Platformer" (indeed, a template already exists for those who want to observe Event's logic, but it will not appear on Google Search).

I agree the platformer tutorial needs an update, the current formatting doesn't really lead very well to navigation ("I left off in the middle of a page the other day....was it part 3 or part 5?" is much harder than "I was working on Step 6: Adding Controls"), and all of the instructions are for older versions of the UI. Basing it off of Helper Wesley's video would be a fantastic improvement.

(Edit: Snipped repetitive info)
I do want to call out that the general "Getting started" and other documentation information should probably be updated to be smoother/more accurate as well.

There are quite a few studies showing that children who only learn a subject via video tutorials (Youtube or otherwise) and never have coursework/book study have a hard time adapting to different concepts or developing critical thinking skills.

I know there are a lot of people asking for more tutorials, but I think making the general documentation better and having updating the tutorials to be more relevant will lead to a better result than just "more tutorials". Both should be maintained, and in a best case scenario, the wiki would allow for content referencing from other parts of the wiki, so you only have to maintain one page for a concept rather than both the main documentation and the tutorial ( this plugin could be very helpful, if it's not already installed in the wiki: https://www.dokuwiki.org/plugin:include )

The plugin above could make it easier for tutorial makers to reference other info, as well as reference previous sections in the tutorial.

Existent Input:

• Please consider watching and including Weasley's existent video "How To Make A Game Without Coding - Platformer" to your explanation (so there's a unified explanation).
• Keep in mind that the tutorial is separated in several sections (starting with the 1st Chapter)
• Feel free to use screen captures using GDevelop's Red Hero asset pack

Yes, all of these changes to the Platformer tutorial make complete sense to me.
Regardless of my feedback above, these changes being implemented will make the platform tutorial much more relevant to the current state of GDevelop.

[CLUSTER NEEDED]
Using Javascript - Advanced Level

This is a difficult one. Unless something has changed, my understanding is that Javascript is not viewed as a first class method of building games in GDevelop, because the languages being used could change at any point. If that is still the high level viewpoint, I think being more clear about the expected skill level to use JS in the engine should be documented.

I've seen a lot of the references/discussion in the JS channel on the discord, and I think some of the issues arise because people are trying to learn Javascript through GDevelop, whereas it more expects you to be a full stack Javascript dev already and understand about using custom APIs along with Javascript already.

[EXTENSION MAINTENANCE NEEDED] - Mid Level Draggable (for physics object) Wiki link to update: https://wiki.gdevelop.io/gdevelop5/extensions/draggable-physics/reference

Context: Extensions are a powerful way for creators to achieve advanced mechanics without having to write longer lines on the event sheet. After research we noticed that users who consider migrating to GDevelop can get nervous because they fear extensions will no longer be maintained

So I think this is another thing the core team needs to decide on, because I think "can get nervous because they fear extensions will no longer be maintained" is 100% true. Extensions are only maintained by their original creators, or if another contributor has an idea on how to make an enhancement. I think it's probably important to be upfront about that with people (extensions in the extension list are not maintained as part of the engine), and maybe provide detail on how to open an extension to better learn about how its logic works?

The new rules for extension publication are as follows:

1. Extension's short description -which appears on the search list- has to explain in less than 70 characters what the extension does.
2. Extension's long description, has to be the introduction on GDevelop's Wiki article
3. A link to test the extension has to be included
4. Owners should be able to be contacted for bug report

While I absolutely agree with these, I think #4 will lead to less people submitting extensions at all, although I do think it is probably the right path forward. I think it's probably worthwhile to talk with the extension team to get their input on that, and decide what that means for the Community extension tab items.