Description
Describe the project you are working on
Godot Engine
Describe the problem or limitation you are having in your project
The technical design of Godot makes it difficult to change default values within the engine without affecting the behaviour of existing projects. This means that whenever defaults must be changed within the engine, it can result in a very frustrating experience for the user.
For example, the current default for Environment’s tonemapping white parameter is 1.0. This is arguably a poor default as it disables most tonemapping functionally and turns the tonemappers into nothing more than a contrast curve at best. A better default may be 2.0, which is the maximum value that works with the Mobile rendering method. So let’s say we update the engine to have a 2.0 default:
- A developer is preparing a game for release that they have built with the default setting for months or years, but needs to update the minor version shortly before launch because of a critical bug that they need fixed. This sort of thing happens often, for example I know of a game that was released with Godot 4.4.1 and was updated from Godot 4.3 only shortly before release to fix a critical issue on Mac OS.
- They may (or may not!) discover that the lighting and visuals are slightly different than what they poured months of effort into; the time before a game's release is extremely stressful, and this discovery may add notable stress to the developer.
- The developer would start by pouring over release notes and change logs trying to find out what has changed with the behaviour of lights or other nodes that they have configured. It is even likely they will not think to look at a default setting because this is something they haven't put too much thought into.
- Eventually they will discover that the default changed by opening the project in both versions of the editor and comparing every property to see what has gone wrong because they couldn’t find the change in default tonemapping value amongst the lists of so many minor changes.
I've experienced engine behaviour changing with a version update and it can be a very frustrating experience. This frustration is heightened when you discover that the change was to simply change a default and was not needed to fix any real limitations in the engine.
Describe the feature / enhancement and how it helps to overcome the problem or limitation
I propose that all changed defaults should be explicitly listed in the migration guides, separate from the existing tables. This changed defaults list should include the previous default and new default value. Because it is a separate list from the others, it will be a valuable tool in quickly determining the impact of updating Godot versions.
This solution only reduces the frustration caused to developers when defaults change and does not fully solve the problem, but I think it is still very worthwhile to improve the user experience of updating to new versions of Godot. Because nodes can be created through scripts, I suspect that it is not possible to fully solve this problem, so even if other upgrade tooling is implemented, this proposed “changed defaults” list will still give value to users.
Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams
Because the class database exists, I suspect that it should be possible to analyze all defaults within the engine and compare between Godot versions to determine which defaults have changed. If such a tool was created, this could be used to give an accurate list that could be used by the release team in release blog posts. The output of this tool would be a table in a text format that matches what would be used in the migration guide to make it easy to copy and paste the result into the official release notes.
Here is an example of what it may look like in the release notes:
Changed defaults
The following default values have been changed between Godot version 4.4 and 4.5. If your project uses any of these properties with their default value, you can achieve a similar behaviour to the existing Godot version by manually changing the values to match the old defaults.
| Property | 4.4 default | 4.5 default |
|---|---|---|
| Environement.tonemap_white | 1.0 | 2.0 |
| etc.. |
I don’t have a strong opinion about where in the migration guide this table appears, but it should be forward-facing, similar to the existing change log.
Currently migration guides are not provided for updates across maintenance releases. This automatic tool could be used to verify that no defaults have changed between, say 4.4 and 4.4.1. (Or maybe this is already done with API validation, in which case this tool would only be used for preparing the "changed defaults" table for the migration guide.)
Additionally, it’s possible this tool could be backported to generate tables that compare earlier versions so that existing releases could have their release notes updated to include the changed defaults. This tool could also be made available to developers to determine what defaults have changed between their current custom build of the engine and the current master build they are pulling in. The tool should be able to target different versions, such as listing all of the changes from 4.2 through to 4.5.
If this enhancement will not be used often, can it be worked around with a few lines of script?
It may be possible to write this tool with scripts; I’m really not sure. Regardless, this is about the Godot release notes, which are owned by the Godot organization.
Is there a reason why this should be core and not an add-on in the asset library?
N/A