feature/match3/move-gems (#7)

Reviewed-on: #7
Co-authored-by: Vladimir nett00n Budylnikov <git@nett00n.org>
Co-committed-by: Vladimir nett00n Budylnikov <git@nett00n.org>

scenes/game/game.gd

@@ -24,19 +24,28 @@ func set_gameplay_mode(mode: String) -> void:
 	load_gameplay(mode)
 
 func load_gameplay(mode: String) -> void:
+	DebugManager.log_debug("Loading gameplay mode: %s" % mode, "Game")
+
 	# Clear existing gameplay
 	for child in gameplay_container.get_children():
+		DebugManager.log_debug("Removing existing child: %s" % child.name, "Game")
 		child.queue_free()
 
 	# Load new gameplay
 	if GAMEPLAY_SCENES.has(mode):
+		DebugManager.log_debug("Found scene path: %s" % GAMEPLAY_SCENES[mode], "Game")
 		var gameplay_scene = load(GAMEPLAY_SCENES[mode])
 		var gameplay_instance = gameplay_scene.instantiate()
+		DebugManager.log_debug("Instantiated gameplay: %s" % gameplay_instance.name, "Game")
 		gameplay_container.add_child(gameplay_instance)
+		DebugManager.log_debug("Added gameplay to container, child count now: %d" % gameplay_container.get_child_count(), "Game")
 
 		# Connect gameplay signals to shared systems
 		if gameplay_instance.has_signal("score_changed"):
 			gameplay_instance.score_changed.connect(_on_score_changed)
+			DebugManager.log_debug("Connected score_changed signal", "Game")
+	else:
+		DebugManager.log_error("Gameplay mode '%s' not found in GAMEPLAY_SCENES" % mode, "Game")
 
 func set_global_score(value: int) -> void:
 	global_score = value
@@ -47,17 +56,17 @@ func _on_score_changed(points: int) -> void:
 	self.global_score += points
 
 func _on_back_button_pressed() -> void:
-	print("Back button pressed in game scene")
+	DebugManager.log_debug("Back button pressed in game scene", "Game")
 	AudioManager.play_ui_click()
 	GameManager.save_game()
 	GameManager.exit_to_main_menu()
 
 func _input(event: InputEvent) -> void:
-	if event.is_action_pressed("ui_accept") and Input.is_action_pressed("ui_select"):
-		# Debug: Switch to clickomania when Space+Enter pressed together
+	if event.is_action_pressed("action_south") and Input.is_action_pressed("action_north"):
+		# Debug: Switch to clickomania when primary+secondary actions pressed together
 		if current_gameplay_mode == "match3":
 			set_gameplay_mode("clickomania")
-			print("Switched to clickomania gameplay")
+			DebugManager.log_debug("Switched to clickomania gameplay", "Game")
 		else:
 			set_gameplay_mode("match3")
-			print("Switched to match3 gameplay")
+			DebugManager.log_debug("Switched to match3 gameplay", "Game")

scenes/game/game.gd.uid

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

scenes/game/gameplays/GameplayInputHandler.gd.uid

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

scenes/game/gameplays/GridGameplay.gd.uid

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

scenes/game/gameplays/Match3DebugMenu.gd

@@ -1,129 +1,36 @@
-extends Control
-
-@onready var regenerate_button: Button = $VBoxContainer/RegenerateButton
-@onready var gem_types_spinbox: SpinBox = $VBoxContainer/GemTypesContainer/GemTypesSpinBox
-@onready var gem_types_label: Label = $VBoxContainer/GemTypesContainer/GemTypesLabel
-@onready var grid_width_spinbox: SpinBox = $VBoxContainer/GridSizeContainer/GridWidthContainer/GridWidthSpinBox
-@onready var grid_height_spinbox: SpinBox = $VBoxContainer/GridSizeContainer/GridHeightContainer/GridHeightSpinBox
-@onready var grid_width_label: Label = $VBoxContainer/GridSizeContainer/GridWidthContainer/GridWidthLabel
-@onready var grid_height_label: Label = $VBoxContainer/GridSizeContainer/GridHeightContainer/GridHeightLabel
-
-var match3_scene: Node2D
+extends DebugMenuBase
 
 func _ready():
-	print("Match3DebugMenu: _ready() called")
-	DebugManager.debug_toggled.connect(_on_debug_toggled)
-	# Initialize with current debug state
+	# Set specific configuration for Match3DebugMenu
+	log_category = "Match3"
+	target_script_path = "res://scenes/game/gameplays/match3_gameplay.gd"
+
+	# Call parent's _ready
+	super._ready()
+
+	DebugManager.log_debug("Match3DebugMenu _ready() completed", log_category)
+
+	# Initialize with current debug state if enabled
 	var current_debug_state = DebugManager.is_debug_enabled()
-	print("Match3DebugMenu: Current debug state is ", current_debug_state)
-	visible = current_debug_state
-	print("Match3DebugMenu: Initial visibility set to ", visible)
 	if current_debug_state:
 		_on_debug_toggled(true)
-	regenerate_button.pressed.connect(_on_regenerate_pressed)
-	gem_types_spinbox.value_changed.connect(_on_gem_types_changed)
-	grid_width_spinbox.value_changed.connect(_on_grid_width_changed)
-	grid_height_spinbox.value_changed.connect(_on_grid_height_changed)
 
-func _find_match3_scene():
+func _find_target_scene():
 	# Debug menu is now: Match3 -> UILayer -> Match3DebugMenu
 	# So we need to go up two levels: get_parent() = UILayer, get_parent().get_parent() = Match3
 	var ui_layer = get_parent()
 	if ui_layer and ui_layer is CanvasLayer:
-		match3_scene = ui_layer.get_parent()
-		if match3_scene and match3_scene.get_script():
-			var script_path = match3_scene.get_script().resource_path
-			if script_path == "res://scenes/game/gameplays/match3_gameplay.gd":
-				print("Debug: Found match3 scene: ", match3_scene.name, " at path: ", match3_scene.get_path())
+		var potential_match3 = ui_layer.get_parent()
+		if potential_match3 and potential_match3.get_script():
+			var script_path = potential_match3.get_script().resource_path
+			if script_path == target_script_path:
+				match3_scene = potential_match3
+				DebugManager.log_debug("Found match3 scene: " + match3_scene.name + " at path: " + str(match3_scene.get_path()), log_category)
+				_update_ui_from_scene()
+				_stop_search_timer()
 				return
 
-	# If we couldn't find it, clear the reference
+	# If we couldn't find it, clear the reference and continue searching
 	match3_scene = null
-	print("Debug: Could not find match3_gameplay scene")
-
-func _on_debug_toggled(enabled: bool):
-	print("Match3DebugMenu: Debug toggled to ", enabled)
-	visible = enabled
-	print("Match3DebugMenu: Visibility set to ", visible)
-	if enabled:
-		# Always refresh match3 scene reference when debug menu opens
-		if not match3_scene:
-			_find_match3_scene()
-		# Update display values
-		if match3_scene and match3_scene.has_method("get") and "TILE_TYPES" in match3_scene:
-			gem_types_spinbox.value = match3_scene.TILE_TYPES
-			gem_types_label.text = "Gem Types: " + str(match3_scene.TILE_TYPES)
-
-		# Update grid size display values
-		if match3_scene and "GRID_SIZE" in match3_scene:
-			var grid_size = match3_scene.GRID_SIZE
-			grid_width_spinbox.value = grid_size.x
-			grid_height_spinbox.value = grid_size.y
-			grid_width_label.text = "Width: " + str(grid_size.x)
-			grid_height_label.text = "Height: " + str(grid_size.y)
-
-func _on_regenerate_pressed():
-	if not match3_scene:
-		_find_match3_scene()
-
-	if not match3_scene:
-		print("Error: Could not find match3 scene for regeneration")
-		return
-
-	if match3_scene.has_method("regenerate_grid"):
-		print("Debug: Calling regenerate_grid()")
-		await match3_scene.regenerate_grid()
-	else:
-		print("Error: match3_scene does not have regenerate_grid method")
-
-func _on_gem_types_changed(value: float):
-	if not match3_scene:
-		_find_match3_scene()
-
-	if not match3_scene:
-		print("Error: Could not find match3 scene for gem types change")
-		return
-
-	var new_value = int(value)
-	if match3_scene.has_method("set_tile_types"):
-		print("Debug: Setting tile types to ", new_value)
-		await match3_scene.set_tile_types(new_value)
-		gem_types_label.text = "Gem Types: " + str(new_value)
-	else:
-		print("Error: match3_scene does not have set_tile_types method")
-
-func _on_grid_width_changed(value: float):
-	if not match3_scene:
-		_find_match3_scene()
-
-	if not match3_scene:
-		print("Error: Could not find match3 scene for grid width change")
-		return
-
-	var new_width = int(value)
-	grid_width_label.text = "Width: " + str(new_width)
-
-	# Get current height
-	var current_height = int(grid_height_spinbox.value)
-
-	if match3_scene.has_method("set_grid_size"):
-		print("Debug: Setting grid size to ", new_width, "x", current_height)
-		await match3_scene.set_grid_size(Vector2i(new_width, current_height))
-
-func _on_grid_height_changed(value: float):
-	if not match3_scene:
-		_find_match3_scene()
-
-	if not match3_scene:
-		print("Error: Could not find match3 scene for grid height change")
-		return
-
-	var new_height = int(value)
-	grid_height_label.text = "Height: " + str(new_height)
-
-	# Get current width
-	var current_width = int(grid_width_spinbox.value)
-
-	if match3_scene.has_method("set_grid_size"):
-		print("Debug: Setting grid size to ", current_width, "x", new_height)
-		await match3_scene.set_grid_size(Vector2i(current_width, new_height))
+	DebugManager.log_error("Could not find match3_gameplay scene", log_category)
+	_start_search_timer()

scenes/game/gameplays/Match3DebugMenu.gd.uid

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

scenes/game/gameplays/SelectableItem.gd.uid

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

scenes/game/gameplays/clickomania_gameplay.gd

@@ -3,8 +3,8 @@ extends Node2D
 signal score_changed(points: int)
 
 func _ready():
-	print("Clickomania gameplay loaded")
+	DebugManager.log_info("Clickomania gameplay loaded", "Clickomania")
 	# Example: Add some score after a few seconds to test the system
 	await get_tree().create_timer(2.0).timeout
 	score_changed.emit(100)
-	print("Clickomania awarded 100 points")
+	DebugManager.log_info("Clickomania awarded 100 points", "Clickomania")

scenes/game/gameplays/clickomania_gameplay.gd.uid

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

scenes/game/gameplays/match3_gameplay.gd

@@ -2,6 +2,13 @@ extends Node2D
 
 signal score_changed(points: int)
 
+enum GameState {
+	WAITING,      # Waiting for player input
+	SELECTING,    # First tile selected
+	SWAPPING,     # Animating tile swap
+	PROCESSING    # Processing matches and cascades
+}
+
 var GRID_SIZE := Vector2i(8, 8)
 var TILE_TYPES := 5
 const TILE_SCENE := preload("res://scenes/game/gameplays/tile.tscn")
@@ -9,19 +16,24 @@ const TILE_SCENE := preload("res://scenes/game/gameplays/tile.tscn")
 var grid := []
 var tile_size: float = 48.0
 var grid_offset: Vector2
+var current_state: GameState = GameState.WAITING
+var selected_tile: Node2D = null
+var cursor_position: Vector2i = Vector2i(0, 0)
+var keyboard_navigation_enabled: bool = false
 
 func _ready():
-	# Set up initial gem pool
-	var gem_indices = []
-	for i in range(TILE_TYPES):
-		gem_indices.append(i)
+	DebugManager.log_debug("Match3 _ready() started", "Match3")
 
-	const TileScript = preload("res://scenes/game/gameplays/tile.gd")
-	TileScript.set_active_gem_pool(gem_indices)
+	# Gem pool will be set individually on each tile during creation
 
 	_calculate_grid_layout()
 	_initialize_grid()
 
+	DebugManager.log_debug("Match3 _ready() completed, calling debug structure check", "Match3")
+
+	# Debug: Check scene tree structure immediately
+	call_deferred("_debug_scene_structure")
+
 func _calculate_grid_layout():
 	var viewport_size = get_viewport().get_visible_rect().size
 	var available_width = viewport_size.x * 0.8  # Use 80% of screen width
@@ -40,25 +52,30 @@ func _calculate_grid_layout():
 	)
 
 func _initialize_grid():
-	# Update gem pool BEFORE creating any tiles
+	# Create gem pool for current tile types
 	var gem_indices = []
 	for i in range(TILE_TYPES):
 		gem_indices.append(i)
 
-	const TileScript = preload("res://scenes/game/gameplays/tile.gd")
-	TileScript.set_active_gem_pool(gem_indices)
-
 	for y in range(GRID_SIZE.y):
 		grid.append([])
 		for x in range(GRID_SIZE.x):
 			var tile = TILE_SCENE.instantiate()
-			tile.position = grid_offset + Vector2(x, y) * tile_size
+			var tile_position = grid_offset + Vector2(x, y) * tile_size
+			tile.position = tile_position
 			tile.grid_position = Vector2i(x, y)
 			add_child(tile)
+
+			# Set gem types for this tile
+			tile.set_active_gem_types(gem_indices)
+
 			# Set tile type after adding to scene tree so sprite reference is available
 			var new_type = randi() % TILE_TYPES
 			tile.tile_type = new_type
-			# print("Debug: Created tile at (", x, ",", y, ") with type ", new_type)
+
+			# Connect tile signals
+			tile.tile_selected.connect(_on_tile_selected)
+			DebugManager.log_debug("Created tile at grid(%d,%d) world_pos(%s) with type %d" % [x, y, tile_position, new_type], "Match3")
 			grid[y].append(tile)
 
 func _has_match_at(pos: Vector2i) -> bool:
@@ -126,10 +143,13 @@ func _clear_matches():
 	if to_clear.size() == 0:
 		return
 
+	# Clear grid references first, then queue nodes for removal
 	for tile in to_clear:
 		grid[tile.grid_position.y][tile.grid_position.x] = null
 		tile.queue_free()
 
+	# Wait one frame for nodes to be queued properly
+	await get_tree().process_frame
 	_drop_tiles()
 	await get_tree().create_timer(0.2).timeout
 	_fill_empty_cells()
@@ -153,16 +173,29 @@ func _drop_tiles():
 					moved = true
 
 func _fill_empty_cells():
+	# Create gem pool for current tile types
+	var gem_indices = []
+	for i in range(TILE_TYPES):
+		gem_indices.append(i)
+
 	for y in range(GRID_SIZE.y):
 		for x in range(GRID_SIZE.x):
 			if not grid[y][x]:
 				var tile = TILE_SCENE.instantiate()
 				tile.grid_position = Vector2i(x, y)
-				tile.tile_type = randi() % TILE_TYPES
 				tile.position = grid_offset + Vector2(x, y) * tile_size
-				grid[y][x] = tile
 				add_child(tile)
 
+				# Set gem types for this tile
+				tile.set_active_gem_types(gem_indices)
+
+				# Set random tile type
+				tile.tile_type = randi() % TILE_TYPES
+
+				grid[y][x] = tile
+				# Connect tile signals for new tiles
+				tile.tile_selected.connect(_on_tile_selected)
+
 	# Fixed: Add recursion protection to prevent stack overflow
 	await get_tree().create_timer(0.1).timeout
 	var max_iterations = 10
@@ -176,7 +209,7 @@ func regenerate_grid():
 	# Use time-based seed to ensure different patterns each time
 	var new_seed = Time.get_ticks_msec()
 	seed(new_seed)
-	print("Debug: Regenerating grid with seed: ", new_seed)
+	DebugManager.log_debug("Regenerating grid with seed: " + str(new_seed), "Match3")
 
 	# Fixed: Clear ALL tile children, not just ones in grid array
 	# This handles any orphaned tiles that might not be tracked in the grid
@@ -187,21 +220,21 @@ func regenerate_grid():
 			if script_path == "res://scenes/game/gameplays/tile.gd":
 				children_to_remove.append(child)
 
-	# Remove all found tile children
-	for child in children_to_remove:
-		child.free()
-
-	# Also clear grid array references
+	# First clear grid array references to prevent access to nodes being freed
 	for y in range(grid.size()):
 		if grid[y] and grid[y] is Array:
 			for x in range(grid[y].size()):
-				# Set to null since we already freed the nodes above
 				grid[y][x] = null
 
 	# Clear the grid array
 	grid.clear()
 
-	# No need to wait for nodes to be freed since we used free()
+	# Remove all found tile children using queue_free for safe cleanup
+	for child in children_to_remove:
+		child.queue_free()
+
+	# Wait for nodes to be properly freed from the scene tree
+	await get_tree().process_frame
 
 	# Fixed: Recalculate grid layout before regenerating tiles
 	_calculate_grid_layout()
@@ -215,7 +248,238 @@ func set_tile_types(new_count: int):
 	await regenerate_grid()
 
 func set_grid_size(new_size: Vector2i):
-	print("Debug: Changing grid size from ", GRID_SIZE, " to ", new_size)
+	DebugManager.log_debug("Changing grid size from " + str(GRID_SIZE) + " to " + str(new_size), "Match3")
 	GRID_SIZE = new_size
 	# Regenerate grid with new size
 	await regenerate_grid()
+
+func reset_all_visual_states() -> void:
+	# Debug function to reset all tile visual states
+	DebugManager.log_debug("Resetting all tile visual states", "Match3")
+	for y in range(GRID_SIZE.y):
+		for x in range(GRID_SIZE.x):
+			if grid[y][x] and grid[y][x].has_method("force_reset_visual_state"):
+				grid[y][x].force_reset_visual_state()
+
+	# Reset game state
+	selected_tile = null
+	current_state = GameState.WAITING
+	keyboard_navigation_enabled = false
+
+func _debug_scene_structure() -> void:
+	DebugManager.log_debug("=== Scene Structure Debug ===", "Match3")
+	DebugManager.log_debug("Match3 node children count: %d" % get_child_count(), "Match3")
+	DebugManager.log_debug("Match3 global position: %s" % global_position, "Match3")
+	DebugManager.log_debug("Match3 scale: %s" % scale, "Match3")
+
+	# Check if grid is properly initialized
+	if not grid or grid.size() == 0:
+		DebugManager.log_error("Grid not initialized when debug structure called", "Match3")
+		return
+
+	# Check tiles
+	var tile_count = 0
+	for y in range(GRID_SIZE.y):
+		for x in range(GRID_SIZE.x):
+			if y < grid.size() and x < grid[y].size() and grid[y][x]:
+				tile_count += 1
+	DebugManager.log_debug("Created %d tiles out of %d expected" % [tile_count, GRID_SIZE.x * GRID_SIZE.y], "Match3")
+
+	# Check first tile in detail
+	if grid.size() > 0 and grid[0].size() > 0 and grid[0][0]:
+		var first_tile = grid[0][0]
+		DebugManager.log_debug("First tile global position: %s" % first_tile.global_position, "Match3")
+		DebugManager.log_debug("First tile local position: %s" % first_tile.position, "Match3")
+
+	# Check parent chain
+	var current_node = self
+	var depth = 0
+	while current_node and depth < 10:
+		DebugManager.log_debug("Parent level %d: %s (type: %s)" % [depth, current_node.name, current_node.get_class()], "Match3")
+		current_node = current_node.get_parent()
+		depth += 1
+
+func _input(event: InputEvent) -> void:
+	# Debug key to reset all visual states
+	if event.is_action_pressed("action_east") and DebugManager.is_debug_enabled():
+		reset_all_visual_states()
+		return
+
+	if current_state == GameState.SWAPPING or current_state == GameState.PROCESSING:
+		return
+
+	# Handle keyboard/gamepad navigation
+	if event.is_action_pressed("move_up"):
+		_move_cursor(Vector2i.UP)
+		keyboard_navigation_enabled = true
+	elif event.is_action_pressed("move_down"):
+		_move_cursor(Vector2i.DOWN)
+		keyboard_navigation_enabled = true
+	elif event.is_action_pressed("move_left"):
+		_move_cursor(Vector2i.LEFT)
+		keyboard_navigation_enabled = true
+	elif event.is_action_pressed("move_right"):
+		_move_cursor(Vector2i.RIGHT)
+		keyboard_navigation_enabled = true
+	elif event.is_action_pressed("action_south"):
+		if keyboard_navigation_enabled:
+			_select_tile_at_cursor()
+
+
+func _move_cursor(direction: Vector2i) -> void:
+	# Input validation for direction vector
+	if abs(direction.x) > 1 or abs(direction.y) > 1:
+		DebugManager.log_error("Invalid cursor direction vector: " + str(direction), "Match3")
+		return
+
+	if direction.x != 0 and direction.y != 0:
+		DebugManager.log_error("Diagonal cursor movement not supported: " + str(direction), "Match3")
+		return
+
+	var old_pos = cursor_position
+	var new_pos = cursor_position + direction
+
+	# Bounds checking
+	new_pos.x = clamp(new_pos.x, 0, GRID_SIZE.x - 1)
+	new_pos.y = clamp(new_pos.y, 0, GRID_SIZE.y - 1)
+
+	if new_pos != cursor_position:
+		# Validate old position before accessing grid
+		if old_pos.x >= 0 and old_pos.y >= 0 and old_pos.x < GRID_SIZE.x and old_pos.y < GRID_SIZE.y:
+			var old_tile = grid[cursor_position.y][cursor_position.x]
+			if old_tile and not old_tile.is_selected:
+				old_tile.is_highlighted = false
+
+		DebugManager.log_debug("Cursor moved from (%d,%d) to (%d,%d)" % [old_pos.x, old_pos.y, new_pos.x, new_pos.y], "Match3")
+		cursor_position = new_pos
+
+		# Validate new position before accessing grid
+		if cursor_position.x >= 0 and cursor_position.y >= 0 and cursor_position.x < GRID_SIZE.x and cursor_position.y < GRID_SIZE.y:
+			var new_tile = grid[cursor_position.y][cursor_position.x]
+			if new_tile and not new_tile.is_selected:
+				new_tile.is_highlighted = true
+
+func _select_tile_at_cursor() -> void:
+	if cursor_position.x >= 0 and cursor_position.y >= 0 and cursor_position.x < GRID_SIZE.x and cursor_position.y < GRID_SIZE.y:
+		var tile = grid[cursor_position.y][cursor_position.x]
+		if tile:
+			DebugManager.log_debug("Keyboard selection at cursor (%d,%d)" % [cursor_position.x, cursor_position.y], "Match3")
+			_on_tile_selected(tile)
+
+func _on_tile_selected(tile: Node2D) -> void:
+	if current_state == GameState.SWAPPING or current_state == GameState.PROCESSING:
+		DebugManager.log_debug("Tile selection ignored - game busy (state: %s)" % [GameState.keys()[current_state]], "Match3")
+		return
+
+	DebugManager.log_debug("Tile selected at (%d,%d), gem type: %d" % [tile.grid_position.x, tile.grid_position.y, tile.tile_type], "Match3")
+
+	if current_state == GameState.WAITING:
+		# First tile selection
+		_select_tile(tile)
+	elif current_state == GameState.SELECTING:
+		if tile == selected_tile:
+			# Deselect current tile
+			DebugManager.log_debug("Same tile clicked - deselecting", "Match3")
+			_deselect_tile()
+		else:
+			# Attempt to swap with selected tile
+			DebugManager.log_debug("Attempting swap between (%d,%d) and (%d,%d)" % [selected_tile.grid_position.x, selected_tile.grid_position.y, tile.grid_position.x, tile.grid_position.y], "Match3")
+			_attempt_swap(selected_tile, tile)
+
+
+func _select_tile(tile: Node2D) -> void:
+	selected_tile = tile
+	tile.is_selected = true
+	current_state = GameState.SELECTING
+	DebugManager.log_debug("Selected tile at (%d, %d)" % [tile.grid_position.x, tile.grid_position.y], "Match3")
+
+func _deselect_tile() -> void:
+	if selected_tile:
+		DebugManager.log_debug("Deselecting tile at (%d,%d)" % [selected_tile.grid_position.x, selected_tile.grid_position.y], "Match3")
+
+		# Clear selection state
+		selected_tile.is_selected = false
+
+		# Handle cursor highlighting for keyboard navigation
+		if keyboard_navigation_enabled:
+			# Clear all highlighting first to avoid conflicts
+			selected_tile.is_highlighted = false
+
+			# Re-highlight cursor position if it's different from the deselected tile
+			var cursor_tile = grid[cursor_position.y][cursor_position.x]
+			if cursor_tile:
+				cursor_tile.is_highlighted = true
+				DebugManager.log_debug("Restored cursor highlighting at (%d,%d)" % [cursor_position.x, cursor_position.y], "Match3")
+		else:
+			# For mouse navigation, just clear highlighting
+			selected_tile.is_highlighted = false
+
+		selected_tile = null
+	current_state = GameState.WAITING
+
+func _are_adjacent(tile1: Node2D, tile2: Node2D) -> bool:
+	if not tile1 or not tile2:
+		return false
+
+	var pos1 = tile1.grid_position
+	var pos2 = tile2.grid_position
+	var diff = abs(pos1.x - pos2.x) + abs(pos1.y - pos2.y)
+	return diff == 1
+
+func _attempt_swap(tile1: Node2D, tile2: Node2D) -> void:
+	if not _are_adjacent(tile1, tile2):
+		DebugManager.log_debug("Tiles are not adjacent, cannot swap", "Match3")
+		return
+
+	DebugManager.log_debug("Starting swap animation: (%d,%d)[type:%d] <-> (%d,%d)[type:%d]" % [tile1.grid_position.x, tile1.grid_position.y, tile1.tile_type, tile2.grid_position.x, tile2.grid_position.y, tile2.tile_type], "Match3")
+
+	current_state = GameState.SWAPPING
+	await _swap_tiles(tile1, tile2)
+
+	# Check if swap creates matches
+	if _has_match_at(tile1.grid_position) or _has_match_at(tile2.grid_position):
+		DebugManager.log_info("Valid swap created matches at (%d,%d) or (%d,%d)" % [tile1.grid_position.x, tile1.grid_position.y, tile2.grid_position.x, tile2.grid_position.y], "Match3")
+		_deselect_tile()
+		current_state = GameState.PROCESSING
+		_clear_matches()
+		await get_tree().create_timer(0.3).timeout
+		current_state = GameState.WAITING
+	else:
+		# Invalid swap - revert
+		DebugManager.log_debug("No matches created, reverting swap", "Match3")
+		await _swap_tiles(tile1, tile2)  # Swap back
+		DebugManager.log_debug("Swap reverted successfully", "Match3")
+		_deselect_tile()
+		current_state = GameState.WAITING
+
+func _swap_tiles(tile1: Node2D, tile2: Node2D) -> void:
+	if not tile1 or not tile2:
+		DebugManager.log_error("Cannot swap tiles - one or both tiles are null", "Match3")
+		return
+
+	# Update grid positions
+	var pos1 = tile1.grid_position
+	var pos2 = tile2.grid_position
+
+	DebugManager.log_debug("Swapping tile positions: (%d,%d) -> (%d,%d), (%d,%d) -> (%d,%d)" % [pos1.x, pos1.y, pos2.x, pos2.y, pos2.x, pos2.y, pos1.x, pos1.y], "Match3")
+
+	tile1.grid_position = pos2
+	tile2.grid_position = pos1
+
+	# Update grid array
+	grid[pos1.y][pos1.x] = tile2
+	grid[pos2.y][pos2.x] = tile1
+
+	# Animate position swap
+	var target_pos1 = grid_offset + Vector2(pos2.x, pos2.y) * tile_size
+	var target_pos2 = grid_offset + Vector2(pos1.x, pos1.y) * tile_size
+
+	DebugManager.log_trace("Animating tile movement over 0.3 seconds", "Match3")
+
+	var tween = create_tween()
+	tween.set_parallel(true)
+	tween.tween_property(tile1, "position", target_pos1, 0.3)
+	tween.tween_property(tile2, "position", target_pos2, 0.3)
+
+	await tween.finished
+	DebugManager.log_trace("Tile swap animation completed", "Match3")

scenes/game/gameplays/match3_gameplay.gd.uid

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

scenes/game/gameplays/tile.gd

@@ -1,7 +1,12 @@
 extends Node2D
 
+signal tile_selected(tile: Node2D)
+
 @export var tile_type: int = 0 : set = _set_tile_type
 var grid_position: Vector2i
+var is_selected: bool = false : set = _set_selected
+var is_highlighted: bool = false : set = _set_highlighted
+var original_scale: Vector2 = Vector2.ONE  # Store the original scale for the board
 
 @onready var sprite: Sprite2D = $Sprite2D
 
@@ -20,25 +25,20 @@ var all_gem_textures = [
 	preload("res://assets/sprites/gems/sg_19.png"),    # 7 - Silver gem
 ]
 
-# Static variable to store the current gem pool for all tiles
-static var current_gem_pool = [0, 1, 2, 3, 4]  # Start with first 5 gems
-
 # Currently active gem types (indices into all_gem_textures)
-var active_gem_types = []  # Will be set from current_gem_pool
+var active_gem_types = []  # Will be set from TileManager
 
 func _set_tile_type(value: int) -> void:
 	tile_type = value
-	print("Debug: _set_tile_type called with value ", value, ", active_gem_types.size() = ", active_gem_types.size())
 	# Fixed: Add sprite null check to prevent crashes during initialization
 	if not sprite:
 		return
 	if value >= 0 and value < active_gem_types.size():
 		var texture_index = active_gem_types[value]
 		sprite.texture = all_gem_textures[texture_index]
-		# print("Debug: Set texture_index ", texture_index, " for tile_type ", value)
 		_scale_sprite_to_fit()
 	else:
-		push_error("Invalid tile type: " + str(value) + ". Available types: 0-" + str(active_gem_types.size() - 1))
+		DebugManager.log_error("Invalid tile type: " + str(value) + ". Available types: 0-" + str(active_gem_types.size() - 1), "Match3")
 
 func _scale_sprite_to_fit() -> void:
 	# Fixed: Add additional null checks
@@ -46,71 +46,137 @@ func _scale_sprite_to_fit() -> void:
 		var texture_size = sprite.texture.get_size()
 		var max_dimension = max(texture_size.x, texture_size.y)
 		var scale_factor = TILE_SIZE / max_dimension
-		sprite.scale = Vector2(scale_factor, scale_factor)
+		original_scale = Vector2(scale_factor, scale_factor)
+		sprite.scale = original_scale
+		DebugManager.log_debug("Set original scale to %s for tile (%d,%d)" % [original_scale, grid_position.x, grid_position.y], "Match3")
 
-# Gem pool management functions
-static func set_active_gem_pool(gem_indices: Array) -> void:
-	# Update static gem pool for new tiles
-	current_gem_pool = gem_indices.duplicate()
+func set_active_gem_types(gem_indices: Array) -> void:
+	if not gem_indices or gem_indices.is_empty():
+		DebugManager.log_error("Empty gem indices array provided", "Tile")
+		return
 
-	# Update all existing tile instances to use new gem pool
-	var scene_tree = Engine.get_main_loop() as SceneTree
-	if scene_tree:
-		var tiles = scene_tree.get_nodes_in_group("tiles")
-		for tile in tiles:
-			if tile.has_method("_update_active_gems"):
-				tile._update_active_gems(gem_indices)
-
-func _update_active_gems(gem_indices: Array) -> void:
 	active_gem_types = gem_indices.duplicate()
+
+	# Validate all gem indices are within bounds
+	for gem_index in active_gem_types:
+		if gem_index < 0 or gem_index >= all_gem_textures.size():
+			DebugManager.log_error("Invalid gem index: %d (valid range: 0-%d)" % [gem_index, all_gem_textures.size() - 1], "Tile")
+			# Use default fallback
+			active_gem_types = [0, 1, 2, 3, 4]
+			break
+
 	# Re-validate current tile type
 	if tile_type >= active_gem_types.size():
 		# Generate a new random tile type within valid range
 		tile_type = randi() % active_gem_types.size()
+
 	_set_tile_type(tile_type)
 
-static func get_active_gem_count() -> int:
-	# Get from any tile instance or default
-	var scene_tree = Engine.get_main_loop() as SceneTree
-	if scene_tree:
-		var tiles = scene_tree.get_nodes_in_group("tiles")
-		if tiles.size() > 0:
-			return tiles[0].active_gem_types.size()
-	return 5  # Default
+func get_active_gem_count() -> int:
+	return active_gem_types.size()
 
-static func add_gem_to_pool(gem_index: int) -> void:
-	var scene_tree = Engine.get_main_loop() as SceneTree
-	if scene_tree:
-		var tiles = scene_tree.get_nodes_in_group("tiles")
-		for tile in tiles:
-			if tile.has_method("_add_gem_type"):
-				tile._add_gem_type(gem_index)
+func add_gem_type(gem_index: int) -> bool:
+	if gem_index < 0 or gem_index >= all_gem_textures.size():
+		DebugManager.log_error("Invalid gem index: %d" % gem_index, "Tile")
+		return false
 
-func _add_gem_type(gem_index: int) -> void:
-	if gem_index >= 0 and gem_index < all_gem_textures.size():
-		if not active_gem_types.has(gem_index):
-			active_gem_types.append(gem_index)
+	if not active_gem_types.has(gem_index):
+		active_gem_types.append(gem_index)
+		return true
 
-static func remove_gem_from_pool(gem_index: int) -> void:
-	var scene_tree = Engine.get_main_loop() as SceneTree
-	if scene_tree:
-		var tiles = scene_tree.get_nodes_in_group("tiles")
-		for tile in tiles:
-			if tile.has_method("_remove_gem_type"):
-				tile._remove_gem_type(gem_index)
+	return false
 
-func _remove_gem_type(gem_index: int) -> void:
+func remove_gem_type(gem_index: int) -> bool:
 	var type_index = active_gem_types.find(gem_index)
-	if type_index != -1 and active_gem_types.size() > 2:  # Keep at least 2 gem types
-		active_gem_types.erase(gem_index)
-		# Update tiles that were using removed type
-		if tile_type >= active_gem_types.size():
-			tile_type = 0
-			_set_tile_type(tile_type)
+	if type_index == -1:
+		return false
+
+	if active_gem_types.size() <= 2:  # Keep at least 2 gem types
+		DebugManager.log_warn("Cannot remove gem type - minimum 2 types required", "Tile")
+		return false
+
+	active_gem_types.erase(gem_index)
+
+	# Update tile if it was using the removed type
+	if tile_type >= active_gem_types.size():
+		tile_type = 0
+		_set_tile_type(tile_type)
+
+	return true
+
+func _set_selected(value: bool) -> void:
+	var old_value = is_selected
+	is_selected = value
+	DebugManager.log_debug("Tile (%d,%d) selection changed: %s -> %s" % [grid_position.x, grid_position.y, old_value, value], "Match3")
+	_update_visual_feedback()
+
+func _set_highlighted(value: bool) -> void:
+	var old_value = is_highlighted
+	is_highlighted = value
+	DebugManager.log_debug("Tile (%d,%d) highlight changed: %s -> %s" % [grid_position.x, grid_position.y, old_value, value], "Match3")
+	_update_visual_feedback()
+
+func _update_visual_feedback() -> void:
+	if not sprite:
+		return
+
+	# Determine target values based on priority: selected > highlighted > normal
+	var target_modulate: Color
+	var target_scale: Vector2
+	var scale_multiplier: float
+
+	if is_selected:
+		# Selected: bright and 20% larger than original board size
+		target_modulate = Color(1.2, 1.2, 1.2, 1.0)
+		scale_multiplier = 1.2
+		DebugManager.log_debug("SELECTING tile (%d,%d): target scale %.2fx, current scale %s" % [grid_position.x, grid_position.y, scale_multiplier, sprite.scale], "Match3")
+	elif is_highlighted:
+		# Highlighted: subtle glow and 10% larger than original board size
+		target_modulate = Color(1.1, 1.1, 1.1, 1.0)
+		scale_multiplier = 1.1
+		DebugManager.log_debug("HIGHLIGHTING tile (%d,%d): target scale %.2fx, current scale %s" % [grid_position.x, grid_position.y, scale_multiplier, sprite.scale], "Match3")
+	else:
+		# Normal state: white and original board size
+		target_modulate = Color.WHITE
+		scale_multiplier = 1.0
+		DebugManager.log_debug("NORMALIZING tile (%d,%d): target scale %.2fx, current scale %s" % [grid_position.x, grid_position.y, scale_multiplier, sprite.scale], "Match3")
+
+	# Calculate target scale relative to original board scale
+	target_scale = original_scale * scale_multiplier
+
+	# Apply modulate immediately
+	sprite.modulate = target_modulate
+
+	# Only animate scale if it's actually changing
+	if sprite.scale != target_scale:
+		DebugManager.log_debug("Animating scale from %s to %s for tile (%d,%d)" % [sprite.scale, target_scale, grid_position.x, grid_position.y], "Match3")
+
+		var tween = create_tween()
+		tween.tween_property(sprite, "scale", target_scale, 0.15)
+
+		# Add completion callback for debugging
+		tween.tween_callback(_on_scale_animation_completed.bind(target_scale))
+	else:
+		DebugManager.log_debug("No scale change needed for tile (%d,%d)" % [grid_position.x, grid_position.y], "Match3")
+
+func _on_scale_animation_completed(expected_scale: Vector2) -> void:
+	DebugManager.log_debug("Scale animation completed for tile (%d,%d): expected %s, actual %s" % [grid_position.x, grid_position.y, expected_scale, sprite.scale], "Match3")
+
+func force_reset_visual_state() -> void:
+	# Force reset all visual states - debug function
+	is_selected = false
+	is_highlighted = false
+	if sprite:
+		sprite.modulate = Color.WHITE
+		sprite.scale = original_scale  # Reset to original board scale, not 1.0
+	DebugManager.log_debug("Forced visual reset on tile (%d,%d) to original scale %s" % [grid_position.x, grid_position.y, original_scale], "Match3")
 
 # Called when the node enters the scene tree for the first time.
 func _ready() -> void:
 	add_to_group("tiles")  # Add to group for gem pool management
-	# Initialize with current static gem pool
-	active_gem_types = current_gem_pool.duplicate()
+
+	# Initialize with default gem pool if not already set
+	if active_gem_types.is_empty():
+		active_gem_types = [0, 1, 2, 3, 4]  # Default to first 5 gems
+
 	_set_tile_type(tile_type)

scenes/game/gameplays/tile.gd.uid

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

scenes/main/Main.gd

@@ -7,11 +7,11 @@ const MAIN_MENU_SCENE = preload("res://scenes/ui/MainMenu.tscn")
 const SETTINGS_MENU_SCENE = preload("res://scenes/ui/SettingsMenu.tscn")
 
 func _ready():
-	print("Main scene ready")
+	DebugManager.log_debug("Main scene ready", "Main")
 	press_any_key_screen.any_key_pressed.connect(_on_any_key_pressed)
 
 func _on_any_key_pressed():
-	print("Transitioning to main menu")
+	DebugManager.log_debug("Transitioning to main menu", "Main")
 	press_any_key_screen.queue_free()
 	show_main_menu()
 
@@ -35,9 +35,9 @@ func clear_current_menu():
 		current_menu = null
 
 func _on_open_settings():
-	print("Opening settings menu")
+	DebugManager.log_debug("Opening settings menu", "Main")
 	show_settings_menu()
 
 func _on_back_to_main_menu():
-	print("Back to main menu")
+	DebugManager.log_debug("Back to main menu", "Main")
 	show_main_menu()

scenes/main/Main.gd.uid

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

scenes/main/PressAnyKeyScreen.gd

@@ -3,12 +3,12 @@ extends Control
 signal any_key_pressed
 
 func _ready():
-	print("PressAnyKeyScreen ready")
+	DebugManager.log_debug("PressAnyKeyScreen ready", "PressAnyKey")
 	update_text()
 
 func _input(event):
-	if event.is_action_pressed("any_key") or event is InputEventScreenTouch:
-		print("Any key pressed: ", event)
+	if event.is_action_pressed("action_south") or event is InputEventScreenTouch or (event is InputEventMouseButton and event.button_index == MOUSE_BUTTON_LEFT and event.pressed):
+		DebugManager.log_debug("Action pressed: " + str(event), "PressAnyKey")
 		any_key_pressed.emit()
 		get_viewport().set_input_as_handled()
 

scenes/main/PressAnyKeyScreen.gd.uid

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

scenes/main/PressAnyKeyScreen.tscn

@@ -1,8 +1,8 @@
 [gd_scene load_steps=16 format=3 uid="uid://gbe1jarrwqsi"]
 
-[ext_resource type="Script" uid="uid://cxw2fjj5onja3" path="res://scenes/main/PressAnyKeyScreen.gd" id="1_0a4p2"]
+[ext_resource type="Script" uid="uid://cq7or0bcm2xfj" path="res://scenes/main/PressAnyKeyScreen.gd" id="1_0a4p2"]
 [ext_resource type="Texture2D" uid="uid://bcr4bokw87m5n" path="res://assets/sprites/characters/skeleton/Skeleton Idle.png" id="2_rjjcb"]
-[ext_resource type="PackedScene" path="res://scenes/ui/DebugToggle.tscn" id="3_debug"]
+[ext_resource type="PackedScene" uid="uid://df2b4wn8j6cxl" path="res://scenes/ui/DebugToggle.tscn" id="3_debug"]
 
 [sub_resource type="AtlasTexture" id="AtlasTexture_l6pue"]
 atlas = ExtResource("2_rjjcb")

scenes/main/main.tscn

@@ -1,9 +1,9 @@
 [gd_scene load_steps=5 format=3 uid="uid://ci2gk11211n0d"]
 
-[ext_resource type="Script" uid="uid://b0uwk2jlm6g08" path="res://scenes/main/Main.gd" id="1_0wfyh"]
+[ext_resource type="Script" uid="uid://rvuchiy0guv3" path="res://scenes/main/Main.gd" id="1_0wfyh"]
 [ext_resource type="PackedScene" uid="uid://gbe1jarrwqsi" path="res://scenes/main/PressAnyKeyScreen.tscn" id="1_o5qli"]
 [ext_resource type="Texture2D" uid="uid://c8y6tlvcgh2gn" path="res://assets/textures/backgrounds/beanstalk-dark.webp" id="2_sugp2"]
-[ext_resource type="PackedScene" path="res://scenes/ui/DebugToggle.tscn" id="4_v7g8d"]
+[ext_resource type="PackedScene" uid="uid://df2b4wn8j6cxl" path="res://scenes/ui/DebugToggle.tscn" id="4_v7g8d"]
 
 [node name="main" type="Control"]
 layout_mode = 3

scenes/ui/DebugMenu.gd

@@ -1,71 +1,17 @@
-extends Control
+extends DebugMenuBase
 
-@onready var regenerate_button: Button = $VBoxContainer/RegenerateButton
-@onready var gem_types_spinbox: SpinBox = $VBoxContainer/GemTypesContainer/GemTypesSpinBox
-@onready var gem_types_label: Label = $VBoxContainer/GemTypesContainer/GemTypesLabel
-@onready var grid_width_spinbox: SpinBox = $VBoxContainer/GridSizeContainer/GridWidthContainer/GridWidthSpinBox
-@onready var grid_height_spinbox: SpinBox = $VBoxContainer/GridSizeContainer/GridHeightContainer/GridHeightSpinBox
-@onready var grid_width_label: Label = $VBoxContainer/GridSizeContainer/GridWidthContainer/GridWidthLabel
-@onready var grid_height_label: Label = $VBoxContainer/GridSizeContainer/GridHeightContainer/GridHeightLabel
-
-var match3_scene: Node2D
-var search_timer: Timer
-
-# Fixed: Add cleanup function
-func _exit_tree():
-	if search_timer:
-		search_timer.queue_free()
-
-func _ready():
-	DebugManager.debug_toggled.connect(_on_debug_toggled)
-
-	# Initialize with current debug state
-	var current_debug_state = DebugManager.is_debug_enabled()
-	visible = current_debug_state
-	regenerate_button.pressed.connect(_on_regenerate_pressed)
-	gem_types_spinbox.value_changed.connect(_on_gem_types_changed)
-	grid_width_spinbox.value_changed.connect(_on_grid_width_changed)
-	grid_height_spinbox.value_changed.connect(_on_grid_height_changed)
-
-	# Initialize gem types spinbox
-	gem_types_spinbox.min_value = 3
-	gem_types_spinbox.max_value = 8
-	gem_types_spinbox.step = 1
-	gem_types_spinbox.value = 5  # Default value
-
-	# Initialize grid size spinboxes
-	grid_width_spinbox.min_value = 4
-	grid_width_spinbox.max_value = 12
-	grid_width_spinbox.step = 1
-	grid_width_spinbox.value = 8  # Default value
-
-	grid_height_spinbox.min_value = 4
-	grid_height_spinbox.max_value = 12
-	grid_height_spinbox.step = 1
-	grid_height_spinbox.value = 8  # Default value
-
-	# Fixed: Create timer for periodic match3 scene search
-	search_timer = Timer.new()
-	search_timer.wait_time = 0.1
-	search_timer.timeout.connect(_find_match3_scene)
-	add_child(search_timer)
-
-	# Start searching immediately and continue until found
-	_find_match3_scene()
-
-func _find_match3_scene():
+func _find_target_scene():
 	# Fixed: Search more thoroughly for match3 scene
 	if match3_scene:
 		# Already found, stop searching
-		if search_timer and search_timer.timeout.is_connected(_find_match3_scene):
-			search_timer.stop()
+		_stop_search_timer()
 		return
 
 	# Search in current scene tree
 	var current_scene = get_tree().current_scene
 	if current_scene:
-		# Try to find match3 by class name first
-		match3_scene = _find_node_by_script(current_scene, "res://scenes/game/gameplays/match3_gameplay.gd")
+		# Try to find match3 by script path first
+		match3_scene = _find_node_by_script(current_scene, target_script_path)
 
 		# Fallback: search by common node names
 		if not match3_scene:
@@ -75,132 +21,9 @@ func _find_match3_scene():
 					break
 
 	if match3_scene:
-		print("Debug: Found match3 scene: ", match3_scene.name)
-		# Update UI with current values
-		if match3_scene.has_method("get") and "TILE_TYPES" in match3_scene:
-			gem_types_spinbox.value = match3_scene.TILE_TYPES
-			gem_types_label.text = "Gem Types: " + str(match3_scene.TILE_TYPES)
-
-		# Update grid size values
-		if "GRID_SIZE" in match3_scene:
-			var grid_size = match3_scene.GRID_SIZE
-			grid_width_spinbox.value = grid_size.x
-			grid_height_spinbox.value = grid_size.y
-			grid_width_label.text = "Width: " + str(grid_size.x)
-			grid_height_label.text = "Height: " + str(grid_size.y)
-
-		# Stop the search timer
-		if search_timer and search_timer.timeout.is_connected(_find_match3_scene):
-			search_timer.stop()
+		DebugManager.log_debug("Found match3 scene: " + match3_scene.name, log_category)
+		_update_ui_from_scene()
+		_stop_search_timer()
 	else:
 		# Continue searching if not found
-		if search_timer and not search_timer.timeout.is_connected(_find_match3_scene):
-			search_timer.timeout.connect(_find_match3_scene)
-			search_timer.start()
-
-func _find_node_by_script(node: Node, script_path: String) -> Node:
-	# Helper function to find node by its script path
-	if node.get_script():
-		var node_script = node.get_script()
-		if node_script.resource_path == script_path:
-			return node
-
-	for child in node.get_children():
-		var result = _find_node_by_script(child, script_path)
-		if result:
-			return result
-
-	return null
-
-func _on_debug_toggled(enabled: bool):
-	visible = enabled
-	if enabled:
-		# Always refresh match3 scene reference when debug menu opens
-		if not match3_scene:
-			_find_match3_scene()
-		# Update display values
-		if match3_scene and match3_scene.has_method("get") and "TILE_TYPES" in match3_scene:
-			gem_types_spinbox.value = match3_scene.TILE_TYPES
-			gem_types_label.text = "Gem Types: " + str(match3_scene.TILE_TYPES)
-
-		# Update grid size display values
-		if match3_scene and "GRID_SIZE" in match3_scene:
-			var grid_size = match3_scene.GRID_SIZE
-			grid_width_spinbox.value = grid_size.x
-			grid_height_spinbox.value = grid_size.y
-			grid_width_label.text = "Width: " + str(grid_size.x)
-			grid_height_label.text = "Height: " + str(grid_size.y)
-
-func _on_regenerate_pressed():
-	if not match3_scene:
-		_find_match3_scene()
-
-	if not match3_scene:
-		print("Error: Could not find match3 scene for regeneration")
-		return
-
-	if match3_scene.has_method("regenerate_grid"):
-		print("Debug: Calling regenerate_grid()")
-		await match3_scene.regenerate_grid()
-	else:
-		print("Error: match3_scene does not have regenerate_grid method")
-
-func _on_gem_types_changed(value: float):
-	if not match3_scene:
-		_find_match3_scene()
-
-	if not match3_scene:
-		print("Error: Could not find match3 scene for gem types change")
-		return
-
-	var new_value = int(value)
-	if match3_scene.has_method("set_tile_types"):
-		print("Debug: Setting tile types to ", new_value)
-		await match3_scene.set_tile_types(new_value)
-		gem_types_label.text = "Gem Types: " + str(new_value)
-	else:
-		print("Error: match3_scene does not have set_tile_types method")
-		# Fallback: try to set TILE_TYPES directly
-		if "TILE_TYPES" in match3_scene:
-			match3_scene.TILE_TYPES = new_value
-			gem_types_label.text = "Gem Types: " + str(new_value)
-
-func _on_grid_width_changed(value: float):
-	if not match3_scene:
-		_find_match3_scene()
-
-	if not match3_scene:
-		print("Error: Could not find match3 scene for grid width change")
-		return
-
-	var new_width = int(value)
-	grid_width_label.text = "Width: " + str(new_width)
-
-	# Get current height
-	var current_height = int(grid_height_spinbox.value)
-
-	if match3_scene.has_method("set_grid_size"):
-		print("Debug: Setting grid size to ", new_width, "x", current_height)
-		await match3_scene.set_grid_size(Vector2i(new_width, current_height))
-	else:
-		print("Error: match3_scene does not have set_grid_size method")
-
-func _on_grid_height_changed(value: float):
-	if not match3_scene:
-		_find_match3_scene()
-
-	if not match3_scene:
-		print("Error: Could not find match3 scene for grid height change")
-		return
-
-	var new_height = int(value)
-	grid_height_label.text = "Height: " + str(new_height)
-
-	# Get current width
-	var current_width = int(grid_width_spinbox.value)
-
-	if match3_scene.has_method("set_grid_size"):
-		print("Debug: Setting grid size to ", current_width, "x", new_height)
-		await match3_scene.set_grid_size(Vector2i(current_width, new_height))
-	else:
-		print("Error: match3_scene does not have set_grid_size method")
+		_start_search_timer()

scenes/ui/DebugMenu.gd.uid

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

scenes/ui/DebugMenuBase.gd

@@ -0,0 +1,213 @@
+class_name DebugMenuBase
+extends Control
+
+@onready var regenerate_button: Button = $VBoxContainer/RegenerateButton
+@onready var gem_types_spinbox: SpinBox = $VBoxContainer/GemTypesContainer/GemTypesSpinBox
+@onready var gem_types_label: Label = $VBoxContainer/GemTypesContainer/GemTypesLabel
+@onready var grid_width_spinbox: SpinBox = $VBoxContainer/GridSizeContainer/GridWidthContainer/GridWidthSpinBox
+@onready var grid_height_spinbox: SpinBox = $VBoxContainer/GridSizeContainer/GridHeightContainer/GridHeightSpinBox
+@onready var grid_width_label: Label = $VBoxContainer/GridSizeContainer/GridWidthContainer/GridWidthLabel
+@onready var grid_height_label: Label = $VBoxContainer/GridSizeContainer/GridHeightContainer/GridHeightLabel
+
+@export var target_script_path: String = "res://scenes/game/gameplays/match3_gameplay.gd"
+@export var log_category: String = "DebugMenu"
+
+var match3_scene: Node2D
+var search_timer: Timer
+
+func _exit_tree():
+	if search_timer:
+		search_timer.queue_free()
+
+func _ready():
+	DebugManager.log_debug("DebugMenuBase _ready() called", log_category)
+	DebugManager.debug_toggled.connect(_on_debug_toggled)
+
+	# Initialize with current debug state
+	var current_debug_state = DebugManager.is_debug_enabled()
+	visible = current_debug_state
+
+	# Connect signals
+	regenerate_button.pressed.connect(_on_regenerate_pressed)
+	gem_types_spinbox.value_changed.connect(_on_gem_types_changed)
+	grid_width_spinbox.value_changed.connect(_on_grid_width_changed)
+	grid_height_spinbox.value_changed.connect(_on_grid_height_changed)
+
+	# Initialize spinbox values with validation
+	_initialize_spinboxes()
+
+	# Set up scene finding
+	_setup_scene_finding()
+
+	# Start searching for target scene
+	_find_target_scene()
+
+func _initialize_spinboxes():
+	# Initialize gem types spinbox
+	gem_types_spinbox.min_value = 3
+	gem_types_spinbox.max_value = 8
+	gem_types_spinbox.step = 1
+	gem_types_spinbox.value = 5  # Default value
+
+	# Initialize grid size spinboxes
+	grid_width_spinbox.min_value = 4
+	grid_width_spinbox.max_value = 12
+	grid_width_spinbox.step = 1
+	grid_width_spinbox.value = 8  # Default value
+
+	grid_height_spinbox.min_value = 4
+	grid_height_spinbox.max_value = 12
+	grid_height_spinbox.step = 1
+	grid_height_spinbox.value = 8  # Default value
+
+func _setup_scene_finding():
+	# Create timer for periodic scene search
+	search_timer = Timer.new()
+	search_timer.wait_time = 0.1
+	search_timer.timeout.connect(_find_target_scene)
+	add_child(search_timer)
+
+# Virtual method - override in derived classes for specific finding logic
+func _find_target_scene():
+	DebugManager.log_error("_find_target_scene() not implemented in derived class", log_category)
+
+func _find_node_by_script(node: Node, script_path: String) -> Node:
+	# Helper function to find node by its script path
+	if not node:
+		return null
+
+	if node.get_script():
+		var node_script = node.get_script()
+		if node_script.resource_path == script_path:
+			return node
+
+	for child in node.get_children():
+		var result = _find_node_by_script(child, script_path)
+		if result:
+			return result
+
+	return null
+
+func _update_ui_from_scene():
+	if not match3_scene:
+		return
+
+	# Update gem types display
+	if match3_scene.has_method("get") and "TILE_TYPES" in match3_scene:
+		gem_types_spinbox.value = match3_scene.TILE_TYPES
+		gem_types_label.text = "Gem Types: " + str(match3_scene.TILE_TYPES)
+
+	# Update grid size display
+	if "GRID_SIZE" in match3_scene:
+		var grid_size = match3_scene.GRID_SIZE
+		grid_width_spinbox.value = grid_size.x
+		grid_height_spinbox.value = grid_size.y
+		grid_width_label.text = "Width: " + str(grid_size.x)
+		grid_height_label.text = "Height: " + str(grid_size.y)
+
+func _stop_search_timer():
+	if search_timer and search_timer.timeout.is_connected(_find_target_scene):
+		search_timer.stop()
+
+func _start_search_timer():
+	if search_timer and not search_timer.timeout.is_connected(_find_target_scene):
+		search_timer.timeout.connect(_find_target_scene)
+		search_timer.start()
+
+func _on_debug_toggled(enabled: bool):
+	DebugManager.log_debug("Debug toggled to " + str(enabled), log_category)
+	visible = enabled
+	if enabled:
+		# Always refresh scene reference when debug menu opens
+		if not match3_scene:
+			_find_target_scene()
+		_update_ui_from_scene()
+
+func _on_regenerate_pressed():
+	if not match3_scene:
+		_find_target_scene()
+
+	if not match3_scene:
+		DebugManager.log_error("Could not find target scene for regeneration", log_category)
+		return
+
+	if match3_scene.has_method("regenerate_grid"):
+		DebugManager.log_debug("Calling regenerate_grid()", log_category)
+		await match3_scene.regenerate_grid()
+	else:
+		DebugManager.log_error("Target scene does not have regenerate_grid method", log_category)
+
+func _on_gem_types_changed(value: float):
+	if not match3_scene:
+		_find_target_scene()
+
+	if not match3_scene:
+		DebugManager.log_error("Could not find target scene for gem types change", log_category)
+		return
+
+	var new_value = int(value)
+	# Input validation
+	if new_value < gem_types_spinbox.min_value or new_value > gem_types_spinbox.max_value:
+		DebugManager.log_error("Invalid gem types value: %d (range: %d-%d)" % [new_value, gem_types_spinbox.min_value, gem_types_spinbox.max_value], log_category)
+		return
+
+	if match3_scene.has_method("set_tile_types"):
+		DebugManager.log_debug("Setting tile types to " + str(new_value), log_category)
+		await match3_scene.set_tile_types(new_value)
+		gem_types_label.text = "Gem Types: " + str(new_value)
+	else:
+		DebugManager.log_error("Target scene does not have set_tile_types method", log_category)
+		# Fallback: try to set TILE_TYPES directly
+		if "TILE_TYPES" in match3_scene:
+			match3_scene.TILE_TYPES = new_value
+			gem_types_label.text = "Gem Types: " + str(new_value)
+
+func _on_grid_width_changed(value: float):
+	if not match3_scene:
+		_find_target_scene()
+
+	if not match3_scene:
+		DebugManager.log_error("Could not find target scene for grid width change", log_category)
+		return
+
+	var new_width = int(value)
+	# Input validation
+	if new_width < grid_width_spinbox.min_value or new_width > grid_width_spinbox.max_value:
+		DebugManager.log_error("Invalid grid width value: %d (range: %d-%d)" % [new_width, grid_width_spinbox.min_value, grid_width_spinbox.max_value], log_category)
+		return
+
+	grid_width_label.text = "Width: " + str(new_width)
+
+	# Get current height
+	var current_height = int(grid_height_spinbox.value)
+
+	if match3_scene.has_method("set_grid_size"):
+		DebugManager.log_debug("Setting grid size to " + str(new_width) + "x" + str(current_height), log_category)
+		await match3_scene.set_grid_size(Vector2i(new_width, current_height))
+	else:
+		DebugManager.log_error("Target scene does not have set_grid_size method", log_category)
+
+func _on_grid_height_changed(value: float):
+	if not match3_scene:
+		_find_target_scene()
+
+	if not match3_scene:
+		DebugManager.log_error("Could not find target scene for grid height change", log_category)
+		return
+
+	var new_height = int(value)
+	# Input validation
+	if new_height < grid_height_spinbox.min_value or new_height > grid_height_spinbox.max_value:
+		DebugManager.log_error("Invalid grid height value: %d (range: %d-%d)" % [new_height, grid_height_spinbox.min_value, grid_height_spinbox.max_value], log_category)
+		return
+
+	grid_height_label.text = "Height: " + str(new_height)
+
+	# Get current width
+	var current_width = int(grid_width_spinbox.value)
+
+	if match3_scene.has_method("set_grid_size"):
+		DebugManager.log_debug("Setting grid size to " + str(current_width) + "x" + str(new_height), log_category)
+		await match3_scene.set_grid_size(Vector2i(current_width, new_height))
+	else:
+		DebugManager.log_error("Target scene does not have set_grid_size method", log_category)

scenes/ui/DebugMenuBase.gd.uid

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

scenes/ui/DebugToggle.gd.uid

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

scenes/ui/MainMenu.gd

@@ -2,20 +2,78 @@ extends Control
 
 signal open_settings
 
+@onready var menu_buttons: Array[Button] = []
+var current_menu_index: int = 0
+var original_button_scales: Array[Vector2] = []
+
 func _ready():
-	print("MainMenu ready")
+	DebugManager.log_info("MainMenu ready", "MainMenu")
+	_setup_menu_navigation()
 
 func _on_new_game_button_pressed():
 	AudioManager.play_ui_click()
-	print("New Game pressed")
+	DebugManager.log_info("New Game pressed", "MainMenu")
 	GameManager.start_new_game()
 
 func _on_settings_button_pressed():
 	AudioManager.play_ui_click()
-	print("Settings pressed")
+	DebugManager.log_info("Settings pressed", "MainMenu")
 	open_settings.emit()
 
 func _on_exit_button_pressed():
 	AudioManager.play_ui_click()
-	print("Exit pressed")
+	DebugManager.log_info("Exit pressed", "MainMenu")
 	get_tree().quit()
+
+func _setup_menu_navigation():
+	menu_buttons.clear()
+	original_button_scales.clear()
+
+	menu_buttons.append($MenuContainer/NewGameButton)
+	menu_buttons.append($MenuContainer/SettingsButton)
+	menu_buttons.append($MenuContainer/ExitButton)
+
+	for button in menu_buttons:
+		original_button_scales.append(button.scale)
+
+	_update_visual_selection()
+
+func _input(event: InputEvent) -> void:
+	if event.is_action_pressed("move_up"):
+		_navigate_menu(-1)
+	elif event.is_action_pressed("move_down"):
+		_navigate_menu(1)
+	elif event.is_action_pressed("action_south"):
+		_activate_current_button()
+	elif event.is_action_pressed("options_menu"):
+		AudioManager.play_ui_click()
+		DebugManager.log_info("Options menu shortcut pressed", "MainMenu")
+		open_settings.emit()
+	elif event.is_action_pressed("quit_game"):
+		AudioManager.play_ui_click()
+		DebugManager.log_info("Quit game shortcut pressed", "MainMenu")
+		get_tree().quit()
+
+func _navigate_menu(direction: int):
+	AudioManager.play_ui_click()
+	current_menu_index = (current_menu_index + direction) % menu_buttons.size()
+	if current_menu_index < 0:
+		current_menu_index = menu_buttons.size() - 1
+	_update_visual_selection()
+	DebugManager.log_info("Menu navigation: index " + str(current_menu_index), "MainMenu")
+
+func _activate_current_button():
+	if current_menu_index >= 0 and current_menu_index < menu_buttons.size():
+		var button = menu_buttons[current_menu_index]
+		DebugManager.log_info("Activating button via keyboard/gamepad: " + button.text, "MainMenu")
+		button.pressed.emit()
+
+func _update_visual_selection():
+	for i in range(menu_buttons.size()):
+		var button = menu_buttons[i]
+		if i == current_menu_index:
+			button.scale = original_button_scales[i] * 1.1
+			button.modulate = Color(1.2, 1.2, 1.0)
+		else:
+			button.scale = original_button_scales[i]
+			button.modulate = Color.WHITE

scenes/ui/MainMenu.gd.uid

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

scenes/ui/MainMenu.tscn

@@ -1,7 +1,7 @@
 [gd_scene load_steps=3 format=3 uid="uid://m8lf3eh3al5j"]
 
-[ext_resource type="Script" uid="uid://b2c35v0f6rymd" path="res://scenes/ui/MainMenu.gd" id="1_b00nv"]
-[ext_resource type="PackedScene" path="res://scenes/ui/DebugToggle.tscn" id="2_debug"]
+[ext_resource type="Script" uid="uid://b2x0kw8f70s8q" path="res://scenes/ui/MainMenu.gd" id="1_b00nv"]
+[ext_resource type="PackedScene" uid="uid://df2b4wn8j6cxl" path="res://scenes/ui/DebugToggle.tscn" id="2_debug"]
 
 [node name="MainMenu" type="Control"]
 layout_mode = 3

scenes/ui/SettingsMenu.gd

@@ -5,17 +5,22 @@ signal back_to_main_menu
 @onready var master_slider = $SettingsContainer/MasterVolumeContainer/MasterVolumeSlider
 @onready var music_slider = $SettingsContainer/MusicVolumeContainer/MusicVolumeSlider
 @onready var sfx_slider = $SettingsContainer/SFXVolumeContainer/SFXVolumeSlider
-@onready var language_selector = $SettingsContainer/LanguageContainer/LanguageSelector
+@onready var language_stepper = $SettingsContainer/LanguageContainer/LanguageStepper
 
 @export var settings_manager: Node = SettingsManager
 @export var localization_manager: Node = LocalizationManager
 
-var language_codes = []
+
+# Navigation system variables
+var navigable_controls: Array[Control] = []
+var current_control_index: int = 0
+var original_control_scales: Array[Vector2] = []
+var original_control_modulates: Array[Color] = []
 
 func _ready():
 	add_to_group("localizable")
-	print("SettingsMenu ready")
-	setup_language_selector()
+	DebugManager.log_info("SettingsMenu ready", "Settings")
+	# Language selector is initialized automatically
 
 	var master_callback = _on_volume_slider_changed.bind("master_volume")
 	if not master_slider.value_changed.is_connected(master_callback):
@@ -29,63 +34,76 @@ func _ready():
 	if not sfx_slider.value_changed.is_connected(sfx_callback):
 		sfx_slider.value_changed.connect(sfx_callback)
 
-	if not language_selector.item_selected.is_connected(Callable(self, "_on_language_selector_item_selected")):
-		language_selector.item_selected.connect(_on_language_selector_item_selected)
+	# Language stepper connections are handled in the .tscn file
 
 	_update_controls_from_settings()
 	update_text()
+	_setup_navigation_system()
 
 func _update_controls_from_settings():
 	master_slider.value = settings_manager.get_setting("master_volume")
 	music_slider.value = settings_manager.get_setting("music_volume")
 	sfx_slider.value = settings_manager.get_setting("sfx_volume")
 
-	var current_lang = settings_manager.get_setting("language")
-	var lang_index = language_codes.find(current_lang)
-	if lang_index >= 0:
-		language_selector.selected = lang_index
+	# Language display is handled by the ValueStepper component
 
 func _on_volume_slider_changed(value, setting_key):
-	settings_manager.set_setting(setting_key, value)
+	# Input validation for volume settings
+	if not setting_key in ["master_volume", "music_volume", "sfx_volume"]:
+		DebugManager.log_error("Invalid volume setting key: " + str(setting_key), "Settings")
+		return
+
+	if not (value is float or value is int):
+		DebugManager.log_error("Invalid volume value type: " + str(typeof(value)), "Settings")
+		return
+
+	# Clamp value to valid range
+	var clamped_value = clamp(float(value), 0.0, 1.0)
+	if clamped_value != value:
+		DebugManager.log_warn("Volume value %f clamped to %f" % [value, clamped_value], "Settings")
+
+	if not settings_manager.set_setting(setting_key, clamped_value):
+		DebugManager.log_error("Failed to set volume setting: " + setting_key, "Settings")
 
 func _exit_settings():
-	print("Exiting settings")
+	DebugManager.log_info("Exiting settings", "Settings")
 	settings_manager.save_settings()
 	back_to_main_menu.emit()
 
 func _input(event):
-	if event.is_action_pressed("ui_cancel") or event.is_action_pressed("ui_menu_toggle"):
-		print("ESC pressed in settings")
+	if event.is_action_pressed("action_east") or event.is_action_pressed("pause_menu"):
+		DebugManager.log_debug("Cancel/back action pressed in settings", "Settings")
 		_exit_settings()
 		get_viewport().set_input_as_handled()
+		return
+
+	# Vertical navigation between controls
+	if event.is_action_pressed("move_up"):
+		_navigate_controls(-1)
+		get_viewport().set_input_as_handled()
+	elif event.is_action_pressed("move_down"):
+		_navigate_controls(1)
+		get_viewport().set_input_as_handled()
+
+	# Horizontal navigation for current control
+	elif event.is_action_pressed("move_left"):
+		_adjust_current_control(-1)
+		get_viewport().set_input_as_handled()
+	elif event.is_action_pressed("move_right"):
+		_adjust_current_control(1)
+		get_viewport().set_input_as_handled()
+
+	# Activate current control
+	elif event.is_action_pressed("action_south"):
+		_activate_current_control()
+		get_viewport().set_input_as_handled()
 
 func _on_back_button_pressed():
 	AudioManager.play_ui_click()
-	print("Back button pressed")
+	DebugManager.log_info("Back button pressed", "Settings")
 	_exit_settings()
 
-func setup_language_selector():
-	var languages_data = settings_manager.get_languages_data()
-	if languages_data.has("languages"):
-		language_selector.clear()
-		language_codes.clear()
 
-		for lang_code in languages_data.languages.keys():
-			language_codes.append(lang_code)
-			var display_name = languages_data.languages[lang_code]["display_name"]
-			language_selector.add_item(display_name)
-
-		var current_lang = settings_manager.get_setting("language")
-		var lang_index = language_codes.find(current_lang)
-		if lang_index >= 0:
-			language_selector.selected = lang_index
-
-func _on_language_selector_item_selected(index: int):
-	if index < language_codes.size():
-		var selected_lang = language_codes[index]
-		settings_manager.set_setting("language", selected_lang)
-		print("Language changed to: ", selected_lang)
-		localization_manager.change_language(selected_lang)
 
 func update_text():
 	$SettingsContainer/SettingsTitle.text = tr("settings_title")
@@ -98,7 +116,105 @@ func update_text():
 
 func _on_reset_setting_button_pressed() -> void:
 	AudioManager.play_ui_click()
-	print("Resetting settings")
+	DebugManager.log_info("Resetting settings", "Settings")
 	settings_manager.reset_settings_to_defaults()
 	_update_controls_from_settings()
 	localization_manager.change_language(settings_manager.get_setting("language"))
+
+func _setup_navigation_system():
+	navigable_controls.clear()
+	original_control_scales.clear()
+	original_control_modulates.clear()
+
+	# Add controls in navigation order
+	navigable_controls.append(master_slider)
+	navigable_controls.append(music_slider)
+	navigable_controls.append(sfx_slider)
+	navigable_controls.append(language_stepper)  # Use the ValueStepper component
+	navigable_controls.append($BackButtonContainer/BackButton)
+	navigable_controls.append($ResetSettingsContainer/ResetSettingButton)
+
+	# Store original visual properties
+	for control in navigable_controls:
+		original_control_scales.append(control.scale)
+		original_control_modulates.append(control.modulate)
+
+	_update_visual_selection()
+
+func _navigate_controls(direction: int):
+	AudioManager.play_ui_click()
+	current_control_index = (current_control_index + direction) % navigable_controls.size()
+	if current_control_index < 0:
+		current_control_index = navigable_controls.size() - 1
+	_update_visual_selection()
+	DebugManager.log_info("Settings navigation: index " + str(current_control_index), "Settings")
+
+func _adjust_current_control(direction: int):
+	if current_control_index < 0 or current_control_index >= navigable_controls.size():
+		return
+
+	var control = navigable_controls[current_control_index]
+
+	# Handle sliders
+	if control is HSlider:
+		var slider = control as HSlider
+		var step = slider.step if slider.step > 0 else 0.1
+		var new_value = slider.value + (direction * step)
+		new_value = clamp(new_value, slider.min_value, slider.max_value)
+		slider.value = new_value
+		AudioManager.play_ui_click()
+		DebugManager.log_info("Slider adjusted: %s = %f" % [_get_control_name(control), new_value], "Settings")
+
+	# Handle language stepper with left/right
+	elif control == language_stepper:
+		if language_stepper.handle_input_action("move_left" if direction == -1 else "move_right"):
+			AudioManager.play_ui_click()
+
+func _activate_current_control():
+	if current_control_index < 0 or current_control_index >= navigable_controls.size():
+		return
+
+	var control = navigable_controls[current_control_index]
+
+	# Handle buttons
+	if control is Button:
+		AudioManager.play_ui_click()
+		DebugManager.log_info("Activating button via keyboard/gamepad: " + control.text, "Settings")
+		control.pressed.emit()
+
+	# Handle language stepper (no action needed on activation, left/right handles it)
+	elif control == language_stepper:
+		DebugManager.log_info("Language stepper selected - use left/right to change", "Settings")
+
+func _update_visual_selection():
+	for i in range(navigable_controls.size()):
+		var control = navigable_controls[i]
+		if i == current_control_index:
+			# Use the ValueStepper's built-in highlighting
+			if control == language_stepper:
+				language_stepper.set_highlighted(true)
+			else:
+				control.scale = original_control_scales[i] * 1.05
+				control.modulate = Color(1.1, 1.1, 0.9)
+		else:
+			# Reset highlighting
+			if control == language_stepper:
+				language_stepper.set_highlighted(false)
+			else:
+				control.scale = original_control_scales[i]
+				control.modulate = original_control_modulates[i]
+
+func _get_control_name(control: Control) -> String:
+	if control == master_slider:
+		return "master_volume"
+	elif control == music_slider:
+		return "music_volume"
+	elif control == sfx_slider:
+		return "sfx_volume"
+	elif control == language_stepper:
+		return language_stepper.get_control_name()
+	else:
+		return "button"
+
+func _on_language_stepper_value_changed(new_value: String, new_index: int):
+	DebugManager.log_info("Language changed via ValueStepper: " + new_value + " (index: " + str(new_index) + ")", "Settings")

scenes/ui/SettingsMenu.gd.uid

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

scenes/ui/SettingsMenu.tscn

@@ -1,7 +1,8 @@
-[gd_scene load_steps=3 format=3 uid="uid://57obmcwyos2g"]
+[gd_scene load_steps=4 format=3 uid="uid://57obmcwyos2g"]
 
-[ext_resource type="Script" uid="uid://bv56qwni68qo" path="res://scenes/ui/SettingsMenu.gd" id="1_oqkcn"]
-[ext_resource type="PackedScene" path="res://scenes/ui/DebugToggle.tscn" id="2_debug"]
+[ext_resource type="Script" uid="uid://dftenhuhwskqa" path="res://scenes/ui/SettingsMenu.gd" id="1_oqkcn"]
+[ext_resource type="PackedScene" uid="uid://df2b4wn8j6cxl" path="res://scenes/ui/DebugToggle.tscn" id="2_debug"]
+[ext_resource type="PackedScene" path="res://scenes/ui/components/ValueStepper.tscn" id="3_value_stepper"]
 
 [node name="SettingsMenu" type="Control" groups=["localizable"]]
 layout_mode = 3
@@ -85,21 +86,7 @@ custom_minimum_size = Vector2(150, 0)
 layout_mode = 2
 text = "Language"
 
-[node name="LanguageSelector" type="OptionButton" parent="SettingsContainer/LanguageContainer"]
-layout_mode = 2
-size_flags_horizontal = 4
-selected = 0
-item_count = 5
-popup/item_0/text = "English"
-popup/item_0/id = 0
-popup/item_1/text = "Español"
-popup/item_1/id = 1
-popup/item_2/text = "Français"
-popup/item_2/id = 2
-popup/item_3/text = "Deutsch"
-popup/item_3/id = 3
-popup/item_4/text = "Русский"
-popup/item_4/id = 2
+[node name="LanguageStepper" parent="SettingsContainer/LanguageContainer" instance=ExtResource("3_value_stepper")]
 
 [node name="BackButtonContainer" type="Control" parent="."]
 layout_mode = 1
@@ -148,6 +135,6 @@ layout_mode = 1
 [connection signal="value_changed" from="SettingsContainer/MasterVolumeContainer/MasterVolumeSlider" to="." method="_on_master_volume_changed"]
 [connection signal="value_changed" from="SettingsContainer/MusicVolumeContainer/MusicVolumeSlider" to="." method="_on_music_volume_changed"]
 [connection signal="value_changed" from="SettingsContainer/SFXVolumeContainer/SFXVolumeSlider" to="." method="_on_sfx_volume_changed"]
-[connection signal="item_selected" from="SettingsContainer/LanguageContainer/LanguageSelector" to="." method="_on_language_selector_item_selected"]
+[connection signal="value_changed" from="SettingsContainer/LanguageContainer/LanguageStepper" to="." method="_on_language_stepper_value_changed"]
 [connection signal="pressed" from="BackButtonContainer/BackButton" to="." method="_on_back_button_pressed"]
 [connection signal="pressed" from="ResetSettingsContainer/ResetSettingButton" to="." method="_on_reset_setting_button_pressed"]

scenes/ui/components/ValueStepper.gd

@@ -0,0 +1,190 @@
+@tool
+extends Control
+class_name ValueStepper
+
+## A reusable UI control for stepping through discrete values with arrow buttons
+##
+## ValueStepper provides left/right arrow navigation for cycling through predefined options.
+## Perfect for settings like language, resolution, difficulty, graphics quality, etc.
+## Supports both mouse clicks and keyboard/gamepad navigation.
+##
+## @tutorial(ValueStepper Usage): See docs/UI_COMPONENTS.md
+
+signal value_changed(new_value: String, new_index: int)
+
+@onready var left_button: Button = $LeftButton
+@onready var right_button: Button = $RightButton
+@onready var value_display: Label = $ValueDisplay
+
+## The data source for values. Override this for custom implementations.
+@export var data_source: String = "language"
+## Custom display format function. Leave empty to use default.
+@export var custom_format_function: String = ""
+
+var values: Array[String] = []
+var display_names: Array[String] = []
+var current_index: int = 0
+
+var original_scale: Vector2
+var original_modulate: Color
+var is_highlighted: bool = false
+
+func _ready():
+	DebugManager.log_info("ValueStepper ready for: " + data_source, "ValueStepper")
+
+	# Store original visual properties
+	original_scale = scale
+	original_modulate = modulate
+
+	# Connect button signals
+	if left_button and not left_button.pressed.is_connected(_on_left_button_pressed):
+		left_button.pressed.connect(_on_left_button_pressed)
+
+	if right_button and not right_button.pressed.is_connected(_on_right_button_pressed):
+		right_button.pressed.connect(_on_right_button_pressed)
+
+	# Initialize data
+	_load_data()
+	_update_display()
+
+## Loads data based on the data_source type
+func _load_data():
+	match data_source:
+		"language":
+			_load_language_data()
+		"resolution":
+			_load_resolution_data()
+		"difficulty":
+			_load_difficulty_data()
+		_:
+			DebugManager.log_warn("Unknown data_source: " + data_source, "ValueStepper")
+
+func _load_language_data():
+	var languages_data = SettingsManager.get_languages_data()
+	if languages_data.has("languages"):
+		values.clear()
+		display_names.clear()
+		for lang_code in languages_data.languages.keys():
+			values.append(lang_code)
+			display_names.append(languages_data.languages[lang_code]["display_name"])
+
+		# Set current index based on current language
+		var current_lang = SettingsManager.get_setting("language")
+		var index = values.find(current_lang)
+		current_index = max(0, index)
+
+		DebugManager.log_info("Loaded %d languages" % values.size(), "ValueStepper")
+
+func _load_resolution_data():
+	# Example resolution data - customize as needed
+	values = ["1920x1080", "1366x768", "1280x720", "1024x768"]
+	display_names = ["1920×1080 (Full HD)", "1366×768", "1280×720 (HD)", "1024×768"]
+	current_index = 0
+	DebugManager.log_info("Loaded %d resolutions" % values.size(), "ValueStepper")
+
+func _load_difficulty_data():
+	# Example difficulty data - customize as needed
+	values = ["easy", "normal", "hard", "nightmare"]
+	display_names = ["Easy", "Normal", "Hard", "Nightmare"]
+	current_index = 1  # Default to "normal"
+	DebugManager.log_info("Loaded %d difficulty levels" % values.size(), "ValueStepper")
+
+## Updates the display text based on current selection
+func _update_display():
+	if values.size() == 0 or current_index < 0 or current_index >= values.size():
+		value_display.text = "N/A"
+		return
+
+	if display_names.size() > current_index:
+		value_display.text = display_names[current_index]
+	else:
+		value_display.text = values[current_index]
+
+## Changes the current value by the specified direction (-1 for previous, +1 for next)
+func change_value(direction: int):
+	if values.size() == 0:
+		DebugManager.log_warn("No values available for: " + data_source, "ValueStepper")
+		return
+
+	var new_index = (current_index + direction) % values.size()
+	if new_index < 0:
+		new_index = values.size() - 1
+
+	current_index = new_index
+	var new_value = values[current_index]
+
+	_update_display()
+	_apply_value_change(new_value, current_index)
+	value_changed.emit(new_value, current_index)
+	DebugManager.log_info("Value changed to: " + new_value + " (index: " + str(current_index) + ")", "ValueStepper")
+
+## Override this method for custom value application logic
+func _apply_value_change(new_value: String, index: int):
+	match data_source:
+		"language":
+			SettingsManager.set_setting("language", new_value)
+			if LocalizationManager:
+				LocalizationManager.change_language(new_value)
+		"resolution":
+			# Apply resolution change logic here
+			DebugManager.log_info("Resolution would change to: " + new_value, "ValueStepper")
+		"difficulty":
+			# Apply difficulty change logic here
+			DebugManager.log_info("Difficulty would change to: " + new_value, "ValueStepper")
+
+## Sets up custom values for the stepper
+func setup_custom_values(custom_values: Array[String], custom_display_names: Array[String] = []):
+	values = custom_values.duplicate()
+	display_names = custom_display_names.duplicate() if custom_display_names.size() > 0 else values.duplicate()
+	current_index = 0
+	_update_display()
+	DebugManager.log_info("Setup custom values: " + str(values.size()) + " items", "ValueStepper")
+
+## Gets the current value
+func get_current_value() -> String:
+	if values.size() > 0 and current_index >= 0 and current_index < values.size():
+		return values[current_index]
+	return ""
+
+## Sets the current value by string
+func set_current_value(value: String):
+	var index = values.find(value)
+	if index >= 0:
+		current_index = index
+		_update_display()
+
+## Visual highlighting for navigation systems
+func set_highlighted(highlighted: bool):
+	is_highlighted = highlighted
+	if highlighted:
+		scale = original_scale * 1.05
+		modulate = Color(1.1, 1.1, 0.9)
+	else:
+		scale = original_scale
+		modulate = original_modulate
+
+## Handle input actions for navigation integration
+func handle_input_action(action: String) -> bool:
+	match action:
+		"move_left":
+			change_value(-1)
+			return true
+		"move_right":
+			change_value(1)
+			return true
+		_:
+			return false
+
+func _on_left_button_pressed():
+	AudioManager.play_ui_click()
+	DebugManager.log_info("Left button clicked", "ValueStepper")
+	change_value(-1)
+
+func _on_right_button_pressed():
+	AudioManager.play_ui_click()
+	DebugManager.log_info("Right button clicked", "ValueStepper")
+	change_value(1)
+
+## For navigation system integration
+func get_control_name() -> String:
+	return data_source + "_stepper"

scenes/ui/components/ValueStepper.gd.uid

@@ -0,0 +1 @@
+uid://7qrls88h24o3

scenes/ui/components/ValueStepper.tscn

@@ -0,0 +1,26 @@
+[gd_scene load_steps=2 format=3 uid="uid://cb6k05r8t7l4l"]
+
+[ext_resource type="Script" path="res://scenes/ui/components/ValueStepper.gd" id="1_value_stepper"]
+
+[node name="ValueStepper" type="HBoxContainer"]
+layout_mode = 2
+size_flags_vertical = 4
+script = ExtResource("1_value_stepper")
+
+[node name="LeftButton" type="Button" parent="."]
+layout_mode = 2
+text = "<"
+
+[node name="ValueDisplay" type="Label" parent="."]
+custom_minimum_size = Vector2(100, 0)
+layout_mode = 2
+size_flags_horizontal = 4
+text = "Value"
+horizontal_alignment = 1
+
+[node name="RightButton" type="Button" parent="."]
+layout_mode = 2
+text = ">"
+
+[connection signal="pressed" from="LeftButton" to="." method="_on_left_button_pressed"]
+[connection signal="pressed" from="RightButton" to="." method="_on_right_button_pressed"]