From 0cf76d595feb6673901a6d4b5a18a385a113b158 Mon Sep 17 00:00:00 2001 From: Vladimir nett00n Budylnikov Date: Sat, 27 Sep 2025 21:00:45 +0400 Subject: [PATCH] Comments and documentation update --- scenes/game/gameplays/match3_gameplay.gd | 53 ++++++++++++++++++------ src/autoloads/DebugManager.gd | 48 +++++++++++++++------ src/autoloads/GameManager.gd | 19 +++++++-- src/autoloads/SaveManager.gd | 11 ++++- 4 files changed, 102 insertions(+), 29 deletions(-) diff --git a/scenes/game/gameplays/match3_gameplay.gd b/scenes/game/gameplays/match3_gameplay.gd index 3097a8e..ef11a2c 100644 --- a/scenes/game/gameplays/match3_gameplay.gd +++ b/scenes/game/gameplays/match3_gameplay.gd @@ -3,7 +3,12 @@ extends Node2D signal score_changed(points: int) signal grid_state_loaded(grid_size: Vector2i, tile_types: int) -enum GameState { WAITING, SELECTING, SWAPPING, PROCESSING } # Waiting for player input # First tile selected # Animating tile swap # Processing matches and cascades +## Match-3 Game State Machine +## WAITING: Idle state, accepting player input for tile selection +## SELECTING: First tile selected, waiting for second tile to complete swap +## SWAPPING: Animation in progress, input blocked during tile swap +## PROCESSING: Detecting matches, clearing tiles, dropping new ones, checking cascades +enum GameState { WAITING, SELECTING, SWAPPING, PROCESSING } var GRID_SIZE := Vector2i(8, 8) var TILE_TYPES := 5 @@ -124,6 +129,7 @@ func _initialize_grid(): func _has_match_at(pos: Vector2i) -> bool: + """Check if tile at position is part of a 3+ match horizontally or vertically""" # Bounds and null checks if not _is_valid_grid_position(pos): return false @@ -151,8 +157,8 @@ func _has_match_at(pos: Vector2i) -> bool: return matches_vertical.size() >= 3 -# Check for any matches on the board func _check_for_matches() -> bool: + """Scan entire grid to detect if any matches exist (used for cascade detection)""" for y in range(GRID_SIZE.y): for x in range(GRID_SIZE.x): if _has_match_at(Vector2i(x, y)): @@ -161,6 +167,12 @@ func _check_for_matches() -> bool: func _get_match_line(start: Vector2i, dir: Vector2i) -> Array: + """Find all consecutive matching tiles in a line from start position in given direction. + + Returns array of tile nodes that form a continuous match. + Direction must be unit vector (1,0), (-1,0), (0,1), or (0,-1). + Searches bidirectionally from start position. + """ # Validate input parameters if not _is_valid_grid_position(start): DebugManager.log_error( @@ -185,13 +197,14 @@ func _get_match_line(start: Vector2i, dir: Vector2i) -> Array: if not "tile_type" in start_tile: return [] - var line = [start_tile] - var type = start_tile.tile_type + var line = [start_tile] # Initialize with start tile + var type = start_tile.tile_type # Type to match against - # Check both directions with safety limits - for offset in [1, -1]: + # Check both directions from start position (bidirectional search) + for offset in [1, -1]: # offset 1 = forward direction, -1 = backward direction var current = start + dir * offset var steps = 0 + # Safety limit prevents infinite loops in case of logic errors while steps < GRID_SIZE.x + GRID_SIZE.y and _is_valid_grid_position(current): if current.y >= grid.size() or current.x >= grid[current.y].size(): break @@ -200,17 +213,23 @@ func _get_match_line(start: Vector2i, dir: Vector2i) -> Array: if not neighbor or not is_instance_valid(neighbor): break + # Stop if tile type doesn't match (end of matching sequence) if not "tile_type" in neighbor or neighbor.tile_type != type: break - line.append(neighbor) - current += dir * offset - steps += 1 + line.append(neighbor) # Add matching tile to sequence + current += dir * offset # Move to next position + steps += 1 # Increment safety counter return line -func _clear_matches(): +func _clear_matches() -> void: + """Find and remove all match groups of 3+ tiles, calculating score and triggering effects. + + Uses flood-fill approach to group connected matches, prevents double-counting tiles. + Handles tile removal, score calculation, and visual effects. + """ # Check grid integrity if not _validate_grid_integrity(): DebugManager.log_error("Grid integrity check failed in _clear_matches", "Match3") @@ -693,6 +712,14 @@ func _select_tile_at_cursor() -> void: func _on_tile_selected(tile: Node2D) -> void: + """Handle tile selection with state machine logic for match-3 gameplay. + + State transitions: + WAITING -> SELECTING: First tile selected + SELECTING -> WAITING: Same tile clicked (deselect) + SELECTING -> SWAPPING: Different tile clicked (attempt swap) + """ + # Block tile selection during busy states if current_state == GameState.SWAPPING or current_state == GameState.PROCESSING: DebugManager.log_debug( "Tile selection ignored - game busy (state: %s)" % [GameState.keys()[current_state]], @@ -736,7 +763,7 @@ func _on_tile_selected(tile: Node2D) -> void: func _select_tile(tile: Node2D) -> void: selected_tile = tile tile.is_selected = true - current_state = GameState.SELECTING + current_state = GameState.SELECTING # State transition: WAITING -> SELECTING DebugManager.log_debug( "Selected tile at (%d, %d)" % [tile.grid_position.x, tile.grid_position.y], "Match3" ) @@ -816,8 +843,8 @@ func _attempt_swap(tile1: Node2D, tile2: Node2D) -> void: "Match3" ) - current_state = GameState.SWAPPING - await _swap_tiles(tile1, tile2) + current_state = GameState.SWAPPING # State transition: SELECTING -> SWAPPING + await _swap_tiles(tile1, tile2) # Animate tile swap # Check if swap creates matches if _has_match_at(tile1.grid_position) or _has_match_at(tile2.grid_position): diff --git a/src/autoloads/DebugManager.gd b/src/autoloads/DebugManager.gd index e18867e..a5fc03d 100644 --- a/src/autoloads/DebugManager.gd +++ b/src/autoloads/DebugManager.gd @@ -1,3 +1,9 @@ +## Debug Manager - Global Debug and Logging System +## +## Provides centralized debug functionality and structured logging for the Skelly project. +## Manages debug state, overlay visibility, and log levels with formatted output. +## Replaces direct print() and push_error() calls with structured logging system. + extends Node signal debug_toggled(enabled: bool) @@ -9,52 +15,63 @@ var debug_overlay_visible: bool = false var current_log_level: LogLevel = LogLevel.INFO -func _ready(): +func _ready() -> void: + """Initialize the DebugManager on game startup""" log_info("DebugManager loaded") -func toggle_debug(): +func toggle_debug() -> void: + """Toggle debug mode on/off and emit signal to connected systems""" debug_enabled = !debug_enabled debug_toggled.emit(debug_enabled) log_info("Debug mode: " + ("ON" if debug_enabled else "OFF")) -func set_debug_enabled(enabled: bool): +func set_debug_enabled(enabled: bool) -> void: + """Set debug mode to specific state without toggling""" if debug_enabled != enabled: debug_enabled = enabled debug_toggled.emit(debug_enabled) func is_debug_enabled() -> bool: + """Check if debug mode is currently enabled""" return debug_enabled -func toggle_overlay(): +func toggle_overlay() -> void: + """Toggle debug overlay visibility""" debug_overlay_visible = !debug_overlay_visible -func set_overlay_visible(visible: bool): +func set_overlay_visible(visible: bool) -> void: + """Set debug overlay visibility to specific state""" debug_overlay_visible = visible func is_overlay_visible() -> bool: + """Check if debug overlay is currently visible""" return debug_overlay_visible -func set_log_level(level: LogLevel): +func set_log_level(level: LogLevel) -> void: + """Set minimum log level for output filtering""" current_log_level = level log_info("Log level set to: " + _log_level_to_string(level)) func get_log_level() -> LogLevel: + """Get current minimum log level""" return current_log_level func _should_log(level: LogLevel) -> bool: + """Determine if message should be logged based on current log level""" return level >= current_log_level func _log_level_to_string(level: LogLevel) -> String: + """Convert LogLevel enum to string representation""" match level: LogLevel.TRACE: return "TRACE" @@ -73,47 +90,54 @@ func _log_level_to_string(level: LogLevel) -> String: func _format_log_message(level: LogLevel, message: String, category: String = "") -> String: + """Format log message with timestamp, level, category, and content""" var timestamp = Time.get_datetime_string_from_system() var level_str = _log_level_to_string(level) var category_str = (" [" + category + "]") if category != "" else "" return "[%s] %s%s: %s" % [timestamp, level_str, category_str, message] -func log_trace(message: String, category: String = ""): +func log_trace(message: String, category: String = "") -> void: + """Log trace-level message (lowest priority, only shown in debug mode)""" if _should_log(LogLevel.TRACE): var formatted = _format_log_message(LogLevel.TRACE, message, category) if debug_enabled: print(formatted) -func log_debug(message: String, category: String = ""): +func log_debug(message: String, category: String = "") -> void: + """Log debug-level message (development information, only shown in debug mode)""" if _should_log(LogLevel.DEBUG): var formatted = _format_log_message(LogLevel.DEBUG, message, category) if debug_enabled: print(formatted) -func log_info(message: String, category: String = ""): +func log_info(message: String, category: String = "") -> void: + """Log info-level message (general information, always shown)""" if _should_log(LogLevel.INFO): var formatted = _format_log_message(LogLevel.INFO, message, category) print(formatted) -func log_warn(message: String, category: String = ""): +func log_warn(message: String, category: String = "") -> void: + """Log warning-level message (potential issues that don't break functionality)""" if _should_log(LogLevel.WARN): var formatted = _format_log_message(LogLevel.WARN, message, category) print(formatted) push_warning(formatted) -func log_error(message: String, category: String = ""): +func log_error(message: String, category: String = "") -> void: + """Log error-level message (serious issues that may break functionality)""" if _should_log(LogLevel.ERROR): var formatted = _format_log_message(LogLevel.ERROR, message, category) print(formatted) push_error(formatted) -func log_fatal(message: String, category: String = ""): +func log_fatal(message: String, category: String = "") -> void: + """Log fatal-level message (critical errors that prevent normal operation)""" if _should_log(LogLevel.FATAL): var formatted = _format_log_message(LogLevel.FATAL, message, category) print(formatted) diff --git a/src/autoloads/GameManager.gd b/src/autoloads/GameManager.gd index f258f14..067b29a 100644 --- a/src/autoloads/GameManager.gd +++ b/src/autoloads/GameManager.gd @@ -1,3 +1,9 @@ +## Game Manager - Centralized Scene Transition System +## +## Manages all scene transitions with race condition protection and input validation. +## Provides safe scene switching for different gameplay modes with error handling. +## Never call get_tree().change_scene_to_file() directly - use GameManager methods. + extends Node const GAME_SCENE_PATH := "res://scenes/game/game.tscn" @@ -8,26 +14,31 @@ var is_changing_scene: bool = false func start_new_game() -> void: + """Start a new match-3 game with fresh save data""" SaveManager.start_new_game() start_game_with_mode("match3") func continue_game() -> void: + """Continue existing match-3 game with saved score intact""" # Don't reset score start_game_with_mode("match3") func start_match3_game() -> void: + """Start new match-3 gameplay mode""" SaveManager.start_new_game() start_game_with_mode("match3") func start_clickomania_game() -> void: + """Start new clickomania gameplay mode""" SaveManager.start_new_game() start_game_with_mode("clickomania") func start_game_with_mode(gameplay_mode: String) -> void: + """Load game scene with specified gameplay mode and safety validation""" # Input validation if not gameplay_mode or gameplay_mode.is_empty(): DebugManager.log_error("Empty or null gameplay mode provided", "GameManager") @@ -39,7 +50,7 @@ func start_game_with_mode(gameplay_mode: String) -> void: ) return - # Prevent concurrent scene changes + # Prevent concurrent scene changes (race condition protection) if is_changing_scene: DebugManager.log_warn("Scene change already in progress, ignoring request", "GameManager") return @@ -72,7 +83,7 @@ func start_game_with_mode(gameplay_mode: String) -> void: # Wait for scene instantiation and tree addition await get_tree().process_frame - await get_tree().process_frame # Additional frame for complete initialization + await get_tree().process_frame # Additional frame ensures complete initialization # Validate scene was loaded successfully if not get_tree().current_scene: @@ -80,7 +91,7 @@ func start_game_with_mode(gameplay_mode: String) -> void: is_changing_scene = false return - # Set gameplay mode with timeout protection + # Configure game scene with requested gameplay mode if get_tree().current_scene.has_method("set_gameplay_mode"): DebugManager.log_info("Setting gameplay mode to: %s" % pending_gameplay_mode, "GameManager") get_tree().current_scene.set_gameplay_mode(pending_gameplay_mode) @@ -97,6 +108,7 @@ func start_game_with_mode(gameplay_mode: String) -> void: func save_game() -> void: + """Save current game state and score via SaveManager""" # Get current score from the active game scene var current_score = 0 if get_tree().current_scene and get_tree().current_scene.has_method("get_global_score"): @@ -107,6 +119,7 @@ func save_game() -> void: func exit_to_main_menu() -> void: + """Exit to main menu with race condition protection""" # Prevent concurrent scene changes if is_changing_scene: DebugManager.log_warn( diff --git a/src/autoloads/SaveManager.gd b/src/autoloads/SaveManager.gd index 40c3d5f..24a9e2e 100644 --- a/src/autoloads/SaveManager.gd +++ b/src/autoloads/SaveManager.gd @@ -1,3 +1,9 @@ +## Save Manager - Secure Game Data Persistence System +## +## Provides secure save/load functionality with tamper detection, race condition protection, +## and permissive validation. Features backup/restore, version migration, and data integrity. +## Implements multi-layered security: checksums, size limits, type validation, and bounds checking. + extends Node const SAVE_FILE_PATH: String = "user://savegame.save" @@ -8,7 +14,7 @@ const MAX_SCORE: int = 999999999 const MAX_GAMES_PLAYED: int = 100000 const MAX_FILE_SIZE: int = 1048576 # 1MB limit -# Save operation protection +# Save operation protection - prevents race conditions var _save_in_progress: bool = false var _restore_in_progress: bool = false @@ -28,10 +34,12 @@ var game_data: Dictionary = { func _ready() -> void: + """Initialize SaveManager and load existing save data on startup""" load_game() func save_game() -> bool: + """Save current game data with race condition protection and error handling""" # Prevent concurrent saves if _save_in_progress: DebugManager.log_warn("Save already in progress, skipping", "SaveManager") @@ -82,6 +90,7 @@ func _perform_save() -> bool: func load_game() -> void: + """Load game data from disk with comprehensive validation and error recovery""" if not FileAccess.file_exists(SAVE_FILE_PATH): DebugManager.log_info("No save file found, using defaults", "SaveManager") return