Cache character pictures and songs on disk

Character pictures are kept in characters/ next to the settings, with an
index.json of when the server last changed each one and when it was
downloaded. Only new or changed pictures are downloaded, using the server's new
/character/details. Older servers fall back to the name list, and pictures are
downloaded again after 7 days.

Downloaded songs are written to songs/ and only their paths are kept in memory.
The folder is emptied when the game starts and when the playlist resets.

common/character_cache.gd

@@ -0,0 +1,138 @@
+class_name CharacterCache
+extends RefCounted
+## Character pictures kept on disk in the [code]characters[/code] folder next to the
+## settings, so each one is downloaded only when it changed on the server.
+##
+## [code]index.json[/code] in the folder records, for each picture, when the server last
+## changed it and when it was downloaded:
+## [codeblock]
+## {"Crono.png": {"modified": 1730000000, "downloaded": 1730100000}}
+## [/codeblock]
+## A cached picture is used while the server's change time matches the index. Servers that
+## can't tell when pictures changed answer 404 for [code]/character/details[/code]; then a
+## cached picture is used until it is [constant MAX_AGE_SECONDS] old.
+
+const FOLDER_NAME: String = "characters"
+const INDEX_FILE_NAME: String = "index.json"
+## How long a picture is used before downloading it again, when the server can't tell
+## whether it changed.
+const MAX_AGE_SECONDS: int = 7 * 24 * 60 * 60
+## The change time of a picture when the server can't tell it.
+const UNKNOWN_TIME: int = -1
+
+# What index.json holds: name -> {"modified": int, "downloaded": int}
+var _index: Dictionary = {}
+# When the server last changed each picture on the list, or UNKNOWN_TIME
+var _modified: Dictionary[String, int] = {}
+
+
+## The folder the pictures are kept in.
+static func folder() -> String:
+	return Settings.config_dir().path_join(FOLDER_NAME)
+
+
+## Fetches the names of the characters and calls [param on_done] with them as an
+## [code]Array[String][/code]. Cached pictures of characters no longer on the server are
+## deleted.
+func load_list(on_done: Callable) -> void:
+	_load_index()
+	var details_fetched: Callable = func details_fetched(details: Array) -> void:
+		_modified.clear()
+		for character: CharacterDetails in details:
+			_modified[character.name] = character.modified
+		_list_loaded(on_done)
+	MusicServerClient.fetch_character_details(details_fetched, _load_names_only.bind(on_done))
+
+
+## Calls [param on_done] with the picture of [param character_name] as an [Image], from
+## disk when the cached one is still fresh, otherwise from the server.
+func fetch_image(character_name: String, on_done: Callable) -> void:
+	var path: String = _file_path(character_name)
+	if _is_fresh(character_name) && FileAccess.file_exists(path):
+		var cached: Image = CharacterCard.image_from_bytes(FileAccess.get_file_as_bytes(path))
+		if cached != null:
+			on_done.call(cached)
+			return
+		GameLog.warning("The cached picture of ", character_name, " is broken")
+	var image_fetched: Callable = func image_fetched(bytes: PackedByteArray) -> void:
+		var picture: Image = CharacterCard.image_from_bytes(bytes)
+		if picture == null:
+			GameLog.warning("Could not load the picture of ", character_name)
+			return
+		_store(character_name, bytes)
+		on_done.call(picture)
+	MusicServerClient.fetch_character_image(character_name, image_fetched)
+
+
+# Servers older than /character/details only list the names
+func _load_names_only(on_done: Callable) -> void:
+	var list_fetched: Callable = func list_fetched(list: Variant) -> void:
+		_modified.clear()
+		if list is Array:
+			for character_name: Variant in list:
+				_modified[str(character_name)] = UNKNOWN_TIME
+		_list_loaded(on_done)
+	MusicServerClient.fetch_character_list(list_fetched)
+
+
+func _list_loaded(on_done: Callable) -> void:
+	var removed: bool = false
+	for character_name: String in _index.keys():
+		if !_modified.has(character_name):
+			DirAccess.remove_absolute(_file_path(character_name))
+			_index.erase(character_name)
+			removed = true
+	if removed:
+		_save_index()
+	var names: Array[String] = []
+	names.assign(_modified.keys())
+	on_done.call(names)
+
+
+func _is_fresh(character_name: String) -> bool:
+	if !_index.has(character_name):
+		return false
+	var entry: Dictionary = _index[character_name]
+	var modified: int = _modified.get(character_name, UNKNOWN_TIME)
+	if modified != UNKNOWN_TIME:
+		return int(entry.get("modified", UNKNOWN_TIME)) == modified
+	var age: float = Time.get_unix_time_from_system() - float(entry.get("downloaded", 0))
+	return age < MAX_AGE_SECONDS
+
+
+func _store(character_name: String, bytes: PackedByteArray) -> void:
+	DirAccess.make_dir_recursive_absolute(folder())
+	var file: FileAccess = FileAccess.open(_file_path(character_name), FileAccess.WRITE)
+	if file == null:
+		GameLog.warning("Could not cache the picture of ", character_name, ": ",
+				error_string(FileAccess.get_open_error()))
+		return
+	file.store_buffer(bytes)
+	file.close()
+	_index[character_name] = {
+		"modified": _modified.get(character_name, UNKNOWN_TIME),
+		"downloaded": int(Time.get_unix_time_from_system()),
+	}
+	_save_index()
+
+
+func _load_index() -> void:
+	_index = {}
+	var path: String = folder().path_join(INDEX_FILE_NAME)
+	if FileAccess.file_exists(path):
+		var parsed: Variant = JSON.parse_string(FileAccess.get_file_as_string(path))
+		if parsed is Dictionary:
+			_index = parsed
+
+
+func _save_index() -> void:
+	var file: FileAccess = FileAccess.open(folder().path_join(INDEX_FILE_NAME),
+			FileAccess.WRITE)
+	if file != null:
+		file.store_string(JSON.stringify(_index, "\t", true))
+
+
+# The server's names are plain file names, but they are made safe anyway since they
+# become paths on this computer
+func _file_path(character_name: String) -> String:
+	return folder().path_join(character_name.validate_filename())