# SGBY-Reset

**Repository Path**: null_331_1413/sgby-reset

## Basic Information

- **Project Name**: SGBY-Reset
- **Description**: 三国霸业（步步高经典游戏）H5 重制：iBaye C 引擎 WebAssembly 版 + 前端。基于 gitee.com/bgwp 开源代码修复与再开发，非官方项目，与步步高无关联。仓库不含游戏数据。
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-18
- **Last Updated**: 2026-10-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 网页版引擎重构

## README

# 三国霸业 重制版（sgby-reset）

步步高（BBK）电子词典经典游戏**三国霸业**的 Web / WebAssembly 版本。
本项目基于 [gitee.com/bgwp](https://gitee.com/bgwp) 的开源代码整理、修 bug，并继续开发新功能。

> **免责声明**：本项目为非官方爱好者重制，与步步高公司无任何关联。
> 本仓库**不含任何游戏数据**，运行所需数据请自行准备，见 [data/README.md](data/README.md)。

## 上游与致谢

| 部分 | 上游 | 许可证 | 取用分支 |
|---|---|---|---|
| C 引擎 | [`bgwp/iBaye`](https://gitee.com/bgwp/iBaye) | MIT | `master`（2026-03-17，Kevin Wang） |
| Web 前端 | [`bgwp/baye-alpha`](https://gitee.com/bgwp/baye-alpha) | GPL-2.0 | `s2`（默认分支，2026-10-09） |

完整署名见 [NOTICE](NOTICE)。

⚠️ 提醒：`baye-alpha` 的 `master` 分支停在 2018 年，是死分支。上游任何分支都要先确认默认分支再拉。

## 目录结构

```
sgby-reset/
├── engine/          C 游戏引擎（iBaye master 整理版）
│   ├── src/         引擎源码
│   └── LICENSE.MIT  上游 MIT 声明（必须保留）
├── web/             H5 前端与部署页
│   ├── *.html       index / m / pc / choose / save / designer ...
│   ├── js/          bridge.js、lcd.js 与编译产物 baye.js + baye.wasm
│   └── mapeditor/   地图编辑器
├── data/            游戏数据说明（数据本身不入库）
├── tools/           构建与服务脚本（serve.sh 通过 serve.py 映射根目录 libs/）
└── docs/            技术文档
```

游戏数据不在本仓库内：统一放工作区根目录 `libs/`（和 `sgby-reset/` 同级），
本地服务会把页面请求的 `/libs/` 映射过去。

## 引擎架构

```
┌────────────────────────────────────────────┐
│  web/*.html  页面层（多操作模式）           │
├────────────────────────────────────────────┤
│  web/js/lcd.js      LCD 渲染（160x96 点阵） │
│  web/js/bridge.js   JS ↔ WASM 桥接          │
├────────────────────────────────────────────┤
│  baye.wasm  ← engine/src 编译               │
│    ├ 平台层  platform/{common,js,win}/      │
│    ├ 资源层  datman.c / fsys.c / data-bind.c│
│    ├ 界面层  showface.c / touch.c           │
│    ├ 主循环  gamEng.c / config.c            │
│    ├ 内政    citycmd*.c / cityedit.c / infdeal.c
│    └ 战斗    Fight.c / FightSub.c / FgtPkAi.c / FgtCount.c / tactic.c
└────────────────────────────────────────────┘
```

`engine/src/bind-objects.c` 把 C 全局变量导出给 JS 直接读写，是桥接层的核心，
改动它会同时影响 `bridge.js`，属于跨层契约。

## 存档格式

一个档位一个文件，`web/` 下存在 localStorage 键 `baye//data//sangoN.sav`（N = 档位号，0 起）。
文件由 14 字节头 + payload 组成，头全部小端：

| 偏移 | 字段 | 说明 |
|---|---|---|
| 0 | magic | `BAYE` |
| 4 | formatVer | 布局版本，当前 `2`；字段一改就要升 |
| 6 | payloadLen | 头之后的字节数 |
| 10 | crc32 | payload 的 CRC32 |

payload 依次是：玩家与武将段 → 变长的 MOD 自定义数据（前有 4 字节长度）→ 战斗与城池段。
**没有头、头校验不过或版本号不认识的存档一律拒绝读取**，不做兼容猜测；
读档时先整体校验再改写游戏状态，坏档不会把游戏读到一半。

存档在浏览器里是十六进制文本（每字节 2 个字符），导出/导入走 `web/save.html` 的文件下载与选择，
不再有"复制一长串字符"的路径。

## 资源包（`.lib`）元数据块

`.lib` 开头是 4 字节小端的资源偏移表，资源一律按绝对偏移寻址，所以**在文件末尾追加一段字节
不会改变任何一个资源的读法**——不认得它的老引擎直接忽略，这正是本节能给包加元数据的原因。
追加的块长 40 字节起，含剧本 ID、剧本名、要求的存档 `formatVersion`、包体 CRC32 和打包时间；
完整布局见 `engine/src/baye/libmeta.h`。

给包写元数据用离线脚本（**剧本 ID 必须手写，工具不从文件名猜**）：

```bash
node tools/libmeta.mjs pack ../libs/某剧本.lib --id sgby-reset-1 --name "三国霸业·重置版"
node tools/libmeta.mjs show <包>.lib      # 看有没有、内容是什么
node tools/libmeta.mjs check <包>.lib     # 只验包体完整性，供脚本用
```

默认写到旁边一个新的 `<包>.meta.lib`，不动原件；`--in-place` 才改原文件（改之前先留 `.bak`）。
引擎开局会打印读到的元数据，JS 侧用 `bayeGetLibScriptId()` / `bayeGetLibMetaCode()` 取。

**当前只读不拦**：包里没有元数据、或块读不通时，引擎照常跑（现网还有 MOD 作者的老包在流通）。
"老包要不要直接拒绝"要站主定，定了才接存档头加 `scriptId` 和档案列表的剧本归属。

## 构建环境

需要三样：emsdk 3.1.51、CMake ≥ 3.5、Ninja。

```bash
git clone --depth 1 https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install 3.1.51     # Windows 下用 emsdk.bat
./emsdk activate 3.1.51
source ./emsdk_env.sh
```

然后告诉脚本 emsdk 在哪（二选一）：

```bash
export EMSDK=/绝对路径/emsdk
# 或
mkdir -p .local && echo /绝对路径/emsdk > .local/emsdk-path
```

## 编译引擎

```bash
./tools/build-wasm.sh              # 编译并部署到 web/js/
./tools/build-wasm.sh --clean      # 干净重建
./tools/build-wasm.sh --no-deploy  # 只编译，不覆盖 web/js/
```

产物为 `baye.js` / `baye.wasm` / `baye.wasm.map`。部署脚本会顺手把各页面里的
`js/baye.js?ver=` 时间戳改掉（浏览器按这个参数缓存引擎，不改就等于还在跑旧引擎）；
需要单独刷新时手动执行 `cd web && python updatejsversion.py baye.js`。

不出浏览器也能验证引擎（实例化 + 导出符号 + 关键入口）：

```bash
node tools/verify-engine.mjs
```

## 本地运行

```bash
./tools/serve.sh            # 默认 8008 端口
```

- 移动端页：http://127.0.0.1:8008/m.html
- 桌面端页：http://127.0.0.1:8008/pc.html

前提：已按 [data/README.md](data/README.md) 把游戏数据放到工作区根目录 `libs/`。
`tools/serve.py` 会把页面请求的 `/libs/` 映射到那里，页面里的相对路径不用改。

## 部署到测试区

`test.bbkgames.com` 是本仓库的专属测试域名，网页部署到**根目录**，游戏数据到 `/libs/`。
七牛空间 `bbkgames-test`；不碰 www 主站和 baye 旧引擎。

```bash
node tools/deploy-test.mjs --local-only   # 不联网，检查产物与 libs.json 引用
node tools/deploy-test.mjs --dry-run      # 对比线上，不上传
node tools/deploy-test.mjs                # 增量上传（默认根目录）
```

Windows 下可直接双击 `tools\部署测试区.bat`（演练版：`tools\部署测试区-演练.bat`）。
首次使用需由站主在 `sgby-reset/.local/qiniu-config.ini` 放置七牛密钥；
跨仓库/域名分工见 [docs/SITE-MAP.md](docs/SITE-MAP.md)，部署细节见
[docs/DEPLOY-TEST.md](docs/DEPLOY-TEST.md)。

## 文档

| 文档 | 内容 |
|---|---|
| [docs/ENGINE-BUGS.md](docs/ENGINE-BUGS.md) | **引擎缺陷定位清单**（2026-10-19 通览 + 三个恶性症状离线复现 + 存疑项实测三档）。只定位、未修复，含行号、实测数字、离线复现手法与建议修复分批 |
| [docs/COLLABORATION.md](docs/COLLABORATION.md) | **协作规则**（给参与本仓库的助手/同事）：可改与不可改的边界、留痕要求、守门命令、git 安全、交付说明模板 |
| [docs/HANDOFF-RUST.md](docs/HANDOFF-RUST.md) | **Rust 重写交接手册**：换实现语言时必须保住的三层契约（JS↔wasm 的 77 个导出 + 14 个 JS 回调 + 启动顺序、`.lib` 两层容器与存档二进制格式、`baye.data` 反射树），含 12 条绑定层陷阱、两处别照抄的自相矛盾、分阶段路线 P0~P4 |
| [docs/FINDINGS.md](docs/FINDINGS.md) | 现状盘点与待办：已处理（问题/证据/处理）、待修待查、结构问题 |
| [docs/SITE-MAP.md](docs/SITE-MAP.md) | 三域名与本仓库的分工 + 第 7 节「分支与发布模型」（dev/master 双分支、稳定版靠标签、主站只跳转） |
| [docs/DEPLOY-TEST.md](docs/DEPLOY-TEST.md) | 测试区部署细节 |

## 当前状态

- ✅ 引擎可从源码完整编译出 wasm，并通过无头实例化验证（`tools/verify-engine.mjs`，当前构建 80 个导出符号）
- ✅ 构建流程已在 Windows 上打通（上游在 Windows 下有 2 处构建缺陷，已修，见 docs/FINDINGS.md）
- ✅ 存档改为**一个档位一个文件**（以前只要存档就固定产生两个文件），带文件头 + CRC32 校验
- ✅ 存档转移改为**文件导出/导入**，删掉了容易出错的长字符串复制粘贴与云码短链
- ✅ `.lib` 尾部元数据块：剧本 ID + 要求版本 + 包体 CRC32，离线脚本能写、引擎能读（**读到但不拦**，见上节）
- ✅ 游戏数据统一放工作区根目录 `libs/`，不再混在仓库工作树里；本地服务映射 `/libs/`
- ✅ 测试区部署链路就绪：`tools/deploy-test.mjs` 默认写七牛 `bbkgames-test` 根目录（网页到根、数据到 `/libs/`）
- ✅ **测试区已于 2026-10-18 首次部署成功**：135 个文件（网页 95 + 数据 40），8 个关键地址与本地 MD5 逐字节一致
- 日常更新：`node tools/deploy-test.mjs`，或双击 `tools\部署测试区.bat`（演练版 `部署测试区-演练.bat`）
- ⚠️ 游戏数据未包含在仓库中
- ⚠️ 与线上部署版的符号一致性核对待重做（见 docs/FINDINGS.md P1 第 5 条）

## 许可证

本仓库整体为 **GPL-2.0-only**（见 [LICENSE](LICENSE)）。

之所以不能沿用上游引擎的 MIT：前端来自 GPL-2.0 的 `baye-alpha`，
GPL 代码并入后整体必须以 GPL 发布。上游 MIT 声明保留在 `engine/LICENSE.MIT`。