[Auto] [Improve] Clarified window resolution vs size and documented missing window actions 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-19",
+      "summary": "Improved window docs: clarified game resolution vs window size, added resize mode, adapt-resolution, center-window and window-icon actions, fullscreen aspect-ratio note, and screen/window size expressions"
     }
   ]
 }

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

@@ -8,28 +8,43 @@ The window of the game is the area in which the game is displayed. It DOES NOT r
 ## Fullscreen
 The "De/activate fullscreen" action allows you to toggle the game between fullscreen on/off. When the window is in fullscreen, it will take up as much area as possible. You can control the action using the "YES" and "NO" actions.
 
+For HTML5 games, a second parameter lets you choose whether the aspect ratio should be kept when switching to fullscreen (kept by default). The "Fullscreen activated?" condition lets you check if the game is currently in fullscreen.
+
 ## Window margins
 The margin of the window is the distance between the side of the window and the game window displayed. Shown below is the preview of a game with 100 px margins on all 4 sides.
 
 ![](/gdevelop5/all-features/annotation_2019-06-29_174027.png)
 
 Notice the black borders on all for sides of the window. The width of the borders is 100px.
 
-## Size of the window
+## Game resolution and window size
+
+GDevelop makes a distinction between two related but separate concepts:
 
-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.
+* The **game resolution** is the size of the game area, in pixels — the number of pixels that the game draws (its virtual width and height).
+* The **window size** is the size, in pixels, of the actual window in which the game is displayed on the system.
 
-While setting the size of the window, if you want to scale the current area to the set resolution, choose "NO". This will decrease the visual quality of the game if the size entered is lower than default and will increase the visual quality if the size entered is higher than the default size.
+The "Game resolution" action changes the resolution (the game area size) without changing the size of the window in which the game runs. The "Game window size" action changes the window size; it has an extra option to also update the game resolution at the same time. If you change the window size without updating the resolution, the game is stretched or reduced to fit in the window.
+
+!!! note
+
+    Changing the window size only works on platforms that support it (Windows, macOS and Linux). Games running in a web browser or on Android/iOS can not update their window size, but the game resolution can still be updated.
 
 ![](/gdevelop5/all-features/annotation_2019-06-29_175454.png)
 
-If you want to scale the set resolution to the window area, choose "YES". This will crop the window and display only the number of pixels entered in the action. This does not affect the visual quality as long as the game is scaled up or down because of the size of the system window.
+## Game resolution resize mode
 
-!!! note
+The "Game resolution resize mode" action sets how the resolution reacts when the window or screen size changes:
+
+* `adaptWidth` updates the game width to fit the window or screen.
+* `adaptHeight` does the same for the game height.
+* An empty value disables automatic resizing.
 
-    The game is cropped starting from the top-left corner of the game.
+The "Automatically adapt the game resolution" action turns this automatic adaptation on or off during the game. It only has an effect when the resize mode is configured to adapt the width or the height.
 
-![](/gdevelop5/all-features/annotation_2019-06-29_175540.png)
+## Center the game window
+
+The "Center the game window on the screen" action moves the window to the center of the screen. This only works on Windows, macOS and Linux (not in a web browser or on Android/iOS).
 
 ## Window title
 
@@ -39,6 +54,17 @@ 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.
 
+## Window's icon
+
+The "Window's icon" action changes the icon shown for the game's window, using an image from the project's resources. As with the title, this is only relevant on Windows, macOS and Linux.
+
+## Reading the screen and window size
+
+A few expressions let you read sizes at runtime, which is useful to position UI relative to the screen or to detect the available space:
+
+* `SceneWindowWidth()` and `SceneWindowHeight()` return the width and height of the scene window (the scene canvas for HTML5 games).
+* `ScreenWidth()` and `ScreenHeight()` return the width and height of the 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/).