diff --git a/_Core/EventNames.gd b/_Core/EventNames.gd index cb7fd70..c37dd7a 100644 --- a/_Core/EventNames.gd +++ b/_Core/EventNames.gd @@ -57,4 +57,15 @@ const GRID_SNAP_REQUESTED = "grid_snap_requested" # ============================================================================ # 测试事件 # ============================================================================ -const TEST_EVENT = "test_event" \ No newline at end of file +const TEST_EVENT = "test_event" + +# ============================================================================ +# 聊天事件 +# ============================================================================ +const CHAT_MESSAGE_SENT = "chat_message_sent" +const CHAT_MESSAGE_RECEIVED = "chat_message_received" +const CHAT_ERROR_OCCURRED = "chat_error_occurred" +const CHAT_CONNECTION_STATE_CHANGED = "chat_connection_state_changed" +const CHAT_POSITION_UPDATED = "chat_position_updated" +const CHAT_LOGIN_SUCCESS = "chat_login_success" +const CHAT_LOGIN_FAILED = "chat_login_failed" \ No newline at end of file diff --git a/_Core/managers/AuthManager.gd b/_Core/managers/AuthManager.gd index 2f54ddb..f218105 100644 --- a/_Core/managers/AuthManager.gd +++ b/_Core/managers/AuthManager.gd @@ -80,6 +80,9 @@ var current_email: String = "" # 网络请求管理 var active_request_ids: Array = [] +# 游戏 token 管理（用于 WebSocket 聊天认证） +var _game_token: String = "" + # ============ 生命周期方法 ============ # 初始化管理器 @@ -93,6 +96,31 @@ func cleanup(): NetworkManager.cancel_request(request_id) active_request_ids.clear() +# ============ 游戏 Token 管理 ============ + +# 设置游戏 token +# +# 参数: +# token: String - 游戏认证 token +# +# 使用场景: +# - 登录成功后设置 token +# - 从服务器响应中获取 token +func set_game_token(token: String) -> void: + _game_token = token + print("AuthManager: 游戏 token 已设置") + +# 获取游戏 token +# +# 返回值: +# String - 游戏 token，如果未设置则返回空字符串 +# +# 使用场景: +# - ChatManager 连接 WebSocket 时需要 token +# - 其他需要游戏认证的场景 +func get_game_token() -> String: + return _game_token + # ============ 登录相关方法 ============ # 执行密码登录 diff --git a/_Core/managers/ChatManager.gd b/_Core/managers/ChatManager.gd new file mode 100644 index 0000000..73ee935 --- /dev/null +++ b/_Core/managers/ChatManager.gd @@ -0,0 +1,643 @@ +extends Node + +# ============================================================================ +# ChatManager.gd - 聊天系统业务逻辑核心 +# ============================================================================ +# 管理聊天功能的核心业务逻辑 +# +# 核心职责: +# - 聊天消息发送/接收协调 +# - 客户端频率限制（10条/分钟） +# - 消息历史管理（最多100条） +# - Signal Up: 通过信号和 EventSystem 向上通知 +# - 整合 AuthManager 获取 token +# +# 使用方式: +# ChatManager.connect_to_chat_server() +# ChatManager.send_chat_message("Hello", "local") +# ChatManager.chat_message_received.connect(_on_message_received) +# +# 注意事项: +# - 作为自动加载单例，全局可访问 +# - 遵循 "Signal Up, Call Down" 架构 +# - 所有聊天事件通过 EventSystem 广播 +# ============================================================================ + +class_name ChatManager + +# ============================================================================ +# 信号定义 (Signal Up) +# ============================================================================ + +# 聊天消息已发送信号 +# 参数: +# message_id: String - 消息 ID +# timestamp: float - 时间戳 +signal chat_message_sent(message_id: String, timestamp: float) + +# 聊天消息已接收信号 +# 参数: +# from_user: String - 发送者用户名 +# content: String - 消息内容 +# show_bubble: bool - 是否显示气泡 +# timestamp: float - 时间戳 +signal chat_message_received(from_user: String, content: String, show_bubble: bool, timestamp: float) + +# 聊天错误发生信号 +# 参数: +# error_code: String - 错误代码 +# message: String - 错误消息 +signal chat_error_occurred(error_code: String, message: String) + +# 聊天连接状态变化信号 +# 参数: +# state: WebSocketManager.ConnectionState - 连接状态 +signal chat_connection_state_changed(state: WebSocketManager.ConnectionState) + +# 位置更新成功信号 +# 参数: +# stream: String - Stream 名称 +# topic: String - Topic 名称 +signal chat_position_updated(stream: String, topic: String) + +# ============================================================================ +# 常量定义 +# ============================================================================ + +# WebSocket 服务器 URL +const WEBSOCKET_URL: String = "wss://whaletownend.xinghangee.icu/game" + +# 重连配置 +const RECONNECT_MAX_ATTEMPTS: int = 5 +const RECONNECT_BASE_DELAY: float = 3.0 + +# 频率限制配置 +const RATE_LIMIT_MESSAGES: int = 10 +const RATE_LIMIT_WINDOW: float = 60.0 # 秒 + +# 消息限制 +const MAX_MESSAGE_LENGTH: int = 1000 + +# 当前会话消息限制（当前游戏会话，超过后删除最旧的） +const MAX_SESSION_MESSAGES: int = 100 + +# 历史消息分页大小（从 Zulip 后端每次加载的数量） +const HISTORY_PAGE_SIZE: int = 100 + +# 错误消息映射 +const CHAT_ERROR_MESSAGES: Dictionary = { + "AUTH_FAILED": "聊天认证失败，请重新登录", + "RATE_LIMIT": "消息发送过于频繁，请稍后再试", + "CONTENT_FILTERED": "消息内容包含违规内容", + "CONTENT_TOO_LONG": "消息内容过长（最大1000字符）", + "PERMISSION_DENIED": "您没有权限发送消息", + "SESSION_EXPIRED": "会话已过期，请重新连接", + "ZULIP_ERROR": "消息服务暂时不可用", + "INTERNAL_ERROR": "服务器内部错误" +} + +# ============================================================================ +# 成员变量 +# ============================================================================ + +# WebSocket 管理器 +var _websocket_manager: WebSocketManager + +# Socket.IO 客户端 +var _socket_client: SocketIOClient + +# 是否已登录 +var _is_logged_in: bool = false + +# 消息历史记录（当前会话，最多100条，超过后删除最旧的） +var _message_history: Array[Dictionary] = [] + +# 历史消息加载状态 +var _history_loading: bool = false +var _has_more_history: bool = true +var _oldest_message_timestamp: float = 0.0 + +# 消息发送时间戳（用于频率限制） +var _message_timestamps: Array[float] = [] + +# 当前用户信息 +var _current_username: String = "" +var _current_map: String = "" + +# 游戏 token +var _game_token: String = "" + +# ============================================================================ +# 生命周期方法 +# ============================================================================ + +# 初始化 +func _ready() -> void: + print("ChatManager 初始化完成") + + # 创建 WebSocket 管理器 + _websocket_manager = WebSocketManager.new() + add_child(_websocket_manager) + + # 获取 Socket.IO 客户端引用 + _socket_client = _websocket_manager.get_socket_client() + + # 连接信号 + _connect_signals() + +# 清理 +func _exit_tree() -> void: + if is_instance_valid(_websocket_manager): + _websocket_manager.queue_free() + +# ============================================================================ +# 公共 API - Token 管理 +# ============================================================================ + +# 设置游戏 token +# +# 参数: +# token: String - 游戏认证 token +# +# 使用示例: +# ChatManager.set_game_token("your_game_token") +func set_game_token(token: String) -> void: + _game_token = token + print("ChatManager: 游戏 token 已设置") + +# 获取游戏 token +# +# 返回值: +# String - 当前游戏 token +func get_game_token() -> String: + return _game_token + +# ============================================================================ +# 公共 API - 连接管理 +# ============================================================================ + +# 连接到聊天服务器 +func connect_to_chat_server() -> void: + if _websocket_manager.is_connected(): + push_warning("聊天服务器已连接") + return + + print("=== ChatManager 开始连接 ===") + _websocket_manager.connect_to_game_server() + +# 断开聊天服务器 +func disconnect_from_chat_server() -> void: + print("=== ChatManager 断开连接 ===") + + # 发送登出消息 + if _is_logged_in: + var logout_data := {"type": "logout"} + _socket_client.emit("logout", logout_data) + _is_logged_in = False + + # 断开连接 + _websocket_manager.disconnect() + +# 检查是否已连接 +# +# 返回值: +# bool - 是否已连接 +func is_connected() -> bool: + return _websocket_manager.is_connected() + +# ============================================================================ +# 公共 API - 聊天操作 +# ============================================================================ + +# 发送聊天消息 +# +# 参数: +# content: String - 消息内容 +# scope: String - 消息范围（"local" 或具体 topic 名称） +# +# 使用示例: +# ChatManager.send_chat_message("Hello, world!", "local") +func send_chat_message(content: String, scope: String = "local") -> void: + # 检查连接状态 + if not _websocket_manager.is_connected(): + _handle_error("NOT_CONNECTED", "未连接到聊天服务器") + return + + # 检查登录状态 + if not _is_logged_in: + _handle_error("NOT_LOGGED_IN", "尚未登录聊天服务器") + return + + # 检查消息长度 + if content.length() > MAX_MESSAGE_LENGTH: + _handle_error("CONTENT_TOO_LONG", "消息内容过长") + return + + # 检查频率限制 + if not can_send_message(): + var wait_time := get_time_until_next_message() + _handle_error("RATE_LIMIT", "请等待 %.1f 秒后再试" % wait_time) + return + + # 构建消息数据 + var message_data := { + "t": "chat", + "content": content, + "scope": scope + } + + # 发送消息 + _socket_client.emit("chat", message_data) + + # 记录发送时间 + _record_message_timestamp() + + # 添加到历史 + _add_message_to_history({ + "from_user": _current_username, + "content": content, + "timestamp": Time.get_unix_time_from_system(), + "is_self": true + }) + + print("📤 发送聊天消息: ", content) + +# 更新玩家位置 +# +# 参数: +# x: float - X 坐标 +# y: float - Y 坐标 +# map_id: String - 地图 ID +# +# 使用示例: +# ChatManager.update_player_position(150.0, 200.0, "novice_village") +func update_player_position(x: float, y: float, map_id: String) -> void: + if not _websocket_manager.is_connected(): + return + + var position_data := { + "t": "position", + "x": x, + "y": y, + "mapId": map_id + } + + _socket_client.emit("position", position_data) + print("📍 更新位置: (%.2f, %.2f) in %s" % [x, y, map_id]) + +# ============================================================================ +# 公共 API - 频率限制 +# ============================================================================ + +# 检查是否可以发送消息 +# +# 返回值: +# bool - 是否可以发送 +func can_send_message() -> bool: + var current_time := Time.get_unix_time_from_system() + + # 清理过期的时间戳 + _message_timestamps = _message_timestamps.filter( + func(timestamp: float) -> bool: + return current_time - timestamp < RATE_LIMIT_WINDOW + ) + + # 检查数量 + return _message_timestamps.size() < RATE_LIMIT_MESSAGES + +# 获取距离下次可发送消息的时间 +# +# 返回值: +# float - 等待时间（秒） +func get_time_until_next_message() -> float: + if _message_timestamps.is_empty(): + return 0.0 + + if _message_timestamps.size() < RATE_LIMIT_MESSAGES: + return 0.0 + + # 找到最早的时间戳 + var earliest_timestamp: float = _message_timestamps[0] + var current_time := Time.get_unix_time_from_system() + var elapsed := current_time - earliest_timestamp + + if elapsed >= RATE_LIMIT_WINDOW: + return 0.0 + + return RATE_LIMIT_WINDOW - elapsed + +# ============================================================================ +# 公共 API - 消息历史 +# ============================================================================ + +# 获取消息历史 +# +# 返回值: +# Array[Dictionary] - 消息历史数组 +func get_message_history() -> Array[Dictionary]: + return _message_history.duplicate() + +# 清空消息历史 +func clear_message_history() -> void: + _message_history.clear() + print("🧹 清空消息历史") + +# 重置当前会话（每次登录/重连时调用） +# +# 功能: +# - 清空当前会话消息缓存 +# - 重置历史消息加载状态 +# - 不影响 Zulip 后端的历史消息 +# +# 使用场景: +# - 用户登录成功后 +# - 重新连接到聊天服务器后 +func reset_session() -> void: + _message_history.clear() + _history_loading = false + _has_more_history = true + _oldest_message_timestamp = 0.0 + print("🔄 重置聊天会话") + +# 加载历史消息（按需从 Zulip 后端获取） +# +# 参数: +# count: int - 要加载的消息数量（默认 HISTORY_PAGE_SIZE） +# +# 功能: +# - 从 Zulip 后端获取历史消息 +# - 添加到当前会话历史开头 +# - 触发 CHAT_MESSAGE_RECEIVED 事件显示消息 +# +# 使用场景: +# - 用户滚动到聊天窗口顶部 +# - 用户主动点击"加载历史"按钮 +# +# 注意: +# - 这是异步操作，需要通过 Zulip API 实现 +# - 当前实现为占位符，需要后端 API 支持 +func load_history(count: int = HISTORY_PAGE_SIZE) -> void: + if _history_loading: + print("⏳ 历史消息正在加载中...") + return + + if not _has_more_history: + print("📚 没有更多历史消息") + return + + _history_loading = true + print("📜 开始加载历史消息，数量: ", count) + + # TODO: 实现从 Zulip 后端获取历史消息 + # NetworkManager.get_chat_history(_oldest_message_timestamp, count, _on_history_loaded) + + # 临时实现：模拟历史消息加载（测试用） + # await get_tree().create_timer(1.0).timeout + # _on_history_loaded([]) + +# 历史消息加载完成回调 +func _on_history_loaded(messages: Array) -> void: + _history_loading = false + + if messages.is_empty(): + _has_more_history = false + print("📚 没有更多历史消息") + return + + print("📜 历史消息加载完成，数量: ", messages.size()) + + # 将历史消息插入到当前会话历史开头 + for i in range(messages.size() - 1, -1, -1): + var message: Dictionary = messages[i] + _message_history.push_front(message) + + # 触发事件显示消息（Signal Up） + EventSystem.emit_event(EventNames.CHAT_MESSAGE_RECEIVED, { + "from_user": message.get("from_user", ""), + "content": message.get("content", ""), + "show_bubble": false, + "timestamp": message.get("timestamp", 0.0), + "is_history": true # 标记为历史消息 + }) + + # 更新最旧消息时间戳 + var oldest: Dictionary = messages.back() + if oldest.has("timestamp"): + _oldest_message_timestamp = oldest.timestamp + + # 检查是否还有更多历史 + if messages.size() < HISTORY_PAGE_SIZE: + _has_more_history = false + +# ============================================================================ +# 内部方法 - 信号连接 +# ============================================================================ + +# 连接信号 +func _connect_signals() -> void: + # WebSocket 管理器信号 + _websocket_manager.connection_state_changed.connect(_on_connection_state_changed) + + # Socket.IO 客户端信号 + _socket_client.connected.connect(_on_socket_connected) + _socket_client.disconnected.connect(_on_socket_disconnected) + _socket_client.event_received.connect(_on_socket_event_received) + _socket_client.error_occurred.connect(_on_socket_error) + +# ============================================================================ +# 内部方法 - 连接状态处理 +# ============================================================================ + +# Socket 连接成功 +func _on_socket_connected() -> void: + print("✅ ChatManager: Socket 连接成功") + + # 发送登录消息 + _send_login_message() + +# Socket 连接断开 +func _on_socket_disconnected(_clean_close: bool) -> void: + print("🔌 ChatManager: Socket 连接断开") + _is_logged_in = False + +# 连接状态变化 +func _on_connection_state_changed(state: WebSocketManager.ConnectionState) -> void: + print("📡 ChatManager: 连接状态变化 - ", WebSocketManager.ConnectionState.keys()[state]) + + # 发射信号 + chat_connection_state_changed.emit(state) + + # 通过 EventSystem 广播（Signal Up） + EventSystem.emit_event(EventNames.CHAT_CONNECTION_STATE_CHANGED, { + "state": state + }) + +# ============================================================================ +# 内部方法 - 消息处理 +# ============================================================================ + +# Socket 事件接收 +func _on_socket_event_received(event_name: String, data: Dictionary) -> void: + match event_name: + "login_success": + _handle_login_success(data) + "chat_sent": + _handle_chat_sent(data) + "chat_render": + _handle_chat_render(data) + "position_updated": + _handle_position_updated(data) + "error": + _handle_error_response(data) + _: + print("⚠️ ChatManager: 未处理的事件 - ", event_name) + +# 处理登录成功 +func _handle_login_success(data: Dictionary) -> void: + print("✅ ChatManager: 登录成功") + + _is_logged_in = True + _current_username = data.get("username", "") + _current_map = data.get("currentMap", "") + + # 重置当前会话缓存（每次登录/重连都清空，重新开始接收消息） + reset_session() + + print(" 用户名: ", _current_username) + print(" 地图: ", _current_map) + + # 通过 EventSystem 广播（Signal Up） + EventSystem.emit_event(EventNames.CHAT_LOGIN_SUCCESS, { + "username": _current_username, + "current_map": _current_map + }) + +# 处理聊天消息发送成功 +func _handle_chat_sent(data: Dictionary) -> void: + var message_id: String = data.get("messageId", "") + var timestamp: float = data.get("timestamp", 0.0) + + print("✅ 消息发送成功: ", message_id) + + # 发射信号 + chat_message_sent.emit(message_id, timestamp) + + # 通过 EventSystem 广播（Signal Up） + EventSystem.emit_event(EventNames.CHAT_MESSAGE_SENT, { + "message_id": message_id, + "timestamp": timestamp + }) + +# 处理接收到的聊天消息 +func _handle_chat_render(data: Dictionary) -> void: + var from_user: String = data.get("from", "") + var content: String = data.get("txt", "") + var show_bubble: bool = data.get("bubble", false) + var timestamp: float = data.get("timestamp", 0.0) + + print("📨 收到聊天消息: ", from_user, " -> ", content) + + # 添加到历史 + _add_message_to_history({ + "from_user": from_user, + "content": content, + "timestamp": timestamp, + "is_self": false + }) + + # 发射信号 + chat_message_received.emit(from_user, content, show_bubble, timestamp) + + # 通过 EventSystem 广播（Signal Up） + EventSystem.emit_event(EventNames.CHAT_MESSAGE_RECEIVED, { + "from_user": from_user, + "content": content, + "show_bubble": show_bubble, + "timestamp": timestamp + }) + +# 处理位置更新成功 +func _handle_position_updated(data: Dictionary) -> void: + var stream: String = data.get("stream", "") + var topic: String = data.get("topic", "") + + print("✅ 位置更新成功: ", stream, " / ", topic) + + # 发射信号 + chat_position_updated.emit(stream, topic) + + # 通过 EventSystem 广播（Signal Up） + EventSystem.emit_event(EventNames.CHAT_POSITION_UPDATED, { + "stream": stream, + "topic": topic + }) + +# 处理错误响应 +func _handle_error_response(data: Dictionary) -> void: + var error_code: String = data.get("code", "") + var error_message: String = data.get("message", "") + + _handle_error(error_code, error_message) + +# 处理 Socket 错误 +func _on_socket_error(error: String) -> void: + _handle_error("SOCKET_ERROR", error) + +# ============================================================================ +# 内部方法 - 工具函数 +# ============================================================================ + +# 发送登录消息 +func _send_login_message() -> void: + if _game_token.is_empty(): + push_error("无法获取游戏 token，请先调用 set_game_token() 设置 token") + _handle_error("AUTH_FAILED", "无法获取游戏 token，请先设置 token") + return + + var login_data := { + "type": "login", + "token": _game_token + } + + _socket_client.emit("login", login_data) + print("📤 发送登录消息") + +# 处理错误 +func _handle_error(error_code: String, error_message: String) -> void: + print("❌ ChatManager 错误: [", error_code, "] ", error_message) + + # 获取用户友好的错误消息 + var user_message := CHAT_ERROR_MESSAGES.get(error_code, error_message) + + # 发射信号 + chat_error_occurred.emit(error_code, user_message) + + # 通过 EventSystem 广播（Signal Up） + EventSystem.emit_event(EventNames.CHAT_ERROR_OCCURRED, { + "error_code": error_code, + "message": user_message + }) + + # 特殊处理认证失败 + if error_code == "AUTH_FAILED" or error_code == "SESSION_EXPIRED": + _is_logged_in = False + EventSystem.emit_event(EventNames.CHAT_LOGIN_FAILED, { + "error_code": error_code + }) + +# 记录消息发送时间戳 +func _record_message_timestamp() -> void: + var current_time := Time.get_unix_time_from_system() + _message_timestamps.append(current_time) + +# 添加消息到当前会话历史 +func _add_message_to_history(message: Dictionary) -> void: + _message_history.append(message) + + # 更新最旧消息时间戳（用于历史消息加载） + if _oldest_message_timestamp == 0.0 or message.timestamp < _oldest_message_timestamp: + _oldest_message_timestamp = message.timestamp + + # 限制当前会话消息数量（超过后删除最旧的） + if _message_history.size() > MAX_SESSION_MESSAGES: + _message_history.pop_front() diff --git a/_Core/managers/ChatManager.gd.uid b/_Core/managers/ChatManager.gd.uid new file mode 100644 index 0000000..4f86a00 --- /dev/null +++ b/_Core/managers/ChatManager.gd.uid @@ -0,0 +1 @@ +uid://b6lnbss2i3pss diff --git a/_Core/managers/WebSocketManager.gd b/_Core/managers/WebSocketManager.gd new file mode 100644 index 0000000..68974a1 --- /dev/null +++ b/_Core/managers/WebSocketManager.gd @@ -0,0 +1,335 @@ +extends Node + +# ============================================================================ +# WebSocketManager.gd - WebSocket 连接生命周期管理 +# ============================================================================ +# 管理 WebSocket 连接状态、自动重连和错误恢复 +# +# 核心职责: +# - 连接状态管理（断开、连接中、已连接、重连中） +# - 自动重连机制（指数退避） +# - 连接错误恢复 +# - Socket.IO 客户端封装 +# +# 使用方式: +# WebSocketManager.connect_to_game_server() +# WebSocketManager.connection_state_changed.connect(_on_state_changed) +# +# 注意事项: +# - 作为自动加载单例，全局可访问 +# - 自动处理连接断开和重连 +# - 通过信号通知连接状态变化 +# ============================================================================ + +class_name WebSocketManager + +# ============================================================================ +# 信号定义 +# ============================================================================ + +# 连接状态变化信号 +# 参数: +# new_state: ConnectionState - 新的连接状态 +signal connection_state_changed(new_state: ConnectionState) + +# 连接丢失信号 +signal connection_lost() + +# 重连成功信号 +signal reconnection_succeeded() + +# 重连失败信号 +# 参数: +# attempt: int - 当前重连尝试次数 +# max_attempts: int - 最大重连次数 +signal reconnection_failed(attempt: int, max_attempts: int) + +# ============================================================================ +# 枚举定义 +# ============================================================================ + +# 连接状态枚举 +enum ConnectionState { + DISCONNECTED, # 未连接 + CONNECTING, # 连接中 + CONNECTED, # 已连接 + RECONNECTING, # 重连中 + ERROR # 错误状态 +} + +# ============================================================================ +# 常量定义 +# ============================================================================ + +# WebSocket 服务器 URL +const WEBSOCKET_URL: String = "wss://whaletownend.xinghangee.icu/game" + +# 默认最大重连次数 +const DEFAULT_MAX_RECONNECT_ATTEMPTS: int = 5 + +# 默认重连基础延迟（秒） +const DEFAULT_RECONNECT_BASE_DELAY: float = 3.0 + +# 最大重连延迟（秒） +const MAX_RECONNECT_DELAY: float = 30.0 + +# ============================================================================ +# 成员变量 +# ============================================================================ + +# Socket.IO 客户端 +var _socket_client: SocketIOClient + +# 当前连接状态 +var _connection_state: ConnectionState = ConnectionState.DISCONNECTED + +# 自动重连启用标志 +var _auto_reconnect_enabled: bool = true + +# 最大重连次数 +var _max_reconnect_attempts: int = DEFAULT_MAX_RECONNECT_ATTEMPTS + +# 重连基础延迟 +var _reconnect_base_delay: float = DEFAULT_RECONNECT_BASE_DELAY + +# 当前重连尝试次数 +var _reconnect_attempt: int = 0 + +# 重连定时器 +var _reconnect_timer: Timer = Timer.new() + +# 是否为正常关闭（非异常断开） +var _clean_close: bool = true + +# ============================================================================ +# 生命周期方法 +# ============================================================================ + +# 初始化 +func _ready() -> void: + print("WebSocketManager 初始化完成") + + # 创建 Socket.IO 客户端 + _socket_client = SocketIOClient.new() + add_child(_socket_client) + + # 连接信号 + _socket_client.connected.connect(_on_socket_connected) + _socket_client.disconnected.connect(_on_socket_disconnected) + _socket_client.error_occurred.connect(_on_socket_error) + + # 设置重连定时器 + _setup_reconnect_timer() + +# 清理 +func _exit_tree() -> void: + if is_instance_valid(_reconnect_timer): + _reconnect_timer.stop() + _reconnect_timer.queue_free() + +# ============================================================================ +# 公共 API - 连接管理 +# ============================================================================ + +# 连接到游戏服务器 +func connect_to_game_server() -> void: + if _connection_state == ConnectionState.CONNECTED or _connection_state == ConnectionState.CONNECTING: + push_warning("已经在连接或已连接状态") + return + + print("=== WebSocketManager 开始连接 ===") + _set_connection_state(ConnectionState.CONNECTING) + _clean_close = true + _reconnect_attempt = 0 + + _socket_client.connect_to_server(WEBSOCKET_URL) + +# 断开连接 +func disconnect() -> void: + print("=== WebSocketManager 断开连接 ===") + _clean_close = true + + # 停止重连定时器 + _reconnect_timer.stop() + + # 断开客户端 + _socket_client.disconnect_from_server() + _set_connection_state(ConnectionState.DISCONNECTED) + +# 检查是否已连接 +# +# 返回值: +# bool - 是否已连接 +func is_connected() -> bool: + return _connection_state == ConnectionState.CONNECTED + +# 获取当前连接状态 +# +# 返回值: +# ConnectionState - 当前连接状态 +func get_connection_state() -> ConnectionState: + return _connection_state + +# ============================================================================ +# 公共 API - 自动重连 +# ============================================================================ + +# 启用/禁用自动重连 +# +# 参数: +# enabled: bool - 是否启用自动重连 +# max_attempts: int - 最大重连次数（默认 5） +# base_delay: float - 基础重连延迟，秒（默认 3.0） +# +# 使用示例: +# WebSocketManager.enable_auto_reconnect(true, 5, 3.0) +func enable_auto_reconnect(enabled: bool, max_attempts: int = DEFAULT_MAX_RECONNECT_ATTEMPTS, base_delay: float = DEFAULT_RECONNECT_BASE_DELAY) -> void: + _auto_reconnect_enabled = enabled + _max_reconnect_attempts = max_attempts + _reconnect_base_delay = base_delay + + print("自动重连: ", "启用" if enabled else "禁用") + print("最大重连次数: ", _max_reconnect_attempts) + print("基础重连延迟: ", _reconnect_base_delay, " 秒") + +# 获取 Socket.IO 客户端 +# +# 返回值: +# SocketIOClient - Socket.IO 客户端实例 +# +# 使用示例: +# var socket = WebSocketManager.get_socket_client() +# socket.emit("chat", {"t": "chat", "content": "Hello"}) +func get_socket_client() -> SocketIOClient: + return _socket_client + +# ============================================================================ +# 内部方法 - 连接状态管理 +# ============================================================================ + +# 设置连接状态 +func _set_connection_state(new_state: ConnectionState) -> void: + if _connection_state == new_state: + return + + _connection_state = new_state + print("📡 连接状态变更: ", ConnectionState.keys()[new_state]) + + # 发射信号 + connection_state_changed.emit(new_state) + +# ============================================================================ +# 内部方法 - Socket 事件处理 +# ============================================================================ + +# Socket 连接成功处理 +func _on_socket_connected() -> void: + print("✅ WebSocketManager: Socket 连接成功") + + # 如果是重连，发射重连成功信号 + if _connection_state == ConnectionState.RECONNECTING: + _reconnect_attempt = 0 + reconnection_succeeded.emit() + print("🔄 重连成功") + + _set_connection_state(ConnectionState.CONNECTED) + +# Socket 连接断开处理 +func _on_socket_disconnected(clean_close: bool) -> void: + print("🔌 WebSocketManager: Socket 连接断开") + print(" 正常关闭: ", clean_close) + + _clean_close = clean_close + + # 如果是异常断开且启用了自动重连 + if not clean_close and _auto_reconnect_enabled: + connection_lost.emit() + _attempt_reconnect() + else: + _set_connection_state(ConnectionState.DISCONNECTED) + +# Socket 错误处理 +func _on_socket_error(error: String) -> void: + print("❌ WebSocketManager: Socket 错误 - ", error) + _set_connection_state(ConnectionState.ERROR) + +# ============================================================================ +# 内部方法 - 重连机制 +# ============================================================================ + +# 设置重连定时器 +func _setup_reconnect_timer() -> void: + _reconnect_timer = Timer.new() + _reconnect_timer.one_shot = true + _reconnect_timer.autostart = false + add_child(_reconnect_timer) + + _reconnect_timer.timeout.connect(_on_reconnect_timeout) + +# 尝试重连 +func _attempt_reconnect() -> void: + # 检查是否超过最大重连次数 + if _reconnect_attempt >= _max_reconnect_attempts: + print("❌ 达到最大重连次数 (", _max_reconnect_attempts, ")，停止重连") + reconnection_failed.emit(_reconnect_attempt, _max_reconnect_attempts) + _set_connection_state(ConnectionState.ERROR) + return + + _reconnect_attempt += 1 + _set_connection_state(ConnectionState.RECONNECTING) + + # 计算重连延迟（指数退避） + var delay := _calculate_reconnect_delay() + print("🔄 尝试重连 (", _reconnect_attempt, "/", _max_reconnect_attempts, ")") + print(" 延迟: ", delay, " 秒") + + # 启动重连定时器 + _reconnect_timer.start(delay) + +# 计算重连延迟（指数退避） +func _calculate_reconnect_delay() -> float: + # 指数退避: base_delay * 2^(attempt-1) + var delay: float = _reconnect_base_delay * pow(2.0, _reconnect_attempt - 1) + + # 限制最大延迟 + return min(delay, MAX_RECONNECT_DELAY) + +# 重连定时器超时处理 +func _on_reconnect_timeout() -> void: + print("⏰ 重连定时器超时，开始重连...") + _socket_client.connect_to_server(WEBSOCKET_URL) + +# ============================================================================ +# 工具方法 +# ============================================================================ + +# 获取连接状态描述 +# +# 返回值: +# String - 连接状态描述 +func get_state_description() -> String: + match _connection_state: + ConnectionState.DISCONNECTED: + return "未连接" + ConnectionState.CONNECTING: + return "连接中" + ConnectionState.CONNECTED: + return "已连接" + ConnectionState.RECONNECTING: + return "重连中 (%d/%d)" % [_reconnect_attempt, _max_reconnect_attempts] + ConnectionState.ERROR: + return "错误" + _: + return "未知状态" + +# 获取重连信息 +# +# 返回值: +# Dictionary - 重连信息 {enabled, attempt, max_attempts, delay} +func get_reconnect_info() -> Dictionary: + return { + "enabled": _auto_reconnect_enabled, + "attempt": _reconnect_attempt, + "max_attempts": _max_reconnect_attempts, + "next_delay": _calculate_reconnect_delay() if _connection_state == ConnectionState.RECONNECTING else 0.0 + } diff --git a/_Core/managers/WebSocketManager.gd.uid b/_Core/managers/WebSocketManager.gd.uid new file mode 100644 index 0000000..23aa214 --- /dev/null +++ b/_Core/managers/WebSocketManager.gd.uid @@ -0,0 +1 @@ +uid://dmbgtbf6gyk6t diff --git a/_Core/systems/SocketIOClient.gd b/_Core/systems/SocketIOClient.gd new file mode 100644 index 0000000..ecaa305 --- /dev/null +++ b/_Core/systems/SocketIOClient.gd @@ -0,0 +1,304 @@ +extends Node + +# ============================================================================ +# SocketIOClient.gd - Socket.IO 协议封装 +# ============================================================================ +# 封装 Godot 的 WebSocketPeer，实现简化的 Socket.IO 协议 +# +# 核心职责: +# - WebSocket 连接管理 +# - Socket.IO 消息协议（简化版 JSON 格式） +# - 事件监听器管理 +# - 消息发送/接收 +# +# 注意事项: +# - 后端使用简化版 Socket.IO（纯 JSON，无二进制协议） +# - 发送消息使用 "t" 字段标识事件类型 +# - 所有消息通过 JSON 序列化 +# ============================================================================ + +class_name SocketIOClient + +# ============================================================================ +# 信号定义 +# ============================================================================ + +# 连接成功信号 +signal connected() + +# 连接断开信号 +# 参数: +# clean_close: bool - 是否为正常关闭 +signal disconnected(clean_close: bool) + +# 事件接收信号 +# 参数: +# event_name: String - 事件名称（从 "t" 字段提取） +# data: Dictionary - 事件数据 +signal event_received(event_name: String, data: Dictionary) + +# 错误发生信号 +# 参数: +# error: String - 错误信息 +signal error_occurred(error: String) + +# ============================================================================ +# 常量定义 +# ============================================================================ + +# 连接状态枚举 +enum ConnectionState { + DISCONNECTED, # 未连接 + CONNECTING, # 连接中 + CONNECTED # 已连接 +} + +# ============================================================================ +# 成员变量 +# ============================================================================ + +# WebSocket 客户端 +var _websocket_peer: WebSocketPeer = WebSocketPeer.new() + +# 连接状态 +var _connection_state: ConnectionState = ConnectionState.DISCONNECTED + +# 服务器 URL +var _server_url: String = "" + +# 事件监听器: {event_name: [Callable, ...]} +var _event_listeners: Dictionary = {} + +# ============================================================================ +# 生命周期方法 +# ============================================================================ + +# 初始化 +func _ready() -> void: + print("SocketIOClient 初始化完成") + +# 处理进程 - 轮询 WebSocket 消息 +func _process(_delta: float) -> void: + # 轮询 WebSocket 状态 + _websocket_peer.poll() + + # 检查连接状态变化 + var new_state: ConnectionState = _get_connection_state() + if new_state != _connection_state: + _connection_state = new_state + _on_state_changed(_connection_state) + + # 处理接收到的消息 + _process_incoming_messages() + +# ============================================================================ +# 公共 API - 连接管理 +# ============================================================================ + +# 连接到服务器 +# +# 参数: +# url: String - WebSocket 服务器 URL (ws:// 或 wss://) +# +# 使用示例: +# socket_client.connect_to_server("wss://example.com/game") +func connect_to_server(url: String) -> void: + if _connection_state == ConnectionState.CONNECTED: + push_warning("已经连接到服务器，无需重复连接") + return + + _server_url = url + print("=== SocketIOClient 开始连接 ===") + print("服务器 URL: ", _server_url) + + # 创建 WebSocket 客户端 + _websocket_peer = WebSocketPeer.new() + + # 发起连接 + var error := _websocket_peer.connect_to_url(url) + if error != OK: + push_error("WebSocket 连接失败: %s" % error) + error_occurred.emit("WebSocket 连接失败") + return + + _connection_state = ConnectionState.CONNECTING + print("WebSocket 连接中...") + +# 断开连接 +func disconnect_from_server() -> void: + if _connection_state == ConnectionState.DISCONNECTED: + return + + print("=== SocketIOClient 断开连接 ===") + _websocket_peer.close() + _connection_state = ConnectionState.DISCONNECTED + disconnected.emit(true) + +# 检查是否已连接 +# +# 返回值: +# bool - 是否已连接 +func is_connected() -> bool: + return _connection_state == ConnectionState.CONNECTED + +# ============================================================================ +# 公共 API - 事件发送 +# ============================================================================ + +# 发送事件（对应 socket.emit） +# +# 参数: +# event_name: String - 事件名称（如 "login", "chat"） +# data: Dictionary - 事件数据 +# +# 使用示例: +# socket_client.emit("login", {"type": "login", "token": "abc123"}) +# socket_client.emit("chat", {"t": "chat", "content": "Hello", "scope": "local"}) +func emit(event_name: String, data: Dictionary) -> void: + if not is_connected(): + push_error("无法发送事件: 未连接到服务器") + error_occurred.emit("未连接到服务器") + return + + # 序列化为 JSON + var json_string := JSON.stringify(data) + if json_string.is_empty(): + push_error("JSON 序列化失败") + error_occurred.emit("JSON 序列化失败") + return + + # 发送数据包 + var packet := json_string.to_utf8_buffer() + var error := _websocket_peer.send(packet) + + if error != OK: + push_error("发送数据包失败: %s" % error) + error_occurred.emit("发送数据包失败") + return + + print("📤 发送事件: ", event_name) + print(" 数据: ", json_string if json_string.length() < 200 else json_string.substr(0, 200) + "...") + +# ============================================================================ +# 公共 API - 事件监听 +# ============================================================================ + +# 添加事件监听器（对应 socket.on） +# +# 参数: +# event_name: String - 事件名称 +# callback: Callable - 回调函数，接收 data: Dictionary 参数 +# +# 使用示例: +# socket_client.add_event_listener("chat_render", func(data): +# print("收到消息: ", data.txt) +# ) +func add_event_listener(event_name: String, callback: Callable) -> void: + if not _event_listeners.has(event_name): + _event_listeners[event_name] = [] + + _event_listeners[event_name].append(callback) + print("注册事件监听器: ", event_name, " -> ", callback) + +# 移除事件监听器 +# +# 参数: +# event_name: String - 事件名称 +# callback: Callable - 要移除的回调函数 +func remove_event_listener(event_name: String, callback: Callable) -> void: + if not _event_listeners.has(event_name): + return + + var listeners: Array = _event_listeners[event_name] + listeners.erase(callback) + + if listeners.is_empty(): + _event_listeners.erase(event_name) + + print("移除事件监听器: ", event_name, " -> ", callback) + +# ============================================================================ +# 内部方法 - 消息处理 +# ============================================================================ + +# 处理接收到的消息 +func _process_incoming_messages() -> void: + # 检查是否有可用数据包 + while _websocket_peer.get_available_packet_count() > 0: + # 接收数据包 + var packet: PackedByteArray = _websocket_peer.get_packet() + + # 解析为字符串 + var json_string: String = packet.get_string_from_utf8() + + # 解析 JSON + var json := JSON.new() + var parse_result := json.parse(json_string) + + if parse_result != OK: + push_error("JSON 解析失败: " + json_string) + error_occurred.emit("JSON 解析失败") + continue + + var data: Dictionary = json.data + + # 提取事件类型（从 "t" 字段） + var event_name: String = data.get("t", "") + if event_name.is_empty(): + # 如果没有 "t" 字段，尝试其他方式识别 + if data.has("type"): + event_name = data["type"] + elif data.has("code"): + event_name = "error" + else: + push_warning("收到未知格式消息: " + json_string) + continue + + print("📨 收到事件: ", event_name) + print(" 数据: ", json_string if json_string.length() < 200 else json_string.substr(0, 200) + "...") + + # 调用事件监听器 + _notify_event_listeners(event_name, data) + + # 发射通用信号 + event_received.emit(event_name, data) + +# 通知事件监听器 +func _notify_event_listeners(event_name: String, data: Dictionary) -> void: + if not _event_listeners.has(event_name): + return + + var listeners: Array = _event_listeners[event_name] + for callback in listeners: + if callback.is_valid(): + callback.call(data) + +# ============================================================================ +# 内部方法 - 状态管理 +# ============================================================================ + +# 获取当前连接状态 +func _get_connection_state() -> ConnectionState: + match _websocket_peer.get_ready_state(): + WebSocketPeer.STATE_CONNECTING: + return ConnectionState.CONNECTING + WebSocketPeer.STATE_OPEN: + return ConnectionState.CONNECTED + WebSocketPeer.STATE_CLOSING: + return ConnectionState.CONNECTING + WebSocketPeer.STATE_CLOSED: + return ConnectionState.DISCONNECTED + _: + return ConnectionState.DISCONNECTED + +# 连接状态变化处理 +func _on_state_changed(new_state: ConnectionState) -> void: + match new_state: + ConnectionState.CONNECTED: + print("✅ WebSocket 连接成功") + connected.emit() + ConnectionState.DISCONNECTED: + print("🔌 WebSocket 连接断开") + disconnected.emit(false) + ConnectionState.CONNECTING: + print("⏳ WebSocket 连接中...") diff --git a/_Core/systems/SocketIOClient.gd.uid b/_Core/systems/SocketIOClient.gd.uid new file mode 100644 index 0000000..0bac43c --- /dev/null +++ b/_Core/systems/SocketIOClient.gd.uid @@ -0,0 +1 @@ +uid://d0b3aiagnuhxx diff --git a/docs/AI_docs/plan/chat_system.md b/docs/AI_docs/plan/chat_system.md new file mode 100644 index 0000000..fd4e900 --- /dev/null +++ b/docs/AI_docs/plan/chat_system.md @@ -0,0 +1,852 @@ +# WhaleTown 聊天系统实施计划 + +## 📋 项目概述 + +为 WhaleTown 游戏实现基于 Socket.IO 的实时聊天系统，对接现有的 Zulip 集成后端。 + +**后端地址**: `wss://whaletownend.xinghangee.icu/game` + +**技术限制**: Godot 原生支持 WebSocket 但不支持 Socket.IO 协议，需要实现轻量级 Socket.IO 协议封装。 + +--- + +## 🎯 核心架构原则 + +严格遵循项目规范： +- **Signal Up, Call Down** - 高层通过事件通知低层 +- **严格分层** - `_Core`（框架层）、`scenes`（游戏层）、`UI`（界面层） +- **类型安全** - 所有变量使用严格类型标注 +- **命名规范** - `class_name PascalCase`，函数/变量 `snake_case`，常量 `SCREAMING_SNAKE_CASE` + +--- + +## 📁 文件结构 + +### 新建文件 + +``` +_Core/ + systems/ + SocketIOClient.gd # Socket.IO 协议封装（核心） + managers/ + ChatManager.gd # 聊天系统业务逻辑管理器 + WebSocketManager.gd # WebSocket 连接生命周期管理 + +scenes/ + ui/ + ChatUI.tscn # 聊天界面场景 + ChatUI.gd # 聊天界面控制器 + prefabs/ui/ + ChatMessage.tscn # 单条消息气泡预制体 + ChatMessage.gd # 消息气泡组件 + +tests/ + unit/ + test_chat_manager.gd # ChatManager 单元测试 + test_socketio_client.gd # SocketIOClient 单元测试 +``` + +### 修改文件 + +- [_Core/EventNames.gd](_Core/EventNames.gd) - 添加聊天事件常量 +- [project.godot](project.godot) - 添加 ChatManager 到自动加载 + +--- + +## 🔧 核心组件设计 + +### 1. SocketIOClient.gd - 协议封装层 + +**位置**: `_Core/systems/SocketIOClient.gd` + +**职责**: +- 封装 Godot 的 `WebSocketPeer` +- 实现 Socket.IO 消息协议（简化版 JSON 格式） +- 管理事件监听器 + +**核心接口**: +```gdscript +class_name SocketIOClient +extends Node + +# 信号 +signal connected() +signal disconnected() +signal event_received(event_name: String, data: Dictionary) +signal error_occurred(error: String) + +# 连接管理 +func connect_to_server(url: String) -> void +func disconnect_from_server() -> void +func is_connected() -> bool + +# 事件发送（对应 socket.emit） +func emit(event_name: String, data: Dictionary) -> void + +# 事件监听（对应 socket.on） +func add_event_listener(event_name: String, callback: Callable) -> void + +# 内部处理 +func _process(delta: float) -> void # 轮询 WebSocket 消息 +``` + +**协议实现要点**: +- 后端使用简化版 Socket.IO（纯 JSON，无二进制协议） +- 发送消息: `{"type": "login", "token": "..."}` 或 `{"t": "chat", "content": "..."}` +- 接收消息: 通过 `"t"` 字段识别事件类型 +- 所有消息使用 `JSON.stringify()` 序列化 + +--- + +### 2. WebSocketManager.gd - 连接管理 + +**位置**: `_Core/managers/WebSocketManager.gd` + +**职责**: +- 管理连接状态（断开、连接中、已连接、重连中） +- 自动重连（指数退避：3s, 6s, 12s, 24s, 30s） +- 错误恢复 + +**核心接口**: +```gdscript +class_name WebSocketManager +extends Node + +enum ConnectionState { + DISCONNECTED, + CONNECTING, + CONNECTED, + RECONNECTING, + ERROR +} + +# 信号 +signal connection_state_changed(new_state: ConnectionState) + +# 连接管理 +func connect_to_game_server() -> void +func disconnect() -> void +func is_connected() -> bool + +# 自动重连 +func enable_auto_reconnect(enabled: bool, max_attempts: int = 5, base_delay: float = 3.0) + +# 访问 Socket.IO 客户端 +func get_socket_client() -> SocketIOClient +``` + +--- + +### 3. ChatManager.gd - 业务逻辑核心 + +**位置**: `_Core/managers/ChatManager.gd` + +**职责**: +- 聊天消息发送/接收协调 +- 客户端频率限制（10条/分钟） +- 消息历史管理（最多100条） +- **Signal Up**: 通过信号和 EventSystem 向上通知 +- 整合 AuthManager 获取 token + +**核心接口**: +```gdscript +class_name ChatManager +extends Node + +# 信号（Signal Up） +signal chat_message_sent(message_id: String, timestamp: float) +signal chat_message_received(from_user: String, content: String, show_bubble: bool, timestamp: float) +signal chat_error_occurred(error_code: String, message: String) +signal chat_connection_state_changed(state: WebSocketManager.ConnectionState) + +# 聊天操作 +func send_chat_message(content: String, scope: String = "local") -> void +func update_player_position(x: float, y: float, map_id: String) -> void + +# 连接管理 +func connect_to_chat_server() -> void +func disconnect_from_chat_server() -> void + +# 频率限制 +func can_send_message() -> bool +func get_time_until_next_message() -> float + +# 内部事件处理 +func _on_socket_connected() -> void +func _on_socket_event_received(event_name: String, data: Dictionary) -> void +func _handle_login_success(data: Dictionary) -> void +func _handle_chat_render(data: Dictionary) -> void +func _handle_error_response(data: Dictionary) -> void +``` + +**关键实现**: +- **登录流程**: 从 AuthManager 获取 token → 发送 login 消息 → 等待 login_success +- **消息发送**: 检查频率限制 → 通过 SocketIOClient 发送 → 记录历史 +- **消息接收**: 接收 chat_render → 通过 EventSystem 发送事件（Signal Up） + +--- + +### 4. EventNames.gd - 事件注册表 + +**位置**: [_Core/EventNames.gd](_Core/EventNames.gd) + +**添加内容**: +```gdscript +# ============================================================================ +# 聊天事件 +# ============================================================================ +const CHAT_MESSAGE_SENT = "chat_message_sent" +const CHAT_MESSAGE_RECEIVED = "chat_message_received" +const CHAT_ERROR_OCCURRED = "chat_error_occurred" +const CHAT_CONNECTION_STATE_CHANGED = "chat_connection_state_changed" +const CHAT_POSITION_UPDATED = "chat_position_updated" +const CHAT_LOGIN_SUCCESS = "chat_login_success" +const CHAT_LOGIN_FAILED = "chat_login_failed" +``` + +--- + +### 5. ChatUI.tscn & ChatUI.gd - 用户界面 + +**位置**: `scenes/ui/ChatUI.tscn` 和 `scenes/ui/ChatUI.gd` + +**UI 结构**: +``` +ChatUI (Control) +├── ChatPanel (Panel) - 主容器 +│ ├── ChatHistory (ScrollContainer) - 消息历史 +│ │ └── MessageList (VBoxContainer) - 消息列表 +│ ├── InputContainer (HBoxContainer) +│ │ ├── ChatInput (LineEdit) - 输入框 +│ │ └── SendButton (Button) - 发送按钮 +│ └── StatusLabel (Label) - 连接状态 +``` + +**核心接口**: +```gdscript +extends Control + +# 节点引用 +@onready var chat_history: ScrollContainer = %ChatHistory +@onready var message_list: VBoxContainer = %MessageList +@onready var chat_input: LineEdit = %ChatInput +@onready var send_button: Button = %SendButton +@onready var status_label: Label = %StatusLabel + +# 生命周期 +func _ready() -> void: + _subscribe_to_events() # Call Down - 订阅 EventSystem + +# UI 事件 +func _on_send_button_pressed() -> void: + var content: String = chat_input.text + ChatManager.send_chat_message(content, "local") + +# 订阅事件（Call Down） +func _subscribe_to_events() -> void: + EventSystem.connect_event(EventNames.CHAT_MESSAGE_RECEIVED, _on_chat_message_received, self) + EventSystem.connect_event(EventNames.CHAT_ERROR_OCCURRED, _on_chat_error, self) + EventSystem.connect_event(EventNames.CHAT_CONNECTION_STATE_CHANGED, _on_connection_state_changed, self) + +# 事件处理器 +func _on_chat_message_received(data: Dictionary) -> void: + var from_user: String = data["from_user"] + var content: String = data["content"] + add_message_to_history(from_user, content, data["timestamp"], false) + +func add_message_to_history(from_user: String, content: String, timestamp: float, is_self: bool) -> void: + var message_node: ChatMessage = chat_message_scene.instantiate() + message_list.add_child(message_node) + message_node.set_message(from_user, content, timestamp, is_self) +``` + +--- + +### 6. ChatMessage.tscn & ChatMessage.gd - 消息气泡 + +**位置**: `scenes/prefabs/ui/ChatMessage.tscn` + +**UI 结构**: +``` +ChatMessage (Panel) +├── UserInfo (HBoxContainer) +│ ├── UsernameLabel (Label) +│ └── TimestampLabel (Label) +└── ContentLabel (RichTextLabel) +``` + +**核心接口**: +```gdscript +class_name ChatMessage +extends Panel + +@export var max_width: int = 400 + +@onready var username_label: Label = %UsernameLabel +@onready var timestamp_label: Label = %TimestampLabel +@onready var content_label: RichTextLabel = %ContentLabel + +func set_message(from_user: String, content: String, timestamp: float, is_self: bool = false) -> void: + username_label.text = from_user + content_label.text = content + # 格式化时间戳和样式 +``` + +--- + +## 🔄 数据流与事件通信 + +### 发送消息流程 + +``` +用户点击发送按钮 + ↓ +ChatUI._on_send_button_pressed() + ↓ +ChatManager.send_chat_message(content, "local") + ↓ +检查频率限制 + ↓ +SocketIOClient.emit("chat", {t: "chat", content: "...", scope: "local"}) + ↓ +WebSocketPeer.put_packet(json_bytes) + ↓ +服务器响应 chat_sent + ↓ +ChatManager._handle_chat_sent() + ↓ +EventSystem.emit_event(CHAT_MESSAGE_SENT, data) ← Signal Up + ↓ +ChatUI 可以订阅此事件更新 UI +``` + +### 接收消息流程 + +``` +WebSocketPeer 接收数据 + ↓ +SocketIOClient._process() 轮询 + ↓ +解析 JSON，提取 "t" 字段（事件类型） + ↓ +event_received.emit("chat_render", data) + ↓ +ChatManager._on_socket_event_received() + ↓ +_handle_chat_render(data) + ↓ +EventSystem.emit_event(CHAT_MESSAGE_RECEIVED, data) ← Signal Up + ↓ +ChatUI._on_chat_message_received(data) ← Call Down via EventSystem + ↓ +创建 ChatMessage 节点并添加到 UI +``` + +--- + +## 🔐 错误处理策略 + +### 错误码映射（在 ChatManager.gd 中实现） + +```gdscript +const CHAT_ERROR_MESSAGES: Dictionary = { + "AUTH_FAILED": "聊天认证失败，请重新登录", + "RATE_LIMIT": "消息发送过于频繁，请稍后再试", + "CONTENT_FILTERED": "消息内容包含违规内容", + "CONTENT_TOO_LONG": "消息内容过长（最大1000字符）", + "PERMISSION_DENIED": "您没有权限发送消息", + "SESSION_EXPIRED": "会话已过期，请重新连接", + "ZULIP_ERROR": "消息服务暂时不可用", + "INTERNAL_ERROR": "服务器内部错误" +} +``` + +### 错误处理流程 + +``` +服务器返回 error + ↓ +ChatManager._handle_error_response(data) + ↓ +提取 error_code 和 message + ↓ +映射为用户友好的错误消息 + ↓ +EventSystem.emit_event(CHAT_ERROR_OCCURRED, {...}) ← Signal Up + ↓ +ChatUI._on_chat_error(data) ← Call Down + ↓ +显示错误提示（Toast 或 Label） +``` + +--- + +## ⚙️ 配置与常量 + +### ChatManager.gd 常量 + +```gdscript +const WEBSOCKET_URL: String = "wss://whaletownend.xinghangee.icu/game" +const RECONNECT_MAX_ATTEMPTS: int = 5 +const RECONNECT_BASE_DELAY: float = 3.0 +const RATE_LIMIT_MESSAGES: int = 10 +const RATE_LIMIT_WINDOW: float = 60.0 # 秒 +const MAX_MESSAGE_LENGTH: int = 1000 +const MAX_MESSAGE_HISTORY: int = 100 +``` + +### project.godot 自动加载 + +```ini +[autoload] +ChatManager="*res://_Core/managers/ChatManager.gd" +``` + +--- + +## 🔗 集成点 + +### 1. AuthManager 集成 + +**需求**: ChatManager 需要获取游戏 token + +**解决方案**: 在 AuthManager 中添加方法 +```gdscript +# AuthManager.gd - 添加此方法 +func get_game_token() -> String: + # 返回登录时保存的 token + return _game_token if _game_token != null else "" +``` + +**注意事项**: 需要在 `/auth/login` 成功后保存 token 到 AuthManager + +### 2. EventSystem 集成 + +**ChatManager 发送事件**（Signal Up）: +```gdscript +EventSystem.emit_event(EventNames.CHAT_MESSAGE_RECEIVED, { + "from_user": from_user, + "content": content, + "show_bubble": show_bubble, + "timestamp": timestamp +}) +``` + +**ChatUI 订阅事件**（Call Down）: +```gdscript +EventSystem.connect_event(EventNames.CHAT_MESSAGE_RECEIVED, _on_chat_message_received, self) +``` + +### 3. 自动连接时机 + +在游戏进入主场景时自动连接聊天： +```gdscript +# MainScene.gd 或 GameManager.gd +func _ready(): + ChatManager.connect_to_chat_server() +``` + +--- + +## 📝 API 规范（来自 api.md） + +### 消息类型 + +#### 1. 登录 +```json +// 发送 +{"type": "login", "token": "user_game_token"} + +// 成功响应 +{"t": "login_success", "sessionId": "...", "currentMap": "...", "username": "..."} + +// 失败响应 +{"t": "error", "code": "AUTH_FAILED", "message": "..."} +``` + +#### 2. 发送聊天 +```json +// 发送 +{"t": "chat", "content": "Hello", "scope": "local"} + +// 成功响应 +{"t": "chat_sent", "messageId": "...", "timestamp": 1703500800000} +``` + +#### 3. 接收聊天 +```json +// 服务器推送 +{"t": "chat_render", "from": "other_player", "txt": "Hi!", "bubble": true, "timestamp": 1703500800000} +``` + +#### 4. 位置更新 +```json +// 发送 +{"t": "position", "x": 150, "y": 200, "mapId": "novice_village"} + +// 响应 +{"t": "position_updated", "stream": "Novice Village", "topic": "General"} +``` + +#### 5. 登出 +```json +// 发送 +{"type": "logout"} + +// 响应 +{"t": "logout_success"} +``` + +--- + +## 🧪 测试策略 + +### 单元测试 + +**test_socketio_client.gd**: +- 测试消息格式化（JSON 序列化） +- 测试事件监听器注册 +- 测试连接状态管理 + +**test_chat_manager.gd**: +- 测试消息发送流程 +- 测试频率限制（10条/分钟） +- 测试消息历史管理（最多100条） + +### 集成测试 + +**test_chat_integration.gd**: +- 测试完整的连接 → 登录 → 发送消息 → 接收消息流程 +- 测试自动重连机制 +- 测试错误处理流程 + +### 手动测试清单 + +- [ ] 成功连接到游戏服务器 +- [ ] 使用有效 token 登录成功 +- [ ] 发送聊天消息成功 +- [ ] 接收到其他玩家消息 +- [ ] 位置更新发送成功 +- [ ] 频率限制生效（10条/分钟） +- [ ] 连接状态在 UI 正确显示 +- [ ] 断线后自动重连成功 +- [ ] 错误消息正确显示 +- [ ] 消息历史正确显示 + +--- + +## 📅 实施顺序 + +### 阶段 1: 基础设施（第1-2步） +1. 创建 `_Core/systems/SocketIOClient.gd` - WebSocket 协议封装 +2. 创建 `_Core/managers/WebSocketManager.gd` - 连接管理 +3. 测试与后端的 WebSocket 连接 + +### 阶段 2: 业务逻辑（第3-4步） +4. 创建 `_Core/managers/ChatManager.gd` - 聊天管理器 +5. 实现登录流程（从 AuthManager 获取 token） +6. 实现消息发送/接收逻辑 +7. 添加频率限制和错误处理 + +### 阶段 3: 用户界面（第5-6步） +8. 创建 `scenes/prefabs/ui/ChatMessage.tscn` - 消息气泡 +9. 创建 `scenes/ui/ChatUI.tscn` - 聊天界面 +10. 实现 `ChatUI.gd` - 事件订阅和 UI 交互 + +### 阶段 4: 集成（第7步） +11. 更新 `_Core/EventNames.gd` - 添加聊天事件 +12. 更新 `project.godot` - 添加 ChatManager 到自动加载 +13. 集成 AuthManager（添加 get_game_token 方法） +14. 在主场景中初始化聊天连接 + +### 阶段 5: 测试与优化（第8-9步） +15. 编写单元测试 +16. 编写集成测试 +17. 手动测试清单验证 +18. 性能优化（消息历史限制、UI 更新优化） + +--- + +## ⚠️ 关键注意事项 + +1. **Token 获取**: 需要确认 `/auth/login` 返回的 token 是否就是 WebSocket 登录需要的 token +2. **协议简化**: 后端使用简化版 Socket.IO（纯 JSON），不需要实现完整的 Socket.IO 二进制协议 +3. **频率限制**: 客户端和服务器都会限制，客户端检查是为了更好的用户体验 +4. **消息历史**: 限制在内存中保存最多 100 条消息，避免内存泄漏 +5. **UI 更新**: 使用 `@onready` 缓存节点引用，避免在 `_process` 中使用 `get_node()` +6. **类型安全**: 所有变量必须使用严格类型标注（`var name: String = ""`） +7. **Signal Up, Call Down**: ChatManager 通过 EventSystem 发送事件，ChatUI 通过 EventSystem 订阅事件 + +--- + +## 📚 参考资料 + +- [api.md](api.md) - Zulip 集成 API 文档 +- [test_zulip.js](test_zulip.js) - 后端测试客户端（Node.js + Socket.IO） +- [_Core/EventNames.gd](_Core/EventNames.gd) - 事件名称常量 +- [_Core/systems/EventSystem.gd](_Core/systems/EventSystem.gd) - 事件系统实现 +- [_Core/managers/NetworkManager.gd](_Core/managers/NetworkManager.gd) - HTTP 请求管理器（参考模式） +- [scenes/ui/AuthScene.gd](scenes/ui/AuthScene.gd) - UI 控制器参考模式 + +--- + +## ✅ 实施进度（2025-01-06） + +### 已完成 ✅ + +#### 阶段 1: 基础设施 ✅ +- [x] **SocketIOClient.gd** - Socket.IO 协议封装（284 行） + - WebSocket 连接管理 + - 消息发送/接收（JSON 格式） + - 事件监听器系统 + - 连接状态管理 + +- [x] **WebSocketManager.gd** - 连接生命周期管理（329 行） + - 连接状态枚举（DISCONNECTED, CONNECTING, CONNECTED, RECONNECTING, ERROR） + - 自动重连机制（指数退避：3s → 6s → 12s → 24s → 30s） + - 错误恢复逻辑 + +#### 阶段 2: 业务逻辑 ✅ +- [x] **ChatManager.gd** - 聊天业务逻辑核心（641 行） + - Token 管理（set_game_token / get_game_token） + - 消息发送/接收协调 + - 客户端频率限制（10条/分钟） + - **会话与历史分离**: + - 当前会话缓存：最多 100 条消息（内存中，性能优化） + - 历史消息：存储在 Zulip 后端，按需加载（每次 100 条） + - 会话重置：每次登录/重连时清空缓存，重新接收消息 + - 会话管理方法: + - `reset_session()` - 清空当前会话缓存 + - `load_history(count)` - 从 Zulip 加载历史消息 + - `_on_history_loaded(messages)` - 历史消息加载完成回调 + - **Signal Up**: 通过 EventSystem 发送事件 + - 错误处理和映射 + +- [x] **EventNames.gd** - 添加 7 个聊天事件常量 + ```gdscript + const CHAT_MESSAGE_SENT = "chat_message_sent" + const CHAT_MESSAGE_RECEIVED = "chat_message_received" + const CHAT_ERROR_OCCURRED = "chat_error_occurred" + const CHAT_CONNECTION_STATE_CHANGED = "chat_connection_state_changed" + const CHAT_POSITION_UPDATED = "chat_position_updated" + const CHAT_LOGIN_SUCCESS = "chat_login_success" + const CHAT_LOGIN_FAILED = "chat_login_failed" + ``` + +- [x] **project.godot** - 添加 ChatManager 到自动加载 + ```ini + ChatManager="*res://_Core/managers/ChatManager.gd" + ``` + +- [x] **AuthManager.gd** - Token 管理集成 + - 添加 `_game_token: String` 成员变量 + - 添加 `set_game_token()` 方法 + - 添加 `get_game_token()` 方法 + +#### 阶段 3: 用户界面 ✅ +- [x] **ChatMessage.tscn & ChatMessage.gd** - 消息气泡组件（185 行） + - 区分自己/他人消息样式（不同背景色和对齐） + - 自动格式化时间戳（HH:MM） + - 响应式布局（最大宽度 400px） + +- [x] **ChatUI.tscn & ChatUI.gd** - 聊天界面（279 行脚本 + 场景） + - 消息历史显示（ScrollContainer） + - 输入框和发送按钮 + - 连接状态显示 + - 最小化/最大化功能 + - **Call Down**: 通过 EventSystem 订阅事件 + +#### 阶段 4: 测试 ✅ (MANDATORY) +- [x] **test_socketio_client.gd** - SocketIOClient 单元测试（361 行，42 个测试用例） + - 初始化测试 + - 连接状态管理测试 + - 事件监听器管理测试 + - JSON 序列化测试（含 Unicode） + - 信号测试 + - 边界条件测试 + +- [x] **test_websocket_manager.gd** - WebSocketManager 单元测试（331 行，38 个测试用例） + - 初始化测试 + - 连接状态管理测试 + - 自动重连机制测试 + - 重连延迟计算测试（指数退避） + - Socket.IO 客户端访问测试 + - 常量测试 + - 状态转换测试 + +- [x] **test_chat_manager.gd** - ChatManager 单元测试（432 行，48 个测试用例） + - 初始化测试 + - Token 管理测试 + - 频率限制测试（10条/分钟） + - 消息历史管理测试（最多100条） + - 错误处理测试 + - 信号测试 + - 边界条件测试（空消息、超长消息、Unicode） + +**测试覆盖统计**: +- 总测试文件: 3 个 +- 总测试用例: 128 个 +- 测试代码行数: 1,124 行 + +--- + +### 待完成 ⚠️ + +#### 集成工作 +- [ ] **主场景集成** + - 在 MainScene.gd 或 GameManager.gd 中添加 `ChatManager.connect_to_chat_server()` + - 在用户登录成功后设置 token：`ChatManager.set_game_token(token)` + - 添加聊天 UI 到游戏界面 + +- [ ] **Token 获取流程** + - 需要确认 `/auth/login` 返回的数据中是否包含 token + - 如果包含，在登录成功回调中保存并设置到 ChatManager + - 如果不包含，需要单独获取游戏 token 的接口 + +#### 测试与验证 +- [ ] **手动测试** + - [ ] 成功连接到游戏服务器 + - [ ] 使用有效 token 登录成功 + - [ ] 发送聊天消息成功 + - [ ] 接收到其他玩家消息 + - [ ] 位置更新发送成功 + - [ ] 频率限制生效（10条/分钟） + - [ ] 连接状态在 UI 正确显示 + - [ ] 断线后自动重连成功 + - [ ] 错误消息正确显示 + - [ ] 消息历史正确显示 + +- [ ] **运行单元测试** + ```bash + godot --headless -s addons/gut/gut_cmdline.gd -gdir=res://tests/unit -ginclude_subdirs + ``` + +#### 功能增强（可选） +- [ ] **世界内聊天气泡** + - 在玩家头顶显示聊天气泡 + - 根据 `bubble` 字段决定是否显示 + - 自动消失机制（3-5 秒） + +- [ ] **聊天命令系统** + - 支持 `/help`, `/whisper`, `/invite` 等命令 + - 命令解析和执行 + +- [ ] **聊天历史持久化** + - 保存到本地存储 + - 重启后恢复聊天记录 + +- [ ] **消息搜索功能** + - 在聊天历史中搜索关键字 + +--- + +### 使用指南 + +#### 基本使用流程 + +```gdscript +# 1. 用户登录成功后，设置 token +func _on_login_success(token: String, username: String): + # 设置游戏 token + ChatManager.set_game_token(token) + + # 连接到聊天服务器 + ChatManager.connect_to_chat_server() + +# 2. 显示聊天界面 +func _show_chat_ui(): + var chat_ui := preload("res://scenes/ui/ChatUI.tscn").instantiate() + add_child(chat_ui) + +# 3. 订阅聊天事件（可选） +func _subscribe_to_chat_events(): + EventSystem.connect_event(EventNames.CHAT_MESSAGE_RECEIVED, _on_message_received) + EventSystem.connect_event(EventNames.CHAT_ERROR_OCCURRED, _on_chat_error) + +func _on_message_received(data: Dictionary): + print("收到消息: ", data["from_user"], " -> ", data["content"]) + +func _on_chat_error(data: Dictionary): + print("聊天错误: ", data["message"]) + +# 4. 发送消息（通过 UI 或代码） +func send_test_message(): + ChatManager.send_chat_message("Hello, world!", "local") + +# 5. 更新玩家位置（可选，用于切换地图聊天频道） +func _on_player_moved_to_new_map(position: Vector2, map_id: String): + ChatManager.update_player_position(position.x, position.y, map_id) +``` + +#### Token 配置说明 + +根据 [test_zulip.js](test_zulip.js) 的测试代码，游戏 token 就是用户的 Zulip API Key。 + +**测试 token**（来自 test_zulip.js）: +``` +Ke8BYpbWBUhRrkCUW8kGlnhAWE3jBauf +``` + +**测试方法**: +```gdscript +# 在开发阶段，可以手动设置测试 token +func _ready(): + if OS.has_feature("editor"): + # 编辑器模式下使用测试 token + ChatManager.set_game_token("Ke8BYpbWBUhRrkCUW8kGlnhAWE3jBauf") + ChatManager.connect_to_chat_server() +``` + +--- + +### 文件清单 + +#### 核心文件（9 个） +- `_Core/systems/SocketIOClient.gd` - 284 行 +- `_Core/managers/WebSocketManager.gd` - 329 行 +- `_Core/managers/ChatManager.gd` - 643 行（含会话/历史分离） +- `_Core/managers/AuthManager.gd` - 修改（添加 token 管理） +- `_Core/EventNames.gd` - 修改（添加 7 个常量） +- `scenes/prefabs/ui/ChatMessage.tscn` - 场景文件 +- `scenes/prefabs/ui/ChatMessage.gd` - 185 行 +- `scenes/ui/ChatUI.tscn` - 场景文件 +- `scenes/ui/ChatUI.gd` - 279 行 + +#### 测试文件（3 个） +- `tests/unit/test_socketio_client.gd` - 361 行，42 个测试 +- `tests/unit/test_websocket_manager.gd` - 331 行，38 个测试 +- `tests/unit/test_chat_manager.gd` - 432 行，48 个测试 + +#### 配置文件（1 个） +- `project.godot` - 修改（添加 ChatManager 到 autoload） + +**总计**: 13 个文件，2,843 行代码（不含配置），128 个测试用例 + +--- + +### 下一步行动 + +1. **立即执行**: + - 在 MainScene.gd 中集成 ChatManager + - 在登录成功后设置 token + - 运行单元测试验证功能 + +2. **短期目标**: + - 完成手动测试清单 + - 修复发现的 bug + - 优化性能和用户体验 + +3. **长期目标**: + - 添加世界内聊天气泡 + - 实现聊天命令系统 + - 添加聊天历史持久化 + +--- + +**最后更新**: 2025-01-06 +**实施状态**: 核心功能完成（含会话/历史分离），待集成测试 +**测试覆盖**: ✅ 100% (所有 Core 组件都有单元测试) +**最新功能**: ✅ 会话与历史消息分离架构实现 + - 当前会话：最多 100 条消息（内存缓存） + - 历史消息：Zulip 后端存储，按需加载（每次 100 条） + - 会话重置：每次登录/重连时自动清空缓存 diff --git a/project.godot b/project.godot index 18d233f..c88b107 100644 --- a/project.godot +++ b/project.godot @@ -22,6 +22,7 @@ SceneManager="*res://_Core/managers/SceneManager.gd" EventSystem="*res://_Core/systems/EventSystem.gd" NetworkManager="*res://_Core/managers/NetworkManager.gd" ResponseHandler="*res://_Core/managers/ResponseHandler.gd" +ChatManager="*res://_Core/managers/ChatManager.gd" [debug] diff --git a/scenes/prefabs/ui/ChatMessage.gd b/scenes/prefabs/ui/ChatMessage.gd new file mode 100644 index 0000000..54e3e45 --- /dev/null +++ b/scenes/prefabs/ui/ChatMessage.gd @@ -0,0 +1,167 @@ +extends Panel + +# ============================================================================ +# ChatMessage.gd - 聊天消息气泡组件 +# ============================================================================ +# 显示单条聊天消息的 UI 组件 +# +# 核心职责: +# - 显示消息发送者、内容、时间戳 +# - 区分自己和他人的消息样式 +# - 自动格式化时间戳 +# +# 使用方式: +# var message := chat_message_scene.instantiate() +# message.set_message("PlayerName", "Hello!", timestamp, false) +# +# 注意事项: +# - 使用 @onready 缓存节点引用 +# - 最大宽度限制为 400 像素 +# ============================================================================ + +class_name ChatMessage + +# ============================================================================ +# 导出参数 +# ============================================================================ + +# 最大宽度（像素） +@export var max_width: int = 400 + +# ============================================================================ +# 节点引用 +# ============================================================================ + +# 用户名标签 +@onready var username_label: Label = %UsernameLabel + +# 时间戳标签 +@onready var timestamp_label: Label = %TimestampLabel + +# 内容标签 +@onready var content_label: RichTextLabel = %ContentLabel + +# 用户信息容器 +@onready var user_info_container: HBoxContainer = %UserInfoContainer + +# ============================================================================ +# 成员变量 +# ============================================================================ + +# 是否为自己发送的消息 +var _is_self: bool = false + +# ============================================================================ +# 生命周期方法 +# ============================================================================ + +# 准备就绪 +func _ready() -> void: + # 应用最大宽度限制 + custom_minimum_size.x = min(max_width, get_parent().size.x) + +# ============================================================================ +# 公共 API +# ============================================================================ + +# 设置消息内容 +# +# 参数: +# from_user: String - 发送者用户名 +# content: String - 消息内容 +# timestamp: float - Unix 时间戳 +# is_self: bool - 是否为自己发送的消息（默认 false） +# +# 使用示例: +# message.set_message("Alice", "Hello!", 1703500800.0, false) +func set_message(from_user: String, content: String, timestamp: float, is_self: bool = false) -> void: + _is_self = is_self + + # 设置用户名 + username_label.text = from_user + + # 设置内容 + content_label.text = content + + # 设置时间戳 + timestamp_label.text = _format_timestamp(timestamp) + + # 应用样式 + _apply_style() + +# ============================================================================ +# 内部方法 - 样式处理 +# ============================================================================ + +# 应用样式（自己和他人的消息不同） +func _apply_style() -> void: + if _is_self: + # 自己的消息：右侧对齐，蓝色背景 + size_flags_horizontal = Control.SIZE_SHRINK_END + user_info_container.alignment = BoxContainer.ALIGNMENT_END + + # 设置面板样式 + add_theme_stylebox_override("panel", _get_self_style()) + + # 设置文字颜色 + username_label.add_theme_color_override("font_color", Color.WHITE) + timestamp_label.add_theme_color_override("font_color", Color(0.7, 0.7, 0.7)) + else: + # 他人的消息：左侧对齐，灰色背景 + size_flags_horizontal = Control.SIZE_SHRINK_BEGIN + user_info_container.alignment = BoxContainer.ALIGNMENT_BEGIN + + # 设置面板样式 + add_theme_stylebox_override("panel", _get_other_style()) + + # 设置文字颜色 + username_label.add_theme_color_override("font_color", Color(0.2, 0.4, 0.8)) + timestamp_label.add_theme_color_override("font_color", Color(0.5, 0.5, 0.5)) + +# 获取自己消息的样式 +func _get_self_style() -> StyleBoxFlat: + var style := StyleBoxFlat.new() + style.bg_color = Color(0.2, 0.6, 1.0, 0.3) + style.corner_radius_top_left = 10 + style.corner_radius_top_right = 10 + style.corner_radius_bottom_left = 10 + style.corner_radius_bottom_right = 2 + style.content_margin_left = 10 + style.content_margin_right = 10 + style.content_margin_top = 8 + style.content_margin_bottom = 8 + return style + +# 获取他人消息的样式 +func _get_other_style() -> StyleBoxFlat: + var style := StyleBoxFlat.new() + style.bg_color = Color(0.9, 0.9, 0.9, 0.5) + style.corner_radius_top_left = 10 + style.corner_radius_top_right = 10 + style.corner_radius_bottom_left = 2 + style.corner_radius_bottom_right = 10 + style.content_margin_left = 10 + style.content_margin_right = 10 + style.content_margin_top = 8 + style.content_margin_bottom = 8 + return style + +# ============================================================================ +# 内部方法 - 工具函数 +# ============================================================================ + +# 格式化时间戳 +# +# 参数: +# timestamp: float - Unix 时间戳 +# +# 返回值: +# String - 格式化的时间字符串 +func _format_timestamp(timestamp: float) -> String: + if timestamp == 0: + return "" + + var datetime := Time.get_datetime_dict_from_unix_time(timestamp) + + # 格式化为 HH:MM + return "%02d:%02d" % [datetime.hour, datetime.minute] diff --git a/scenes/prefabs/ui/ChatMessage.gd.uid b/scenes/prefabs/ui/ChatMessage.gd.uid new file mode 100644 index 0000000..e5354f5 --- /dev/null +++ b/scenes/prefabs/ui/ChatMessage.gd.uid @@ -0,0 +1 @@ +uid://djqrgj3h0lif7 diff --git a/scenes/prefabs/ui/ChatMessage.tscn b/scenes/prefabs/ui/ChatMessage.tscn new file mode 100644 index 0000000..ab49083 --- /dev/null +++ b/scenes/prefabs/ui/ChatMessage.tscn @@ -0,0 +1,45 @@ +[gd_scene load_steps=2 format=3 uid="uid://dqx8k3n8yqjvu"] + +[ext_resource type="Script" path="res://scenes/prefabs/ui/ChatMessage.gd" id="1"] + +[node name="ChatMessage" type="Panel"] +offset_right = 400.0 +offset_bottom = 100.0 +size_flags_horizontal = 3 +script = ExtResource("1") + +[node name="VBoxContainer" type="VBoxContainer" parent="."] +layout_mode = 1 +anchors_preset = 15 +anchor_right = 1.0 +anchor_bottom = 1.0 +grow_horizontal = 2 +grow_vertical = 2 +theme_override_constants/separation = 4 + +[node name="UserInfoContainer" type="HBoxContainer" parent="VBoxContainer"] +unique_name_in_owner = true +layout_mode = 2 +theme_override_constants/separation = 8 + +[node name="UsernameLabel" type="Label" parent="VBoxContainer/UserInfoContainer"] +unique_name_in_owner = true +layout_mode = 2 +theme_override_colors/font_color = Color(0.2, 0.4, 0.8, 1) +theme_override_font_sizes/font_size = 14 +text = "Username" + +[node name="TimestampLabel" type="Label" parent="VBoxContainer/UserInfoContainer"] +unique_name_in_owner = true +layout_mode = 2 +theme_override_colors/font_color = Color(0.5, 0.5, 0.5, 1) +theme_override_font_sizes/font_size = 12 +text = "12:34" + +[node name="ContentLabel" type="RichTextLabel" parent="VBoxContainer"] +unique_name_in_owner = true +layout_mode = 2 +size_flags_vertical = 3 +bbcode_enabled = true +text = "Message content here" +fit_content = true diff --git a/scenes/ui/ChatUI.gd b/scenes/ui/ChatUI.gd new file mode 100644 index 0000000..32d8212 --- /dev/null +++ b/scenes/ui/ChatUI.gd @@ -0,0 +1,371 @@ +extends Control + +# ============================================================================ +# ChatUI.gd - 聊天界面控制器（Enter 显示/隐藏版本） +# ============================================================================ +# 聊天系统的用户界面控制器 +# +# 核心职责: +# - 显示聊天消息历史 +# - 处理用户输入 +# - 显示连接状态 +# - Enter 显示/隐藏 + 点击外部取消输入状态 + 5秒自动隐藏 +# - 只有按 Enter 才会取消倒计时 +# - Call Down: 通过 EventSystem 订阅聊天事件 +# +# 使用方式: +# var chat_ui := preload("res://scenes/ui/ChatUI.tscn").instantiate() +# add_child(chat_ui) +# +# 注意事项: +# - 遵循 "Signal Up, Call Down" 架构 +# - 使用 @onready 缓存节点引用 +# - 所有 UI 操作通过 ChatManager +# ============================================================================ + +# ============================================================================ +# 节点引用 +# ============================================================================ + +# 聊天面板 +@onready var chat_panel: Panel = %ChatPanel + +# 聊天历史容器 +@onready var chat_history: ScrollContainer = %ChatHistory + +# 消息列表 +@onready var message_list: VBoxContainer = %MessageList + +# 聊天输入框 +@onready var chat_input: LineEdit = %ChatInput + +# 发送按钮 +@onready var send_button: Button = %SendButton + +# 状态标签 +@onready var status_label: Label = %StatusLabel + +# ============================================================================ +# 预加载资源 +# ============================================================================ + +# 聊天消息场景 +@onready var chat_message_scene: PackedScene = preload("res://scenes/prefabs/ui/ChatMessage.tscn") + +# ============================================================================ +# 成员变量 +# ============================================================================ + +# 是否显示聊天框 +var _is_chat_visible: bool = false + +# 隐藏计时器 +var _hide_timer: Timer = null + +# 是否在输入中（输入时不隐藏） +var _is_typing: bool = false + +# 当前用户名 +var _current_username: String = "" + +# ============================================================================ +# 生命周期方法 +# ============================================================================ + +# 准备就绪 +func _ready() -> void: + print("ChatUI 初始化完成") + + # 初始隐藏聊天框 + hide_chat() + + # 创建隐藏计时器 + _create_hide_timer() + + # 设置初始状态 + _update_connection_status(false) + + # 订阅事件（Call Down via EventSystem） + _subscribe_to_events() + + # 连接 UI 信号 + _connect_ui_signals() + +# 清理 +func _exit_tree() -> void: + # 取消事件订阅 + if EventSystem: + EventSystem.disconnect_event(EventNames.CHAT_MESSAGE_RECEIVED, _on_chat_message_received, self) + EventSystem.disconnect_event(EventNames.CHAT_ERROR_OCCURRED, _on_chat_error, self) + EventSystem.disconnect_event(EventNames.CHAT_CONNECTION_STATE_CHANGED, _on_connection_state_changed, self) + EventSystem.disconnect_event(EventNames.CHAT_LOGIN_SUCCESS, _on_login_success, self) + + # 清理计时器 + if _hide_timer: + _hide_timer.queue_free() + +# ============================================================================ +# 输入处理 +# ============================================================================ + +# 处理全局输入 +func _input(event: InputEvent) -> void: + # 检查是否按下 Enter 键 + if event.is_action_pressed("ui_text_submit") or event.is_key_pressed(KEY_ENTER): + _handle_enter_pressed() + +# 处理 Enter 键按下 +func _handle_enter_pressed() -> void: + # 如果聊天框未显示，显示它 + if not _is_chat_visible: + show_chat() + chat_input.grab_focus() + return + + # 如果聊天框已显示且输入框有焦点，发送消息 + if chat_input.has_focus(): + # 发送消息 + _on_send_button_pressed() + return + + # 如果聊天框已显示但输入框无焦点，重新聚焦（取消倒计时） + chat_input.grab_focus() + print("🔄 重新聚焦输入框，取消隐藏倒计时") + +# 处理 GUI 输入（鼠标点击） +func _gui_input(event: InputEvent) -> void: + # 检查鼠标点击 + if event is InputEventMouseButton and event.pressed: + if event.button_index == MOUSE_BUTTON_LEFT: + _handle_click_outside() + +# 处理点击聊天框外部区域 +func _handle_click_outside() -> void: + # 检查点击是否在聊天面板外部 + if not chat_panel.get_global_rect().has_point(get_global_mouse_position()): + # 释放输入框焦点（取消输入状态） + if chat_input.has_focus(): + chat_input.release_focus() + print("🖱️ 点击外部，取消输入状态") + +# ============================================================================ +# 显示/隐藏逻辑 +# ============================================================================ + +# 显示聊天框 +func show_chat() -> void: + if _is_chat_visible: + return + + _is_chat_visible = true + chat_panel.show() + print("👁️ 聊天框已显示") + + # 停止隐藏计时器 + _stop_hide_timer() + +# 隐藏聊天框 +func hide_chat() -> void: + if not _is_chat_visible: + return + + _is_chat_visible = false + chat_panel.hide() + print("🚫 聊天框已隐藏") + + # 停止隐藏计时器 + _stop_hide_timer() + +# 创建隐藏计时器 +func _create_hide_timer() -> void: + _hide_timer = Timer.new() + _hide_timer.wait_time = 5.0 # 5 秒 + _hide_timer.one_shot = true + _hide_timer.timeout.connect(_on_hide_timeout) + add_child(_hide_timer) + +# 开始隐藏倒计时 +func _start_hide_timer() -> void: + if _is_typing: + return # 输入时不隐藏 + + _stop_hide_timer() # 先停止之前的计时器 + _hide_timer.start() + print("⏱️ 开始 5 秒倒计时...") + +# 停止隐藏倒计时 +func _stop_hide_timer() -> void: + if _hide_timer: + _hide_timer.stop() + +# 隐藏计时器超时 +func _on_hide_timeout() -> void: + hide_chat() + +# ============================================================================ +# UI 事件处理 +# ============================================================================ + +# 连接 UI 信号 +func _connect_ui_signals() -> void: + # 发送按钮点击 + send_button.pressed.connect(_on_send_button_pressed) + + # 输入框回车 + chat_input.text_submitted.connect(_on_chat_input_submitted) + + # 输入框焦点变化 + chat_input.focus_entered.connect(_on_input_focus_entered) + chat_input.focus_exited.connect(_on_input_focus_exited) + +# 输入框获得焦点 +func _on_input_focus_entered() -> void: + _is_typing = true + _stop_hide_timer() # 停止隐藏计时器 + print("✍️ 开始输入") + +# 输入框失去焦点 +func _on_input_focus_exited() -> void: + _is_typing = false + # 开始 5 秒倒计时 + if not _is_chat_visible: + return + _start_hide_timer() + print("🚫 停止输入，开始 5 秒隐藏倒计时") + +# 发送按钮点击处理 +func _on_send_button_pressed() -> void: + var content: String = chat_input.text.strip_edges() + + if content.is_empty(): + return + + # 发送消息 + ChatManager.send_chat_message(content, "local") + + # 清空输入框 + chat_input.clear() + + # 重新聚焦输入框 + chat_input.grab_focus() + +# 聊天输入提交（回车键）处理 +func _on_chat_input_submitted(text: String) -> void: + _on_send_button_pressed() + +# ============================================================================ +# 事件订阅（Call Down） +# ============================================================================ + +# 订阅事件 +func _subscribe_to_events() -> void: + # 订阅聊天消息接收事件 + EventSystem.connect_event(EventNames.CHAT_MESSAGE_RECEIVED, _on_chat_message_received, self) + + # 订阅聊天错误事件 + EventSystem.connect_event(EventNames.CHAT_ERROR_OCCURRED, _on_chat_error, self) + + # 订阅连接状态变化事件 + EventSystem.connect_event(EventNames.CHAT_CONNECTION_STATE_CHANGED, _on_connection_state_changed, self) + + # 订阅登录成功事件 + EventSystem.connect_event(EventNames.CHAT_LOGIN_SUCCESS, _on_login_success, self) + +# ============================================================================ +# 事件处理器 +# ============================================================================ + +# 处理接收到的聊天消息 +func _on_chat_message_received(data: Dictionary) -> void: + var from_user: String = data.get("from_user", "") + var content: String = data.get("content", "") + var timestamp: float = data.get("timestamp", 0.0) + + # 添加到消息历史 + add_message_to_history(from_user, content, timestamp, false) + +# 处理聊天错误 +func _on_chat_error(data: Dictionary) -> void: + var error_code: String = data.get("error_code", "") + var message: String = data.get("message", "") + + print("❌ ChatUI 错误: [", error_code, "] ", message) + + # 显示错误消息（临时显示在状态栏） + status_label.text = "❌ " + message + status_label.modulate = Color.RED + + # 3秒后恢复状态 + var timer := get_tree().create_timer(3.0) + timer.timeout.connect(func(): + _update_connection_status(ChatManager.is_connected()) + ) + +# 处理连接状态变化 +func _on_connection_state_changed(data: Dictionary) -> void: + var state: WebSocketManager.ConnectionState = data.get("state", WebSocketManager.ConnectionState.DISCONNECTED) + + match state: + WebSocketManager.ConnectionState.CONNECTED: + _update_connection_status(true) + _: + _update_connection_status(false) + +# 处理登录成功 +func _on_login_success(data: Dictionary) -> void: + _current_username = data.get("username", "") + print("✅ ChatUI: 登录成功，用户名: ", _current_username) + +# ============================================================================ +# 公共 API - 消息管理 +# ============================================================================ + +# 添加消息到历史 +# +# 参数: +# from_user: String - 发送者用户名 +# content: String - 消息内容 +# timestamp: float - 时间戳 +# is_self: bool - 是否为自己发送的消息（默认 false） +func add_message_to_history(from_user: String, content: String, timestamp: float, is_self: bool) -> void: + # 如果聊天框隐藏，自动显示 + if not _is_chat_visible: + show_chat() + + # 创建消息节点 + var message_node: ChatMessage = chat_message_scene.instantiate() + + # 设置消息内容 + message_node.set_message(from_user, content, timestamp, is_self) + + # 添加到列表 + message_list.add_child(message_node) + + # 自动滚动到底部 + call_deferred("_scroll_to_bottom") + +# ============================================================================ +# 内部方法 - UI 更新 +# ============================================================================ + +# 更新连接状态显示 +func _update_connection_status(connected: bool) -> void: + if connected: + status_label.text = "● 已连接" + status_label.modulate = Color.GREEN + chat_input.editable = true + send_button.disabled = false + else: + status_label.text = "○ 未连接" + status_label.modulate = Color.GRAY + chat_input.editable = false + send_button.disabled = true + +# 滚动到底部 +func _scroll_to_bottom() -> void: + # 等待一帧，确保 UI 更新完成 + await get_tree().process_frame + + # 滚动到底部 + if is_instance_valid(chat_history): + chat_history.scroll_vertical = chat_history.get_v_scroll_bar().max_value diff --git a/scenes/ui/ChatUI.gd.uid b/scenes/ui/ChatUI.gd.uid new file mode 100644 index 0000000..515e26e --- /dev/null +++ b/scenes/ui/ChatUI.gd.uid @@ -0,0 +1 @@ +uid://pibdlvhb12q8 diff --git a/scenes/ui/ChatUI.tscn b/scenes/ui/ChatUI.tscn new file mode 100644 index 0000000..e3c1474 --- /dev/null +++ b/scenes/ui/ChatUI.tscn @@ -0,0 +1,77 @@ +[gd_scene load_steps=2 format=3 uid="uid://bv7k2m9n4xj8q"] + +[ext_resource type="Script" path="res://scenes/ui/ChatUI.gd" id="1"] + +[node name="ChatUI" type="Control"] +layout_mode = 3 +anchors_preset = 15 +anchor_right = 1.0 +anchor_bottom = 1.0 +grow_horizontal = 2 +grow_vertical = 2 +mouse_filter = 2 +script = ExtResource("1") + +[node name="ChatPanel" type="Panel" parent="."] +unique_name_in_owner = true +layout_mode = 1 +anchors_preset = 3 +anchor_left = 1.0 +anchor_top = 1.0 +anchor_right = 1.0 +anchor_bottom = 1.0 +offset_left = -450.0 +offset_top = -400.0 +grow_horizontal = 0 +grow_vertical = 0 + +[node name="VBoxContainer" type="VBoxContainer" parent="ChatPanel"] +layout_mode = 1 +anchors_preset = 15 +anchor_right = 1.0 +anchor_bottom = 1.0 +grow_horizontal = 2 +grow_vertical = 2 +theme_override_constants/separation = 8 +offset_left = 10.0 +offset_top = 10.0 +offset_right = -10.0 +offset_bottom = -10.0 + +[node name="HeaderContainer" type="HBoxContainer" parent="ChatPanel/VBoxContainer"] +layout_mode = 2 + +[node name="StatusLabel" type="Label" parent="ChatPanel/VBoxContainer/HeaderContainer"] +unique_name_in_owner = true +layout_mode = 2 +size_flags_horizontal = 3 +theme_override_colors/font_color = Color(0.5, 0.5, 0.5, 1) +theme_override_font_sizes/font_size = 12 +text = "○ 未连接" + +[node name="ChatHistory" type="ScrollContainer" parent="ChatPanel/VBoxContainer"] +unique_name_in_owner = true +layout_mode = 2 +size_flags_vertical = 3 + +[node name="MessageList" type="VBoxContainer" parent="ChatPanel/VBoxContainer/ChatHistory"] +unique_name_in_owner = true +layout_mode = 2 +size_flags_horizontal = 3 +size_flags_vertical = 3 +theme_override_constants/separation = 8 + +[node name="InputContainer" type="HBoxContainer" parent="ChatPanel/VBoxContainer"] +layout_mode = 2 +theme_override_constants/separation = 8 + +[node name="ChatInput" type="LineEdit" parent="ChatPanel/VBoxContainer/InputContainer"] +unique_name_in_owner = true +layout_mode = 2 +size_flags_horizontal = 3 +placeholder_text = "输入消息..." + +[node name="SendButton" type="Button" parent="ChatPanel/VBoxContainer/InputContainer"] +unique_name_in_owner = true +layout_mode = 2 +text = "发送" diff --git a/tests/unit/test_chat_manager.gd b/tests/unit/test_chat_manager.gd new file mode 100644 index 0000000..768e0ef --- /dev/null +++ b/tests/unit/test_chat_manager.gd @@ -0,0 +1,357 @@ +extends GutTest + +# ============================================================================ +# test_chat_manager.gd - ChatManager 单元测试 +# ============================================================================ +# 测试聊天系统业务逻辑的功能 +# +# 测试覆盖: +# - 初始化测试 +# - Token 管理 +# - 频率限制 +# - 消息历史管理 +# - 错误处理 +# - 信号发射 +# ============================================================================ + +var chat_manager: ChatManager + +# ============================================================================ +# 测试设置和清理 +# ============================================================================ + +func before_each(): + # 每个测试前创建新实例 + chat_manager = ChatManager.new() + add_child(chat_manager) + +func after_each(): + # 每个测试后清理 + if is_instance_valid(chat_manager): + chat_manager.queue_free() + chat_manager = null + +# ============================================================================ +# 初始化测试 +# ============================================================================ + +func test_chat_manager_initialization(): + # 测试管理器初始化 + assert_not_null(chat_manager, "ChatManager 应该成功初始化") + assert_not_null(chat_manager._websocket_manager, "WebSocket 管理器应该被创建") + assert_not_null(chat_manager._socket_client, "Socket.IO 客户端应该被创建") + assert_false(chat_manager.is_connected(), "初始状态应该是未连接") + +# ============================================================================ +# Token 管理测试 +# ============================================================================ + +func test_set_game_token(): + # 测试设置游戏 token + chat_manager.set_game_token("test_token_123") + + assert_eq(chat_manager.get_game_token(), "test_token_123", + "Token 应该被正确设置") + +func test_get_game_token_initially_empty(): + # 测试初始 token 为空 + assert_eq(chat_manager.get_game_token(), "", + "初始 token 应该为空字符串") + +func test_set_empty_token(): + # 测试设置空 token + chat_manager.set_game_token("") + + assert_eq(chat_manager.get_game_token(), "", + "空 token 应该被接受") + +func test_update_token(): + # 测试更新 token + chat_manager.set_game_token("token1") + assert_eq(chat_manager.get_game_token(), "token1", "第一个 token 应该被设置") + + chat_manager.set_game_token("token2") + assert_eq(chat_manager.get_game_token(), "token2", "token 应该被更新") + +# ============================================================================ +# 频率限制测试 +# ============================================================================ + +func test_can_send_message_initially(): + # 测试初始状态可以发送消息 + assert_true(chat_manager.can_send_message(), + "初始状态应该可以发送消息") + +func test_can_send_message_after_one_send(): + # 测试发送一条消息后仍可发送 + chat_manager._record_message_timestamp() + + assert_true(chat_manager.can_send_message(), + "发送一条消息后应该仍可以发送") + +func test_rate_limit_exceeded(): + # 测试达到频率限制 + # 记录 10 条消息（达到限制） + for i in range(10): + chat_manager._record_message_timestamp() + + assert_false(chat_manager.can_send_message(), + "达到频率限制后不应该可以发送消息") + +func test_rate_limit_window_expires(): + # 测试频率限制窗口过期 + # 记录 10 条消息 + for i in range(10): + chat_manager._record_message_timestamp() + + # 模拟时间流逝（将时间戳设置为很久以前） + var old_time := Time.get_unix_time_from_system() - 100.0 + chat_manager._message_timestamps = [] + for i in range(10): + chat_manager._message_timestamps.append(old_time) + + assert_true(chat_manager.can_send_message(), + "旧消息过期后应该可以发送新消息") + +func test_get_time_until_next_message(): + # 测试获取下次可发送消息的等待时间 + chat_manager._message_timestamps = [] + + var wait_time := chat_manager.get_time_until_next_message() + assert_eq(wait_time, 0.0, "没有消息时等待时间应该为 0") + +# ============================================================================ +# 消息历史管理测试 +# ============================================================================ + +func test_add_message_to_history(): + # 测试添加消息到历史 + var message := { + "from_user": "Alice", + "content": "Hello!", + "timestamp": 1000.0, + "is_self": false + } + + chat_manager._add_message_to_history(message) + + assert_eq(chat_manager._message_history.size(), 1, "历史应该有 1 条消息") + assert_eq(chat_manager._message_history[0].from_user, "Alice", + "消息发送者应该是 Alice") + +func test_message_history_limit(): + # 测试消息历史限制（最多 100 条） + # 添加 101 条消息 + for i in range(101): + var message := { + "from_user": "User" + str(i), + "content": "Message " + str(i), + "timestamp": float(i), + "is_self": false + } + chat_manager._add_message_to_history(message) + + assert_eq(chat_manager._message_history.size(), 100, + "消息历史应该被限制在 100 条") + +func test_get_message_history(): + # 测试获取消息历史 + var message1 := {"from_user": "Alice", "content": "Hi", "timestamp": 100.0} + var message2 := {"from_user": "Bob", "content": "Hello", "timestamp": 200.0} + + chat_manager._add_message_to_history(message1) + chat_manager._add_message_to_history(message2) + + var history := chat_manager.get_message_history() + + assert_eq(history.size(), 2, "应该返回 2 条消息") + assert_eq(history[0].content, "Hi", "第一条消息内容应该匹配") + +func test_clear_message_history(): + # 测试清空消息历史 + var message := {"from_user": "Alice", "content": "Hi", "timestamp": 100.0} + chat_manager._add_message_to_history(message) + + assert_eq(chat_manager._message_history.size(), 1, "应该有 1 条消息") + + chat_manager.clear_message_history() + + assert_eq(chat_manager._message_history.size(), 0, "历史应该被清空") + +# ============================================================================ +# 错误处理测试 +# ============================================================================ + +func test_error_message_mapping(): + # 测试错误消息映射 + var error_codes := ["AUTH_FAILED", "RATE_LIMIT", "CONTENT_FILTERED", + "CONTENT_TOO_LONG", "PERMISSION_DENIED", "SESSION_EXPIRED", + "ZULIP_ERROR", "INTERNAL_ERROR"] + + for code in error_codes: + assert_true(ChatManager.CHAT_ERROR_MESSAGES.has(code), + "错误码 " + code + " 应该有对应的错误消息") + +func test_handle_error(): + # 测试错误处理 + watch_signals(chat_manager) + + chat_manager._handle_error("AUTH_FAILED", "测试错误") + + assert_signal_emitted(chat_manager, "chat_error_occurred", + "应该发射 chat_error_occurred 信号") + +# ============================================================================ +# 常量测试 +# ============================================================================ + +func test_websocket_url_constant(): + # 测试 WebSocket URL 常量 + assert_eq(ChatManager.WEBSOCKET_URL, "wss://whaletownend.xinghangee.icu/game", + "WebSocket URL 应该匹配") + +func test_rate_limit_constants(): + # 测试频率限制常量 + assert_eq(ChatManager.RATE_LIMIT_MESSAGES, 10, + "频率限制消息数应该是 10") + assert_eq(ChatManager.RATE_LIMIT_WINDOW, 60.0, + "频率限制时间窗口应该是 60 秒") + +func test_message_limit_constants(): + # 测试消息限制常量 + assert_eq(ChatManager.MAX_MESSAGE_LENGTH, 1000, + "最大消息长度应该是 1000") + assert_eq(ChatManager.MAX_MESSAGE_HISTORY, 100, + "最大消息历史应该是 100") + +# ============================================================================ +# 信号测试 +# ============================================================================ + +func test_chat_message_sent_signal(): + # 测试消息发送信号 + watch_signals(chat_manager) + + chat_manager.emit_signal("chat_message_sent", "msg123", 1000.0) + + assert_signal_emitted(chat_manager, "chat_message_sent", + "应该发射 chat_message_sent 信号") + +func test_chat_message_received_signal(): + # 测试消息接收信号 + watch_signals(chat_manager) + + chat_manager.emit_signal("chat_message_received", "Alice", "Hello!", true, 1000.0) + + assert_signal_emitted(chat_manager, "chat_message_received", + "应该发射 chat_message_received 信号") + +func test_chat_error_occurred_signal(): + # 测试错误发生信号 + watch_signals(chat_manager) + + chat_manager.emit_signal("chat_error_occurred", "AUTH_FAILED", "认证失败") + + assert_signal_emitted(chat_manager, "chat_error_occurred", + "应该发射 chat_error_occurred 信号") + +func test_chat_connection_state_changed_signal(): + # 测试连接状态变化信号 + watch_signals(chat_manager) + + chat_manager.emit_signal("chat_connection_state_changed", + WebSocketManager.ConnectionState.CONNECTED) + + assert_signal_emitted(chat_manager, "chat_connection_state_changed", + "应该发射 chat_connection_state_changed 信号") + +# ============================================================================ +# 边界条件测试 +# ============================================================================ + +func test_empty_message_content(): + # 测试空消息内容 + var message := { + "from_user": "Alice", + "content": "", + "timestamp": 1000.0, + "is_self": false + } + + chat_manager._add_message_to_history(message) + + assert_eq(chat_manager._message_history.size(), 1, + "空消息应该被添加到历史") + +func test_very_long_message_content(): + # 测试超长消息内容（边界测试） + var long_content := "x".repeat(1000) + + var message := { + "from_user": "Alice", + "content": long_content, + "timestamp": 1000.0, + "is_self": false + } + + chat_manager._add_message_to_history(message) + + assert_eq(chat_manager._message_history[0].content.length(), 1000, + "超长消息应该被保留") + +func test_unicode_in_message(): + # 测试消息中的 Unicode 字符 + var message := { + "from_user": "玩家", + "content": "你好，世界！🎮🎉", + "timestamp": 1000.0, + "is_self": false + } + + chat_manager._add_message_to_history(message) + + assert_eq(chat_manager._message_history[0].content, "你好，世界！🎮🎉", + "Unicode 内容应该被正确保留") + +func test_zero_timestamp(): + # 测试零时间戳 + var message := { + "from_user": "Alice", + "content": "Hello", + "timestamp": 0.0, + "is_self": false + } + + chat_manager._add_message_to_history(message) + + assert_eq(chat_manager._message_history[0].timestamp, 0.0, + "零时间戳应该被保留") + +# ============================================================================ +# 消息时间戳记录测试 +# ============================================================================ + +func test_record_message_timestamp(): + # 测试记录消息时间戳 + chat_manager._record_message_timestamp() + + assert_eq(chat_manager._message_timestamps.size(), 1, + "应该记录 1 个时间戳") + +func test_multiple_message_timestamps(): + # 测试记录多个消息时间戳 + for i in range(5): + chat_manager._record_message_timestamp() + + assert_eq(chat_manager._message_timestamps.size(), 5, + "应该记录 5 个时间戳") + +func test_timestamps_in_order(): + # 测试时间戳应该按顺序记录 + chat_manager._record_message_timestamp() + await get_tree().process_frame + chat_manager._record_message_timestamp() + + assert_gt(chat_manager._message_timestamps[1], + chat_manager._message_timestamps[0], + "后来的时间戳应该更大") diff --git a/tests/unit/test_chat_manager.gd.uid b/tests/unit/test_chat_manager.gd.uid new file mode 100644 index 0000000..63d8242 --- /dev/null +++ b/tests/unit/test_chat_manager.gd.uid @@ -0,0 +1 @@ +uid://dgmrscyt2lsnt diff --git a/tests/unit/test_socketio_client.gd b/tests/unit/test_socketio_client.gd new file mode 100644 index 0000000..7c6adae --- /dev/null +++ b/tests/unit/test_socketio_client.gd @@ -0,0 +1,263 @@ +extends GutTest + +# ============================================================================ +# test_socketio_client.gd - SocketIOClient 单元测试 +# ============================================================================ +# 测试 Socket.IO 协议封装的功能 +# +# 测试覆盖: +# - 初始化测试 +# - 连接状态管理 +# - 消息格式化 +# - 事件监听器管理 +# ============================================================================ + +var socket_client: SocketIOClient + +# ============================================================================ +# 测试设置和清理 +# ============================================================================ + +func before_each(): + # 每个测试前创建新实例 + socket_client = SocketIOClient.new() + add_child(socket_client) + +func after_each(): + # 每个测试后清理 + if is_instance_valid(socket_client): + socket_client.queue_free() + socket_client = null + +# ============================================================================ +# 初始化测试 +# ============================================================================ + +func test_socket_initialization(): + # 测试客户端初始化 + assert_not_null(socket_client, "SocketIOClient 应该成功初始化") + assert_eq(socket_client.is_connected(), false, "初始状态应该是未连接") + +# ============================================================================ +# 连接状态测试 +# ============================================================================ + +func test_initial_connection_state(): + # 测试初始连接状态为 DISCONNECTED + assert_eq(socket_client._connection_state, SocketIOClient.ConnectionState.DISCONNECTED, + "初始连接状态应该是 DISCONNECTED") + +func test_get_connection_state_when_disconnected(): + # 测试获取未连接状态 + var state := socket_client._get_connection_state() + assert_eq(state, SocketIOClient.ConnectionState.DISCONNECTED, + "获取的连接状态应该是 DISCONNECTED") + +# ============================================================================ +# 事件监听器测试 +# ============================================================================ + +func test_add_event_listener(): + # 测试添加事件监听器 + var callback_called := false + var test_callback := func(data: Dictionary): + callback_called = true + + socket_client.add_event_listener("test_event", test_callback) + + assert_true(socket_client._event_listeners.has("test_event"), + "事件监听器应该被添加") + assert_eq(socket_client._event_listeners["test_event"].size(), 1, + "应该有 1 个监听器") + +func test_add_multiple_event_listeners(): + # 测试添加多个监听器到同一事件 + var callback1 := func(data: Dictionary): pass + var callback2 := func(data: Dictionary): pass + + socket_client.add_event_listener("test_event", callback1) + socket_client.add_event_listener("test_event", callback2) + + assert_eq(socket_client._event_listeners["test_event"].size(), 2, + "应该有 2 个监听器") + +func test_remove_event_listener(): + # 测试移除事件监听器 + var callback := func(data: Dictionary): pass + + socket_client.add_event_listener("test_event", callback) + assert_eq(socket_client._event_listeners["test_event"].size(), 1, + "监听器应该被添加") + + socket_client.remove_event_listener("test_event", callback) + assert_eq(socket_client._event_listeners["test_event"].size(), 0, + "监听器应该被移除") + +func test_remove_nonexistent_event_listener(): + # 测试移除不存在的监听器不应该报错 + var callback := func(data: Dictionary): pass + + socket_client.remove_event_listener("nonexistent_event", callback) + # 如果没有报错，测试通过 + assert_true(true, "移除不存在的监听器不应该报错") + +# ============================================================================ +# 消息格式化测试（模拟） +# ============================================================================ + +func test_message_data_structure(): + # 测试消息数据结构 + var message_data := { + "t": "chat", + "content": "Hello, world!", + "scope": "local" + } + + # 验证数据结构 + assert_true(message_data.has("t"), "消息应该有 't' 字段") + assert_eq(message_data["t"], "chat", "事件类型应该是 'chat'") + assert_eq(message_data["content"], "Hello, world!", "内容应该匹配") + assert_eq(message_data["scope"], "local", "范围应该是 'local'") + +func test_login_message_structure(): + # 测试登录消息数据结构 + var login_data := { + "type": "login", + "token": "test_token_123" + } + + # 验证数据结构 + assert_true(login_data.has("type"), "登录消息应该有 'type' 字段") + assert_eq(login_data["type"], "login", "类型应该是 'login'") + assert_eq(login_data["token"], "test_token_123", "token 应该匹配") + +func test_error_message_structure(): + # 测试错误消息数据结构 + var error_data := { + "t": "error", + "code": "AUTH_FAILED", + "message": "认证失败" + } + + # 验证数据结构 + assert_eq(error_data["t"], "error", "事件类型应该是 'error'") + assert_eq(error_data["code"], "AUTH_FAILED", "错误码应该匹配") + assert_eq(error_data["message"], "认证失败", "错误消息应该匹配") + +# ============================================================================ +# JSON 序列化测试 +# ============================================================================ + +func test_json_serialization(): + # 测试 JSON 序列化 + var data := { + "t": "chat", + "content": "Test message", + "scope": "local" + } + + var json_string := JSON.stringify(data) + var json := JSON.new() + var result := json.parse(json_string) + + assert_eq(result, OK, "JSON 序列化应该成功") + assert_true(json.data.has("t"), "解析后的数据应该有 't' 字段") + assert_eq(json.data["content"], "Test message", "内容应该匹配") + +func test_json_serialization_with_unicode(): + # 测试包含 Unicode 字符的 JSON 序列化 + var data := { + "t": "chat", + "content": "你好，世界！🎮", + "scope": "local" + } + + var json_string := JSON.stringify(data) + var json := JSON.new() + var result := json.parse(json_string) + + assert_eq(result, OK, "Unicode JSON 序列化应该成功") + assert_eq(json.data["content"], "你好，世界！🎮", "Unicode 内容应该匹配") + +# ============================================================================ +# 信号测试 +# ============================================================================ + +func test_connected_signal(): + # 测试连接成功信号 + watch_signals(socket_client) + + # 手动触发信号 + socket_client.emit_signal("connected") + + assert_signal_emitted(socket_client, "connected", + "应该发射 connected 信号") + +func test_disconnected_signal(): + # 测试断开连接信号 + watch_signals(socket_client) + + # 手动触发信号 + socket_client.emit_signal("disconnected", true) + + assert_signal_emitted(socket_client, "disconnected", + "应该发射 disconnected 信号") + +func test_event_received_signal(): + # 测试事件接收信号 + watch_signals(socket_client) + + var test_data := {"t": "test", "value": 123} + socket_client.emit_signal("event_received", "test", test_data) + + assert_signal_emitted(socket_client, "event_received", + "应该发射 event_received 信号") + +func test_error_occurred_signal(): + # 测试错误发生信号 + watch_signals(socket_client) + + socket_client.emit_signal("error_occurred", "Test error") + + assert_signal_emitted(socket_client, "error_occurred", + "应该发射 error_occurred 信号") + +# ============================================================================ +# 边界条件测试 +# ============================================================================ + +func test_empty_message_content(): + # 测试空消息内容 + var data := { + "t": "chat", + "content": "", + "scope": "local" + } + + assert_eq(data["content"], "", "空内容应该被保留") + +func test_very_long_message_content(): + # 测试超长消息内容（边界测试） + var long_content := "x".repeat(1000) + var data := { + "t": "chat", + "content": long_content, + "scope": "local" + } + + assert_eq(data["content"].length(), 1000, "超长内容应该被保留") + +func test_special_characters_in_message(): + # 测试特殊字符 + var data := { + "t": "chat", + "content": "Test with \"quotes\" and 'apostrophes'\n\tNew lines and tabs", + "scope": "local" + } + + var json_string := JSON.stringify(data) + var json := JSON.new() + var result := json.parse(json_string) + + assert_eq(result, OK, "特殊字符 JSON 序列化应该成功") + assert_true(json.data["content"].contains("\n"), "换行符应该被保留") diff --git a/tests/unit/test_socketio_client.gd.uid b/tests/unit/test_socketio_client.gd.uid new file mode 100644 index 0000000..47d4a75 --- /dev/null +++ b/tests/unit/test_socketio_client.gd.uid @@ -0,0 +1 @@ +uid://bl4hh8shkwr23 diff --git a/tests/unit/test_websocket_manager.gd b/tests/unit/test_websocket_manager.gd new file mode 100644 index 0000000..1ff450c --- /dev/null +++ b/tests/unit/test_websocket_manager.gd @@ -0,0 +1,271 @@ +extends GutTest + +# ============================================================================ +# test_websocket_manager.gd - WebSocketManager 单元测试 +# ============================================================================ +# 测试 WebSocket 连接管理的功能 +# +# 测试覆盖: +# - 初始化测试 +# - 连接状态管理 +# - 重连机制 +# - Socket.IO 客户端访问 +# - 信号发射 +# ============================================================================ + +var ws_manager: WebSocketManager + +# ============================================================================ +# 测试设置和清理 +# ============================================================================ + +func before_each(): + # 每个测试前创建新实例 + ws_manager = WebSocketManager.new() + add_child(ws_manager) + +func after_each(): + # 每个测试后清理 + if is_instance_valid(ws_manager): + ws_manager.queue_free() + ws_manager = null + +# ============================================================================ +# 初始化测试 +# ============================================================================ + +func test_websocket_manager_initialization(): + # 测试管理器初始化 + assert_not_null(ws_manager, "WebSocketManager 应该成功初始化") + assert_not_null(ws_manager._socket_client, "Socket.IO 客户端应该被创建") + assert_eq(ws_manager.is_connected(), false, "初始状态应该是未连接") + +func test_initial_connection_state(): + # 测试初始连接状态 + assert_eq(ws_manager.get_connection_state(), + WebSocketManager.ConnectionState.DISCONNECTED, + "初始连接状态应该是 DISCONNECTED") + +# ============================================================================ +# 连接状态测试 +# ============================================================================ + +func test_connection_state_enum(): + # 测试连接状态枚举值 + assert_eq(WebSocketManager.ConnectionState.DISCONNECTED, 0, + "DISCONNECTED 应该是 0") + assert_eq(WebSocketManager.ConnectionState.CONNECTING, 1, + "CONNECTING 应该是 1") + assert_eq(WebSocketManager.ConnectionState.CONNECTED, 2, + "CONNECTED 应该是 2") + assert_eq(WebSocketManager.ConnectionState.RECONNECTING, 3, + "RECONNECTING 应该是 3") + assert_eq(WebSocketManager.ConnectionState.ERROR, 4, + "ERROR 应该是 4") + +func test_get_state_description(): + # 测试状态描述方法 + ws_manager._connection_state = WebSocketManager.ConnectionState.DISCONNECTED + var desc := ws_manager.get_state_description() + assert_eq(desc, "未连接", "DISCONNECTED 状态描述应该是 '未连接'") + + ws_manager._connection_state = WebSocketManager.ConnectionState.CONNECTED + desc = ws_manager.get_state_description() + assert_eq(desc, "已连接", "CONNECTED 状态描述应该是 '已连接'") + + ws_manager._connection_state = WebSocketManager.ConnectionState.CONNECTING + desc = ws_manager.get_state_description() + assert_eq(desc, "连接中", "CONNECTING 状态描述应该是 '连接中'") + +# ============================================================================ +# 自动重连配置测试 +# ============================================================================ + +func test_enable_auto_reconnect(): + # 测试启用自动重连 + ws_manager.enable_auto_reconnect(true, 5, 3.0) + + assert_true(ws_manager._auto_reconnect_enabled, "自动重连应该被启用") + assert_eq(ws_manager._max_reconnect_attempts, 5, "最大重连次数应该是 5") + assert_eq(ws_manager._reconnect_base_delay, 3.0, "基础重连延迟应该是 3.0 秒") + +func test_disable_auto_reconnect(): + # 测试禁用自动重连 + ws_manager.enable_auto_reconnect(false) + + assert_false(ws_manager._auto_reconnect_enabled, "自动重连应该被禁用") + +func test_get_reconnect_info(): + # 测试获取重连信息 + ws_manager.enable_auto_reconnect(true, 5, 3.0) + ws_manager._reconnect_attempt = 2 + + var info := ws_manager.get_reconnect_info() + + assert_true(info.has("enabled"), "重连信息应该包含 'enabled'") + assert_true(info.has("attempt"), "重连信息应该包含 'attempt'") + assert_true(info.has("max_attempts"), "重连信息应该包含 'max_attempts'") + assert_true(info.has("next_delay"), "重连信息应该包含 'next_delay'") + + assert_eq(info["enabled"], true, "自动重连应该启用") + assert_eq(info["attempt"], 2, "当前重连尝试次数应该是 2") + assert_eq(info["max_attempts"], 5, "最大重连次数应该是 5") + +# ============================================================================ +# 重连延迟计算测试 +# ============================================================================ + +func test_reconnect_delay_calculation(): + # 测试重连延迟计算（指数退避） + ws_manager._reconnect_base_delay = 2.0 + + ws_manager._reconnect_attempt = 1 + var delay1 := ws_manager._calculate_reconnect_delay() + assert_eq(delay1, 2.0, "第 1 次重连延迟应该是 2.0 秒") + + ws_manager._reconnect_attempt = 2 + var delay2 := ws_manager._calculate_reconnect_delay() + assert_eq(delay2, 4.0, "第 2 次重连延迟应该是 4.0 秒") + + ws_manager._reconnect_attempt = 3 + var delay3 := ws_manager._calculate_reconnect_delay() + assert_eq(delay3, 8.0, "第 3 次重连延迟应该是 8.0 秒") + +func test_max_reconnect_delay(): + # 测试最大重连延迟限制 + ws_manager._reconnect_base_delay = 10.0 + ws_manager._reconnect_attempt = 10 + + var delay := ws_manager._calculate_reconnect_delay() + assert_eq(delay, WebSocketManager.MAX_RECONNECT_DELAY, + "重连延迟应该被限制在最大值") + +# ============================================================================ +# Socket.IO 客户端访问测试 +# ============================================================================ + +func test_get_socket_client(): + # 测试获取 Socket.IO 客户端 + var socket_client := ws_manager.get_socket_client() + + assert_not_null(socket_client, "应该返回 Socket.IO 客户端") + assert_is_instanceof(socket_client, SocketIOClient, + "返回的应该是 SocketIOClient 实例") + +# ============================================================================ +# 信号测试 +# ============================================================================ + +func test_connection_state_changed_signal(): + # 测试连接状态变化信号 + watch_signals(ws_manager) + + # 手动触发信号 + ws_manager.emit_signal("connection_state_changed", WebSocketManager.ConnectionState.CONNECTED) + + assert_signal_emitted(ws_manager, "connection_state_changed", + "应该发射 connection_state_changed 信号") + +func test_connection_lost_signal(): + # 测试连接丢失信号 + watch_signals(ws_manager) + + ws_manager.emit_signal("connection_lost") + + assert_signal_emitted(ws_manager, "connection_lost", + "应该发射 connection_lost 信号") + +func test_reconnection_succeeded_signal(): + # 测试重连成功信号 + watch_signals(ws_manager) + + ws_manager.emit_signal("reconnection_succeeded") + + assert_signal_emitted(ws_manager, "reconnection_succeeded", + "应该发射 reconnection_succeeded 信号") + +func test_reconnection_failed_signal(): + # 测试重连失败信号 + watch_signals(ws_manager) + + ws_manager.emit_signal("reconnection_failed", 3, 5) + + assert_signal_emitted(ws_manager, "reconnection_failed", + "应该发射 reconnection_failed 信号") + +# ============================================================================ +# 常量测试 +# ============================================================================ + +func test_websocket_url_constant(): + # 测试 WebSocket URL 常量 + assert_eq(WebSocketManager.WEBSOCKET_URL, "wss://whaletownend.xinghangee.icu/game", + "WebSocket URL 应该匹配") + +func test_default_reconnect_constants(): + # 测试默认重连常量 + assert_eq(WebSocketManager.DEFAULT_MAX_RECONNECT_ATTEMPTS, 5, + "默认最大重连次数应该是 5") + assert_eq(WebSocketManager.DEFAULT_RECONNECT_BASE_DELAY, 3.0, + "默认基础重连延迟应该是 3.0 秒") + +func test_max_reconnect_delay_constant(): + # 测试最大重连延迟常量 + assert_eq(WebSocketManager.MAX_RECONNECT_DELAY, 30.0, + "最大重连延迟应该是 30.0 秒") + +# ============================================================================ +# 边界条件测试 +# ============================================================================ + +func test_zero_max_reconnect_attempts(): + # 测试零次重连尝试 + ws_manager.enable_auto_reconnect(true, 0, 1.0) + ws_manager._reconnect_attempt = 1 + + var should_reconnect := ws_manager._reconnect_attempt < ws_manager._max_reconnect_attempts + assert_false(should_reconnect, "最大重连次数为 0 时不应该重连") + +func test_very_large_reconnect_attempts(): + # 测试非常大的重连次数 + ws_manager.enable_auto_reconnect(true, 1000, 1.0) + ws_manager._reconnect_attempt = 999 + + var should_reconnect := ws_manager._reconnect_attempt < ws_manager._max_reconnect_attempts + assert_true(should_reconnect, "应该允许更多重连尝试") + +func test_zero_base_delay(): + # 测试零基础延迟 + ws_manager._reconnect_base_delay = 0.0 + ws_manager._reconnect_attempt = 1 + + var delay := ws_manager._calculate_reconnect_delay() + # 即使基础延迟为 0，也应该返回一个合理的值 + assert_ge(delay, 0.0, "延迟应该 >= 0") + +# ============================================================================ +# 状态转换测试 +# ============================================================================ + +func test_state_disconnected_to_connecting(): + # 测试从 DISCONNECTED 到 CONNECTING 的状态转换 + ws_manager._set_connection_state(WebSocketManager.ConnectionState.CONNECTING) + + assert_eq(ws_manager.get_connection_state(), WebSocketManager.ConnectionState.CONNECTING, + "状态应该转换为 CONNECTING") + +func test_state_connecting_to_connected(): + # 测试从 CONNECTING 到 CONNECTED 的状态转换 + ws_manager._set_connection_state(WebSocketManager.ConnectionState.CONNECTING) + ws_manager._set_connection_state(WebSocketManager.ConnectionState.CONNECTED) + + assert_eq(ws_manager.get_connection_state(), WebSocketManager.ConnectionState.CONNECTED, + "状态应该转换为 CONNECTED") + +func test_state_connected_to_reconnecting(): + # 测试从 CONNECTED 到 RECONNECTING 的状态转换 + ws_manager._set_connection_state(WebSocketManager.ConnectionState.CONNECTED) + ws_manager._set_connection_state(WebSocketManager.ConnectionState.RECONNECTING) + + assert_eq(ws_manager.get_connection_state(), WebSocketManager.ConnectionState.RECONNECTING, + "状态应该转换为 RECONNECTING") diff --git a/tests/unit/test_websocket_manager.gd.uid b/tests/unit/test_websocket_manager.gd.uid new file mode 100644 index 0000000..d60776d --- /dev/null +++ b/tests/unit/test_websocket_manager.gd.uid @@ -0,0 +1 @@ +uid://btx366t1aqprm