[Auto] [Improve] Clarified window resolution vs size and documented resize mode, centering, icon, and 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-14",
+      "summary": "Improved window docs: clarified game resolution vs window size, documented resize mode (adapt width/height), auto-adapt, center window, window icon, and size expressions"
     }
   ]
 }

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

@@ -31,6 +31,31 @@ 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)
 
+## Game resolution and window size
+
+It's useful to distinguish two related concepts:
+
+* The **game resolution** is the number of pixels the game draws (the game area). This is what the "Game resolution" action changes. Changing it does not change the size of the window — the game is simply stretched or scaled to fit.
+* The **game window size** is the size, in pixels, of the actual window on screen. The "Game window size" action changes it, but this only works on Windows, macOS and Linux: games running in a browser or on a phone cannot resize their window. When changing the window size you can choose whether the game resolution should also be updated, or whether the game should be stretched/reduced to fit the new window.
+
+## Resize mode
+
+By default the game keeps a fixed resolution. The "Game resolution resize mode" action lets you adapt the resolution to the window:
+
+* **Adapt width** updates the game width to fill the window or screen (the height stays fixed).
+* **Adapt height** updates the game height instead (the width stays fixed).
+* Leaving the mode empty disables resizing.
+
+The "Automatically adapt the game resolution" action controls whether this adaptation happens continuously while the window or screen size changes (it only has an effect when a resize mode is set).
+
+## Center the window
+
+The "Center the game window on the screen" action moves the window to the middle of the screen. This only works on Windows, macOS and Linux — it has no effect in a browser or on iOS/Android.
+
+## Window icon
+
+The "Window's icon" action changes the icon shown for the game's window, using an image from the project's resources.
+
 ## 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 +64,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 sizes
+
+A few expressions let you read the current dimensions, which is handy to position objects relative to the visible area or to react to different screens:
+
+* `SceneWindowWidth()` and `SceneWindowHeight()` return the size of the scene window (the 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/).