docs：为核心管理器添加详细中文注释

- GameManager.gd：游戏状态管理注释 - NetworkManager.gd：网络请求管理注释 - SceneManager.gd：场景切换管理注释 - StringUtils.gd：字符串工具函数注释按照docs注释规范，添加文件头、函数说明、参数描述和使用示例方便协同开发者快速理解和调用
2026-01-02 21:19:53 +08:00
parent aaaf2b31a8
commit 2f1ccbc2cd
4 changed files with 708 additions and 59 deletions
--- a/_Core/managers/GameManager.gd
+++ b/_Core/managers/GameManager.gd
@@ -1,50 +1,142 @@
 extends Node

-# 游戏管理器 - 全局游戏状态管理
-# 单例模式，管理游戏的整体状态和生命周期
+# ============================================================================
+# GameManager.gd - 游戏管理器
+# ============================================================================
+# 全局单例管理器，负责游戏状态管理和生命周期控制
+# 
+# 核心职责:
+# - 游戏状态切换 (加载、认证、游戏中、暂停等)
+# - 用户信息管理
+# - 全局配置访问
+# - 系统初始化和清理
+#
+# 使用方式:
+#   GameManager.change_state(GameManager.GameState.IN_GAME)
+#   GameManager.set_current_user("player123")
+#
+# 注意事项:
+# - 作为自动加载单例，全局可访问
+# - 状态变更会触发 game_state_changed 信号
+# - 状态切换应该通过 change_state() 方法进行
+# ============================================================================

+# ============ 信号定义 ============
+
+# 游戏状态变更信号
+# 参数: new_state - 新的游戏状态
 signal game_state_changed(new_state: GameState)

+# ============ 枚举定义 ============
+
+# 游戏状态枚举
+# 定义了游戏的各种运行状态
 enum GameState {
-	LOADING,    # 加载中
-	AUTH,       # 认证状态
-	MAIN_MENU,  # 主菜单
-	IN_GAME,    # 游戏中
-	PAUSED,     # 暂停
-	SETTINGS    # 设置
+	LOADING,    # 加载中 - 游戏启动时的初始化状态
+	AUTH,       # 认证状态 - 用户登录/注册界面
+	MAIN_MENU,  # 主菜单 - 游戏主界面
+	IN_GAME,    # 游戏中 - 正在进行游戏
+	PAUSED,     # 暂停 - 游戏暂停状态
+	SETTINGS    # 设置 - 设置界面
 }

-var current_state: GameState = GameState.LOADING
-var previous_state: GameState = GameState.LOADING
-var current_user: String = ""
-var game_version: String = "1.0.0"
+# ============ 成员变量 ============

+# 状态管理
+var current_state: GameState = GameState.LOADING    # 当前游戏状态
+var previous_state: GameState = GameState.LOADING   # 上一个游戏状态
+
+# 用户信息
+var current_user: String = ""                       # 当前登录用户名
+
+# 游戏配置
+var game_version: String = "1.0.0"                  # 游戏版本号
+
+# ============ 生命周期方法 ============
+
+# 初始化游戏管理器
+# 在节点准备就绪时调用，设置初始状态
 func _ready():
 	print("GameManager 初始化完成")
-	change_state(GameState.AUTH)
+	change_state(GameState.AUTH)  # 启动时进入认证状态

+# ============ 状态管理方法 ============
+
+# 切换游戏状态
+# 
+# 参数:
+#   new_state: GameState - 要切换到的新状态
+# 
+# 功能:
+# - 检查状态是否需要切换
+# - 记录状态变更历史
+# - 发送状态变更信号
+# - 输出状态变更日志
 func change_state(new_state: GameState):
+	# 避免重复切换到相同状态
 	if current_state == new_state:
 		return
 	
+	# 记录状态变更
 	previous_state = current_state
 	current_state = new_state
 	
+	# 输出状态变更日志
 	print("游戏状态变更: ", GameState.keys()[previous_state], " -> ", GameState.keys()[current_state])
+	
+	# 发送状态变更信号
 	game_state_changed.emit(new_state)

+# 获取当前游戏状态
+# 
+# 返回值:
+#   GameState - 当前的游戏状态
 func get_current_state() -> GameState:
 	return current_state

+# 获取上一个游戏状态
+# 
+# 返回值:
+#   GameState - 上一个游戏状态
+# 
+# 使用场景:
+# - 从暂停状态恢复时，返回到之前的状态
+# - 错误处理时回退到安全状态
 func get_previous_state() -> GameState:
 	return previous_state

+# ============ 用户管理方法 ============
+
+# 设置当前登录用户
+# 
+# 参数:
+#   username: String - 用户名
+# 
+# 功能:
+# - 存储当前登录用户信息
+# - 输出用户设置日志
+# 
+# 注意事项:
+# - 用户登录成功后调用此方法
+# - 用户登出时应传入空字符串
 func set_current_user(username: String):
 	current_user = username
 	print("当前用户设置为: ", username)

+# 获取当前登录用户
+# 
+# 返回值:
+#   String - 当前登录的用户名，未登录时为空字符串
 func get_current_user() -> String:
 	return current_user

+# 检查用户是否已登录
+# 
+# 返回值:
+#   bool - true表示已登录，false表示未登录
+# 
+# 使用场景:
+# - 进入需要登录的功能前检查
+# - UI显示逻辑判断
 func is_user_logged_in() -> bool:
 	return not current_user.is_empty()
--- a/_Core/managers/NetworkManager.gd
+++ b/_Core/managers/NetworkManager.gd
@@ -1,45 +1,96 @@
 extends Node

-# 网络请求管理器 - 统一处理所有HTTP请求
+# ============================================================================
+# NetworkManager.gd - 网络请求管理器
+# ============================================================================
+# 全局单例管理器，统一处理所有HTTP请求
+# 
+# 核心职责:
+# - 统一的HTTP请求接口 (GET, POST, PUT, DELETE, PATCH)
+# - 认证相关API封装 (登录、注册、验证码等)
+# - 请求状态管理和错误处理
+# - 支持API v1.1.1规范的响应处理
+#
+# 使用方式:
+#   NetworkManager.login("user@example.com", "password", callback)
+#   var request_id = NetworkManager.get_request("/api/data", callback)
+#
+# 注意事项:
+# - 作为自动加载单例，全局可访问
+# - 所有请求都是异步的，通过回调函数或信号处理结果
+# - 支持请求超时和取消功能
+# - 自动处理JSON序列化和反序列化
+# ============================================================================

-# 信号定义
+# ============ 信号定义 ============
+
+# 请求完成信号
+# 参数: 
+#   request_id: String - 请求唯一标识符
+#   success: bool - 请求是否成功
+#   data: Dictionary - 响应数据
 signal request_completed(request_id: String, success: bool, data: Dictionary)
+
+# 请求失败信号
+# 参数:
+#   request_id: String - 请求唯一标识符
+#   error_type: String - 错误类型名称
+#   message: String - 错误消息
 signal request_failed(request_id: String, error_type: String, message: String)

-# API配置
+# ============ 常量定义 ============
+
+# API基础URL - 所有请求的根地址
 const API_BASE_URL = "https://whaletownend.xinghangee.icu"
+
+# 默认请求超时时间（秒）
 const DEFAULT_TIMEOUT = 30.0

-# 请求类型枚举
+# ============ 枚举定义 ============
+
+# HTTP请求方法枚举
 enum RequestType {
-	GET,
-	POST,
-	PUT,
-	DELETE,
-	PATCH
+	GET,     # 获取数据
+	POST,    # 创建数据
+	PUT,     # 更新数据
+	DELETE,  # 删除数据
+	PATCH    # 部分更新数据
 }

 # 错误类型枚举
+# 用于分类不同类型的网络错误
 enum ErrorType {
-	NETWORK_ERROR,      # 网络连接错误
-	TIMEOUT_ERROR,      # 请求超时
-	PARSE_ERROR,        # JSON解析错误
-	HTTP_ERROR,         # HTTP状态码错误
-	BUSINESS_ERROR      # 业务逻辑错误
+	NETWORK_ERROR,      # 网络连接错误 - 无法连接到服务器
+	TIMEOUT_ERROR,      # 请求超时 - 服务器响应时间过长
+	PARSE_ERROR,        # JSON解析错误 - 服务器返回格式错误
+	HTTP_ERROR,         # HTTP状态码错误 - 4xx, 5xx状态码
+	BUSINESS_ERROR      # 业务逻辑错误 - API返回的业务错误
 }

-# 请求状态
+# ============ 请求信息类 ============
+
+# 请求信息封装类
+# 存储单个HTTP请求的所有相关信息
 class RequestInfo:
-	var id: String
-	var url: String
-	var method: RequestType
-	var headers: PackedStringArray
-	var body: String
-	var timeout: float
-	var start_time: float
-	var http_request: HTTPRequest
-	var callback: Callable
+	var id: String                    # 请求唯一标识符
+	var url: String                   # 完整的请求URL
+	var method: RequestType           # HTTP请求方法
+	var headers: PackedStringArray    # 请求头数组
+	var body: String                  # 请求体内容
+	var timeout: float                # 超时时间（秒）
+	var start_time: float             # 请求开始时间戳
+	var http_request: HTTPRequest     # Godot HTTPRequest节点引用
+	var callback: Callable            # 完成时的回调函数
 	
+	# 构造函数
+	# 
+	# 参数:
+	#   request_id: String - 请求唯一标识符
+	#   request_url: String - 请求URL
+	#   request_method: RequestType - HTTP方法
+	#   request_headers: PackedStringArray - 请求头（可选）
+	#   request_body: String - 请求体（可选）
+	#   request_timeout: float - 超时时间（可选，默认使用DEFAULT_TIMEOUT）
 	func _init(request_id: String, request_url: String, request_method: RequestType, 
 			   request_headers: PackedStringArray = [], request_body: String = "", 
 			   request_timeout: float = DEFAULT_TIMEOUT):
@@ -49,40 +100,107 @@ class RequestInfo:
 		headers = request_headers
 		body = request_body
 		timeout = request_timeout
+		# 记录请求开始时间（简化版时间戳）
 		start_time = Time.get_time_dict_from_system().hour * 3600 + Time.get_time_dict_from_system().minute * 60 + Time.get_time_dict_from_system().second

-# 活动请求管理
-var active_requests: Dictionary = {}
-var request_counter: int = 0
+# ============ 成员变量 ============

+# 活动请求管理
+var active_requests: Dictionary = {}                 # 存储所有活动请求 {request_id: RequestInfo}
+var request_counter: int = 0                         # 请求计数器，用于生成唯一ID
+
+# ============ 生命周期方法 ============
+
+# 初始化网络管理器
+# 在节点准备就绪时调用
 func _ready():
 	print("NetworkManager 已初始化")

 # ============ 公共API接口 ============

 # 发送GET请求
+# 
+# 参数:
+#   endpoint: String - API端点路径（如: "/api/users"）
+#   callback: Callable - 完成时的回调函数（可选）
+#   timeout: float - 超时时间（可选，默认30秒）
+# 
+# 返回值:
+#   String - 请求ID，可用于取消请求或跟踪状态
+# 
+# 使用示例:
+#   var request_id = NetworkManager.get_request("/api/users", my_callback)
 func get_request(endpoint: String, callback: Callable = Callable(), timeout: float = DEFAULT_TIMEOUT) -> String:
 	return send_request(endpoint, RequestType.GET, [], "", callback, timeout)

 # 发送POST请求
+# 
+# 参数:
+#   endpoint: String - API端点路径
+#   data: Dictionary - 要发送的数据（将自动转换为JSON）
+#   callback: Callable - 完成时的回调函数（可选）
+#   timeout: float - 超时时间（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 使用示例:
+#   var data = {"name": "张三", "age": 25}
+#   var request_id = NetworkManager.post_request("/api/users", data, my_callback)
 func post_request(endpoint: String, data: Dictionary, callback: Callable = Callable(), timeout: float = DEFAULT_TIMEOUT) -> String:
 	var body = JSON.stringify(data)
 	var headers = ["Content-Type: application/json"]
 	return send_request(endpoint, RequestType.POST, headers, body, callback, timeout)

 # 发送PUT请求
+# 
+# 参数:
+#   endpoint: String - API端点路径
+#   data: Dictionary - 要更新的数据
+#   callback: Callable - 完成时的回调函数（可选）
+#   timeout: float - 超时时间（可选）
+# 
+# 返回值:
+#   String - 请求ID
 func put_request(endpoint: String, data: Dictionary, callback: Callable = Callable(), timeout: float = DEFAULT_TIMEOUT) -> String:
 	var body = JSON.stringify(data)
 	var headers = ["Content-Type: application/json"]
 	return send_request(endpoint, RequestType.PUT, headers, body, callback, timeout)

 # 发送DELETE请求
+# 
+# 参数:
+#   endpoint: String - API端点路径
+#   callback: Callable - 完成时的回调函数（可选）
+#   timeout: float - 超时时间（可选）
+# 
+# 返回值:
+#   String - 请求ID
 func delete_request(endpoint: String, callback: Callable = Callable(), timeout: float = DEFAULT_TIMEOUT) -> String:
 	return send_request(endpoint, RequestType.DELETE, [], "", callback, timeout)

 # ============ 认证相关API ============

 # 用户登录
+# 
+# 参数:
+#   identifier: String - 用户标识符（邮箱或手机号）
+#   password: String - 用户密码
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 回调函数签名:
+#   func callback(success: bool, data: Dictionary, error_info: Dictionary)
+# 
+# 使用示例:
+#   NetworkManager.login("user@example.com", "password123", func(success, data, error):
+#       if success:
+#           print("登录成功: ", data)
+#       else:
+#           print("登录失败: ", error.message)
+#   )
 func login(identifier: String, password: String, callback: Callable = Callable()) -> String:
 	var data = {
 		"identifier": identifier,
@@ -91,6 +209,18 @@ func login(identifier: String, password: String, callback: Callable = Callable()
 	return post_request("/auth/login", data, callback)

 # 验证码登录
+# 
+# 参数:
+#   identifier: String - 用户标识符（邮箱或手机号）
+#   verification_code: String - 验证码
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 使用场景:
+# - 用户忘记密码时的替代登录方式
+# - 提供更安全的登录选项
 func verification_code_login(identifier: String, verification_code: String, callback: Callable = Callable()) -> String:
 	var data = {
 		"identifier": identifier,
@@ -99,11 +229,39 @@ func verification_code_login(identifier: String, verification_code: String, call
 	return post_request("/auth/verification-code-login", data, callback)

 # 发送登录验证码
+# 
+# 参数:
+#   identifier: String - 用户标识符（邮箱或手机号）
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 功能:
+# - 向已注册用户发送登录验证码
+# - 支持邮箱和手机号
+# - 有频率限制保护
 func send_login_verification_code(identifier: String, callback: Callable = Callable()) -> String:
 	var data = {"identifier": identifier}
 	return post_request("/auth/send-login-verification-code", data, callback)

 # 用户注册
+# 
+# 参数:
+#   username: String - 用户名
+#   password: String - 密码
+#   nickname: String - 昵称
+#   email: String - 邮箱地址（可选）
+#   email_verification_code: String - 邮箱验证码（可选）
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 注意事项:
+# - 如果提供邮箱，建议同时提供验证码
+# - 用户名和邮箱必须唯一
+# - 密码需要符合安全要求
 func register(username: String, password: String, nickname: String, email: String = "", 
 			  email_verification_code: String = "", callback: Callable = Callable()) -> String:
 	var data = {
@@ -112,6 +270,7 @@ func register(username: String, password: String, nickname: String, email: Strin
 		"nickname": nickname
 	}
 	
+	# 可选参数处理
 	if email != "":
 		data["email"] = email
 	if email_verification_code != "":
@@ -120,11 +279,35 @@ func register(username: String, password: String, nickname: String, email: Strin
 	return post_request("/auth/register", data, callback)

 # 发送邮箱验证码
+# 
+# 参数:
+#   email: String - 邮箱地址
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 功能:
+# - 向指定邮箱发送验证码
+# - 用于注册时的邮箱验证
+# - 支持测试模式（开发环境）
 func send_email_verification(email: String, callback: Callable = Callable()) -> String:
 	var data = {"email": email}
 	return post_request("/auth/send-email-verification", data, callback)

 # 验证邮箱
+# 
+# 参数:
+#   email: String - 邮箱地址
+#   verification_code: String - 验证码
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 功能:
+# - 验证邮箱验证码的有效性
+# - 通常在注册流程中使用
 func verify_email(email: String, verification_code: String, callback: Callable = Callable()) -> String:
 	var data = {
 		"email": email,
@@ -133,20 +316,66 @@ func verify_email(email: String, verification_code: String, callback: Callable =
 	return post_request("/auth/verify-email", data, callback)

 # 获取应用状态
+# 
+# 参数:
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 功能:
+# - 检查API服务器状态
+# - 获取应用基本信息
+# - 用于网络连接测试
 func get_app_status(callback: Callable = Callable()) -> String:
 	return get_request("/", callback)

 # 重新发送邮箱验证码
+# 
+# 参数:
+#   email: String - 邮箱地址
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 使用场景:
+# - 用户未收到验证码时重新发送
+# - 验证码过期后重新获取
 func resend_email_verification(email: String, callback: Callable = Callable()) -> String:
 	var data = {"email": email}
 	return post_request("/auth/resend-email-verification", data, callback)

 # 忘记密码 - 发送重置验证码
+# 
+# 参数:
+#   identifier: String - 用户标识符（邮箱或手机号）
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 功能:
+# - 向用户发送密码重置验证码
+# - 用于密码找回流程的第一步
 func forgot_password(identifier: String, callback: Callable = Callable()) -> String:
 	var data = {"identifier": identifier}
 	return post_request("/auth/forgot-password", data, callback)

 # 重置密码
+# 
+# 参数:
+#   identifier: String - 用户标识符
+#   verification_code: String - 重置验证码
+#   new_password: String - 新密码
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 功能:
+# - 使用验证码重置用户密码
+# - 密码找回流程的第二步
 func reset_password(identifier: String, verification_code: String, new_password: String, callback: Callable = Callable()) -> String:
 	var data = {
 		"identifier": identifier,
@@ -156,6 +385,19 @@ func reset_password(identifier: String, verification_code: String, new_password:
 	return post_request("/auth/reset-password", data, callback)

 # 修改密码
+# 
+# 参数:
+#   user_id: String - 用户ID
+#   old_password: String - 旧密码
+#   new_password: String - 新密码
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 功能:
+# - 已登录用户修改密码
+# - 需要验证旧密码
 func change_password(user_id: String, old_password: String, new_password: String, callback: Callable = Callable()) -> String:
 	var data = {
 		"user_id": user_id,
@@ -165,6 +407,21 @@ func change_password(user_id: String, old_password: String, new_password: String
 	return put_request("/auth/change-password", data, callback)

 # GitHub OAuth登录
+# 
+# 参数:
+#   github_id: String - GitHub用户ID
+#   username: String - GitHub用户名
+#   nickname: String - 显示昵称
+#   email: String - GitHub邮箱
+#   avatar_url: String - 头像URL（可选）
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 功能:
+# - 通过GitHub账号登录或注册
+# - 支持第三方OAuth认证
 func github_login(github_id: String, username: String, nickname: String, email: String, avatar_url: String = "", callback: Callable = Callable()) -> String:
 	var data = {
 		"github_id": github_id,
@@ -173,6 +430,7 @@ func github_login(github_id: String, username: String, nickname: String, email:
 		"email": email
 	}
 	
+	# 可选头像URL
 	if avatar_url != "":
 		data["avatar_url"] = avatar_url
 	
--- a/_Core/managers/SceneManager.gd
+++ b/_Core/managers/SceneManager.gd
@@ -1,33 +1,96 @@
 extends Node

-# 场景管理器 - 负责场景切换和管理
-# 提供场景切换的统一接口
+# ============================================================================
+# SceneManager.gd - 场景管理器
+# ============================================================================
+# 全局单例管理器，负责场景切换和管理
+# 
+# 核心职责:
+# - 场景切换的统一接口
+# - 场景路径映射管理
+# - 场景切换过渡效果
+# - 场景状态跟踪
+#
+# 使用方式:
+#   SceneManager.change_scene("main")
+#   SceneManager.register_scene("custom", "res://scenes/custom.tscn")
+#
+# 注意事项:
+# - 作为自动加载单例，全局可访问
+# - 场景切换是异步操作，支持过渡效果
+# - 场景名称必须在 scene_paths 中注册
+# ============================================================================

+# ============ 信号定义 ============
+
+# 场景切换完成信号
+# 参数: scene_name - 切换到的场景名称
 signal scene_changed(scene_name: String)
+
+# 场景切换开始信号
+# 参数: scene_name - 即将切换到的场景名称
 signal scene_change_started(scene_name: String)

-var current_scene_name: String = ""
-var is_changing_scene: bool = false
+# ============ 成员变量 ============

-# 场景路径映射
+# 场景状态
+var current_scene_name: String = ""                 # 当前场景名称
+var is_changing_scene: bool = false                 # 是否正在切换场景
+
+# 场景路径映射表
+# 将场景名称映射到实际的文件路径
+# 便于统一管理和修改场景路径
 var scene_paths: Dictionary = {
-	"main": "res://scenes/maps/main_scene.tscn",
-	"auth": "res://scenes/ui/LoginWindow.tscn",
-	"game": "res://scenes/maps/game_scene.tscn",
-	"battle": "res://scenes/maps/battle_scene.tscn",
-	"inventory": "res://scenes/ui/InventoryWindow.tscn",
-	"shop": "res://scenes/ui/ShopWindow.tscn",
-	"settings": "res://scenes/ui/SettingsWindow.tscn"
+	"main": "res://scenes/MainScene.tscn",           # 主场景 - 游戏入口
+	"auth": "res://scenes/ui/LoginWindow.tscn",      # 认证场景 - 登录窗口
+	"game": "res://scenes/maps/game_scene.tscn",     # 游戏场景 - 主要游戏内容
+	"battle": "res://scenes/maps/battle_scene.tscn", # 战斗场景 - 战斗系统
+	"inventory": "res://scenes/ui/InventoryWindow.tscn", # 背包界面
+	"shop": "res://scenes/ui/ShopWindow.tscn",       # 商店界面
+	"settings": "res://scenes/ui/SettingsWindow.tscn" # 设置界面
 }

+# ============ 生命周期方法 ============
+
+# 初始化场景管理器
+# 在节点准备就绪时调用
 func _ready():
 	print("SceneManager 初始化完成")

+# ============ 场景切换方法 ============
+
+# 切换到指定场景
+# 
+# 参数:
+#   scene_name: String - 要切换到的场景名称（必须在scene_paths中注册）
+#   use_transition: bool - 是否使用过渡效果，默认为true
+# 
+# 返回值:
+#   bool - 切换是否成功
+# 
+# 功能:
+# - 检查场景切换状态和场景是否存在
+# - 显示过渡效果（可选）
+# - 执行场景切换
+# - 更新当前场景状态
+# - 发送相关信号
+# 
+# 使用示例:
+#   var success = SceneManager.change_scene("main", true)
+#   if success:
+#       print("场景切换成功")
+# 
+# 注意事项:
+# - 场景切换是异步操作
+# - 切换过程中会阻止新的切换请求
+# - 场景名称必须预先注册
 func change_scene(scene_name: String, use_transition: bool = true):
+	# 防止重复切换
 	if is_changing_scene:
 		print("场景切换中，忽略新的切换请求")
 		return false
 	
+	# 检查场景是否存在
 	if not scene_paths.has(scene_name):
 		print("错误: 未找到场景 ", scene_name)
 		return false
@@ -35,40 +98,89 @@ func change_scene(scene_name: String, use_transition: bool = true):
 	var scene_path = scene_paths[scene_name]
 	print("开始切换场景: ", current_scene_name, " -> ", scene_name)
 	
+	# 设置切换状态
 	is_changing_scene = true
 	scene_change_started.emit(scene_name)
 	
+	# 显示过渡效果
 	if use_transition:
 		await show_transition()
 	
+	# 执行场景切换
 	var error = get_tree().change_scene_to_file(scene_path)
 	if error != OK:
 		print("场景切换失败: ", error)
 		is_changing_scene = false
 		return false
 	
+	# 更新状态
 	current_scene_name = scene_name
 	is_changing_scene = false
 	scene_changed.emit(scene_name)
 	
+	# 隐藏过渡效果
 	if use_transition:
 		await hide_transition()
 	
 	print("场景切换完成: ", scene_name)
 	return true

+# ============ 查询方法 ============
+
+# 获取当前场景名称
+# 
+# 返回值:
+#   String - 当前场景的名称
 func get_current_scene_name() -> String:
 	return current_scene_name

+# ============ 场景注册方法 ============
+
+# 注册新场景
+# 
+# 参数:
+#   scene_name: String - 场景名称（用于切换时引用）
+#   scene_path: String - 场景文件路径
+# 
+# 功能:
+# - 将场景名称和路径添加到映射表
+# - 支持运行时动态注册场景
+# 
+# 使用示例:
+#   SceneManager.register_scene("boss_battle", "res://scenes/boss/boss_battle.tscn")
 func register_scene(scene_name: String, scene_path: String):
 	scene_paths[scene_name] = scene_path
 	print("注册场景: ", scene_name, " -> ", scene_path)

+# ============ 过渡效果方法 ============
+
+# 显示场景切换过渡效果
+# 
+# 功能:
+# - 显示场景切换时的过渡动画
+# - 为用户提供视觉反馈
+# 
+# 注意事项:
+# - 这是异步方法，需要await等待完成
+# - 当前实现为简单的延时，可扩展为复杂动画
+# 
+# TODO: 实现淡入淡出、滑动等过渡效果
 func show_transition():
 	# TODO: 实现场景切换过渡效果
 	print("显示场景切换过渡效果")
 	await get_tree().create_timer(0.2).timeout

+# 隐藏场景切换过渡效果
+# 
+# 功能:
+# - 隐藏场景切换完成后的过渡动画
+# - 恢复正常的游戏显示
+# 
+# 注意事项:
+# - 这是异步方法，需要await等待完成
+# - 与show_transition()配对使用
+# 
+# TODO: 实现与show_transition()对应的隐藏效果
 func hide_transition():
 	# TODO: 隐藏场景切换过渡效果
 	print("隐藏场景切换过渡效果")