Implement a dedicated slider.wav sound effect that triggers only during manual slider adjustments

.all-contributorsrc

@@ -6,5 +6,6 @@
   "files": ["README.md"],
   "imageSize": 100,
   "contributorsPerLine": 7,
+  "contributors": [],
   "badgeTemplate": "[<image-card alt=\"All Contributors\" src=\"https://img.shields.io/github/all-contributors/<%= projectOwner %>/<%= projectName %>?color=ee8449&style=flat-square\" ></image-card>](<%= contributorsUrl %>)"
 }

README.md

@@ -77,6 +77,7 @@ You can play this game on [Itch.io](https://ikostan.itch.io/sky-lock-assault)
    - [Release Drafter](https://github.com/release-drafter/release-drafter?tab=readme-ov-file#readme)
    - [Close Stale Issues and PRs](https://github.com/actions/stale)
    - [AllContributors GitHub App](https://allcontributors.org/docs/en/bot/installation)
+   - [DeepSource](https://github.com/deepsource)
 9. [Free Web Browser Game Deployment Platforms](files/docs/Platforms_for_Web_Deployment_Guide.md)
 <!-- markdownlint-enable line-length -->
 
@@ -145,6 +146,21 @@ these GPL requirements, a separate license is available upon request.
 - Observer-based Settings System: Centralized GameSettingsResource that handles
   automatic persistence and UI synchronization through signals.
 
+
+### Project Structure (`scripts/`)
+
+Post-Refactor Phase 4 (PR `#582`), the root `scripts/` directory has been fully
+reorganised into purpose-specific sub-directories:
+<!-- markdownlint-disable MD013 -->
+| Directory            | Contents                                                                                                                                                                                     |
+|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `scripts/core/`      | Foundational systems: `game_paths.gd` (centralised path registry), `globals.gd`, `main_scene.gd`, `settings.gd`                                                                              |
+| `scripts/resources/` | Data containers & configuration: `game_settings_resource.gd`, `audio_constants.gd`                                                                                                           |
+| `scripts/entities/`  | Game objects: `player.gd`, `bullet.gd`, `weapon.gd`                                                                                                                                          |
+| `scripts/system/`    | Platform wrappers & integrations: `audio_web_bridge.gd`, `JavaScriptBridgeWrapper.gd`, `OSWrapper.gd`                                                                                        |
+| `scripts/managers/`  | Game-loop managers: `audio_manager.gd`, `parallax_manager.gd`, `resource_preloader.gd`                                                                                                       |
+| `scripts/ui/`        | Interface layer: `hud.gd`; sub-dirs `menus/` (main, pause, options, audio, gameplay, key-mapping, advanced), `screens/` (splash, loading), `components/` (volume slider, input remap button) |
+<!-- markdownlint-enable MD013 -->
 ---
 
 ## 🟢 Current Development Status
@@ -289,6 +305,19 @@ to user input devices:
 - Modifier-aware remapping requires explicit key+modifier press for
   unique bindings.
 
+###  Milestone 14
+
+**Status:** Stable gameplay loop with synced UI systems and GUT-based
+unit testing.
+**Active Focus:** Gameplay expansion (AI enemies, multiplayer, levels).
+**Version:** v0.9.18
+
+### Milestone 16
+
+**Status:** Stable gameplay loop with fully refactored script architecture, 
+synced UI systems, and GUT-based unit testing.
+**Active Focus:** Gameplay expansion (AI enemies, multiplayer, levels).
+
 Track progress via [Milestones](https://github.com/ikostan/SkyLockAssault/milestones).
 
 ---

files/sounds/sfx/slider.wav.import

@@ -0,0 +1,24 @@
+[remap]
+
+importer="wav"
+type="AudioStreamWAV"
+uid="uid://6asmf6p6ftp5"
+path="res://.godot/imported/slider.wav-562467666e90bfee2364ab6985972073.sample"
+
+[deps]
+
+source_file="res://files/sounds/sfx/slider.wav"
+dest_files=["res://.godot/imported/slider.wav-562467666e90bfee2364ab6985972073.sample"]
+
+[params]
+
+force/8_bit=false
+force/mono=false
+force/max_rate=false
+force/max_rate_hz=44100
+edit/trim=false
+edit/normalize=false
+edit/loop_mode=0
+edit/loop_begin=0
+edit/loop_end=-1
+compress/mode=2

scripts/core/globals.gd

@@ -377,7 +377,8 @@ static func set_game_version_for_tests(value: String) -> void:
 ## Use _input instead of _unhandled_input to catch events BEFORE the UI consumes them.
 func _input(_event: InputEvent) -> void:
 	# The Ultimate Menu Check: Does a UI element currently have keyboard/gamepad focus?
-	var ui_has_focus: bool = is_instance_valid(get_viewport().gui_get_focus_owner())
+	var focus_owner: Control = get_viewport().gui_get_focus_owner()
+	var ui_has_focus: bool = is_instance_valid(focus_owner)
 
 	# Gate 1: Only play UI sounds if a UI element is focused OR we are in a known menu state
 	var is_menu_context: bool = (
@@ -392,6 +393,11 @@ func _input(_event: InputEvent) -> void:
 		# We use the global Input singleton here because it perfectly handles
 		# analog joystick deadzone debouncing, which event.is_echo() misses.
 		if Input.is_action_just_pressed(action):
+			# NEW: Prevent double-audio when adjusting sliders.
+			# If a slider has focus, left/right adjusts the value instead of navigating.
+			if focus_owner is Slider and (action == "ui_left" or action == "ui_right"):
+				return
+
 			_play_ui_navigation_sfx()
 			return  # Exit once sound is triggered to avoid double-plays
 

scripts/managers/audio_manager.gd

@@ -12,6 +12,13 @@ signal volume_changed(bus_name: String, volume: float)
 signal mute_toggled(bus_name: String, is_muted: bool)
 # --------------------------------------------
 
+# --- NEW: SFX CACHING & MANAGEMENT ---
+## Base path for all UI sound effects.
+const SFX_DIR_PATH: String = "res://files/sounds/sfx/"
+
+## Hard cap for cached SFX streams to prevent unbounded memory growth.
+const MAX_SFX_CACHE_SIZE: int = 20
+
 @export_category("Master Volume")
 @export var master_volume: float
 @export var master_muted: bool
@@ -31,6 +38,9 @@ signal mute_toggled(bus_name: String, is_muted: bool)
 @export var menu_muted: bool
 
 var current_config_path: String = Settings.CONFIG_PATH
+# --- NEW: SFX CACHING & MANAGEMENT ---
+## Dictionary to store preloaded AudioStreams to prevent disk I/O stutter.
+var _sfx_cache: Dictionary = {}
 
 
 func _ready() -> void:
@@ -333,3 +343,68 @@ func reset_volumes() -> void:
 	apply_all_volumes()
 	save_volumes()
 	Globals.log_message("Audio volumes reset to defaults.", Globals.LogLevel.DEBUG)
+
+
+## Centralized SFX Playback API (Issue #565)
+## Handles non-positional audio with LRU caching and auto-cleanup.
+## :param sfx_name: The filename without extension (e.g., "slider").
+## :param bus_name: Target audio bus (defaults to SFX_Menu).
+## :param pitch_scale: Pitch override for variety.
+## :param volume_db: Volume offset in decibels.
+func play_sfx(
+	sfx_name: String,
+	bus_name: String = AudioConstants.BUS_SFX_MENU,
+	pitch_scale: float = 1.0,
+	volume_db: float = 0.0
+) -> void:
+	if sfx_name.is_empty():
+		return
+
+	# 1. Resolve and Cache the AudioStream (with LRU Eviction)
+	if not _sfx_cache.has(sfx_name):
+		var full_path: String = SFX_DIR_PATH + sfx_name + ".wav"
+		var stream: AudioStream = load(full_path)
+
+		if stream:
+			# Eviction strategy: If cache is full, remove the oldest (first) entry
+			if _sfx_cache.size() >= MAX_SFX_CACHE_SIZE:
+				var oldest_key: String = _sfx_cache.keys()[0]
+				_sfx_cache.erase(oldest_key)
+				Globals.log_message(
+					"SFX cache full. Evicted: " + oldest_key, Globals.LogLevel.DEBUG
+				)
+
+			_sfx_cache[sfx_name] = stream
+		else:
+			Globals.log_message(
+				"SFX file not found or failed to load: " + full_path, Globals.LogLevel.WARNING
+			)
+			return
+	else:
+		# LRU Update: Godot 4 Dictionaries preserve insertion order.
+		# By erasing and re-inserting, we push this active sound to the "newest" end of the dictionary.
+		var stream: AudioStream = _sfx_cache[sfx_name]
+		_sfx_cache.erase(sfx_name)
+		_sfx_cache[sfx_name] = stream
+
+	# 2. Instantiate and Configure the Player
+	var player := AudioStreamPlayer.new()
+	add_child(player)
+
+	player.stream = _sfx_cache[sfx_name]
+	player.pitch_scale = pitch_scale
+	player.volume_db = volume_db
+
+	# 3. Bus Validation & Routing
+	if AudioServer.get_bus_index(bus_name) == -1:
+		Globals.log_message(
+			"Invalid bus '%s' requested for SFX. Falling back to SFX_Menu." % bus_name,
+			Globals.LogLevel.WARNING
+		)
+		player.bus = AudioConstants.BUS_SFX_MENU
+	else:
+		player.bus = bus_name
+
+	# 4. Play and Auto-Cleanup
+	player.play()
+	player.finished.connect(player.queue_free)

scripts/resources/audio_constants.gd

@@ -7,13 +7,19 @@
 
 extends Node
 
+# --- Audio Bus Names ---
 const BUS_MASTER: String = "Master"
 const BUS_MUSIC: String = "Music"
 const BUS_SFX: String = "SFX"
 const BUS_SFX_ROTORS: String = "SFX_Rotors"
 const BUS_SFX_WEAPON: String = "SFX_Weapon"
 const BUS_SFX_MENU: String = "SFX_Menu"
 
+# --- SFX Asset IDs ---
+const SFX_SLIDER: String = "slider"
+const SFX_MUTE_TOGGLE: String = "mute_toggle"  # For future CheckButton task
+const SFX_UI_NAVIGATION: String = "ui_navigation"
+
 # Centralized config with defaults and var mappings
 const BUS_CONFIG: Dictionary = {
 	BUS_MASTER:

scripts/ui/components/volume_slider.gd

@@ -1,48 +1,157 @@
 ## Copyright (C) 2025 Egor Kostan
 ## SPDX-License-Identifier: GPL-3.0-or-later
-# New: Register as global class for testing and reuse
-class_name VolumeSlider
+## volume_slider.gd
+##
+## Handles the volume control slider UI component.
+## Sends volume updates to AudioManager and handles debounced saving.
+## Plays rate-limited SFX exclusively on manual user interactions,
+## safely ignoring programmatic volume changes to prevent audio spam.
 
+class_name VolumeSlider
 extends HSlider
 
+## The cooldown in milliseconds to prevent audio spam during rapid slider drags.
+const SFX_COOLDOWN_MS: int = 60
+
+## The name of the audio bus this slider controls (e.g., "Master", "Music").
 @export var bus_name: String
+
+## The internal index of the audio bus, resolved at runtime.
 var bus_index: int
 
-# New: Debounce timer for saving settings
+## Debounce timer for saving settings to avoid disk I/O spam during continuous sliding.
 var save_debounce_timer: Timer
 
+# --- SFX Rate Limiting and State ---
+
+## Timestamp of the last played SFX to enforce the cooldown.
+var _last_sfx_time: int = 0
+
+## Tracks the previous value to ensure SFX only plays on actual deltas.
+var _previous_value: float = -1.0
+
+## Tracks whether the user is actively holding the mouse button down over the slider.
+var _is_dragging: bool = false
 
+
+## Initializes the slider, resolves the bus index, syncs the initial value without
+## triggering signals, and sets up the debounce timer.
+## :rtype: void
 func _ready() -> void:
 	# Get bus id by name
 	bus_index = AudioServer.get_bus_index(bus_name)
 
+	# Guard against invalid audio bus names to avoid runtime errors
+	if bus_index == -1:
+		var err_msg: String = (
+			"VolumeSlider Error: Invalid audio bus name '%s'. Disabling slider." % bus_name
+		)
+		Globals.log_message(err_msg, Globals.LogLevel.ERROR)
+
+		# Kill all interactions on this dead component
+		editable = false
+		mouse_filter = Control.MOUSE_FILTER_IGNORE
+		focus_mode = Control.FOCUS_NONE
+		return
+
 	# Set current bus volume value first (without triggering signal yet)
-	value = db_to_linear(AudioServer.get_bus_volume_db(bus_index))
+	var initial_val: float = db_to_linear(AudioServer.get_bus_volume_db(bus_index))
+	_previous_value = initial_val
+	value = initial_val
 
 	# Now connect signal for future changes
 	value_changed.connect(_on_value_changed)
 
-	# New: Initialize debounce timer (0.5s delay, one-shot)
+	# Safely track input without overriding the base _gui_input virtual method
+	gui_input.connect(_on_gui_input)
+
+	# Initialize debounce timer (0.5s delay, one-shot)
 	save_debounce_timer = Timer.new()
 	save_debounce_timer.wait_time = 0.5
 	save_debounce_timer.one_shot = true
 	save_debounce_timer.timeout.connect(_on_debounce_timeout)
-	add_child(save_debounce_timer)  # Add to scene tree for auto-processing
+	add_child(save_debounce_timer)
+
+
+## Safe method for external scripts to update the slider without triggering SFX or saves.
+## Use this instead of modifying `value` directly when restoring settings.
+## :param new_value: The target volume (0.0 to 1.0).
+## :type new_value: float
+## :rtype: void
+func set_value_programmatically(new_value: float) -> void:
+	# Guard against external updates if the bus is invalid
+	if bus_index == -1:
+		return
+
+	# Godot 4 native method: updates visual value without emitting 'value_changed'
+	set_value_no_signal(new_value)
+
+	# Explicitly sync the audio backend, since the signal was bypassed
+	AudioServer.set_bus_volume_db(bus_index, linear_to_db(new_value))
+	AudioManager.set_volume(bus_name, new_value)
+
+	# Sync the delta tracker so the next manual interaction calculates correctly
+	_previous_value = new_value
+
+
+## Tracks mouse drag state for accurate interaction gating, even if the cursor
+## leaves the slider's bounding box while dragging.
+## :param event: The input event passed by the UI system.
+## :type event: InputEvent
+## :rtype: void
+func _on_gui_input(event: InputEvent) -> void:
+	if event is InputEventMouseButton and event.button_index == MOUSE_BUTTON_LEFT:
+		_is_dragging = event.pressed
+
+
+## Signal listener for when the slider value changes manually.
+## :param new_value: The new volume level from the slider (0.0 to 1.0).
+## :type new_value: float
+## :rtype: void
+func _on_value_changed(new_value: float) -> void:
+	AudioServer.set_bus_volume_db(bus_index, linear_to_db(new_value))
+	AudioManager.set_volume(bus_name, new_value)
+
+	# Attempt to play interaction feedback
+	_handle_slider_sfx(new_value)
+
+	# Godot automatically restarts an active timer when start() is called
+	save_debounce_timer.start()
+
+
+## Guards SFX playback against redundant values and rapid spam.
+## Ensures sound only plays during legitimate, rate-limited user interactions.
+## :param new_value: The updated slider value.
+## :type new_value: float
+## :rtype: void
+func _handle_slider_sfx(new_value: float) -> void:
+	# Guard 1: Only play if the value actually changed (float-safe delta check)
+	if is_equal_approx(new_value, _previous_value):
+		return
+
+	# Commit the value tracker early so delta checks stay accurate even if rate-limited
+	_previous_value = new_value
+
+	# Guard 2: Only play if user is actively interacting (Mouse Drag or Keyboard Focus)
+	var is_mouse_active: bool = _is_dragging
+	var is_keyboard_active: bool = has_focus()
+
+	if not (is_mouse_active or is_keyboard_active):
+		return
+
+	# Guard 3: Rate limit to prevent audio spam during rapid drags
+	var current_time: int = Time.get_ticks_msec()
+	if current_time - _last_sfx_time < SFX_COOLDOWN_MS:
+		return
 
+	# Commit time state only after all guards pass
+	_last_sfx_time = current_time
 
-# change bus value/volume
-func _on_value_changed(value: float) -> void:
-	AudioServer.set_bus_volume_db(bus_index, linear_to_db(value))
-	AudioManager.set_volume(bus_name, value)
-	# New: Start/restart debounce timer instead of immediate save
-	if save_debounce_timer.is_stopped():
-		save_debounce_timer.start()
-	else:
-		save_debounce_timer.stop()
-		save_debounce_timer.start()
+	AudioManager.play_sfx(AudioConstants.SFX_SLIDER)
 
 
-# New: Called on timer timeout—perform the batched save
+## Called on timer timeout—performs the batched disk save.
+## :rtype: void
 func _on_debounce_timeout() -> void:
 	AudioManager.save_volumes()
 	Globals.log_message("Debounced settings save triggered.", Globals.LogLevel.DEBUG)