diff --git a/docs/gdevelop5/all-features/scene/reference.md b/docs/gdevelop5/all-features/scene/reference.md index 072b823ca9..1c34e9ff63 100644 --- a/docs/gdevelop5/all-features/scene/reference.md +++ b/docs/gdevelop5/all-features/scene/reference.md @@ -11,6 +11,9 @@ To pause a scene, use the "Pause and start a new scene" action. **Preload scene** Preload a scene resources as soon as possible in background. +**Unload scene resources** +Unload the resources of a scene from memory. This frees up memory but means the scene's resources will need to be reloaded if the scene is accessed again later. + **Pause and start a new scene** Pause this scene and start the specified one. Later, you can use the "Stop and go back to previous scene" action to go back to this scene. @@ -29,6 +32,9 @@ Change the background color of the scene. **Scene preloaded** Check if scene resources have finished to load in background. +**Scene resources unloaded** +Check if scene resources have been unloaded from memory. + **At the beginning of the scene** Is true only when scene just begins. @@ -52,6 +58,35 @@ Compare The progress of resources loading in background for a scene (between 0 a | `SceneLoadingProgress(scene name)` | Return The progress of resources loading in background for a scene (between 0 and 1).. || | | _🔤 Name of a scene (String)_ | Scene name | +## Resource Management Strategies + +GDevelop provides flexible resource management strategies to optimize memory usage and loading performance: + +### Project-level Settings +The [project properties](/gdevelop5/interface/project-manager/properties) allow you to set the default resource preloading strategy for all scenes. By default, all scene resources are preloaded in the background for fast scene switching. + +### Scene-level Settings +Each scene can override the project's default settings through its Scene Properties dialog (accessible by right-clicking on the scene in the Scene Editor): + +- **Resources preloading:** Control whether this scene's resources should be preloaded in the background +- **Resources unloading:** Specify when the scene's resources should be unloaded from memory when leaving the scene + +### When to Use Different Strategies + +**Default Strategy (Preload all, never unload):** +- Best for most games with moderate resource usage +- Provides fastest scene switching +- Resources stay in memory throughout the game session + +**Selective Preloading:** +- Useful for large games with many scenes +- Reduces initial loading time by only preloading critical scenes +- Good for web games to minimize bandwidth usage + +**Resource Unloading:** +- Essential for games with very large assets per scene +- Helps manage memory on low-end devices +- Useful for modular games where players may not visit all scenes --- diff --git a/docs/gdevelop5/interface/project-manager/properties.md b/docs/gdevelop5/interface/project-manager/properties.md index 8a1f35ad72..4380056326 100644 --- a/docs/gdevelop5/interface/project-manager/properties.md +++ b/docs/gdevelop5/interface/project-manager/properties.md @@ -23,9 +23,28 @@ It is in these properties, you can find: * **Maximum FPS:** By default, 60 is the maximum number of frames per second. If this value is set to 0, the game will run at the highest framerate the device/computer it's running on can handle. * **Scale mode (also called "Sampling"):** when set to linear, textures will be antialiased, meaning that their edges will be smoothed and the image will render well even if resized. Set to "nearest" to keep pixels visible, without any interpolation. This is the setting for games that use pixel art, or games are pixel perfect. * **Project file type:** By default, your game is saved in a single file. You can also choose to save it as multiple files: each scene, external layout, and external event sheet will be saved in a different file. This is perfect for working on a large game in a team and sharing your game in a version control system like Github or Mercurial. +* **Resources preloading:** Controls the default strategy for preloading scene resources across your entire game. By default, all scene resources are preloaded in the background for fast scene switching. You can disable this globally to reduce initial loading time, especially useful for large or modular games, or web games where you want to minimize the resources that need to be loaded. Individual scenes can override this setting in their [scene properties](#scene-specific-resource-settings). * **AdMob application ID (for iOS and Android):** ID number used to connect your game with your AdMob account. Only required if you're running ads in your game. [Read more about AdMob](/gdevelop5/all-features/admob). * **Firebase configuration string:** The mandatory authentication key for use with Firebase events. Only required if you're using Firebase in your project. [Read more about Firebase](https://wiki.gdevelop.io/gdevelop5/all-features/firebase/quickstart). +## Scene-specific resource settings + +While the project properties control the global default for resource preloading, each scene can have its own resource management settings that override the project defaults. To access these settings: + +1. Open the scene in the Scene Editor +2. Right-click on the scene background +3. Select "Scene properties" from the context menu + +In the Scene Properties dialog, you can configure: + +* **Resources preloading:** Override the project's default preloading strategy for this specific scene. Choose to enable or disable preloading for this scene regardless of the project setting. +* **Resources unloading:** Specify when the scene's resources should be unloaded from memory. By default, scene resources are kept in memory after leaving the scene for fast re-entry. You can choose to unload resources when the scene is left to free up memory, though this means resources will need to be reloaded if the scene is accessed again later. + +These settings are particularly useful for: +- **Large scenes with many assets:** Disable preloading and enable unloading to manage memory usage +- **Rarely accessed scenes:** Disable preloading to reduce initial game loading time +- **Critical scenes:** Keep preloading enabled for scenes that need instant access +- **Web games:** Optimize loading strategies to balance performance and bandwidth usage ## Branding and Loading screen diff --git a/docs/gdevelop5/interface/project-manager/resources.md b/docs/gdevelop5/interface/project-manager/resources.md index 61870a056a..9f94c8302c 100644 --- a/docs/gdevelop5/interface/project-manager/resources.md +++ b/docs/gdevelop5/interface/project-manager/resources.md @@ -8,6 +8,28 @@ You can find the resource manager at **Project manager** → **Game settings** ![](/gdevelop5/interface/project-manager/resources/pasted/20230309-205340.png) +## Resource Preloading and Unloading Strategies + +GDevelop offers flexible resource management strategies to optimize your game's performance and memory usage. These strategies control when resources are loaded and unloaded: + +### Global Settings +In the [project properties](/gdevelop5/interface/project-manager/properties), you can set the default resource preloading strategy for all scenes: +- **Preload all scenes (default):** All scene resources are preloaded in the background for fast scene switching +- **Disable global preloading:** Scenes only load resources when accessed, reducing initial loading time + +### Scene-Specific Settings +Each scene can override the global settings through its Scene Properties dialog (right-click on the scene in the Scene Editor): +- **Resources preloading:** Enable or disable preloading for individual scenes +- **Resources unloading:** Choose when to unload scene resources from memory when leaving the scene + +These strategies are particularly beneficial for: +- **Large games:** Manage memory usage by selectively loading/unloading resources +- **Web games:** Reduce bandwidth and initial loading time +- **Mobile games:** Optimize memory usage on devices with limited RAM +- **Modular games:** Load only the content players are likely to use + +For detailed information about these strategies, see the [Scene Resource Management documentation](/gdevelop5/all-features/scene/reference#resource-management-strategies). + ## Interface When you click on **Resources**, a new tab is opened where you can edit and control the resources in your game, all the resources in this new tab will be exported during the export of the game. @@ -57,7 +79,9 @@ Images can appear blurry if they're scaled to a ratio they were not meant to be, ### Preload as sound/music -This allows you to preload audio files as music/sound, making them start quickly as you don't have to wait for the audio to load. If the appropriate toggle isn't checked, the first time this audio file is played it may be distorted as it's loaded in. +This allows you to preload individual audio files as music/sound, making them start quickly as you don't have to wait for the audio to load. If the appropriate toggle isn't checked, the first time this audio file is played it may be distorted as it's loaded in. + +Note that this individual resource preloading setting works independently of the [global and scene-specific resource strategies](#resource-preloading-and-unloading-strategies) described above, which control when entire scenes' resources are loaded and unloaded. ![](/gdevelop5/interface/project-manager/resources/pasted/20230310-181721.png)