[Auto] [Improve] Documented window resolution vs size, resize modes, centering, icon, and screen-size expressions

automated_updates_data.json

@@ -92,6 +92,10 @@
     {
       "date": "2026-04-22",
       "summary": "Improved resources-loading docs (named Preload scene action, documented SceneLoadingProgress expression and AreSceneAssetsLoaded condition, clarified custom loading screen approach) and added extension lifecycle functions table to events/functions docs"
+    },
+    {
+      "date": "2026-06-09",
+      "summary": "Improved window docs: clarified game resolution vs window size, added resolution resize mode (adaptWidth/adaptHeight) and auto-adapt, window centering, window icon, and screen/window size expressions"
     }
   ]
 }

docs/gdevelop5/all-features/window/index.md

@@ -15,6 +15,17 @@ The margin of the window is the distance between the side of the window and the
 
 Notice the black borders on all for sides of the window. The width of the borders is 100px.
 
+## Game resolution and window size
+
+It's important to understand the difference between two related but distinct concepts:
+
+* The **game resolution** is the size, in pixels, of the area that the game draws (the number of pixels visible in the game). This is what determines how much of the game world is shown.
+* The **window size** is the size of the actual system window in which the game runs.
+
+When the two don't match, the game is stretched or reduced to fit in the window.
+
+The "Game resolution" action changes the resolution (the game area size) without changing the size of the window. The "Game window size" action changes the system window instead. Note that the window size can only be changed on desktop (Windows, macOS, Linux): games running in a browser or on mobile can not resize their window, but their game resolution can still be updated.
+
 ## Size of the window
 
 Size of the window is the number of pixels visible in the game. The "Width" field refers to the number of pixels in the horizontal directions while the "Height" field refers to the number of pixels in the vertical direction.
@@ -31,6 +42,24 @@ If you want to scale the set resolution to the window area, choose "YES". This w
 
 ![](/gdevelop5/all-features/annotation_2019-06-29_175540.png)
 
+## Adapting the resolution to the screen size
+
+When the window or screen size changes (for example when the player resizes the window, or on different mobile screens), you can decide how the game resolution should react with the "Game resolution resize mode":
+
+* **adaptWidth**: the game width is updated to fit the window or screen, keeping the height fixed.
+* **adaptHeight**: the game height is updated to fit the window or screen, keeping the width fixed.
+* Leave it empty to disable resizing entirely, so the game resolution stays the same and the game is stretched to fill the window.
+
+The "Automatically adapt the game resolution" action controls whether the resolution is re-computed while the game is running when the window or screen size changes. This only has an effect when a resize mode (adaptWidth or adaptHeight) is set.
+
+## Center the game window
+
+The "Center the game window on the screen" action moves the game window to the center of the screen. This only works on Windows, macOS and Linux — it has no effect in a web browser or on iOS/Android.
+
+## Window icon
+
+The "Window's icon" action changes the icon of the game's window, using an image from the game's resources. This applies to the desktop window.
+
 ## Window title
 
 The window title is the name of the window that is visible on the title bar (located at the top) of the window. The default title name is "Preview of ProjectName" during a preview.
@@ -39,6 +68,13 @@ By default, the game name is used for the executable name (on Windows, macOS and
 
 With the action to change the title, the title bar on Windows, macOS and Linux will be changed. Nothing will be visible on Android and iOS. For HTML5 games, the web page title will be changed.
 
+## Reading the screen and window size
+
+Several expressions let you read sizes at runtime, which is useful to position interface elements or to react to different screens:
+
+* `SceneWindowWidth` and `SceneWindowHeight` return the size of the scene window (or the scene canvas for HTML5 games).
+* `ScreenWidth` and `ScreenHeight` return the size of the whole screen (or the page for HTML5 games running in a browser).
+
 ## Reference
 
 All actions, conditions and expressions are listed in [the window reference page](/gdevelop5/all-features/window/reference/).