🕹️ 像素时光机 / Pixel Time Machine

在浏览器里重温小霸王时光 — 一个 CRT 怀旧风格的 NES/FC 网页模拟器
199 款经典游戏 · 即时存档 · 手柄支持 · 移动端虚拟按键

---

📸 截图

TODO: 添加实际运行截图（游戏库界面 + 游戏运行界面 + 移动端界面）

---

✨ 功能特色

功能	说明
🎮 NES 模拟内核	基于 Nostalgist.js，浏览器原生运行，无需安装插件
📺 CRT 扫描线 + 霓虹主题	致敬 90 年代显像管电视，像素风 UI 全套设计
💾 即时存档	随时存/读，多存档位，基于 IndexedDB 持久化
📱 移动端虚拟手柄	触屏设备完整支持，响应式布局适配手机/平板
🎮 原生手柄支持	Gamepad API，插上手柄即玩
🔍 游戏库管理	分类浏览、关键词搜索、收藏、评分
📊 游玩统计	游玩时长、历史记录追踪
🔐 合规设计	用户自行加载 ROM，项目不分发受版权保护的内容

---

🛠️ 技术栈

┌──────────────────────────────────────────────┐
│              UI Layer (React 19)             │
│  GameLibrary  │  GameScreen  │  VirtualPad   │
├──────────────────────────────────────────────┤
│           Emulator Service                   │
│  Nostalgist Core │ Audio │ Input │ Save/Load │
├──────────────────────────────────────────────┤
│            Storage Layer                     │
│     IndexedDB (Dexie) — ROMs / States / Config│
└──────────────────────────────────────────────┘

模块	技术
框架	React 19 + TypeScript
模拟器	Nostalgist.js (NES 模拟内核)
状态管理	Zustand
渲染	Canvas API
音频	Web Audio API
手柄	Gamepad API
存储	IndexedDB (Dexie ORM)
构建	Vite 8
样式	CSS Variables + 自定义像素主题
包管理	pnpm

---

🚀 快速开始

前置要求

• Node.js >= 18
• pnpm >= 8（推荐）或 npm/yarn

安装 & 启动

# 1. 克隆仓库
git clone https://github.com/Zchary1106/pixel-time-machine.git
cd pixel-time-machine

# 2. 安装依赖
pnpm install

# 3. 启动开发服务器
pnpm dev

打开浏览器访问 http://localhost:5173，开始游戏！🎮

构建生产版本

# 构建
pnpm build

# 本地预览构建结果
pnpm preview

构建产物位于 dist/ 目录，可以直接部署到任何静态托管服务。

---

🌐 部署指南

方式一：Vercel（推荐，一键部署）

1. 点击上方按钮，或在 Vercel 中导入此仓库
2. 框架选择 Vite，其他设置保持默认
3. 点击 Deploy，等待约 30 秒即可上线

方式二：GitHub Pages

1. 修改 vite.config.ts，添加 base 路径：

   export default defineConfig({
     base: '/pixel-time-machine/',
     // ...其他配置
   })

2. 构建并部署：

   pnpm build

3. 在仓库 Settings → Pages 中，选择 gh-pages 分支或手动上传 dist/ 目录

方式三：Netlify

# 安装 Netlify CLI
npm i -g netlify-cli

# 构建 & 部署
pnpm build
netlify deploy --prod --dir=dist

方式四：Docker

FROM node:18-alpine AS builder
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN npm i -g pnpm && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80

docker build -t pixel-time-machine .
docker run -p 8080:80 pixel-time-machine

方式五：任意静态服务器

pnpm build

# 用任何你喜欢的方式托管 dist/ 目录
# 例如 Python:
cd dist && python3 -m http.server 8080

# 或者 serve:
npx serve dist

---

🎮 使用说明

键盘控制

按键	功能
↑ ↓ ← →	方向键
Z	A 键
X	B 键
Enter	Start
Shift	Select
F5	快速存档
F8	快速读档

手柄支持

插入 USB/蓝牙手柄后自动识别，支持 Xbox、PlayStation、Switch Pro 等标准手柄。

移动端

在手机/平板上打开页面，自动显示虚拟手柄按键。

---

⚖️ 法律声明

本项目是一个开源的 NES 模拟器前端，仅提供模拟器运行环境，不包含任何受版权保护的 ROM 文件。

• roms/ 目录中的文件需要用户自行准备合法拥有的 ROM
• 请确保你拥有对应游戏卡带的合法副本
• 本项目不鼓励、不支持任何形式的盗版行为

---

⭐ Star History

---

📜 License

MIT © Zchary1106

---

_{用 ❤️ 和像素构建 · 致敬那些和小霸王一起度过的午后时光
INSERT COIN TO CONTINUE 🪙}