300 lines
6.4 KiB
Markdown
300 lines
6.4 KiB
Markdown
# 开发者技术文档
|
|
|
|
## 项目架构
|
|
|
|
### 客户端架构
|
|
|
|
```
|
|
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 连接
|
|
|
|
**主要方法**:
|
|
```gdscript
|
|
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)
|
|
|
|
**职责**: 处理角色的移动、动画和状态
|
|
|
|
**主要属性**:
|
|
```gdscript
|
|
var character_id: String
|
|
var character_name: String
|
|
var is_online: bool
|
|
var move_speed: float = 200.0
|
|
```
|
|
|
|
**主要方法**:
|
|
```gdscript
|
|
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)
|
|
|
|
**职责**: 管理角色之间的对话交互
|
|
|
|
**主要方法**:
|
|
```gdscript
|
|
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)`
|
|
|
|
## 数据模型
|
|
|
|
### 角色数据
|
|
|
|
```gdscript
|
|
{
|
|
"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 格式：
|
|
```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` - 角色档案
|
|
|
|
**外观数据结构**:
|
|
```gdscript
|
|
{
|
|
"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` - 对话过滤
|
|
|
|
**速率限制配置**:
|
|
```gdscript
|
|
{
|
|
"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`
|
|
|
|
### 注释规范
|
|
```gdscript
|
|
## 类文档注释
|
|
## 描述类的用途和职责
|
|
class_name MyClass
|
|
|
|
## 函数文档注释
|
|
## 参数:
|
|
## - param1: 参数描述
|
|
## 返回: 返回值描述
|
|
func my_function(param1: String) -> int:
|
|
# 行内注释
|
|
return 0
|
|
```
|
|
|
|
### 信号定义
|
|
```gdscript
|
|
## 当某事件发生时触发
|
|
signal event_happened(data: Dictionary)
|
|
```
|
|
|
|
## 性能优化
|
|
|
|
### 对象池
|
|
使用对象池减少内存分配：
|
|
```gdscript
|
|
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)
|
|
```
|
|
|
|
### 网络优化
|
|
- 使用消息批处理
|
|
- 实现状态差异同步
|
|
- 减少不必要的网络请求
|
|
|
|
### 渲染优化
|
|
- 使用视锥剔除
|
|
- 优化碰撞检测
|
|
- 减少节点数量
|
|
|
|
## 调试技巧
|
|
|
|
### 打印调试
|
|
```gdscript
|
|
print("Debug:", variable)
|
|
print_debug("Stack trace")
|
|
```
|
|
|
|
### 断点调试
|
|
在代码行号左侧点击设置断点，按 F5 运行调试模式。
|
|
|
|
### 性能分析
|
|
使用 Godot 内置的性能监视器：
|
|
```gdscript
|
|
Performance.get_monitor(Performance.TIME_FPS)
|
|
Performance.get_monitor(Performance.MEMORY_STATIC)
|
|
```
|
|
|
|
## 服务器 API
|
|
|
|
详细的服务器 API 文档请参考 [server/README.md](server/README.md)
|
|
|
|
## 相关文档
|
|
|
|
- [项目状态](PROJECT_STATUS.md) - 当前开发状态
|
|
- [测试指南](HOW_TO_TEST.md) - 测试方法
|
|
- [环境配置](SETUP.md) - 开发环境配置
|
|
- [主游戏规格](.kiro/specs/godot-ai-town-game/) - 核心系统规格
|
|
- [角色自定义规格](.kiro/specs/character-appearance-customization/) - 外观系统规格
|