# risingsunol_godot

**Repository Path**: yancm52/risingsunol_godot

## Basic Information

- **Project Name**: risingsunol_godot
- **Description**: 旭日战魂录 前后端代码
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 20
- **Forks**: 12
- **Created**: 2024-06-22
- **Last Updated**: 2026-04-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RisingSunOL

基于 Godot 4 和 Colyseus 的多人联机桌游项目，用来复刻并实现类旭日题材的回合制区域控制玩法。仓库同时包含客户端、服务端、资源文件与基础测试脚本，适合用于本地联调、二次开发、玩法研究和开源协作。

![项目截图](assets/QQ%E6%88%AA%E5%9B%BE20250309210311.png)

## 项目概览

- 客户端引擎：Godot 4.3
- 渲染模式：GL Compatibility
- 联机框架：Colyseus 0.15
- 客户端联机插件：godot_colyseus
- 服务端语言：Node.js ESM
- 默认本地联调地址：ws://localhost:2567
- 默认房间类型：my_room

本项目当前采用前后端分离结构：

- Godot 客户端负责大厅、UI、地图、卡牌、单位表现和本地交互。
- Colyseus 服务端负责房间管理、同步广播、回合流转和部分规则校验。

## 目录结构

```text
.
├─ scene/                  Godot 主要业务代码
│  ├─ main.gd              客户端入口逻辑
│  ├─ NetHandler.gd        网络连接、房间通信、消息分发
│  ├─ game/                主游戏流程与地图战斗逻辑
│  ├─ lobby/               房间大厅和准备阶段界面
│  ├─ menu/                主菜单
│  ├─ managers/            重构后的客户端管理器
│  ├─ models/              重构后的客户端数据模型
│  └─ constants/           客户端常量
├─ assets/                 图片、音频、字体等资源
├─ addons/                 Godot 插件，包含 godot_colyseus
├─ server/                 Colyseus 服务端
│  ├─ src/index.js         服务启动入口
│  ├─ src/app.config.js    服务配置与房间注册
│  ├─ src/rooms/           房间逻辑、规则处理、校验器
│  ├─ loadtest/            简单压测脚本
│  └─ test/                服务端测试脚本
└─ project.godot           Godot 工程配置
```

## 核心玩法说明

当前代码中已经实现或预留了以下核心概念：

- 家族颜色：red、purple、green、blue、yellow
- 游戏阶段：ally、order、action、temple、war
- 政令类型：train、recruit、harvest、marshal、betray
- 地图区域：8 个主要区域，带相邻移动和海陆通路逻辑
- 单位类型：warrior、monk、general、city、monster

如果你是第一次接手这个仓库，建议优先阅读以下文件：

- scene/NetHandler.gd
- scene/game/game.gd
- server/src/app.config.js
- server/src/rooms/MyRoom.js
- server/src/rooms/validators.js

## 环境要求

### 客户端

- Godot 4.3
- Windows 开发环境优先，其他平台理论可运行，但未完整验证

### 服务端

- Node.js 16.13 及以上
- npm 8 及以上

## 快速开始

### 1. 克隆仓库

```bash
git clone <your-fork-or-repo-url>
cd risingsunol
```

### 2. 安装服务端依赖

```bash
cd server
npm install
```

### 3. 启动服务端

```bash
npm run start
```

默认情况下，Colyseus 服务会监听本机 2567 端口。

如果启动正常，你可以在浏览器打开以下地址确认服务状态：

- http://localhost:2567/
- http://localhost:2567/colyseus

说明：

- 根路径在非 production 环境下会挂载 Colyseus Playground。
- /colyseus 是监控面板，适合联调时观察房间与客户端连接情况。

### 4. 启动 Godot 客户端

1. 用 Godot 4.3 打开仓库根目录。
2. 确认主场景为 scene/main.tscn。
3. 直接点击运行即可。

客户端默认在开发模式下连接：

```text
ws://localhost:2567
```

## 本地联调流程

推荐按下面的顺序操作：

1. 先进入 server 目录执行 npm run start。
2. 确认 2567 端口已监听。
3. 用 Godot 打开项目并运行客户端。
4. 在大厅创建房间或加入已有房间。
5. 多开客户端进行联机验证。

项目已经启用了 multirun 插件配置，适合在本地同时打开多个 Godot 窗口做联机测试。

## 生产环境接入说明

客户端网络入口在 scene/NetHandler.gd。

当前逻辑为：

- EventBus.is_pro 为 false 时，连接 ws://localhost:2567
- EventBus.is_pro 为 true 时，连接生产环境服务器地址

如果你需要部署到远程服务器，至少需要完成这两项：

1. 把 scene/NetHandler.gd 中的生产环境地址替换成实际的 ws 或 wss 地址。
2. 在进入生产模式前，把 EventBus.is_pro 切换为 true，或改造成从配置文件读取。

建议后续改造方向：

- 将服务地址抽到单独配置文件或导出参数中。
- 区分开发、测试、生产三套环境。
- 为 Colyseus monitor 增加访问保护。

## 服务端开发说明

服务端入口与关键文件如下：

- server/src/index.js：启动 Colyseus 服务
- server/src/app.config.js：注册 my_room 房间和监控路由
- server/src/rooms/MyRoom.js：主房间逻辑
- server/src/rooms/validators.js：消息输入校验
- server/src/rooms/handlers/：拆分后的房间消息处理模块

当前 package.json 中可直接使用的命令：

```bash
npm run start
npm test
npm run loadtest
```

说明：

- npm run start：使用 nodemon 启动服务，适合开发阶段热重启。
- npm test：运行服务端测试脚本。
- npm run loadtest：运行 Colyseus 的简单连接压测脚本。

## 客户端开发说明

客户端主要模块如下：

- scene/main.gd：主场景逻辑组织
- scene/NetHandler.gd：客户端网络同步中心
- scene/eventBus.gd：全局信号总线
- scene/game/game.gd：主要回合、单位、卡牌和战斗表现逻辑
- scene/managers/：已开始抽离的职责管理器
- scene/models/：已开始抽离的数据模型


## 给开源开发者的阅读路径

如果你是第一次参与这个项目，可以按下面顺序理解代码：

1. 先看 project.godot，确认 Godot 版本、入口场景和自动加载脚本。
2. 再看 scene/eventBus.gd 和 scene/NetHandler.gd，了解客户端通信主线。
3. 然后看 scene/lobby 和 scene/game，理解从大厅到对局的界面流转。
4. 接着看 server/src/app.config.js 和 server/src/rooms/MyRoom.js，理解服务端房间如何驱动游戏。
5. 最后看 server/src/rooms/handlers 和 validators.js，了解当前重构方向与规则校验点。

## 常见问题

### 客户端连不上服务端

排查顺序：

1. 确认 server 目录下的服务已经启动。
2. 确认 2567 端口没有被其他程序占用。
3. 确认客户端仍在使用 ws://localhost:2567。
4. 确认本地防火墙没有拦截 Node.js。


## 后续可完善方向

- 增加完整规则文档和阶段流程图
- 为房间协议补充消息格式说明
- 增加客户端自动化回归测试方案
- 增加服务端更贴近业务的单元测试和集成测试
- 增加 Docker 部署和远程服务器部署说明