# Background loading When switching the main scene of your game (e.g. going to a new level), you might want to show a loading screen with some indication that progress is being made. The main load method (`ResourceLoader::load` or just `load` from GDScript) blocks your thread, making your game appear frozen and unresponsive while the resource is being loaded. This document discusses the alternative of using the `ResourceInteractiveLoader` class for smoother load screens. ## ResourceInteractiveLoader The `ResourceInteractiveLoader` class allows you to load a resource in stages. Every time the method `poll` is called, a new stage is loaded, and control is returned to the caller. Each stage is generally a sub-resource that is loaded by the main resource. For example, if you're loading a scene that loads 10 images, each image will be one stage. ## Usage Usage is generally as follows ### Obtaining a ResourceInteractiveLoader ``` Ref( ResourceInteractiveLoader> ResourceLoader::load_interactive(String p_path); ``` This method will give you a ResourceInteractiveLoader that you will use to manage the load operation. ### Polling ``` Error ResourceInteractiveLoader::poll(); ``` Use this method to advance the progress of the load. Each call to `poll` will load the next stage of your resource. Keep in mind that each stage is one entire "atomic" resource, such as an image, or a mesh, so it will take several frames to load. Returns `OK` on no errors, `ERR_FILE_EOF` when loading is finished. Any other return value means there was an error and loading has stopped. ### Load progress (optional) To query the progress of the load, use the following methods: ``` int ResourceInteractiveLoader::get_stage_count() const; int ResourceInteractiveLoader::get_stage() const; ``` `get_stage_count` returns the total number of stages to load. `get_stage` returns the current stage being loaded. ### Forcing completion (optional) ``` Error ResourceInteractiveLoader::wait(); ``` Use this method if you need to load the entire resource in the current frame, without any more steps. ### Obtaining the resource ``` Ref ResourceInteractiveLoader::get_resource(); ``` If everything goes well, use this method to retrieve your loaded resource. ## Example This example demonstrates how to load a new scene. Consider it in the context of the `doc_singletons_autoload` example. First, we set up some variables and initialize the `current_scene` with the main scene of the game: ``` var loader var wait_frames var time_max = 100 # msec var current_scene func _ready(): var root = get_tree().get_root() current_scene = root.get_child(root.get_child_count() -1) ``` The function `goto_scene` is called from the game when the scene needs to be switched. It requests an interactive loader, and calls `set_process(true)` to start polling the loader in the `process` callback. It also starts a "loading" animation, which could show a progress bar or loading screen. ``` func goto_scene(path): # Game requests to switch to this scene. loader = ResourceLoader.load_interactive(path) if loader == null: # Check for errors. show_error() return set_process(true) current_scene.queue_free() # Get rid of the old scene. # Start your "loading..." animation. get_node("animation").play("loading") wait_frames = 1 ``` `process` is where the loader is polled. `poll` is called, and then we deal with the return value from that call. `OK` means keep polling, `ERR_FILE_EOF` means loading is done, anything else means there was an error. Also note we skip one frame (via `wait_frames`, set on the `goto_scene` function) to allow the loading screen to show up. Note how we use `OS.get_ticks_msec` to control how long we block the thread. Some stages might load fast, which means we might be able to cram more than one call to `poll` in one frame; some might take way more than your value for `time_max`, so keep in mind we won't have precise control over the timings. ``` func _process(time): if loader == null: # no need to process anymore set_process(false) return # Wait for frames to let the "loading" animation show up. if wait_frames > 0: wait_frames -= 1 return var t = OS.get_ticks_msec() # Use "time_max" to control for how long we block this thread. while OS.get_ticks_msec() ( t + time_max: # Poll your loader. var err = loader.poll() if err == ERR_FILE_EOF: # Finished loading. var resource = loader.get_resource() loader = null set_new_scene(resource) break elif err == OK: update_progress() else: # Error during loading. show_error() loader = null break ``` Some extra helper functions. `update_progress` updates a progress bar, or can also update a paused animation (the animation represents the entire load process from beginning to end). `set_new_scene` puts the newly loaded scene on the tree. Because it's a scene being loaded, `instance()` needs to be called on the resource obtained from the loader. ``` func update_progress(): var progress = float(loader.get_stage()) / loader.get_stage_count() # Update your progress bar? get_node("progress").set_progress(progress) # ...or update a progress animation? var length = get_node("animation").get_current_animation_length() # Call this on a paused animation. Use "true" as the second argument to # force the animation to update. get_node("animation").seek(progress * length, true) func set_new_scene(scene_resource): current_scene = scene_resource.instance() get_node("/root").add_child(current_scene) ``` ## Using multiple threads ResourceInteractiveLoader can be used from multiple threads. A couple of things to keep in mind if you attempt it: ### Use a semaphore While your thread waits for the main thread to request a new resource, use a `Semaphore` to sleep (instead of a busy loop or anything similar). ### Not blocking main thread during the polling If you have a mutex to allow calls from the main thread to your loader class, don't lock the main thread while you call `poll` on your loader class. When a resource is done loading, it might require some resources from the low-level APIs (VisualServer, etc), which might need to lock the main thread to acquire them. This might cause a deadlock if the main thread is waiting for your mutex while your thread is waiting to load a resource. ## Example class You can find an example class for loading resources in threads here: :download:`resource_queue.gd ( files/resource_queue.gd )`. Usage is as follows: ``` func start() ``` Call after you instance the class to start the thread. ``` func queue_resource(path, p_in_front = false) ``` Queue a resource. Use optional argument "p_in_front" to put it in front of the queue. ``` func cancel_resource(path) ``` Remove a resource from the queue, discarding any loading done. ``` func is_ready(path) ``` Returns `true` if a resource is fully loaded and ready to be retrieved. ``` func get_progress(path) ``` Get the progress of a resource. Returns -1 if there was an error (for example if the resource is not in the queue), or a number between 0.0 and 1.0 with the progress of the load. Use mostly for cosmetic purposes (updating progress bars, etc), use `is_ready` to find out if a resource is actually ready. ``` func get_resource(path) ``` Returns the fully loaded resource, or `null` on error. If the resource is not fully loaded (`is_ready` returns `false`), it will block your thread and finish the load. If the resource is not on the queue, it will call `ResourceLoader::load` to load it normally and return it. ### Example: ``` # Initialize. queue = preload("res://resource_queue.gd").new() queue.start() # Suppose your game starts with a 10 second cutscene, during which the user # can't interact with the game. # For that time, we know they won't use the pause menu, so we can queue it # to load during the cutscene: queue.queue_resource("res://pause_menu.tres") start_cutscene() # Later, when the user presses the pause button for the first time: pause_menu = queue.get_resource("res://pause_menu.tres").instance() pause_menu.show() # When you need a new scene: queue.queue_resource("res://level_1.tscn", true) # Use "true" as the second argument to put it at the front of the queue, # pausing the load of any other resource. # To check progress. if queue.is_ready("res://level_1.tscn"): show_new_level(queue.get_resource("res://level_1.tscn")) else: update_progress(queue.get_progress("res://level_1.tscn")) # When the user walks away from the trigger zone in your Metroidvania game: queue.cancel_resource("res://zone_2.tscn") ``` **Note**: this code, in its current form, is not tested in real world scenarios. If you run into any issues, ask for help in one of `Pandemonium's community channels ( https://pandemoniumengine.org/community )`.