6.4 KiB
6.4 KiB
开发者技术文档
项目架构
客户端架构
Main (Node)
├─ NetworkManager (Node) - 网络连接管理
├─ GameStateManager (Node) - 游戏状态管理
├─ UILayer (CanvasLayer) - UI 层
│ ├─ LoginScreen (Control) - 登录界面
│ ├─ CharacterCreation (Control) - 角色创建界面
│ ├─ HUD (Control) - 游戏内 UI
│ └─ DialogueBox (Control) - 对话框
└─ GameWorld (Node2D) - 游戏世界
├─ TileMap (TileMap) - 场景地图
├─ Characters (Node2D) - 角色容器
│ ├─ PlayerCharacter (CharacterBody2D) - 本地玩家
│ └─ RemoteCharacter (CharacterBody2D) - 其他角色
└─ Camera (Camera2D) - 摄像机
服务器架构
WebSocket Server (Node.js + TypeScript)
├─ ConnectionManager - 管理客户端连接
├─ AuthenticationService - 身份验证
├─ CharacterManager - 角色管理
├─ WorldState - 世界状态管理
├─ MessageRouter - 消息路由
├─ AdminAPI - 管理接口
├─ BackupManager - 备份管理
├─ LogManager - 日志管理
└─ HealthChecker - 健康检查
核心系统
网络管理器 (NetworkManager)
职责: 管理客户端与服务器的 WebSocket 连接
主要方法:
func connect_to_server(url: String) -> void
func disconnect_from_server() -> void
func send_message(message: Dictionary) -> void
func is_connected() -> bool
信号:
connected_to_server()- 连接成功disconnected_from_server()- 断开连接connection_error(error: String)- 连接错误message_received(message: Dictionary)- 收到消息
角色控制器 (CharacterController)
职责: 处理角色的移动、动画和状态
主要属性:
var character_id: String
var character_name: String
var is_online: bool
var move_speed: float = 200.0
主要方法:
func move_to(direction: Vector2) -> void
func set_position_smooth(target_pos: Vector2) -> void
func play_animation(anim_name: String) -> void
func set_online_status(online: bool) -> void
对话系统 (DialogueSystem)
职责: 管理角色之间的对话交互
主要方法:
func start_dialogue(target_character_id: String) -> void
func send_message(message: String) -> void
func end_dialogue() -> void
func show_bubble(character_id: String, message: String, duration: float) -> void
信号:
dialogue_started(character_id: String)dialogue_ended()message_received(sender: String, message: String)
数据模型
角色数据
{
"id": "unique_character_id",
"name": "角色名称",
"owner_id": "player_account_id",
"position": {
"x": 100.0,
"y": 200.0
},
"is_online": true,
"appearance": {
"head_color": "#F5DEB3",
"body_color": "#4169E1",
"foot_color": "#8B4513"
},
"created_at": 1234567890,
"last_seen": 1234567890
}
消息协议
所有消息使用 JSON 格式：
{
"type": "message_type",
"data": {},
"timestamp": 1234567890
}
消息类型:
auth_request/auth_response- 身份验证character_create- 创建角色character_move- 角色移动character_state- 角色状态更新dialogue_send- 发送对话world_state- 世界状态同步friend_request- 好友请求private_message- 私聊消息
扩展功能
角色外观自定义
组件:
CharacterCustomization.gd- 外观自定义管理CharacterPersonalization.gd- 个性化设置CharacterProfile.gd- 角色档案
外观数据结构:
{
"head_color": "#F5DEB3",
"body_color": "#4169E1",
"foot_color": "#8B4513",
"created_at": 1234567890,
"version": "1.0"
}
社交系统
组件:
FriendSystem.gd- 好友管理PrivateChatSystem.gd- 私聊功能RelationshipNetwork.gd- 关系网络SocialManager.gd- 社交管理器
安全系统
组件:
SecurityManager.gd- 安全管理RateLimiter.gd- 速率限制DialogueFilter.gd- 对话过滤
速率限制配置:
{
"max_requests": 10,
"time_window": 60.0, # 秒
"cooldown": 5.0 # 秒
}
添加新功能
1. 创建规格文档
在 .kiro/specs/ 创建新目录：
.kiro/specs/your-feature/
├── requirements.md # 需求和验收标准
├── design.md # 架构和设计
└── tasks.md # 实施计划
2. 实现功能
创建必要的脚本和场景：
scripts/YourFeature.gd
scenes/YourFeature.tscn
3. 编写测试
创建测试文件：
tests/test_your_feature.gd
4. 集成到主系统
在 Main.gd 或相关管理器中集成新功能。
代码规范
命名约定
- 变量和函数:
snake_case - 类名:
PascalCase - 常量:
UPPER_CASE - 私有变量:
_leading_underscore
注释规范
## 类文档注释
## 描述类的用途和职责
class_name MyClass
## 函数文档注释
## 参数:
## - param1: 参数描述
## 返回: 返回值描述
func my_function(param1: String) -> int:
# 行内注释
return 0
信号定义
## 当某事件发生时触发
signal event_happened(data: Dictionary)
性能优化
对象池
使用对象池减少内存分配：
var object_pool: Array = []
func get_object():
if object_pool.is_empty():
return create_new_object()
return object_pool.pop_back()
func return_object(obj):
object_pool.append(obj)
网络优化
- 使用消息批处理
- 实现状态差异同步
- 减少不必要的网络请求
渲染优化
- 使用视锥剔除
- 优化碰撞检测
- 减少节点数量
调试技巧
打印调试
print("Debug:", variable)
print_debug("Stack trace")
断点调试
在代码行号左侧点击设置断点，按 F5 运行调试模式。
性能分析
使用 Godot 内置的性能监视器：
Performance.get_monitor(Performance.TIME_FPS)
Performance.get_monitor(Performance.MEMORY_STATIC)
服务器 API
详细的服务器 API 文档请参考 server/README.md