diff --git a/automated_updates_data.json b/automated_updates_data.json index eb14cff8ead..3f59ff223af 100644 --- a/automated_updates_data.json +++ b/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-22", + "summary": "Improved window docs: distinguished game resolution from window size, added resolution resize mode (adapt width/height) and auto-adapt, fullscreen aspect ratio, centering/icon, and dimension expressions" } ] } diff --git a/docs/gdevelop5/all-features/window/index.md b/docs/gdevelop5/all-features/window/index.md index c3ef482243a..f67b6191d08 100644 --- a/docs/gdevelop5/all-features/window/index.md +++ b/docs/gdevelop5/all-features/window/index.md @@ -6,7 +6,9 @@ title: Window and game area The window of the game is the area in which the game is displayed. It DOES NOT refer to the system window that includes the toolbar, title bar on the top and a frame on the other three sides. ## 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. +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. + +For HTML5 games, the action has a second parameter to keep the aspect ratio of the game: when enabled (the default), black borders are added if needed so the game is not stretched. ## 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. @@ -15,21 +17,32 @@ 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. -## Size of the window +## Game resolution and window size + +It's important to distinguish two different things: + +* The **game resolution** is the number of pixels visible in the game area (the "Width" and "Height" of the game). This is the size at which your game is rendered. +* The **window size** is the size, in pixels, of the system window in which the game is displayed. + +The window is usually larger than the game resolution: the game is then scaled up to fill the window. This means a low game resolution stays sharp even on a large screen (and is the recommended way to support many screen sizes). -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" action changes the game area size without changing the window. The "Game window size" action changes the window itself — this only works on Windows, macOS and Linux, as games running in a browser or on mobile cannot resize their window. This action also lets you choose whether the game resolution should be updated to match: if not, the game is stretched or reduced to fit the new window. -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. +## Adapting the game resolution to the screen -![](/gdevelop5/all-features/annotation_2019-06-29_175454.png) +The "Game resolution resize mode" action controls how the game area reacts to a window or screen of a different shape than the game resolution: -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. +* **Adapt width**: the game width is updated so the game fills the window or screen (the height stays fixed). +* **Adapt height**: the game height is updated instead (the width stays fixed). +* **Disabled** (empty value): the resolution is never changed; black borders are added or the game is stretched to fit. -!!! note +The "Automatically adapt the game resolution" action enables or disables this update happening *live* when the window or screen size changes during the game. It only has an effect when a resize mode (adapt width or height) is set. - The game is cropped starting from the top-left corner of the game. +These options are also available, with default values, in the project properties. -![](/gdevelop5/all-features/annotation_2019-06-29_175540.png) +## Centering and the window icon + +On Windows, macOS and Linux, the "Center the game window on the screen" action repositions the window in the middle of the screen, and the "Window's icon" action changes the icon shown for the game's window. Neither has any effect in a browser or on iOS/Android. ## Window title @@ -39,6 +52,10 @@ 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 dimensions + +Expressions are available to read sizes at runtime. The *scene window* width and height return the size of the area in which the scene is rendered (the canvas for HTML5 games), while the *screen* width and height return the size of the whole screen (or the page for HTML5 games running in a browser). These are useful, for example, to position user interface objects relative to the visible area. + ## Reference All actions, conditions and expressions are listed in [the window reference page](/gdevelop5/all-features/window/reference/). \ No newline at end of file