Decouple Fuel System using GameSettingsResource and Signals

scenes/main_scene.tscn

@@ -4,7 +4,7 @@
 [ext_resource type="PackedScene" uid="uid://cb4n4cqkuddqg" path="res://scenes/pause_menu.tscn" id="1_w2twt"]
 [ext_resource type="Texture2D" uid="uid://ce63ga8f5mua7" path="res://files/trees/tree_01.png" id="2_fm3ay"]
 [ext_resource type="FontFile" uid="uid://borwvgqdgawbj" path="res://files/fonts/EMPIREST.TTF" id="2_pu3yx"]
-[ext_resource type="PackedScene" uid="uid://37rarq1yywmc" path="res://scenes/player.tscn" id="2_pw63i"]
+[ext_resource type="PackedScene" uid="uid://37rarq1yywmc" path="res://scenes/Player.tscn" id="2_pw63i"]
 [ext_resource type="Script" uid="uid://csdce7ynrpivs" path="res://scripts/resource_preloader.gd" id="3_c1pb6"]
 [ext_resource type="Texture2D" uid="uid://bsmbcgovcph7p" path="res://files/trees/tree_02.png" id="3_sgkfd"]
 [ext_resource type="Texture2D" uid="uid://syw5eae1ebna" path="res://files/trees/tree_11.png" id="4_qj6t7"]

scripts/game_settings_resource.gd

@@ -15,6 +15,96 @@ extends Resource
 ## without the UI having to explicitly call persistence or logging methods.
 signal setting_changed(setting_name: String, new_value: Variant)
 
+## SIGNAL: fuel_depleted
+##
+## Emitted when current_fuel reaches exactly 0.0.
+## External systems (like the Player or UI) can connect to this to trigger
+## game-over states or low-fuel warnings without polling every frame.
+signal fuel_depleted
+
+@export_group("Fuel System")
+
+## Maximum fuel capacity.
+@export var max_fuel: float = 100.0:
+	set(value):
+		# NEW: Enforce a logical minimum capacity of 1.0. This prevents a misconfigured
+		# save file or options slider from shrinking the tank to 0.0 and
+		# accidentally triggering a runtime "Game Over" flameout.
+		var new_max: float = max(1.0, value)
+
+		if _max_fuel == new_max:
+			return
+		_max_fuel = new_max
+
+		# Use the backing field for comparisons, but trigger the public
+		# setter for current_fuel if needed
+		if _current_fuel > _max_fuel:
+			self.current_fuel = _max_fuel
+
+		setting_changed.emit("max_fuel", _max_fuel)
+	get:
+		return _max_fuel
+
+## Current fuel level. Clamped between 0.0 and max_fuel.
+@export var current_fuel: float = 100.0:
+	set(value):
+		# NEW: Use private backing field to safely clamp and check values without recursion
+		var old_value: float = _current_fuel
+		var new_fuel: float = clamp(value, 0.0, _max_fuel)
+
+		if _current_fuel == new_fuel:
+			return
+
+		_current_fuel = new_fuel
+
+		if old_value > 0.0 and _current_fuel == 0.0:
+			fuel_depleted.emit()
+
+		setting_changed.emit("current_fuel", _current_fuel)
+	get:
+		# NEW: Return the backing field
+		return _current_fuel
+
+## Base rate of fuel consumption per second.
+@export var base_consumption_rate: float = 1.0
+
+# NEW: Migrated thresholds from player.gd to centralize all fuel configuration
+@export var high_fuel_threshold: float = 90.0:
+	set(value):
+		if _high_fuel_threshold == value:
+			return
+		_high_fuel_threshold = value
+		setting_changed.emit("high_fuel_threshold", _high_fuel_threshold)
+	get:
+		return _high_fuel_threshold
+
+@export var medium_fuel_threshold: float = 50.0:
+	set(value):
+		if _medium_fuel_threshold == value:
+			return
+		_medium_fuel_threshold = value
+		setting_changed.emit("medium_fuel_threshold", _medium_fuel_threshold)
+	get:
+		return _medium_fuel_threshold
+
+@export var low_fuel_threshold: float = 30.0:
+	set(value):
+		if _low_fuel_threshold == value:
+			return
+		_low_fuel_threshold = value
+		setting_changed.emit("low_fuel_threshold", _low_fuel_threshold)
+	get:
+		return _low_fuel_threshold
+
+@export var no_fuel_threshold: float = 15.0:
+	set(value):
+		if _no_fuel_threshold == value:
+			return
+		_no_fuel_threshold = value
+		setting_changed.emit("no_fuel_threshold", _no_fuel_threshold)
+	get:
+		return _no_fuel_threshold
+
 @export_group("Logging")
 # Current log level: 0=DEBUG, 1=INFO, 2=WARNING, 3=ERROR, 4=NONE
 @export_range(0, 4, 1) var current_log_level: int = 1:
@@ -58,9 +148,20 @@ signal setting_changed(setting_name: String, new_value: Variant)
 @export var options_scene: PackedScene
 
 # Private member variables moved to bottom to satisfy class-definitions-order
+# NEW: GDScript requires backing fields to be declared BEFORE
+# the properties that reference them.
+# Moved these from the bottom of the script to the top to resolve
+# the "Identifier not declared" scope error.
+var _max_fuel: float = 100.0
+var _current_fuel: float = _max_fuel  # ← Automatically syncs to whatever max_fuel is
 var _current_log_level: int = 1
 var _difficulty: float = 1.0
 var _enable_debug_logging: bool = false
+# NEW: Add backing fields
+var _high_fuel_threshold: float = 90.0
+var _medium_fuel_threshold: float = 50.0
+var _low_fuel_threshold: float = 30.0
+var _no_fuel_threshold: float = 15.0
 
 
 func _init() -> void:
@@ -69,3 +170,13 @@ func _init() -> void:
 		key_mapping_scene = load("res://scenes/key_mapping_menu.tscn")
 	if not options_scene:
 		options_scene = load("res://scenes/options_menu.tscn")
+	# NEW: Safely enforce the invariant that a brand new resource
+	# always starts with a full tank, without bypassing the validation setters.
+	_current_fuel = _max_fuel
+
+
+## Helper method to increase fuel safely.
+## Increases fuel level by specified amount, clamped to max_fuel.
+func refuel(amount: float) -> void:
+	if amount > 0:
+		current_fuel += amount

scripts/globals.gd

@@ -79,10 +79,17 @@ func _on_setting_changed(setting_name: String, new_value: Variant) -> void:
 	var log_msg: String = "Setting '%s' updated to: %s" % [setting_name, str(new_value)]
 
 	# Automatically log the change
-	log_message(log_msg, LogLevel.DEBUG)
+	# OLD: log_message(log_msg, LogLevel.DEBUG)
+	# NEW: Prevent log spam by filtering out high-frequency runtime changes like fuel ticks
+	if setting_name != "current_fuel":
+		log_message(log_msg, LogLevel.DEBUG)
 
 	# Automatically persist to disk
-	_save_settings()
+	# OLD: _save_settings()
+	# NEW: Prevent disk I/O lag by stopping current_fuel from
+	# triggering a file save on every frame/timer tick
+	if setting_name != "current_fuel":
+		_save_settings()
 
 
 ## Centralized "ensure initial focus" helper.
@@ -151,7 +158,8 @@ func load_key_mapping(menu_to_hide: Node) -> void:
 	get_tree().root.add_child(km_instance)
 
 
-## Loads persisted settings from config if valid types; skips invalid/missing to keep current.
+## Loads persisted settings from config if valid types;
+## skips invalid/missing to keep current.
 ## :param path: Config file path (default: Settings.CONFIG_PATH).
 ## :type path: String
 ## :rtype: void
@@ -202,6 +210,26 @@ func _load_settings(path: String = Settings.CONFIG_PATH) -> void:
 					LogLevel.DEBUG
 				)
 
+		# NEW: Load the fuel related settings
+		if config.has_section_key("Settings", "max_fuel"):
+			var loaded_max: Variant = config.get_value("Settings", "max_fuel")
+			if loaded_max is float or loaded_max is int:
+				settings.max_fuel = float(loaded_max)
+			else:
+				log_message(
+					"Invalid type for max_fuel: " + str(typeof(loaded_max)), LogLevel.WARNING
+				)
+
+		if config.has_section_key("Settings", "current_fuel"):
+			var loaded_current: Variant = config.get_value("Settings", "current_fuel")
+			if loaded_current is float or loaded_current is int:
+				settings.current_fuel = float(loaded_current)
+			else:
+				log_message(
+					"Invalid type for current_fuel: " + str(typeof(loaded_current)),
+					LogLevel.WARNING
+				)
+
 		# Disable the guard and log a single summary instead
 		_is_loading_settings = false
 		log_message("All settings loaded and synchronized.", LogLevel.DEBUG)
@@ -226,6 +254,10 @@ func _save_settings(path: String = Settings.CONFIG_PATH) -> void:
 	config.set_value("Settings", "difficulty", settings.difficulty)
 	# NEW: Persist the debug logging flag
 	config.set_value("Settings", "enable_debug_logging", settings.enable_debug_logging)
+	# NEW: Persist the fuel settings
+	config.set_value("Settings", "max_fuel", settings.max_fuel)
+	config.set_value("Settings", "current_fuel", settings.current_fuel)
+
 	err = config.save(path)
 	if err != OK:
 		log_message("Failed to save settings: " + str(err), LogLevel.ERROR)
@@ -321,7 +353,9 @@ func _notification(what: int) -> void:
 
 		# Example: Save game state if you have a save system.
 		# Replace with your actual save function, e.g., from a save_manager.gd.
-		# save_game_state()  # Uncomment and implement as needed.
+		# OLD: # save_game_state()  # Uncomment and implement as needed.
+		# NEW: Explicitly save all settings (including current_fuel) right before the game quits
+		_save_settings()
 
 		# After cleanup, let the quit proceed (optional on desktop; auto on web).
 		get_tree().quit()

scripts/main_scene.gd

@@ -188,9 +188,16 @@ func setup_decor_layer(viewport: Vector2) -> void:
 func _process(delta: float) -> void:
 	var scroll_speed: float = player.speed["speed"] * delta * Globals.settings.difficulty * 0.8
 	background.scroll_offset.y += scroll_speed
-	if player.fuel["fuel"] <= 0:
+
+	# OLD: if player.fuel["fuel"] <= 0:
+	# NEW: Check the global settings resource for current fuel,
+	# since the local dictionary key was removed.
+	if Globals.settings.current_fuel <= 0:
 		background.scroll_offset = Vector2(0, 0)
 
+	# 1. Critical unbound controls warning (shown ONCE per session)
+	# Flag stays true until player fixes bindings (e.g., in key_mapping.gd after remap).
+
 	# 1. Critical unbound controls warning (shown ONCE per session)
 	# Flag stays true until player fixes bindings (e.g., in key_mapping.gd after remap).
 	# Do NOT reset here — that would make it repeat every 4s (bug fixed).