Skip to content

Commit 29795e4

Browse files
committed
Use the canvas_items/expand stretch mode/aspect by default for new projects
This ensures 2D elements are always at a readable size regardless of window size or screen resolution. In the era of hiDPI displays being common, this is generally considered a better default for nearly all games (as opposed to non-game applications). The `expand` stretch aspect ensures there are no black bars when the window aspect ratio differs from the base aspect ratio (16:9 by default), which matches previous behavior under the `disabled` stretch mode. Behavior for controls that are not anchored correctly is overall slightly improved by these defaults: instead of floating somewhere in the middle of the screen, the controls will be at their expected location when the window aspect ratio is the same as the base aspect ratio. Regardless, both the previous and new defaults require the use of anchors for UIs to scale correctly across different aspect ratios. Existing projects are not affected by this change, as this only affects projects created after this commit is merged.
1 parent 81cecf0 commit 29795e4

2 files changed

Lines changed: 5 additions & 2 deletions

File tree

doc/classes/ProjectSettings.xml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1082,12 +1082,12 @@
10821082
[code]"keep"[/code]: Keep aspect ratio when stretching the screen. This means that the viewport retains its original size regardless of the screen resolution, and black bars will be added to the top/bottom of the screen ("letterboxing") or the sides ("pillarboxing").
10831083
[code]"keep_width"[/code]: Keep aspect ratio when stretching the screen. If the screen is wider than the base size, black bars are added at the left and right (pillarboxing). But if the screen is taller than the base resolution, the viewport will be grown in the vertical direction (and more content will be visible at the bottom). You can also think of this as "Expand Vertically".
10841084
[code]"keep_height"[/code]: Keep aspect ratio when stretching the screen. If the screen is taller than the base size, black bars are added at the top and bottom (letterboxing). But if the screen is wider than the base resolution, the viewport will be grown in the horizontal direction (and more content will be visible to the right). You can also think of this as "Expand Horizontally".
1085-
[code]"expand"[/code]: Keep aspect ratio when stretching the screen, but keep neither the base width nor height. Depending on the screen aspect ratio, the viewport will either be larger in the horizontal direction (if the screen is wider than the base size) or in the vertical direction (if the screen is taller than the original size).
1085+
[code]"expand"[/code]: Keep aspect ratio when stretching the screen, but keep neither the base width nor height. Depending on the screen aspect ratio, the viewport will either be larger in the horizontal direction (if the screen is wider than the base size) or in the vertical direction (if the screen is taller than the original size). This is the default for projects created starting in Godot 4.8.
10861086
</member>
10871087
<member name="display/window/stretch/mode" type="String" setter="" getter="" default="&quot;disabled&quot;" keywords="disabled, canvas_items, viewport">
10881088
Defines how the base size is stretched to fit the resolution of the window or screen.
10891089
[code]"disabled"[/code]: No stretching happens. One unit in the scene corresponds to one pixel on the screen. In this mode, [member display/window/stretch/aspect] has no effect. Recommended for non-game applications.
1090-
[code]"canvas_items"[/code]: The base size specified in width and height in the project settings is stretched to cover the whole screen (taking [member display/window/stretch/aspect] into account). This means that everything is rendered directly at the target resolution. 3D is unaffected, while in 2D, there is no longer a 1:1 correspondence between sprite pixels and screen pixels, which may result in scaling artifacts. Recommended for most games that don't use a pixel art aesthetic, although it is possible to use this stretch mode for pixel art games too (especially in 3D).
1090+
[code]"canvas_items"[/code]: The base size specified in width and height in the project settings is stretched to cover the whole screen (taking [member display/window/stretch/aspect] into account). This means that everything is rendered directly at the target resolution. 3D is unaffected, while in 2D, there is no longer a 1:1 correspondence between sprite pixels and screen pixels, which may result in scaling artifacts. Recommended for most games that don't use a pixel art aesthetic, although it is possible to use this stretch mode for pixel art games too (especially in 3D). This is the default for projects created starting in Godot 4.8.
10911091
[code]"viewport"[/code]: The size of the root [Viewport] is set precisely to the base size specified in the Project Settings' Display section. The scene is rendered to this viewport first. Finally, this viewport is scaled to fit the screen (taking [member display/window/stretch/aspect] into account). Recommended for games that use a pixel art aesthetic.
10921092
</member>
10931093
<member name="display/window/stretch/scale" type="float" setter="" getter="" default="1.0">

editor/editor_node.cpp

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8334,8 +8334,11 @@ void EditorNode::notify_settings_overrides_changed() {
83348334
// to cover the command line workflow of creating projects using `touch project.godot`.
83358335
//
83368336
// This is used to set better defaults for new projects without affecting existing projects.
8337+
// Keep the list alphabetically sorted.
83378338
HashMap<String, Variant> EditorNode::get_initial_settings() {
83388339
HashMap<String, Variant> settings;
8340+
settings["display/window/stretch/aspect"] = "expand";
8341+
settings["display/window/stretch/mode"] = "canvas_items";
83398342
settings["physics/3d/physics_engine"] = "Jolt Physics";
83408343
settings["rendering/rendering_device/driver.windows"] = "d3d12";
83418344
return settings;

0 commit comments

Comments
 (0)