# sunrise-game-frame-client

**Repository Path**: lieng618/sunrise-game-frame-client

## Basic Information

- **Project Name**: sunrise-game-frame-client
- **Description**: Godot 4.6 C# 客户端示例：2D像素风RPG游戏，实现了登录、角色属性、角色信息、地图探索、角色与怪物位置同步、聊天、背包、邮件等基础玩法。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-04
- **Last Updated**: 2026-06-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Godot, 游戏, 游戏开发, 客户端

## README

# Sunrise Game Frame Client

Sunrise 游戏框架的 **Godot 4.6 + C#** 客户端示例项目（游戏名：Sunrise Fantasy）。演示从网关鉴权、TCP 协议通信，到 2D 地图探索、多人同步、聊天/背包/邮件等完整玩法链路。

## 技术栈

| 类别 | 选型 |
|------|------|
| 引擎 | Godot 4.6（Forward Plus） |
| 语言 | C# / .NET 8 |
| 网络 | Protobuf + 自定义 Topic 分包 |
| 配置 | Luban 导表（JSON → `src/GenLuban/`） |
| 物理 | Jolt Physics（3D 引擎配置，2D 玩法使用 CharacterBody2D） |

## 功能概览

- **登录**：支持开发模式（UID）与生产模式（邮箱 + JWT）；网关 HTTP 鉴权 → 获取游戏服地址 → TCP 握手 → 选角/创角
- **地图**：TileMap 手编场景 + Nav 网格导出，支持多地图切换（10001–10010）
- **多人**：SceneSync / UnitEnter / UnitLeave / 位置与属性同步
- **HUD**：左上角快捷菜单（角色、邮件、背包、聊天）+ 右下角小地图
- **系统**：世界聊天、背包、邮件、角色信息（改名/头像/登出）
- **离线模式**：登录页「离线游戏」可直接进入主世界（无网络同步）

## 目录结构

```
sunrise-game-frame-client/
├── assets/                   # 精灵图、UI 素材
├── data/
│   ├── config/               # Luban 导出的 JSON 配置
│   └── nav/                  # 地图可行走网格（编辑器 Export Nav Grid 生成）
├── proto/                    # 游戏协议 .proto + gen.bat
├── scenes/
│   ├── login/                # 登录界面 + SunriseLogin Autoload 场景
│   ├── maps/                 # 地图场景 map_10001.tscn …
│   └── entities/             # 玩家等实体预制体
├── src/
│   ├── Announcement/         # 公告服务
│   ├── Chat/                 # 聊天服务
│   ├── Config/               # Luban 加载、本地设置
│   ├── Entities/             # 玩家、怪物、动物控制器
│   ├── GenLuban/             # Luban 生成代码（勿手改）
│   ├── GenProto/             # protoc 生成代码（勿手改）
│   ├── Item/                 # 背包服务
│   ├── Log/                  # 客户端日志
│   ├── Login/                # 登录与网络模块（Autoload: SunriseLogin）
│   ├── LubanLib/             # Luban 运行时库
│   ├── Mail/                 # 邮件服务
│   ├── Map/                  # 地图注册、同步、寻路、深度排序
│   ├── Network/              # 网络包处理器注册
│   ├── Scenes/               # LoginScreen、MapSession 等场景脚本
│   ├── Session/              # 本地玩家状态
│   ├── UI/                   # HUD、面板、图标辅助类
│   └── Utils/                # 通用工具类
├── tables/                   # Luban 配表源文件与工具链
├── project.godot
└── sunrise-game-frame-client.csproj
```

## 环境要求

- [Godot 4.6](https://godotengine.org/)（含 .NET 支持）
- [.NET 8 SDK](https://dotnet.microsoft.com/download)

## 快速开始

### 1. 克隆并打开项目

用 Godot 4.6 打开本目录，等待 C# 项目首次构建完成。

### 2. 启动游戏服与网关

客户端默认连接 `http://127.0.0.1:8090` 网关。需先启动配套的 Sunrise 游戏服务端（本仓库仅含客户端）。

服务器地址 ： https://gitee.com/lieng618/sunrise-game-frame

### 3. 运行

- **F5** 运行：进入登录页
- **开发模式**（默认）：点击「登录游戏」→ 输入 UID（默认 `test`）→ 登录
- **生产模式**：设置中切换为「生产」→ 注册/登录邮箱账号
- 或点击「离线游戏」进入离线主世界

### 4. 调整网关、日志与开发模式

登录页右上角 **设置** 可修改：

| 选项 | 说明 |
|------|------|
| 网关地址 | HTTP 网关根地址，默认 `http://127.0.0.1:8090` |
| 日志级别 | Info（精简）/ Debug（详细，含网络日志） |
| 开发模式 | **开发**：UID 直连，无需注册；**生产**：邮箱注册/登录 + JWT |

设置保存在 `user://client_settings.json`。

## 登录界面说明

主界面提供四个入口：

| 按钮 | 开发模式 | 生产模式 |
|------|----------|----------|
| 注册游戏 | 提示无需注册 | 邮箱 + 密码 + 验证码注册 |
| 登录游戏 | 弹出 UID 输入框 | 邮箱 + 密码登录；支持忘记密码（验证码重置） |
| 离线游戏 | 跳过网络，直接进入主世界 | 同左 |
| 退出游戏 | 退出应用 | 同左 |

生产模式登录成功后，客户端会缓存 JWT，再请求服务器状态与对外服地址，最后通过 TCP 发送 `C2S_Login { token }` 进入游戏。

## 核心架构

```
登录页 (LoginScreen)
    ↓ 登录成功 / 离线
地图场景 (MapSession)
    ├── MapEntryCoordinator   ← S2C_LastMap，切图 + C2S_Enter
    ├── MapSyncCoordinator    ← 单位进出、位置/属性同步
    ├── PlayerController        ← 本地移动 + C2S 位置上报
    ├── RemotePlayerController  ← 其他玩家插值显示
    └── UI 层 (HudMenuBar, MinimapPanel, 各功能面板)

SunriseLogin (Autoload)            ← 登录与网络全局单例
GameNetworkHandlers.RegisterAll()  ← 启动时注册全部 S2C 处理器
LocalPlayerState                   ← 当前角色服务器数据缓存
ChatService / ItemService / MailService  ← 各玩法模块协议与本地状态
```

### 玩家鉴权流程

```mermaid
sequenceDiagram
    participant Client
    participant Http as HttpServer
    participant Mail as 邮箱
    participant Game as GameServer

    Note over Client,Http: 生产模式 — 注册
    Client->>Http: POST /send_code?email=
    Http->>Mail: SMTP 邮件
    Client->>Http: POST /register?email&password&code

    Note over Client,Http: 生产模式 — 登录
    Client->>Http: POST /login?email&password
    Http-->>Client: JWT Token
    Client->>Http: GET /server_status (Authorization)
    Client->>Http: GET /external_address (Authorization)
    Client->>Game: TCP + C2S_Login(token)

    Note over Client,Game: 开发模式 — 登录
    Client->>Http: GET /server_status?uid=
    Client->>Http: GET /external_address?uid=
    Client->>Game: TCP + C2S_Login(uid)
```

### 登录模块

登录与网络模块位于 `src/Login/`，通过 `scenes/login/sunrise_login.tscn` 配置为 Autoload（`SunriseLogin`）。包含网关 HTTP 鉴权、TCP 连接、Login 协议、心跳保活等完整登录流程。

主要类：

| 类 | 说明 |
|------|------|
| `SunriseLogin` | Autoload 入口，提供全局访问 |
| `LoginService` | 登录流程编排 |
| `GateHttpClient` | 网关 HTTP 请求 |
| `GameNetworkClient` | TCP 客户端，登录后继续用于游戏包收发 |
| `LoginConfig` | 登录配置（网关地址、超时、心跳等） |
| `LoginSession` | 登录成功后的会话信息 |
| `ProtobufUtil` | Protobuf 解析与日志格式化 |

### 配置表

- JSON 路径：`res://data/config/`
- 加载入口：`ConfigTables.Load()`（登录页 `_Ready` 时调用）
- 生成代码：`src/GenLuban/`（由 Luban 工具链生成，不在此仓库维护生成脚本）

### 地图与 Nav

1. 在 Godot 编辑器中打开 `scenes/maps/map_XXXXX.tscn` 编辑 TileMap
2. 选中根节点 `MapSession`，勾选 **Export Nav Grid** 导出 `data/nav/XXXXX.nav.json`
3. 在 `GameMapRegistry` 中注册新地图 id（若新增）

运行时加载手编场景与 Nav 文件，**不会** procedurally 重新生成地形。

### 协议代码生成

```bat
cd proto
gen.bat
```

需要本机 `protoc` 在 PATH 或 `proto/` 目录下。输出到 `src/GenProto/`。

## 主要源码入口

| 文件 | 说明 |
|------|------|
| `src/Login/SunriseLogin.cs` | 登录与网络 Autoload 入口 |
| `src/Login/LoginService.cs` | 登录流程编排 |
| `src/Login/GameNetworkClient.cs` | TCP 客户端 |
| `src/Scenes/LoginScreen.cs` | 登录 UI（开发/生产双模式、注册/登录/离线） |
| `src/Config/ClientSettingsStore.cs` | 网关、日志、开发模式持久化 |
| `src/Scenes/MapSession.cs` | 地图场景生命周期、UI 挂载、进图逻辑 |
| `src/Network/GameNetworkHandlers.cs` | 全部 S2C 包注册与分发 |
| `src/Map/MapSyncCoordinator.cs` | 多人/怪物单位同步 |
| `src/Map/MapEntryCoordinator.cs` | 地图切换与 Enter/Leave |
| `src/Entities/Player/PlayerController.cs` | 本地玩家移动与网络上报 |
| `src/UI/HudMenuBar.cs` | 左上角 HUD 快捷栏 |

## 开发说明

- **命名空间**：统一使用 `SunriseGameFrameClient.*`（如 `SunriseGameFrameClient.Login`、`SunriseGameFrameClient.Map` 等）
- **分辨率**：设计 640×360，窗口默认 1280×720（canvas_items 拉伸）
- **新增 S2C 处理器**：在 `GameNetworkHandlers.RegisterAll()` 中注册，并实现对应 Service 方法
- **新增地图**：场景 + Nav + `GameMapRegistry` 三处同步更新
- **联调建议**：本地开发保持「开发模式」+ 默认 UID；对接正式网关时切换「生产模式」并配置网关地址