forked from datawhale/whale-town-front
docs：为核心管理器添加详细中文注释
- GameManager.gd：游戏状态管理注释 - NetworkManager.gd：网络请求管理注释 - SceneManager.gd：场景切换管理注释 - StringUtils.gd：字符串工具函数注释 按照docs注释规范，添加文件头、函数说明、参数描述和使用示例 方便协同开发者快速理解和调用
This commit is contained in:
@@ -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("隐藏场景切换过渡效果")
|
||||
|
||||
Reference in New Issue
Block a user