# 开发者技术文档

## 项目架构

### 客户端架构

```
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/) - 外观系统规格