Save the quiz and continue it after a restart; load characters from a folder

The quiz is saved to current_quiz.json in the config folder after every
change, and the game goes on where it was when it starts again: the
players with their points and characters, every song with who got a point
for it and whether it was played, answered or is playing, and the songs
downloaded ahead with their files. The song that was playing is ready to
play again. Songs whose files are gone are downloaded again.

On a server, the saved songs are checked against the server's playlist. If
it changed, e.g. after a sync, or another server is used, the quiz starts
over with the same players. A quiz from a music folder continues offline,
including how far a prepared quiz has come. A new game is saved like any
other change, and a file that can't be read starts a new quiz.

Characters can be read from a folder picked in Settings instead of the
server, for this session. A music folder with a characters folder brings
its own characters, e.g. for a themed quiz; that folder is not counted as
a soundtrack. When the characters come from somewhere else, players pick
their characters again.

Closes #11, closes #44

data/music_folder.gd

@@ -8,19 +8,25 @@ extends RefCounted
 ## order or at random, and only the song's name is the answer.
 ##
 ## Hidden files and folders, and files the game can't play (see [AudioFile]), are left
-## out.
+## out. A subfolder called [code]characters[/code] holds the quiz's own characters
+## instead of songs, see [member characters_path].
 
 enum Kind { EMPTY, SOUNDTRACKS, PREPARED_QUIZ }
 enum PlayOrder { IN_ORDER, RANDOM }
 
 ## How many files are tried before giving up when files can't be read.
 const MAX_TRIES: int = 20
+## The subfolder with the quiz's own characters. Any case, e.g. "Characters", works.
+const CHARACTERS_FOLDER: String = "characters"
 
 ## The folder's path.
 var path: String = ""
 var kind: Kind = Kind.EMPTY
 ## How a prepared quiz is played. Change it with [method set_play_order].
 var play_order: PlayOrder = PlayOrder.IN_ORDER
+## The folder's [constant CHARACTERS_FOLDER] subfolder when it has pictures, so a themed
+## quiz can bring its own characters. Empty when there is none.
+var characters_path: String = ""
 
 # Soundtrack folder: soundtrack name -> paths of its songs
 var _soundtracks: Dictionary[String, PackedStringArray] = {}
@@ -35,7 +41,14 @@ var _quiz_next: int = 0
 static func scan(folder_path: String) -> MusicFolder:
 	var folder: MusicFolder = MusicFolder.new()
 	folder.path = folder_path.trim_suffix("/")
-	var subfolders: PackedStringArray = _visible(DirAccess.get_directories_at(folder.path))
+	var subfolders: PackedStringArray = []
+	for subfolder: String in _visible(DirAccess.get_directories_at(folder.path)):
+		if subfolder.to_lower() == CHARACTERS_FOLDER:
+			var characters: String = folder.path.path_join(subfolder)
+			if !FolderCharacters.picture_names(characters).is_empty():
+				folder.characters_path = characters
+		else:
+			subfolders.append(subfolder)
 	if !subfolders.is_empty():
 		for subfolder: String in subfolders:
 			var songs: PackedStringArray = _songs_in(folder.path.path_join(subfolder), true)
@@ -86,6 +99,35 @@ func restart() -> void:
 	_quiz_next = 0
 
 
+## How far a prepared quiz has come, to continue it after a restart with
+## [method restore_progress].
+func progress() -> Dictionary:
+	return {"play_order": play_order, "queue": Array(_quiz_queue), "next": _quiz_next}
+
+
+## Continues a prepared quiz from [param saved], as given by [method progress]. Songs
+## that are no longer in the folder are left out. Returns false, changing nothing, when
+## [param saved] does not fit this folder.
+func restore_progress(saved: Dictionary) -> bool:
+	if kind != Kind.PREPARED_QUIZ || !(saved.get("queue") is Array) \
+			|| !(saved.get("next") is float || saved.get("next") is int):
+		return false
+	var queue: PackedStringArray = []
+	var next: int = int(saved.next)
+	var known: Dictionary = {}
+	for song_path: String in _quiz_songs:
+		known[song_path] = true
+	for i: int in saved.queue.size():
+		if known.has(str(saved.queue[i])):
+			queue.append(str(saved.queue[i]))
+		elif i < int(saved.next):
+			next -= 1
+	play_order = int(saved.get("play_order", play_order)) as PlayOrder
+	_quiz_queue = queue
+	_quiz_next = clampi(next, 0, queue.size())
+	return true
+
+
 ## The next song to play, or null when a prepared quiz has played every song or no file
 ## can be read.
 func next_song() -> SongObject: