[Auto] [Improve] Clarified window size vs resolution and fixed screenshot docs syntax

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-05-17",
+      "summary": "Improved window docs (clarified window size vs game resolution, added resize mode, adapt-at-runtime, center window, window icon, and screen/window dimension expressions) and screenshot docs (fixed expression syntax, clarified desktop-only support)"
     }
   ]
 }

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

@@ -5,7 +5,11 @@ title: Screenshot extension
 
 This extension lets you save a screenshot of the running game in a specified folder.
 
-Note: As of GDevelop 5.0.0-beta92 the screenshot action is no longer an extension. Just add an action and search for `screenshot` or go to `Other Actions`/`Screenshot`/`Take screenshot`.
+!!! note
+
+    Taking a screenshot only works when the game is exported for Windows, macOS or Linux. It is not supported on mobile or in web (browser) exports.
+
+Add the action and search for `screenshot` or go to `Other Actions`/`Screenshot`/`Take screenshot`.
 
 ### Actions
 
@@ -17,9 +21,7 @@ Use this action to save a screenshot of everything which is currently drawn on t
 
 **Save path**: The file path where the screenshot should be saved.
 
-The save path needs to be an absolute path on the file system (Like "C:\MyFolder\MyScreenshot.png" on Windows)'
-
-Relative paths are not supported.
+The save path needs to be an absolute path on the file system (like `C:\MyFolder\MyScreenshot.png` on Windows). Relative paths are not supported. If the path does not end with `.png`, the extension is automatically appended.
 
 !!! note
 
@@ -29,9 +31,11 @@ Relative paths are not supported.
 
 This path:
 
-``` <FileSystem::PicturesPath>() + <FileSystem::PathDelimiter>() + "my_screenshot.png" ```
+```
+FileSystem::PicturesPath() + FileSystem::PathDelimiter() + "my_screenshot.png"
+```
 
-This will save the screenshot to the *Pictures* folder on Windows, Linux and MacOS.
+This will save the screenshot to the *Pictures* folder on Windows, Linux and macOS.
 
 ## Reference
 

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

@@ -8,6 +8,8 @@ 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.
 
+A second parameter "Keep aspect ratio" is available for HTML5 games: when enabled, black bars are added around the game (letterboxing/pillarboxing) to preserve the original aspect ratio when going 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.
 
@@ -17,20 +19,37 @@ Notice the black borders on all for sides of the window. The width of the border
 
 ## 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.
+GDevelop distinguishes between two different sizes:
 
-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.
+- **Game window size**: the size, in pixels, of the system window in which the game is displayed (Windows, macOS, Linux). On mobile and in the browser, the window size is controlled by the operating system or the page — it cannot be changed by the game.
+- **Game resolution**: the number of pixels visible inside the game area (the "virtual" canvas the game is drawn on). Changing the resolution does not change the window size: instead, the game area is either stretched or scaled to fit the window.
 
-![](/gdevelop5/all-features/annotation_2019-06-29_175454.png)
+Use the **Game window size** action to resize the system window on desktop. The action has an additional "Also update the game resolution?" option:
 
-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.
+- **YES**: the game resolution is updated to match the new window size — every pixel of the game is drawn 1:1 with a screen pixel.
+- **NO**: only the window changes, and the game is stretched or shrunk to fit. Use this if you want a fixed-resolution game (for pixel art for example) and only want the window to grow.
 
-!!! note
+Use the **Game resolution** action to change only the resolution. This is useful to switch between resolution presets without resizing the player's window.
 
-    The game is cropped starting from the top-left corner of the game.
+![](/gdevelop5/all-features/annotation_2019-06-29_175454.png)
 
 ![](/gdevelop5/all-features/annotation_2019-06-29_175540.png)
 
+### Adapting the resolution to the window
+
+Two related actions control whether GDevelop automatically updates the game resolution as the window or screen size changes:
+
+- **Game resolution resize mode**: choose `"adaptWidth"` to update the game width so that the game fills the window horizontally (with no black bars on the sides), `"adaptHeight"` to do the same on the vertical axis, or leave it empty to keep a fixed resolution.
+- **Automatically adapt the game resolution**: enable this to keep the game resolution in sync with window/screen size changes during the game (e.g. when the player resizes the window or rotates their phone). When disabled, the resolution is only set when explicitly changed by an action.
+
+### Center the window on the screen
+
+The **Center the game window on the screen** action centers the game window. It only works on Windows, macOS and Linux — not in browser or on mobile.
+
+### Window icon
+
+Use the **Window's icon** action to change the icon shown by the operating system for the game window. Pass the resource name of an image. Note that the icon shown on the player's desktop shortcut, taskbar, or app store listing is set during export and not affected by this action.
+
 ## 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 +58,18 @@ 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.
 
+You can read back the current title with the `WindowTitle()` expression.
+
+## Reading screen and window dimensions
+
+A few expressions are provided to read the current sizes:
+
+- `SceneWindowWidth()` / `SceneWindowHeight()`: size, in pixels, of the area where the game scene is drawn (the canvas for HTML5 games).
+- `ScreenWidth()` / `ScreenHeight()`: size of the player's screen (or page, for browser games).
+- `ColorDepth()`: color depth, in bits, of the screen.
+
+These are commonly used together with the "Game resolution" action to react to the player's screen, or to position UI elements relative to the game area regardless of the current resolution.
+
 ## Reference
 
 All actions, conditions and expressions are listed in [the window reference page](/gdevelop5/all-features/window/reference/).