Rename Project Settings, Display, Window width and height, and test_width and test_height settings to match their function

[madmiraal]

Describe the project you are working on

Godot Editor UI design

Describe the problem or limitation you are having in your project

As originally identified by @leonkrause here, the Project Settings display/window/size/test_width and test_height should be renamed to window_width and window_height to reflect their function. To avoid confusion, it was further suggested to rename the display/window/size/width and height to reflect their function too.

The display/window/size/width and height parameters affect the root viewport size. On desktop platforms, by default, the viewport size also defines the initial window size. On iOS, Android and HTML5 platforms, the window size is specified by the device or the browser. How the viewport is displayed on a device or a window with a different size to the viewport size depends on the display/window/stretch settings.

The display/window/size/test_width and test_height parameters only affect desktop platforms. It is ignored on iOS, Android, and HTML5. By default, a desktop's initial window size is the viewport size. These parameters can be used to set the game's initial window width and height to be different from the viewport size. Note: On desktop platforms, unless the resizable property is disabled, the window size can still be changed by the user. These parameters are normally used to test what the viewport and stretch settings will look like on different screen resolutions -- especially pixel art -- and I assume this is why it was called "test" initially, but ultimately it's the initial desktop window size.

Some historical context for this proposal

A PR (godotengine/godot#47522) was created to rename: display/window/size/test_width -> display/window/size/window_width display/window/size/test_height -> display/window/size/window_height display/window/size/width -> display/window/size/viewport_width display/window/size/height -> display/window/size/viewport_height

However window_width and window_height were considered ambiguous. To reflect the order of importance, it was agreed to rename: display/window/size/test_width -> display/window/size/window_width_override display/window/size/test_height -> display/window/size/window_height_override

However, although renaming display/window/size/width and height to display/window/size/viewport_width and height had merit from a technical point of view, there was doubt that it would be a good change from a UX point of view. Furthermore, it was considered worth looking into separating display/window parameters and display/viewport parameters.

So, it was suggested that a proposal be opened to discuss it further and include more users in the discussion, including tutorial makers, to use the opportunity to figure out the most natural structure for these settings.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

Rename: display/window/size/test_width, display/window/size/test_height, display/window/size/width and display/window/size/height to better reflect their function and make it easier for new users to understand their purpose.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

See PR godotengine/godot#47522.

If this enhancement will not be used often, can it be worked around with a few lines of script?

No.

Is there a reason why this should be core and not an add-on in the asset library?

It affects the editor's display of project settings.

[akien-mga]

Thanks for opening a proposal. As discussed in https://github.com/godotengine/godot/pull/47522 indeed, we want to take the opportunity to make sure that we rename those in a way that makes both sense from a technical point of view but also that makes things clear for users (and especially new users, as configuring window/viewport settings are among the most important settings for all projects).

Would be interesting to have input from people used to documenting and teaching Godot. CC @godotengine/documentation

This is for 4.0+ and we can break compatibility if it makes the overall set of settings easier to understand and use.

[nezvers]

I have a simple question thought proposal - what normal, non-Godot, or even non-game dev would call those and instantly have an idea what it is or what for it is? I'd say something in lines of "game resolution" or "view resolution" and "window resolution" or "initial window resolution". I'd say it's common sense that window can be resizable or be in a not initial state, so hiding behind an ambiguous name like "test width/ height" is not the correct thing to do, just because it ends up different in the end product.

[madmiraal]

@nezvers The problem with "resolution" is that the published game's actual resolution (including the height to width ratio) depends on the device that it's played on, and that is outside of your control. It's only on desktop platforms, when the game is not run at fullscreen and resizable is disabled that the final resolution can be controlled (and then you need to keep it a minimum expected size). In all other circumstances you need to specify how your Viewport size is converted to the actual screen or window resolution; using the stretch modes. Ultimately, by the time you publish your game, you need to understand what the Viewport is and specify how it's size is converted to the actual screen or window size. And, yes, that requires that the layout of your Control nodes is not "brittle". Until then, and to help beginners, when running the game from the editor, the window size is simply the Viewport size.

[ehmprah]

+1 for window_size/viewport_size or separating display/window parameters and display/viewport parameters.

[mhilbrunner]

cc @cbscribe @NathanLovato as Akien outlined, maybe you have input for this from experience with teaching Godot :)

[akien-mga]

Fixed by https://github.com/godotengine/godot/pull/47522.

But feel free to continue discussion if there are ideas to improve this further.

[oeleo1]

Frankly, the new names are much more debatable than the old ones. As a newbie, I had no problems with the old names. As an expert I have mixed feelings with the new names:

I appreciate the original wish for improvement and the effort @madmiraal has put into it and the fact that this proposal has gone through the process But after reading all of the opinions expressed, I am very much in favor of @reduz comment to just rename the test to override but I also acknolwedge the reaction that override doesn't override anything for it is relevant for desktop only.

1. viewport_width/height doesn't make much sense for newbies which don't know viewports. For experts, viewport is confusing as there may be several of them. So you have to clarify it's the root viewport in the doc.
2. window_width/height_override doesn't make much sense for desktop as it still doesn't override anything cf. the original objection, so it is confusing, besides the fact that the first set says viewport and the second set window which is inconsistent.

So why not KISS?

I hereby propose to revert the first set to width/height and change the second set to desktop_width/height. These terms IMO are much less debatable than the new ones, and remember, they are all under window/size.