Refactor Phase 4: Migrate Resources, Path Centralization, Test Suite Stabilization, and Docs Alignment

config_resources/default_settings.tres

@@ -2,7 +2,7 @@
 
 [ext_resource type="PackedScene" uid="uid://dxep4xm1sl8im" path="res://scenes/key_mapping_menu.tscn" id="1_qho2n"]
 [ext_resource type="PackedScene" uid="uid://cl4m4q2eurcn0" path="res://scenes/options_menu.tscn" id="2_b4w4u"]
-[ext_resource type="Script" uid="uid://cgtk0ximoo5ty" path="res://scripts/game_settings_resource.gd" id="3_qb8m4"]
+[ext_resource type="Script" uid="uid://cgtk0ximoo5ty" path="res://scripts/resources/game_settings_resource.gd" id="3_qb8m4"]
 
 [resource]
 script = ExtResource("3_qb8m4")

files/docs/Development_Guide.md

@@ -81,22 +81,25 @@ else:
 
 - Tip: Use Tween for fades (e.g., modulate.a from 0 to 1).
 
-### Working with Game Settings (Observer Pattern)
-
-The project now uses an Observer Pattern for configuration.
-When adding a new setting:
-
-1. Define the Property: Add the property to
-   `scripts/game_settings_resource.gd` with
-   a proper setter that emits the `setting_changed` signal.
-2. Update Globals: Add the new property to the `_save_settings()` and
-   `_load_settings()` functions in globals.gd to ensure persistence.
-3. UI Integration: Connect your UI elements to the `Globals.settings.setting_changed`
-   signal.
-   - Crucial: Always disconnect this signal in `_on_tree_exited()` to prevent
-     memory leaks and stale observers.
-4. No Manual Saves: Do not call save functions directly from the UI; changing the
-   resource value is sufficient to trigger a save.
+### Adding a New Game Setting
+To introduce a new global setting (e.g., `difficulty`), follow this pattern:
+
+1. **Define the Property**: Add the variable to 
+   `res://scripts/resources/game_settings_resource.gd` with an `@export` 
+   annotation so it can be edited in the Godot inspector. Update the custom 
+   `_to_string` method. This resource holds the active state and emits a 
+   `setting_changed` signal upon modification.
+2. **Persist the Value**: Persistence is exclusively managed by `globals.gd`. 
+   Update `_save_settings()` and `_load_settings()` in `globals.gd` 
+   to ensure the new property from `game_settings_resource.gd` is read from 
+   and written to `user://settings.cfg` using `ConfigFile`.
+
+| Step               | File                                                | Action                                                                                          |
+|:-------------------|:----------------------------------------------------|:------------------------------------------------------------------------------------------------|
+| 1. Definition      | `res://scripts/resources/game_settings_resource.gd` | Add `@export var property_name: Type = DefaultValue` and update `_to_string()`                  |
+| 2. Persistence     | `globals.gd`                                        | Add to ConfigFile `.set_value()` in `_save_settings()` and `.get_value()` in `_load_settings()` |
+| 3. Observer Signal | `globals.gd`                                        | Add the variable name to `_on_setting_changed` to filter log spam or prevent excessive disk I/O |
+| 4. UI Binding      | `res://scenes/options_menu.tscn`                    | Create slider/toggle and connect signals to update `Globals.settings.property_name`             |
 
 #### The technical documentation for the "Working with Game Settings" section
 
@@ -118,15 +121,15 @@ use the following signature:
   - `new_value`: **Variant** (The newly assigned, clamped value)
 
 #### 2. Core Files Reference
-
-| Component                  | File Path                                 | Responsibility                                                                    |
-|----------------------------|-------------------------------------------|-----------------------------------------------------------------------------------|
-| **Data Source (Subject)**  | `res://scripts/game_settings_resource.gd` | Defines properties (difficulty, log level), performs clamping, and emits signals. |
-| **Logic Observer**         | `res://scripts/globals.gd`                | Connects to the resource to trigger centralized logging and `_save_settings()`.   |
-| **UI Observer (Gameplay)** | `res://scripts/gameplay_settings.gd`      | Syncs sliders and labels with the resource state using `set_value_no_signal`.     |
-| **UI Observer (Advanced)** | `res://scripts/advanced_settings.gd`      | Syncs log level dropdowns and handles web-specific JavaScript callbacks.          |
-| **Persistence Settings**   | `res://scripts/settings.gd`               | Manages low-level `InputMap` serialization and legacy migration logic.            |
-
+<!-- markdownlint-disable MD033 -->
+| Component                           | File Path                                           | Responsibility                                                                             |
+|-------------------------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------|
+| **Data Source (Subject)**           | `res://scripts/resources/game_settings_resource.gd` | Defines properties (difficulty, log level), performs clamping, and emits signals.          |
+| <del>**Logic Observer**             | <del>`res://scripts/globals.gd`</del>               | <del>Connects to the resource to trigger centralized logging and `_save_settings()`.</del> |
+| **UI Observer (Gameplay)**          | `res://scripts/ui/menus/gameplay_settings.gd`       | Syncs sliders and labels with the resource state using `set_value_no_signal`.              |
+| **UI Observer (Advanced)**          | `res://scripts/ui/menus/advanced_settings.gd`       | Syncs log level dropdowns and handles web-specific JavaScript callbacks.                   |
+| <del>**Persistence Settings**</del> | <del>`res://scripts/settings.gd`</del>              | <del>Manages low-level `InputMap` serialization and legacy migration logic.</del>          |
+<!-- markdownlint-enable MD033 -->
 #### 3. Connection Example for UI
 
 To prevent infinite recursion, UI handlers should always check for equality or use `no_signal` methods when responding to the resource:

project.godot

@@ -26,9 +26,9 @@ general/default_playback_type.web=0
 
 Globals="*res://scripts/core/globals.gd"
 Settings="*res://scripts/core/settings.gd"
-AudioConstants="*res://scripts/audio_constants.gd"
+AudioConstants="*res://scripts/resources/audio_constants.gd"
 AudioManager="*res://scripts/managers/audio_manager.gd"
-AudioWebBridge="*res://scripts/audio_web_bridge.gd"
+AudioWebBridge="*res://scripts/system/audio_web_bridge.gd"
 
 [debug]
 

scenes/Player.tscn

@@ -1,6 +1,6 @@
 [gd_scene load_steps=7 format=3 uid="uid://37rarq1yywmc"]
 
-[ext_resource type="Script" uid="uid://bcplrymg5tt06" path="res://scripts/player.gd" id="1_tuyoq"]
+[ext_resource type="Script" uid="uid://bcplrymg5tt06" path="res://scripts/entities/player.gd" id="1_tuyoq"]
 [ext_resource type="PackedScene" uid="uid://bafpwe0qf0vm0" path="res://scenes/weapon.tscn" id="2_fjrip"]
 [ext_resource type="PackedScene" uid="uid://blc0ioe12jlnk" path="res://scenes/bullet.tscn" id="3_smehm"]
 [ext_resource type="PackedScene" uid="uid://bh47kclxgeeah" path="res://scenes/rotor_left.tscn" id="4_ur7pv"]

scenes/bullet.tscn

@@ -1,6 +1,6 @@
 [gd_scene load_steps=4 format=3 uid="uid://blc0ioe12jlnk"]
 
-[ext_resource type="Script" uid="uid://uyw8e8i6adxn" path="res://scripts/bullet.gd" id="1_mkf8s"]
+[ext_resource type="Script" uid="uid://uyw8e8i6adxn" path="res://scripts/entities/bullet.gd" id="1_mkf8s"]
 [ext_resource type="Texture2D" uid="uid://b7utqr70u1mex" path="res://files/sprite/laser_sprites/01.png" id="2_y25gk"]
 
 [sub_resource type="CircleShape2D" id="CircleShape2D_l5glv"]

scenes/main_scene.tscn

@@ -76,8 +76,8 @@
 [ext_resource type="Texture2D" uid="uid://btyfigdtk3x88" path="res://files/random_decor/crates_4.png" id="68_f3krf"]
 [ext_resource type="Texture2D" uid="uid://bvxu5x1awjrjv" path="res://files/random_decor/dirt_001.png" id="69_7tyuc"]
 [ext_resource type="Texture2D" uid="uid://f4hxu68qa4fi" path="res://files/random_decor/dirt_002.png" id="70_isor2"]
-[ext_resource type="Script" uid="uid://blu5qujicfa7e" path="res://scripts/hud.gd" id="72_sgkfd"]
-[ext_resource type="Script" uid="uid://b5x2ehdthhrla" path="res://scripts/parallax_manager.gd" id="76_qj6t7"]
+[ext_resource type="Script" uid="uid://blu5qujicfa7e" path="res://scripts/ui/hud.gd" id="72_sgkfd"]
+[ext_resource type="Script" uid="uid://b5x2ehdthhrla" path="res://scripts/managers/parallax_manager.gd" id="76_qj6t7"]
 
 [sub_resource type="StyleBoxFlat" id="StyleBoxFlat_pu3yx"]
 bg_color = Color(0.2627451, 0.2627451, 0.2627451, 0.5882353)

scenes/weapon.tscn

@@ -1,6 +1,6 @@
 [gd_scene load_steps=2 format=3 uid="uid://bafpwe0qf0vm0"]
 
-[ext_resource type="Script" uid="uid://dcr6gx3oaboj8" path="res://scripts/weapon.gd" id="1_xasec"]
+[ext_resource type="Script" uid="uid://dcr6gx3oaboj8" path="res://scripts/entities/weapon.gd" id="1_xasec"]
 
 [node name="WeaponManager" type="Node2D"]
 script = ExtResource("1_xasec")

scripts/core/game_paths.gd

@@ -0,0 +1,52 @@
+## Copyright (C) 2026 Egor Kostan
+## SPDX-License-Identifier: GPL-3.0-or-later
+## game_paths.gd
+## Centralized repository for all hardcoded script and scene paths.
+## Use this class to reference paths globally to avoid fragility and improve refactoring.
+
+class_name GamePaths
+extends RefCounted
+
+# =========================================================
+# SCRIPT PATHS
+# =========================================================
+
+## Path to the player entity script.
+const PLAYER: String = "res://scripts/entities/player.gd"
+
+## Path to the HUD UI script.
+const HUD: String = "res://scripts/ui/hud.gd"
+
+## Path to the audio web bridge system script.
+const AUDIO_WEB_BRIDGE: String = "res://scripts/system/audio_web_bridge.gd"
+
+## Path to the input remap button component script.
+const INPUT_REMAP_BUTTON: String = "res://scripts/ui/components/input_remap_button.gd"
+
+## Path to the gameplay settings menu script.
+const GAMEPLAY_SETTINGS: String = "res://scripts/ui/menus/gameplay_settings.gd"
+
+## Path to the core settings singleton/script.
+const SETTINGS: String = "res://scripts/core/settings.gd"
+
+# =========================================================
+# SCENE PATHS
+# =========================================================
+
+## Path to the audio settings menu scene.
+const AUDIO_SETTINGS_SCENE: String = "res://scenes/audio_settings.tscn"
+
+## Path to the main game scene.
+const MAIN_SCENE: String = "res://scenes/main_scene.tscn"
+
+## Path to the key mapping menu scene.
+const KEY_MAPPING_SCENE: String = "res://scenes/key_mapping_menu.tscn"
+
+## Path to the gameplay settings menu scene.
+const GAMEPLAY_SETTINGS_SCENE: String = "res://scenes/gameplay_settings.tscn"
+
+## Path to the pause menu scene.
+const PAUSE_MENU_SCENE: String = "res://scenes/pause_menu.tscn"
+
+## Path to the options menu scene.
+const OPTIONS_MENU_SCENE: String = "res://scenes/options_menu.tscn"

scripts/core/game_paths.gd.uid

@@ -0,0 +1 @@
+uid://cj4el7nxnxm07

test/gut/gut_test_helper.gd

@@ -4,7 +4,7 @@
 ## Shared helper functions and mock builders for GUT unit tests.
 extends RefCounted
 
-const PLAYER_SCRIPT_PATH: String = "res://scripts/player.gd"
+const PLAYER_SCRIPT_PATH: String = GamePaths.PLAYER
 
 
 ## Helper to safely hard-free a node without causing engine crashes.
@@ -60,7 +60,7 @@ static func build_mock_player_scene() -> Node:
 	panel.add_child(stats)
 
 	# Assign the extracted hud.gd script directly to the mock panel
-	var hud_script := load("res://scripts/hud.gd")
+	var hud_script := load(GamePaths.HUD)
 	if hud_script:
 		panel.set_script(hud_script)
 

test/gut/test_audio_reset_button.gd

@@ -8,7 +8,7 @@
 
 extends "res://addons/gut/test.gd"
 
-var audio_scene: PackedScene = load("res://scenes/audio_settings.tscn")
+var audio_scene: PackedScene = load(GamePaths.AUDIO_SETTINGS_SCENE)
 var audio_instance: Control
 var test_config_path: String = "user://test_reset.cfg"
 

test/gut/test_audio_web_bridge.gd

@@ -7,7 +7,7 @@
 
 extends "res://addons/gut/test.gd"
 
-const AudioWebBridge = preload("res://scripts/audio_web_bridge.gd")
+const AudioWebBridge = preload(GamePaths.AUDIO_WEB_BRIDGE)
 
 func before_each() -> void:
 	# Reset AudioManager to a known clean state before each test

test/gut/test_blank_key_labels_on_missing_config.gd

@@ -17,7 +17,7 @@
 
 extends GutTest
 
-const InputRemapButton := preload("res://scripts/input_remap_button.gd")
+const InputRemapButton := preload(GamePaths.INPUT_REMAP_BUTTON)
 
 const TEST_CONFIG_MISSING_PATH: String = "user://test_blank_missing.cfg"
 const TEST_CONFIG_PARTIAL_PATH: String = "user://test_blank_partial.cfg"

test/gut/test_decor_layer_transformations.gd

@@ -15,7 +15,7 @@ var viewport_mock: Vector2 = Vector2(1920, 1080)
 
 func before_each() -> void:
 	await get_tree().process_frame
-	main_scene = preload("res://scenes/main_scene.tscn").instantiate()
+	main_scene = preload(GamePaths.MAIN_SCENE).instantiate()
 	add_child(main_scene)
 	await get_tree().process_frame
 

test/gut/test_deduplication_on_device_switch.gd

@@ -8,7 +8,7 @@
 
 extends GutTest
 
-const InputRemapButton: Script = preload("res://scripts/input_remap_button.gd")
+const InputRemapButton: Script = preload(GamePaths.INPUT_REMAP_BUTTON)
 const TEST_ACTION: String = "speed_up"
 
 var button: InputRemapButton

test/gut/test_deduplication_on_rapid_remap.gd

@@ -8,7 +8,7 @@
 
 extends GutTest
 
-const InputRemapButton: Script = preload("res://scripts/input_remap_button.gd")
+const InputRemapButton: Script = preload(GamePaths.INPUT_REMAP_BUTTON)
 const TEST_ACTION: String = "speed_up"
 
 var button: InputRemapButton

test/gut/test_deduplication_on_remap.gd

@@ -8,7 +8,7 @@
 
 extends GutTest
 
-const InputRemapButton: Script = preload("res://scripts/input_remap_button.gd")
+const InputRemapButton: Script = preload(GamePaths.INPUT_REMAP_BUTTON)
 const TEST_ACTION: String = "speed_up"
 
 var button: InputRemapButton

test/gut/test_deduplication_on_reset.gd

@@ -20,7 +20,7 @@ func before_each() -> void:
 	def_ev.physical_keycode = KEY_W
 	InputMap.action_add_event(TEST_ACTION, def_ev)
 	InputMap.action_add_event(TEST_ACTION, def_ev.duplicate())  # Duplicate
-	menu = load("res://scenes/key_mapping_menu.tscn").instantiate()
+	menu = load(GamePaths.KEY_MAPPING_SCENE).instantiate()
 	add_child(menu)
 	menu.keyboard.button_pressed = true  # Keyboard mode
 

test/gut/test_fuel_additional_edge_cases.gd

@@ -28,7 +28,7 @@ func test_fuel_consumption_with_scaling() -> void:
 
 	# NEW: Instantiate the main scene locally and use GUT's add_child_autoqfree().
 	# This ensures the scene and all its dynamically generated Sprite2D children are safely queued for deletion.
-	main_scene = load("res://scenes/main_scene.tscn").instantiate()
+	main_scene = load(GamePaths.MAIN_SCENE).instantiate()
 	add_child_autoqfree(main_scene)
 	player_root = main_scene.get_node("Player")
 	player_root.fuel_timer.stop()

test/gut/test_fuel_integration.gd

@@ -2,6 +2,7 @@
 ## SPDX-License-Identifier: GPL-3.0-or-later
 ## test_fuel_integration_gut.gd
 ## GUT integration tests for Fuel System signals and persistence.
+
 extends "res://addons/gut/test.gd"
 
 const TEST_CONFIG_PATH: String = "user://test_fuel_persistence.cfg"

test/gut/test_game_settings_resource.gd

@@ -10,7 +10,7 @@
 
 extends "res://addons/gut/test.gd"
 
-const GameplaySettings = preload("res://scripts/gameplay_settings.gd")
+const GameplaySettings = preload(GamePaths.GAMEPLAY_SETTINGS)
 var gameplay_menu: Control
 var _resource: GameSettingsResource
 
@@ -20,7 +20,7 @@ func before_each() -> void:
 	Globals.settings = _resource
 
 	# Instantiate the menu for initialization tests
-	gameplay_menu = load("res://scenes/gameplay_settings.tscn").instantiate()
+	gameplay_menu = load(GamePaths.GAMEPLAY_SETTINGS_SCENE).instantiate()
 	# Inject mock wrapper to avoid real JS/OS calls during unit tests
 	gameplay_menu.os_wrapper = OSWrapper.new() 
 
@@ -74,7 +74,7 @@ func test_gs_ready_01_02_ui_initialization_sync() -> void:
 	var test_difficulty: float = 1.7
 	_resource.difficulty = test_difficulty
 
-	var new_menu: Variant = load("res://scenes/gameplay_settings.tscn").instantiate()
+	var new_menu: Variant = load(GamePaths.GAMEPLAY_SETTINGS_SCENE).instantiate()
 	add_child_autofree(new_menu)
 	await get_tree().process_frame
 
@@ -121,7 +121,7 @@ func test_gs_ready_06_safe_init_non_web() -> void:
 	stub(mock_os, "has_feature").to_return(false)
 
 	# FIX: Instantiate from the SCENE, not just the script
-	var menu: Control = load("res://scenes/gameplay_settings.tscn").instantiate()
+	var menu: Control = load(GamePaths.GAMEPLAY_SETTINGS_SCENE).instantiate()
 	menu.os_wrapper = mock_os
 
 	add_child_autofree(menu)

test/gut/test_gameplay_settings_js.gd

@@ -7,13 +7,13 @@
 
 extends "res://addons/gut/test.gd"
 
-const GameplaySettings = preload("res://scripts/gameplay_settings.gd")
+const GameplaySettings = preload(GamePaths.GAMEPLAY_SETTINGS)
 var gameplay_menu: Control
 
 func before_each() -> void:
 	# Fresh resource to isolate state
 	Globals.settings = GameSettingsResource.new()
-	gameplay_menu = load("res://scenes/gameplay_settings.tscn").instantiate()
+	gameplay_menu = load(GamePaths.GAMEPLAY_SETTINGS_SCENE).instantiate()
 	# Inject mock wrapper to simulate web environment
 	gameplay_menu.os_wrapper = OSWrapper.new() 
 	add_child_autofree(gameplay_menu)

test/gut/test_gameplay_settings_lifecycle.gd

@@ -6,12 +6,12 @@
 
 extends "res://addons/gut/test.gd"
 
-const GameplaySettings = preload("res://scripts/gameplay_settings.gd")
+const GameplaySettings = preload(GamePaths.GAMEPLAY_SETTINGS)
 var gameplay_menu: Control
 
 func before_each() -> void:
 	Globals.settings = GameSettingsResource.new()
-	gameplay_menu = load("res://scenes/gameplay_settings.tscn").instantiate()
+	gameplay_menu = load(GamePaths.GAMEPLAY_SETTINGS_SCENE).instantiate()
 	gameplay_menu.os_wrapper = OSWrapper.new() 
 	add_child_autofree(gameplay_menu)
 	await get_tree().process_frame
@@ -56,7 +56,7 @@ func test_gs_life_02_back_button_restoration() -> void:
 
 ## GS-LIFE-08 | Web overlay visibility cleanup
 func test_gs_life_08_web_overlay_cleanup() -> void:
-	var test_menu: Control = load("res://scenes/gameplay_settings.tscn").instantiate()
+	var test_menu: Control = load(GamePaths.GAMEPLAY_SETTINGS_SCENE).instantiate()
 	var mock_js_bridge: Variant = double(JavaScriptBridgeWrapper).new()
 	var mock_os: Variant = double(OSWrapper).new()
 
@@ -93,7 +93,7 @@ func test_gs_life_05_null_globals_safety() -> void:
 ## GS-LIFE-09 | Unexpected removal (unintentional exit) restores previous menu
 func test_gs_life_09_unexpected_removal_restoration() -> void:
 	# 1. Setup: Create fresh instance but do not parent yet
-	var test_menu: Control = load("res://scenes/gameplay_settings.tscn").instantiate()
+	var test_menu: Control = load(GamePaths.GAMEPLAY_SETTINGS_SCENE).instantiate()
 
 	# 2. Mock a previous menu in the stack
 	var mock_prev: Control = Control.new()

test/gut/test_gameplay_settings_ui.gd

@@ -7,7 +7,7 @@
 
 extends "res://addons/gut/test.gd"
 
-const GameplaySettings = preload("res://scripts/gameplay_settings.gd")
+const GameplaySettings = preload(GamePaths.GAMEPLAY_SETTINGS)
 var gameplay_menu: Control
 var _resource: GameSettingsResource
 
@@ -16,7 +16,7 @@ func before_each() -> void:
 	_resource = GameSettingsResource.new()
 	Globals.settings = _resource
 
-	gameplay_menu = load("res://scenes/gameplay_settings.tscn").instantiate()
+	gameplay_menu = load(GamePaths.GAMEPLAY_SETTINGS_SCENE).instantiate()
 	# Inject mock wrapper to bypass real web/OS calls
 	gameplay_menu.os_wrapper = OSWrapper.new() 
 

test/gut/test_get_pause_binding_label_for_device.gd

@@ -7,7 +7,7 @@ extends GutTest
 var settings: Node
 
 func before_each() -> void:
-	settings = preload("res://scripts/settings.gd").new()
+	settings = preload(GamePaths.SETTINGS).new()
 	add_child_autofree(settings)
 
 	# Ensure clean input state