From 114ee5c104c80dc6c027da6706d005fc09c6a41e Mon Sep 17 00:00:00 2001 From: 4ian <1280130+4ian@users.noreply.github.com> Date: Sat, 6 Jun 2026 10:46:44 +0000 Subject: [PATCH] [Auto] [Improve] Clarified window docs: game resolution vs window size, resize modes, and screen expressions --- automated_updates_data.json | 4 ++ docs/gdevelop5/all-features/window/index.md | 51 +++++++++++++++++---- 2 files changed, 46 insertions(+), 9 deletions(-) diff --git a/automated_updates_data.json b/automated_updates_data.json index b2d10e2b2e4..a462fb28483 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-06", + "summary": "Improved window docs: clarified game resolution vs window size distinction, added resize mode, adapt-resolution, center window, window icon, fullscreen aspect ratio, and screen-size expressions" } ] } diff --git a/docs/gdevelop5/all-features/window/index.md b/docs/gdevelop5/all-features/window/index.md index c3ef482243a..160b47c7a8b 100644 --- a/docs/gdevelop5/all-features/window/index.md +++ b/docs/gdevelop5/all-features/window/index.md @@ -6,7 +6,11 @@ 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, a second parameter lets you choose whether to keep the aspect ratio (enabled by default). When kept, black borders are added if the screen ratio does not match the game; when disabled, the game is stretched to fill the whole screen. + +You can also check if the game is currently in fullscreen with the "Fullscreen activated?" condition. ## 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 +19,39 @@ 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 rendered by the game (the size of the game area). This is what you set in the game properties and what determines how much of your scene is visible. +* The **game window size** is the size, in pixels, of the system window in which the game is displayed. The game resolution is scaled up or down to fit inside the window. + +### Game resolution + +The "Game resolution" action changes the resolution of the game, effectively changing the size of the visible game area. This does not change the size of the window in which the game is running: the rendered area is scaled to fit the window. + +### Game window size -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 window size" action changes the size of the system window. This only works on platforms that support it: games running in a browser or on mobile phones can not change their window size (the game resolution can still be changed). -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. +This action has a parameter to choose whether the game resolution should also be updated: -![](/gdevelop5/all-features/annotation_2019-06-29_175454.png) +* Choose **YES** to update the game resolution to match the new window size, so more (or less) of the scene becomes visible. +* Choose **NO** to keep the current resolution: the game is then stretched or reduced to fit inside the window. -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. +### Resize mode -!!! note +The "Game resolution resize mode" action controls how the game resolution reacts when the window or screen size changes: - The game is cropped starting from the top-left corner of the game. +* `adaptWidth` updates the game width to fit the window or screen (the height stays fixed). +* `adaptHeight` updates the game height to fit the window or screen (the width stays fixed). +* An empty value disables automatic resizing. -![](/gdevelop5/all-features/annotation_2019-06-29_175540.png) +The "Automatically adapt the game resolution" action enables or disables updating the resolution while the game is running. This only has an effect when the resize mode is set to adapt the width or the height. + +## Center the window + +The "Center the game window on the screen" action centers the window. This only works on Windows, macOS and Linux (it has no effect in a web browser or on iOS/Android). ## Window title @@ -39,6 +61,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 icon + +The "Window's icon" action changes the icon displayed for the game's window, using an image from your project's resources. This applies to the desktop window (Windows, macOS and Linux). + +## Reading the screen and window size + +A few expressions let you read sizes at runtime, which is useful to position objects relative to the visible area or to adapt your interface: + +* `SceneWindowWidth` and `SceneWindowHeight` return the size of the scene window (or 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/). \ No newline at end of file