whale-town-front/_Core/managers/SceneManager.gd

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 _next_scene_position: Variant = null            # 下一个场景的初始位置 (Vector2 or null)
var _next_spawn_name: String = ""                   # 下一个场景的出生点名称 (String)

# 场景路径映射表
# 将场景名称映射到实际的文件路径
# 便于统一管理和修改场景路径
var scene_paths: Dictionary = {
	"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", # 设置界面
	"room": "res://scenes/Maps/room.tscn",           # 房间场景
	"square": "res://scenes/Maps/square.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
	
	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()
	
	# 更新场景名称（在切换之前设置，确保新场景的 _ready 能获取正确的名称）
	current_scene_name = scene_name
	
	# 执行场景切换
	var error = get_tree().change_scene_to_file(scene_path)
	if error != OK:
		print("场景切换失败: ", error)
		current_scene_name = ""  # 恢复为空
		is_changing_scene = false
		return false
	
	# 更新状态
	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

# 设置下一个场景的初始位置
func set_next_scene_position(pos: Vector2) -> void:
	_next_scene_position = pos

# 获取并清除下一个场景的初始位置
func get_next_scene_position() -> Variant:
	var pos = _next_scene_position
	_next_scene_position = null
	return pos

# 设置下一个场景的出生点名称
func set_next_spawn_name(spawn_name: String) -> void:
	_next_spawn_name = spawn_name

# 获取并清除下一个场景的出生点名称
func get_next_spawn_name() -> String:
	var name = _next_spawn_name
	_next_spawn_name = ""
	return 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("隐藏场景切换过渡效果")
	await get_tree().create_timer(0.2).timeout