# DOFramework

**Repository Path**: daixiwei/doframework

## Basic Information

- **Project Name**: DOFramework
- **Description**: No description available
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-11
- **Last Updated**: 2026-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DOFramework

DOFramework 是一个面向 Unity 2022.3 LTS 的 Lua 游戏开发框架。项目以 XLua 作为脚本运行时，使用 DOAsset 管理资源，通过 UnityWebSocket、Protobuf 与 zlib 提供完整的网络通信链路，并在 Lua 层实现模块化业务与 UGUI 生命周期管理。

仓库不仅包含框架代码，还提供了可以直接运行的 Login/Main 示例、HTTP + WebSocket 测试服务器、Excel 配表工具、协议生成工具和网页自动构建服务，适合作为 Lua 项目的基础工程或框架实现参考。

## 主要特性

- **Lua 驱动的业务架构**：C# 只负责 Unity 生命周期和资源、网络、HTTP、UGUI 桥接，业务流程集中在 Lua 的 Control、Model、Define 和 View 中。
- **明确的应用生命周期**：全局唯一 `App` 统一管理事件、定时器、资源、View、网络客户端和业务 Control；Control 按注册顺序启动、按逆序关闭。
- **DOAsset 资源管理**：支持本地资源、子图集、场景和远端资源加载；Lua 通过 XLua 直接调用 DOAsset，请求编号、回调队列、取消和引用计数均由 DOAsset 统一管理。
- **完整网络链路**：示例包含 HTTP 登录、WebSocket 连接、16 字节大端协议包、Protobuf 编解码、zlib 压缩、心跳、断线重连、请求超时及离线队列。
- **UGUI View 框架**：支持异步加载、分帧调度、页面导航、弹窗栈、单一全局模态遮罩、层级深度、淡入淡出、对象池和 SubView Tab。
- **编辑器与 Player 分离的 Lua 加载方式**：Editor 直接读取 `Assets/Lua` 源码；Player 通过 DOAsset 加载预编译的 Lua 5.4 目录包。
- **配套开发工具**：支持 Excel 导出 JSON/Lua 配表、Protobuf 描述数据生成、Unity EditMode/PlayMode 测试以及可视化自动打包。

## 技术栈

| 模块 | 用途 |
|---|---|
| Unity `2022.3.52f1` | 项目运行环境 |
| XLua + Lua 5.4 | Lua 虚拟机及 C#/Lua 互操作 |
| DOAsset | AssetBundle、资源引用和热更新清单管理 |
| UnityWebSocket | WebSocket 传输 |
| lua-protobuf | Protobuf 编解码 |
| zlib | 协议包压缩与解压 |
| UGUI | Lua View、弹窗、导航和 SubView 界面系统 |

## 快速启动

### 1. 准备环境

- 安装 Unity Hub 和 Unity `2022.3.52f1`。
- 安装 Node.js 与 npm，用于运行配套测试服务器。
- 如果需要构建 Player 或使用网页构建服务，需额外安装 Python 3，并确保可以通过 `python` 命令启动。

建议使用仓库记录的 Unity 版本打开项目，避免资源序列化或包版本发生非预期升级。

### 2. 启动测试服务器

在独立的 PowerShell 窗口执行：

```powershell
cd D:\work\DOFramework\TestServer
npm install
npm run start:zlib
```

服务器会在 `127.0.0.1:8080` 同时提供：

- `POST /login`：验证登录并返回游戏服 WebSocket 地址与临时连接 Token；
- `ws://127.0.0.1:8080`：处理 Protobuf 协议包、心跳、Echo、推送、半包和粘包测试。

示例客户端默认启用 zlib，并会压缩所有发出的协议包，因此联调时必须使用 `npm run start:zlib`。普通的 `npm start` 仅用于主动关闭客户端压缩配置后的无压缩测试。

### 3. 在 Unity 中运行

1. 使用 Unity Hub 打开仓库根目录 `D:\work\DOFramework`。
2. 等待 Unity 完成脚本编译和资源导入。
3. 打开场景 `Assets/Scenes/SampleScene.unity`。
4. 确认测试服务器仍在运行，然后进入 Play Mode。
5. 登录界面已预填账号 `unity-client` 和 Token `test-token`，直接点击登录即可。

登录成功后会进入 `MainView`。可以通过信息、网络、资料三个 Tab，以及模态弹窗和高深度二级弹窗，验证 SubView 生命周期、页面状态、网络 Echo、弹窗栈与层级排序。

## 启动链路

1. `SampleScene` 中的 `Launcher` 初始化 DOAsset，并在资源准备完成后创建并启动 `DOFramework.LuaScriptMgr` 和各个 C# 桥接层。
2. Editor 直接从 `Assets/Lua` 加载 Lua 源码，并执行入口模块 `Main`。
3. `Main.lua` 创建唯一 `App`，通过 `IS(...)` 获取并注册 `NetworkControl`、`MainControl` 和 `LoginControl` 单例。
4. `App` 启动业务 Control 并显示登录界面；之后由 `LuaScriptMgr` 逐帧驱动桥接回调和 Lua 更新。
5. 用户登录时，客户端先通过 HTTP 获取 WebSocket 地址和专用 Token，再建立 WebSocket 并发送 Protobuf `LoginRequest`。
6. 收到 `LoginResponse` 后，入口流程切换到 Main 模块；退出时按逆序关闭业务 Control 并释放 Lua VM、网络连接、资源引用和 UGUI 监听器。

`Launcher` 与 `LuaScriptMgr` 的关键配置如下，缺失或非法配置会立即报错：

| 配置 | 示例值 | 说明 |
|---|---|---|
| DOAsset 资源模式 | `Editor` / `StreamingAssets` | Editor 与 Player 统一使用 `Launcher._assetLoadMode` |
| DOAsset 配置 | `Assets/DOAssetConfig.asset` | 资源根目录为 `Assets/BundleRes/` |
| Lua 入口模块 | `Main` | 必须返回包含 `start`、`update`、`shutdown` 的 table |
| 跨场景保留 | 启用 | 切换场景时保留 Lua 运行环境 |

## 目录说明

| 目录 | 职责 |
|---|---|
| `Assets/Lua/Framework` | App、事件、定时器、资源、网络和 View 基础设施 |
| `Assets/Lua/Module` | Login、Main、Network 示例业务模块 |
| `Assets/Lua/Protocol` | Protobuf 描述数据、消息编号和编解码入口 |
| `Assets/Lua/EmmyApi` | Lua 编辑器类型声明，不进入 Player |
| `Assets/Scripts/Core` | Launcher、LuaScriptMgr 以及资源、HTTP、WebSocket、UGUI 桥接层 |
| `Assets/Modules` | XLua、DOAsset、UnityWebSocket 和解压模块 |
| `Assets/BundleRes` | 示例 UI Prefab 和 Player 使用的 Lua 目录包 |
| `数据表` | Excel 源表及导出的 JSON 配置 |
| `TestServer` | HTTP + Protobuf WebSocket 测试服务器 |
| `BuildWeb` | Unity 自动构建网页和串行任务服务 |
| `Tools` | Lua 编译与本地辅助脚本 |

## Lua 模块约定

所有运行时 Lua 源码放在 `Assets/Lua`，扩展名固定为 `.lua`，并通过 `require("目录.模块")` 引用。示例业务采用以下结构：

```text
Module/<业务名>/
├─ init.lua              # 按 Define、Model、Control 顺序加载当前模块
├─ <业务名>Control.lua   # 接收意图、调用模型并驱动界面
├─ <业务名>Model.lua     # 保存模块状态和业务数据
├─ <业务名>Define.lua    # 声明事件、界面名称和 View 注册配置
└─ View/                 # 模块所属 UGUI View 与 SubView
```

`NetworkControl` 是业务网络访问的唯一边界，负责按 Protobuf 完整类型名查找消息编号、编解码、发送请求及分发已解码消息；Login、Main 等业务 Control 只传递消息类型字符串和业务字段表，不直接依赖 `Protocol`、协议数字 ID 或原始字节。各模块的 Control 和 Model 都通过 `IS(...)` 获取单例，模块入口负责建立全局类表，跨模块页面流程由 `Main.lua` 统一组装。`App` 只负责注册并驱动业务 Control 的生命周期，不再把 Control 称为 Service。

## 配表与协议生成

在 Unity 中打开 `Tools/导表工具`，可以把 `数据表` 目录中的 Excel 文件导出到 `数据表/配置生成文件`。Editor 运行时会直接读取 JSON；Player 构建前会生成 `Assets/Lua/ConfigData`，再编译为 `Assets/BundleRes/Lua/ConfigData.bytes`。

修改 `TestServer/proto` 中的 `.proto` 文件或消息编号后执行：

```powershell
cd D:\work\DOFramework\TestServer
npm run generate:lua-proto
npm run check:lua-proto
```

生成结果写入 `Assets/Lua/Protocol/Protocol.lua`。运行时使用预编译描述数据，不依赖外部 `protoc`。

## 测试

测试服务器集成测试：

```powershell
cd D:\work\DOFramework\TestServer
npm test
```

Unity 测试可通过以下菜单运行：

- `Tools/测试/运行框架 EditMode 测试`
- `Tools/测试/运行框架 PlayMode 测试`

需要重新生成示例 UI Prefab 时，使用 `Tools/Lua/生成 UGUI 测试界面`。

## 引导点击录制

Unity Editor 提供 `Tools/引导/引导录制工具`。进入 Play Mode 后直接开始录制，工具会自动发现运行时 View，并动态监听其下的全部 UGUI Button，无需手工填写 View 名称。

每条记录只包含 `viewName` 和 `buttonPath` 两列。停止录制后点击“复制到剪切板”，剪切板不包含标题行，粘贴到 Excel 会自动按制表符分成两列；View 根节点运行时直接使用真实 `viewName`，按钮路径从根节点内部开始，例如登录按钮为 `Panel/LoginButton`，可直接对应 Lua View 中的控件路径。

## Player 与网页自动构建

Player 不直接读取 `.lua` 源文件。自动构建会先把 JSON 配表转换为 Lua，再调用 `Tools/compile_lua.py` 将各一级目录编译为 `.bytes` 包，最后构建 DOAsset AssetBundle 和 Player。

启动本地构建网页：

```powershell
cd D:\work\DOFramework
python -m pip install -r BuildWeb/requirements.txt
python BuildWeb/server.py --config BuildWeb/config.json --open
```

默认访问地址为 `http://127.0.0.1:8765`。真实构建前必须关闭正在打开同一项目的 Unity；完整配置、支持平台、上传方式和产物说明见 [BuildWeb/README.md](BuildWeb/README.md)。

## 常见问题

- **登录请求失败**：确认 `TestServer` 正在监听 `8080` 端口，并且使用的是 `npm run start:zlib`。
- **端口被占用**：测试客户端默认固定访问 `127.0.0.1:8080`；如需修改端口，必须同步修改 `LoginControl.lua` 的 HTTP 地址和服务器启动参数。
- **Player 提示缺少 Lua 目录包**：不要只执行普通 Player 构建；应先完成 Lua 配表生成、Lua 编译和 DOAsset AssetBundle 构建。
- **修改 Lua 后 Player 中未生效**：Editor 会直读源码，但 Player 使用 `.bytes` 包，需要重新执行 Lua 编译和资源构建。
- **无法加载示例 UI**：确认 `Assets/DOAssetConfig.asset` 的资源根目录仍为 `Assets/BundleRes/`，并检查示例 Prefab 是否存在。

## 许可证

本项目使用 [MIT License](LICENSE)。