0

Description

"Background resource loading is something that can be done easily with the built-in `ResourceLoader`. There's numerous tutorials about how to achieve it, including the [Godot documentation itself](https:\/\/docs.godotengine.org\/en\/stable\/tutorials\/io\/background_loading.html).\r\n\r\n## Functions\r\n\r\nThe following script is meant to be attached to a simple node and invoked when needed. The caller has to provide a list of directories to browse (not recursively) and a `Callable` that allows assigning a contextually unique identifier is a resource needs to be loaded.\r\n\r\nFor example, in the calling script, assuming the loading script is attached to a node referenced as `resource_scanner`. First, define a function to assign identifier. A simple case could be:\r\n\r\n```gdscript\r\nfunc _provide_resource_id(path : String) -> String:\r\n\treturn path.get_basename() if path != null and path.get_extension() == \"json\" else \"\"\r\n```\r\n\r\nThis will return the basename of a resource file when the extension is `.json`. Then, simply call the `load_resources` function as follow:\r\n\r\n```grscript\r\nresource_scanner.load_resources([\"res:\/\/resources\", \"user:\/\/resources\", \"\/not\/a\/valid\/directory\"], _provide_resource_id)\r\n```\r\n\r\nIt will launch the background loading of resources located in the provided list of directories. Internal and external directories can be addressed thanks to the `ResourceLoader` capabilities.\r\n\r\nThe method `load_resources` take the following parameters:\r\n- An array or `String` as a list of directory paths to scan,\r\n- A `Callable` to provide identifiers to resources to load,\r\n- An optional `float` that determines the resource loading state polling period, in seconds (by default, 0.1).\r\n\r\nThe result of the processing is provided through signals\r\n\r\n## Signals\r\n\r\nThe following signals allows retrieving the result of the background loading :\r\n\r\n- `on_progress(value : float)` : Indicates the current loading progression. `value` varies from 0 to 1.\r\n- `on_error(code : int, res_id : String)` : Trigged when an error occurs. The code is the value of the enum `ResourceLoadErroor` provided in the snippet script. `res_id` is the identifier provided by the `Callable` evoked earlier.\r\n- `on_loaded(result : Dictionary[String, Object])` : Trigged when the background loading is finished. `result` is a map that associate the identifier provided by the callable to a loaded resource, which can be `null` if the loading failed."

Main code

class_name DeferedResourceLoader
extends Node

signal on_progress(value : float)

signal on_loaded(result : Dictionary[String, Object])

signal on_error(code : ResourceLoadError, res_id : String)

enum ResourceLoadError {
	INVALID_PARAMS,
	INVALID_RESOURCE,
	LOAD_FAILED,
	INVALID_DIRECTORY
}

func load_resources(directories : Array[String], get_resource_id : Callable, polling_period : float = 0.1) -> void:
	var res_map : Dictionary[String, Object] = {}
	var load_list : Dictionary[String, String] = {}

	if directories == null:
		on_error.emit(ResourceLoadError.INVALID_PARAMS, "")
		return

	for dir_path in directories: # TODO : Recursive
		if dir_path == null:
			on_error.emit(ResourceLoadError.INVALID_PARAMS,dir_path)
		var correct_path :=  dir_path if dir_path.ends_with("/") else "%s/" % (dir_path)
		var res_path := ResourceLoader.list_directory(dir_path)
		for file_name in res_path:
			var id : String = get_resource_id.call(file_name)
			if not(id == null or id == ""):
				var fullname := correct_path + file_name
				if ResourceLoader.load_threaded_request(fullname) != OK:
					on_error.emit(ResourceLoadError.LOAD_FAILED, id)
				else:
					res_map[id] = null
					load_list[id] = fullname

	var total_item_count := load_list.size()
	on_progress.emit(0.0)

	var timer : Timer = Timer.new()
	add_child(timer)
	timer.set_autostart(false)
	timer.set_one_shot(false)
	timer.timeout.connect(_load_loop.bind(res_map, load_list, float(total_item_count), timer))
	timer.start(polling_period)

func _load_loop(res_map : Dictionary[String, Object], load_list : Dictionary[String, String], total_count : float, timer : Timer) -> void:
	for r in res_map:
		if res_map[r] == null:
			var fullname := load_list[r]
			var to_erase = true
			match ResourceLoader.load_threaded_get_status(fullname):
				ResourceLoader.THREAD_LOAD_INVALID_RESOURCE:
					on_error.emit(ResourceLoadError.INVALID_RESOURCE, r)
				ResourceLoader.THREAD_LOAD_FAILED:
					on_error.emit(ResourceLoadError.LOAD_FAILED, r)
				ResourceLoader.THREAD_LOAD_LOADED:
					res_map[r] = ResourceLoader.load_threaded_get(fullname)
				ResourceLoader.THREAD_LOAD_IN_PROGRESS:
					to_erase = false
			if to_erase:
				load_list.erase(r)
	on_progress.emit((total_count - load_list.size()) / total_count)

	if load_list.is_empty():
		timer.timeout.disconnect(_load_loop.bind(res_map, load_list, total_count, timer))
		timer.queue_free()
		on_loaded.emit(res_map)

Comments