# WGS

**Repository Path**: xingbiao/wgs

## Basic Information

- **Project Name**: WGS
- **Description**: WGS — 网页游戏模拟器
纯前端多平台复古游戏模拟器，在浏览器中运行 FC / GBC / GBA / NDS 游戏。无需安装、无需插件、无需服务器，打开网页即可玩。

特性
四平台支持：FC（NES）、GBC、GBA、NDS
纯前端运行：文件不出本机，存档保存在浏览器本地 IndexedDB
存档导入导出：.wg
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-09-08
- **Last Updated**: 2026-09-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# WGS — 网页游戏模拟器

纯前端多平台复古游戏模拟器，在浏览器中运行 FC / GBC / GBA / NDS 游戏。无需服务器，文件不出本机。

> ⚠️ **NDS 功能暂不可用**：melonDS 核心仍处于调试阶段，NDS 游戏暂无法正常游玩，后续版本会修复。

## 特性

- **多平台支持**：FC（NES）、GBC、GBA；NDS 调试中
- **纯前端运行**：文件不出本机，存档保存在浏览器本地 IndexedDB
- **存档管理**：支持 .wgs 格式导入导出（含 CRC32 校验），可跨设备迁移
- **金手指支持**：GameGenie、CodeBreaker、十六进制直写，自动持久化
- **键盘映射**：可视化按键配置面板，支持自定义键盘映射；默认键位随平台自适应（FC/GBC 为 X=A、Z=B，GBA 为 Z=A、X=B）
- **NDS 布局**：竖屏 / 横屏 / 单屏切换，触摸屏支持（待修复）
- **移动端适配**：响应式布局，触屏操控
- **画面增强**：WebGL2 超分辨率（Scale2x / xBRZ，最高 4x）、CRT 滤镜、锐化，四档预设一键切换
- **离线可用**：PWA 支持，可安装到桌面/手机；安装引导横幅（触发 `beforeinstallprompt`）

## 技术栈

| 层 | 技术 |
|---|---|
| 框架 | React 18 + TypeScript 5 |
| 构建 | Vite 6 |
| 渲染 | Canvas2D / WebGL2（超分着色器、CRT 滤镜） |
| 多线程 | Web Worker（模拟核心独立线程） |
| 音频 | AudioWorklet（低延迟音频输出） |
| 存储 | IndexedDB（Dexie 封装） |
| 状态管理 | Zustand |
| 桌面端 | Electron（可选打包） |

## 快速开始

### 1. 源码构建（浏览器运行）

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 打开浏览器访问 http://localhost:5173/
# 拖入 ROM 文件即可开始游戏
```

**构建生产版本：**

```bash
npm run build    # 构建到 dist/
npm run preview  # 预览构建产物
```

> 生产构建已集成 PWA（Service Worker + manifest），在 HTTPS 或 localhost 下可安装为桌面/移动应用。

### 2. 桌面安装包

从 [Gitee Releases](https://gitee.com/wannacodefly/wgs/releases) 下载对应操作系统的安装包：

| 平台 | 安装包格式 |
|------|-----------|
| Windows | `.zip` 便携版（无需安装） |
| macOS | `.dmg`（x64 与 arm64 双架构） |
| Linux | `.tar.gz` |
| 网页版 | `wgs-pwa-*.zip`（构建产物，可部署到任意静态托管） |

> 桌面版基于 Electron 封装，与浏览器版功能完全一致。

**本地打包：**

```bash
npm run pack:win    # Windows 便携版 (需要 Windows 环境)
npm run pack:mac    # macOS dmg (需要 macOS 环境)
npm run pack:linux  # Linux tar.gz
npm run pack:pwa    # 构建 PWA 并打包为 zip 到 release/
```

### 3. 终端版本（npm 安装）

无需浏览器，在终端里直接玩 FC / GBC / GBA 游戏，支持 ANSI TrueColor（24-bit）半块渲染、CPU 超分、存档回读。

```bash
# 全局安装
npm install -g wgs-terminal

# 直接游玩（按任意键开始，方向键+X/Z+回车+空格=控制）
wgs-terminal --rom ./game.gba

# 常用选项
wgs-terminal --rom ./game.gba --upscale 2x    # Scale2x 超分
wgs-terminal --rom ./game.gba --audio on      # 开启音频（系统命令播放）
wgs-terminal --rom ./game.gba --speed 4       # 4 倍速
wgs-terminal --rom ./game.gba --mode quad     # quad 渲染模式（默认 half）
wgs-terminal --rom ./game.gba --cheat CODE     # 金手指
wgs-terminal --rom ./game.gba --patch patch.ips # 打 IPS/UPS 补丁
```

> 终端版与浏览器版共享同一模拟核心（jsnes / gameboy-emulator / gbajs），颜色、分辨率、帧率均保持 web 版水准，不降级。

## 架构设计

项目采用 **主线程 (UI)** 与 **工作线程 (模拟核心)** 分离的架构，确保高负载的模拟运算不阻塞页面交互。

```
┌──────────────────────────────────────────────────────┐
│                    主线程 (UI)                        │
│   ┌──────────┐  ┌────────────┐  ┌────────────────┐  │
│   │ React    │  │ WebGL2/    │  │ AudioWorklet   │  │
│   │ Player   │  │ Canvas 渲染 │  │ 音频输出       │  │
│   └────┬─────┘  └─────┬──────┘  └────────────────┘  │
│        │              │                             │
│   ┌────┴──────────────┴─────────────────────────┐  │
│   │           引擎层 (Engine)                     │  │
│   │       帧调度 · 倍速 · 消息路由 · 输入转发      │  │
│   └────────────────────┬──────────────────────────┘  │
│                        │ postMessage                  │
├────────────────────────┼──────────────────────────────┤
│                        │        Web Worker             │
│   ┌────────────────────┴──────────────────────────┐   │
│   │              模拟核心适配器层                    │   │
│   │                                              │   │
│   │   FC (jsnes)  GBC (gameboy-emulator)         │   │
│   │   GBA (gbajs)  NDS (melonDS WASM)            │   │
│   │                                              │   │
│   │   存档管理 (IndexedDB)  金手指解析  ROM加载    │   │
│   └──────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────┘
```

### 核心模块说明

- **渲染器 (`src/video/`)**：支持 OpenGL ES 2.0/3.0 硬件加速渲染，内置 Scale2x、xBRZ、CRT 等后处理滤镜。
- **音频引擎 (`src/audio/`)**：使用 `AudioWorklet` 实现与主线程解耦的低延迟音频环形缓冲区。
- **输入系统 (`src/input/`)**：统一管理键盘事件与虚拟按键（触屏），支持自定义按键映射与宏定义。
- **存档系统 (`src/save/`)**：基于 Dexie.js 的 IndexedDB 封装，自动管理 SRAM 状态与即时存档。

## 模拟核心

| 平台 | 核心项目 | 许可 | 备注 |
|------|----------|------|------|
| FC / NES | [jsnes](https://github.com/bfirsh/jsnes) | MIT | 纯 JS 实现 |
| GBC | [gameboy-emulator](https://github.com/robatron/gameboy-emulator) | MIT | 纯 JS 实现 |
| GBA | [gbajs](https://github.com/endrift/gbajs) | MIT | 包含浏览器兼容补丁 |
| NDS | [melonDS](https://github.com/melonDS-emu/melonDS) | GPLv3 | C++ 编译为 WebAssembly |

> 本项目**壳层代码**（React UI、适配器、引擎、渲染）以 **MIT** 许可开源。melonDS 核心遵循上游 **GPLv3** 许可。

## 参与开发

1.  Fork 本仓库
2.  创建特性分支 (`git checkout -b feature/amazing-feature`)
3.  提交更改 (`git commit -m 'Add some amazing feature'`)
4.  推送到分支 (`git push origin feature/amazing-feature`)
5.  发起 Pull Request

## 免责声明

本项目仅供学习研究使用。不提供任何游戏 ROM 文件，用户需自行准备并确保拥有合法使用权。

## License

壳层代码 (MIT License)

Copyright (c) 2024 Wannacodefly

各模拟核心遵循其上游许可证（见上表）。