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

popups/SettingsPopup.tscn

@@ -106,6 +106,43 @@ popup/item_0/id = 0
 popup/item_1/text = "At random"
 popup/item_1/id = 1
 
+[node name="CharactersRow" type="HBoxContainer" parent="SettingsPanel/VBoxContainer"]
+layout_mode = 2
+
+[node name="Title" type="Label" parent="SettingsPanel/VBoxContainer/CharactersRow"]
+layout_mode = 2
+theme_type_variation = &"SettingsRowLabel"
+text = "Characters"
+
+[node name="CharactersLabel" type="Label" parent="SettingsPanel/VBoxContainer/CharactersRow"]
+unique_name_in_owner = true
+layout_mode = 2
+size_flags_horizontal = 3
+mouse_filter = 1
+text = "From the server"
+text_overrun_behavior = 3
+
+[node name="ChooseCharactersButton" type="Button" parent="SettingsPanel/VBoxContainer/CharactersRow"]
+unique_name_in_owner = true
+layout_mode = 2
+focus_mode = 0
+text = "Choose…"
+
+[node name="UseServerCharactersButton" type="Button" parent="SettingsPanel/VBoxContainer/CharactersRow"]
+unique_name_in_owner = true
+visible = false
+layout_mode = 2
+focus_mode = 0
+text = "Use server"
+
+[node name="CharactersErrorLabel" type="Label" parent="SettingsPanel/VBoxContainer"]
+unique_name_in_owner = true
+visible = false
+layout_mode = 2
+theme_type_variation = &"HighlightMedium"
+text = "No pictures found"
+text_overrun_behavior = 3
+
 [node name="FullscreenButton" type="CheckButton" parent="SettingsPanel/VBoxContainer" unique_id=400304684]
 unique_name_in_owner = true
 layout_mode = 2
@@ -182,3 +219,13 @@ ok_button_text = "Select Current Folder"
 file_mode = 2
 access = 2
 use_native_dialog = true
+
+[node name="CharacterFolderDialog" type="FileDialog" parent="."]
+unique_name_in_owner = true
+title = "Choose a folder of characters"
+initial_position = 2
+size = Vector2i(800, 500)
+ok_button_text = "Select Current Folder"
+file_mode = 2
+access = 2
+use_native_dialog = true

popups/character_card.gd

@@ -3,8 +3,11 @@ extends Panel
 ## One character in the character select popup: its picture and name. Clicking it picks
 ## the character.
 
-## Emitted with the character's picture when the card is clicked.
-signal new_character_selected(img_texture: ImageTexture)
+## Emitted with the character's picture and name when the card is clicked.
+signal new_character_selected(img_texture: ImageTexture, character_name: String)
+
+## The character's name: its picture's file name, e.g. "PaperMario.png".
+var character_name: String = ""
 
 @onready var character_image: TextureRect = %CharacterTextureRect
 @onready var character_name_label: Label = %CharacterName
@@ -19,12 +22,13 @@ func _ready() -> void:
 ## Shows [param character_name] and its picture. [param fetch_image] is called with the
 ## name and a Callable that takes the picture as an [Image], e.g.
 ## [method CharacterCache.fetch_image].
-func set_character_name(character_name: String, fetch_image: Callable) -> void:
-	character_name_label.text = display_name(character_name)
+func set_character_name(new_name: String, fetch_image: Callable) -> void:
+	character_name = new_name
+	character_name_label.text = display_name(new_name)
 	tooltip_text = character_name_label.text
 	var image_fetched: Callable = func image_fetched(picture: Image) -> void:
 		character_image.texture = ImageTexture.create_from_image(picture)
-	fetch_image.call(character_name, image_fetched)
+	fetch_image.call(new_name, image_fetched)
 
 
 ## The name to show for a picture's [param file_name]: without the file extension, and
@@ -58,4 +62,4 @@ func _on_gui_input(event: InputEvent) -> void:
 			&& event.button_index == MOUSE_BUTTON_LEFT && Settings.character_select_open:
 		accept_event()
 		GameLog.debug(character_name_label.text)
-		new_character_selected.emit(character_image.texture)
+		new_character_selected.emit(character_image.texture, character_name)

popups/character_select_popup.gd

@@ -1,13 +1,24 @@
 class_name CharacterSelectPopup
 extends BasePopup
+## The characters players pick from, from the server or from a folder on this computer
+## (see [method Settings.characters_dir]).
 
-## Emitted with the picture of the character that was picked.
-signal character_selected(texture: ImageTexture)
+## Emitted with the picture and name of the character that was picked.
+signal character_selected(texture: ImageTexture, character_name: String)
+
+## Emitted when the characters come from somewhere else than before, e.g. a folder was
+## picked. Characters picked before are not in the new set.
+signal source_changed
 
 var can_select_character: bool = false
 var character: PackedScene = preload("res://popups/CharacterCard.tscn")
 ## Keeps the pictures on disk, so only changed ones are downloaded.
 var character_cache: CharacterCache = CharacterCache.new()
+## Where the characters shown come from: [member character_cache] or a [FolderCharacters].
+var source: RefCounted = character_cache
+## The folder the characters shown come from, or empty for the server. Null before the
+## characters were first loaded.
+var source_dir: Variant = null
 
 @onready var character_panel: Panel = %CharacterPanel
 @onready var title_label: Label = %TitleLabel
@@ -25,18 +36,30 @@ func _on_close_timeout() -> void:
 	close_timer.stop()
 
 
+## Loads the characters from where [method Settings.characters_dir] says. Emits
+## [signal source_changed] when that is somewhere else than last time.
 func load_characters() -> void:
 	GameLog.debug("load_characters")
+	var dir: String = Settings.characters_dir()
+	var changed: bool = source_dir != null && source_dir != dir
+	source_dir = dir
+	source = character_cache if dir.is_empty() else FolderCharacters.new(dir)
+	var loading: RefCounted = source
 	var list_loaded: Callable = func list_loaded(names: Array[String]) -> void:
 		GameLog.debug("list_loaded")
+		# The source changed again before the server answered
+		if source != loading:
+			return
 		Settings.delete_children(character_grid)
 		for character_name: String in names:
 			GameLog.debug("character_name ", character_name)
 			var character_box: CharacterCard = character.instantiate()
 			character_grid.add_child(character_box)
-			character_box.set_character_name(character_name, character_cache.fetch_image)
+			character_box.set_character_name(character_name, loading.fetch_image)
 			character_box.new_character_selected.connect(_on_character_selected)
-	character_cache.load_list(list_loaded)
+	loading.load_list(list_loaded)
+	if changed:
+		source_changed.emit()
 
 
 func show_grid(player_name: String) -> void:
@@ -53,12 +76,12 @@ func close() -> void:
 	Settings.character_select_open = false
 
 
-func _on_character_selected(texture: ImageTexture) -> void:
+func _on_character_selected(texture: ImageTexture, character_name: String) -> void:
 	GameLog.debug("_on_character_selected")
 	# Not close(): character_select_open stays true until close_timer fires, so the click
 	# that picked the character does not also select a song behind it
 	visible = false
 	if can_select_character:
-		character_selected.emit(texture)
+		character_selected.emit(texture, character_name)
 		close_timer.start()
 		can_select_character = false

popups/settings_popup.gd

@@ -7,6 +7,8 @@ extends BasePopup
 ##
 ## A music folder (see [MusicFolder]) is used instead of the server until Use server is
 ## pressed or the game is closed. The settings that need the server are off meanwhile.
+## A folder of characters (see [FolderCharacters]) is used the same way; without one, a
+## music folder's own [code]characters[/code] folder is used, or else the server's.
 ##
 ## The quiz settings, such as the winning score, are in [QuizSettingsCard].
 
@@ -14,6 +16,9 @@ extends BasePopup
 ## order is changed. A new game starts.
 signal server_changed
 
+## Emitted when a folder of characters is picked or Use server is pressed for them.
+signal characters_changed
+
 ## Space between the rows and the panel's edges.
 const PADDING: Vector2 = Vector2(20, 12)
 
@@ -33,6 +38,11 @@ const PADDING: Vector2 = Vector2(20, 12)
 @onready var play_order_row: HBoxContainer = %PlayOrderRow
 @onready var play_order_button: OptionButton = %PlayOrderButton
 @onready var folder_dialog: FileDialog = %FolderDialog
+@onready var characters_label: Label = %CharactersLabel
+@onready var choose_characters_button: Button = %ChooseCharactersButton
+@onready var use_server_characters_button: Button = %UseServerCharactersButton
+@onready var characters_error_label: Label = %CharactersErrorLabel
+@onready var character_folder_dialog: FileDialog = %CharacterFolderDialog
 @onready var open_config_folder_button: Button = %OpenConfigFolderButton
 
 ## Shows a folder in the system's file manager. The tests replace it, so no file manager
@@ -54,6 +64,9 @@ func _ready() -> void:
 	choose_folder_button.pressed.connect(folder_dialog.popup_centered)
 	folder_dialog.dir_selected.connect(use_music_folder)
 	use_server_button.pressed.connect(use_server)
+	choose_characters_button.pressed.connect(character_folder_dialog.popup_centered)
+	character_folder_dialog.dir_selected.connect(use_character_folder)
+	use_server_characters_button.pressed.connect(use_server_characters)
 	open_config_folder_button.pressed.connect(open_config_folder)
 	open_config_folder_button.tooltip_text = Settings.config_dir()
 	play_order_button.item_selected.connect(_on_play_order_selected)
@@ -104,6 +117,26 @@ func open_config_folder() -> void:
 	show_folder.call(dir)
 
 
+## Reads the characters from the folder at [param path] instead of the server. A folder
+## without pictures is not used, and the popup says so.
+func use_character_folder(path: String) -> void:
+	if FolderCharacters.picture_names(path).is_empty():
+		characters_error_label.text = "No pictures found in " + path.trim_suffix("/").get_file()
+		characters_error_label.visible = true
+		_fit_to_rows()
+		return
+	Settings.character_folder = path.trim_suffix("/")
+	_show_music_source()
+	characters_changed.emit()
+
+
+## Uses the server's characters again, or the music folder's own if it has them.
+func use_server_characters() -> void:
+	Settings.character_folder = ""
+	_show_music_source()
+	characters_changed.emit()
+
+
 func lower_cache() -> void:
 	Playlist.number_of_tracks_to_preload = maxi(Playlist.number_of_tracks_to_preload - 1, 1)
 	cache_label.text = str(Playlist.number_of_tracks_to_preload)
@@ -141,6 +174,7 @@ func _on_visibility_changed() -> void:
 		add_to_database_button.set_pressed_no_signal(Settings.add_to_stats)
 	else:
 		folder_error_label.visible = false
+		characters_error_label.visible = false
 		_fit_to_rows()
 
 
@@ -162,6 +196,15 @@ func _show_music_source() -> void:
 		folder_label.text = folder.display_name()
 		folder_label.tooltip_text = folder.path
 	play_order_row.visible = folder != null && folder.kind == MusicFolder.Kind.PREPARED_QUIZ
+	characters_error_label.visible = false
+	use_server_characters_button.visible = !Settings.character_folder.is_empty()
+	characters_label.tooltip_text = Settings.characters_dir()
+	if !Settings.character_folder.is_empty():
+		characters_label.text = Settings.character_folder.get_file()
+	elif !Settings.characters_dir().is_empty():
+		characters_label.text = "From " + folder.display_name()
+	else:
+		characters_label.text = "From the server"
 	for control: BaseButton in [select_server_button, low_played_button, add_to_database_button]:
 		control.disabled = folder != null
 	_fit_to_rows()