# lingshu-arcade

**Repository Path**: magic2060/lingshu-arcade

## Basic Information

- **Project Name**: lingshu-arcade
- **Description**: 还是你现有那套`lingshu-` 前缀，名字够宽——打怪、避障以后想再塞几种小游戏进来也不用改名。

备选：`lingshu-game-box` （更强调"合集"）、`pixel-holdout` （更偏游戏本身的调性）。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 灵枢街机（Lingshu Arcade）

一款用 **Vue3 + Canvas 2D + Electron** 从零手写的单机街机合集。没有 Unity/Cocos，没有外部图片/音频素材——所有画面与音效都由代码实时生成，打包后是一个可离线运行的 Windows 桌面游戏。

当前收录四个玩法：

| 玩法 | 类型 | 简介 |
| --- | --- | --- |
| **灵枢·熵潮**（主玩法） | 俯视角生存射击 | 自动射击、走位躲弹、拾取灵能升级，撑过 180 秒一次的「熵核」首领战，分数越高越难 |
| **弹幕回廊**（挑战模式） | 弹幕闪避 | 在圆形回廊中贴身擦弹得分，冲刺自带无敌，三条命拼高分 |
| **灵链蛇行**（经典模式） | 网格贪吃蛇 | 方向键转向吞食灵能，越吃越长、越吃越快，撞墙或咬到自己即结束 |
| **灵枢·跃迁**（平台模式） | 横版跳跃平台 | 踩踏巡逻敌人、收集金币、跳过深坑，三关递进跑到终点旗 |

> 关于“截图”：仓库未内置截图文件，可用下面的文字速写代替。
>
> - 大厅：深色科幻底色，顶部是「灵枢街机」标题与五块统计卡（各玩法最高分 / 操作提示），下方是玩法卡网格，每张卡左侧有发光色条，右侧显示最高分与“进入玩法”按钮。
> - 主玩法：青蓝色网格地面 + 中央能量阵，玩家是带护盾环的三角形飞船，红色三角/橙色菱形/紫色六边形等敌人从四周涌来，子弹与粒子叠加发光，右上角有分数、波次、计时与生命条。
> - 贪吃蛇：深色棋盘网格 + 薄荷色霓虹蛇身，蛇头带眼睛，食物是旋转的金色菱形；左右两侧显示分数、长度、速度与最高分。
> - 平台跳跃：暗色瓦片地面与单向平台，青白色小人、紫色地巡怪、粉色弹跳怪、金色金币与终点旗；摄像机横向跟随，掉进深坑会从复活点重生。
> - 结算：半透明毛玻璃面板，中央是大号分数与「本机最高」，下方按玩法显示存活时间、击杀 / 长度 / 关卡等统计。截图位建议放在每个玩法说明段落上方。

---

## 玩法说明

### 主玩法：灵枢·熵潮

**操作**

| 输入 | 作用 |
| --- | --- |
| `W A S D` / 方向键 | 移动 |
| 鼠标移动 | 瞄准（自动开火，不需要点左键） |
| `空格` / `Shift` | 冲刺（短暂无敌，有冷却） |
| `Esc` / `P` | 暂停 / 继续 |
| `1` `2` `3` | 升级时快速选择卡片 |
| `R` | 结算 / 暂停界面重开；贪吃蛇与平台玩法在游玩中也可直接重开 |

**规则与计分**

- 击杀敌人得分，基础分见下表；**连击倍率**最高 ×9：每次击杀后 2.6 秒内继续击杀即可叠层，受伤或超时清零。
- 实际得分 = 敌人基础分 × 当前连击倍率（四舍五入）。
- 击杀掉落灵能球，拾取后积累经验；经验满自动进入「灵能进化」，从 3 张强化卡中选 1 张（可叠层）。
- 每 30 秒进入下一波，刷怪间隔从 1.15 秒逐渐压缩到 0.34 秒，敌人数量、血量、伤害随存活时间增长。
- 每 180 秒出现一只「熵核」首领：环形弹幕 + 召唤小怪，血量按形态递增；击杀额外 **+800 分**。
- 生命归零即结算，记录写入本地，保留最高分与最近 8 局成绩。

| 敌人 | 特点 | 基础分 |
| --- | --- | --- |
| 追猎者（红三角） | 直线追击 | 30 |
| 疾冲者（橙菱形） | 蓄力后高速冲刺 | 36 |
| 分裂体（紫六边形） | 死亡分裂成 2 个裂片 | 45 |
| 裂片（紫圆） | 高速小怪 | 12 |
| 哨戒炮（青圆环） | 保持距离并瞄准射击（有预警线） | 55 |
| 碾压者（红方块） | 高血量慢速 | 75 |
| 熵核（首领） | 环形弹幕 + 召唤 | 1200 + 800 奖励 |

**强化卡池**（共 14 张，可叠层）：灵能过载（射速）、锋锐附魔（伤害）、分裂弹幕（多重弹）、贯穿符文、致命弱点（暴击）、疾风步、生命扩容、回春术、短距跃迁（冲刺 CD）、灵能虹吸（拾取范围）、环绕灵刃、嗜血共鸣（击杀回血）、巨像弹丸、应急补给。

### 挑战模式：弹幕回廊

- `W A S D` / 方向键移动，`空格` / `Shift` 冲刺（约 1.2 秒冷却，冲刺期间无敌）。
- 三种弹幕：瞄准弹、环形弹、螺旋弹；被击中扣 1 点生命（共 3 点），并清空身边弹幕、获得短暂无敌。
- **擦弹**：贴近子弹掠过 +2 分；存活每秒 +10 分；拾取能量块 +45 分。
- 每 20 秒提升一波弹幕密度。三条命耗尽结算，同样记录最高分。

### 经典模式：灵链蛇行

**操作**

| 输入 | 作用 |
| --- | --- |
| `↑ ↓ ← →` / `W A S D` | 转向（不能 180° 直接掉头，连续转向会进入 2 格输入缓冲） |
| `P` / `Esc` | 暂停 / 继续 |
| `R` | 立即重开（分数、长度归零） |

**规则与计分**

- 蛇按固定网格步进，吃到食物 **+10 分**，蛇身 **+1 格**；每长一格，步进间隔从 0.16 秒逐步缩短到 0.062 秒。
- 撞到棋盘边界或咬到自己的身体立即结束；棋盘填满时判定「完美通关」。
- 食物永远生成在空格子上，不会与蛇身重叠。
- 最高分与最近 8 局记录写入本地存档，重开或重启应用后仍然保留。

### 平台模式：灵枢·跃迁

**操作**

| 输入 | 作用 |
| --- | --- |
| `A` `D` / `← →` | 左右移动（带加速与减速） |
| `空格` / `W` / `↑` | 跳跃；**按住越久跳得越高**，轻点是小跳 |
| `P` / `Esc` | 暂停 / 继续 |
| `R` | 重开整轮（回到第一关，分数与生命归零） |

**规则与计分**

- 共 3 关，从起点跑到终点旗即过关，中途自动衔接下一关；通关三关后显示「全部关卡通关」。
- 玩家有 **3 点生命**。从上方踩踏敌人可击败它并弹起（**+50 分**），从侧面接触扣 1 点生命并被击退。
- 金币 **+100 分**；每通过一关 **+500 分**。
- 掉进深坑扣 1 点生命，并从本关起点或已激活的复活点（青色光柱）重生；生命归零即结算。
- 瓦片包含实心块与单向平台（可从下方跳穿、从上方落住），摄像机跟随玩家并限制在关卡边界内。
- 手感参数（重力、可变跳跃高度、土狼时间、跳跃缓冲、加减速）集中在
  `src/games/platformer/PlatformerGame.js` 顶部常量区，调参说明见 [平台玩法文档](docs/platformer.md)。

---

## 快速开始

### 0. 环境要求

- Node.js ≥ 18（建议 20/22 LTS；本机验证使用 v24.19.0）
- npm ≥ 9
- Windows 10/11（打包目标为 Windows x64）

### 1. 安装依赖（统一走 npmmirror）

```bash
npm install --registry=https://registry.npmmirror.com
```

项目根目录的 `.npmrc` 已写入镜像配置，通常直接 `npm install` 即可。

### 2. 开发调试（浏览器）

```bash
npm run dev
# 打开 http://localhost:5173
```

### 3. 开发调试（Electron 窗口）

```bash
npm run electron:dev
```

该命令会先启动 Vite（5173），再拉起 Electron 加载开发地址，改代码可热更新。

### 4. 构建前端产物

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

### 5. 打包 Windows exe

**Electron 下载慢是国内最常见的坑**，务必先设置镜像环境变量（PowerShell 示例）：

```powershell
$env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"
$env:ELECTRON_BUILDER_BINARIES_MIRROR = "https://npmmirror.com/mirrors/electron-builder-binaries/"
npm run electron:build
```

CMD 写法：

```bat
set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
set ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/
npm run electron:build
```

如果在安装依赖阶段就卡在 Electron 二进制下载，可先执行：

```bash
npm install --registry=https://registry.npmmirror.com --electron_mirror=https://npmmirror.com/mirrors/electron/
```

产物在 `release/`：

- `lingshu-arcade-1.1.0-setup.exe` —— NSIS 安装包（可选安装目录、创建桌面/开始菜单快捷方式）
- `lingshu-arcade-1.1.0-portable.exe` —— 免安装单文件版
- `win-unpacked/` —— 解包目录，便于排查启动问题

### 6. 直接运行已构建产物

- 免安装：双击 `release/lingshu-arcade-1.1.0-portable.exe`
- 安装版：运行 `lingshu-arcade-1.1.0-setup.exe` 后从开始菜单启动
- 调试解包版：`release/win-unpacked/灵枢街机.exe`
- 只想看前端：`npm run build && npm run preview`

> 本仓库在开发机上已实际验证：`npm run dev` 能在浏览器完整游玩、`npm run build` 通过、`npm run electron:build` 成功产出上述两个 exe。
> 两个新玩法（灵链蛇行、灵枢·跃迁）在 Chromium 无头浏览器中做了真键盘实测：分数变化、暂停/恢复、重开归零、死亡结算、最高分落盘均已验证；平台玩法三关另用无头物理仿真验证可完整通关。
> v1.1.0 打包后，`win-unpacked/灵枢街机.exe` 与 `lingshu-arcade-1.1.0-portable.exe` 均已在本机启动并截图确认：窗口标题正常、大厅渲染出四个玩法卡片、无黑屏。
> 未验证项：Electron 窗口内的实际游玩操作（自动化环境的模拟鼠标点击无法驱动该窗口），这部分需你双击 exe 手动确认。

---

## Gitee Release 发布步骤

1. 在 Gitee 新建仓库并推送代码（本仓库默认未配置远端）：

   ```bash
   git remote add origin https://gitee.com/<你的账号>/lingshu-arcade.git
   git push -u origin master
   ```

2. 打标签并推送：

   ```bash
   git tag -a v1.1.0 -m "灵枢街机 v1.1.0"
   git push origin v1.1.0
   ```

3. 打开仓库页面 →「发行版」→「新建发行版」，选择标签 `v1.1.0`，填写标题与更新说明。

4. 上传 `release/` 下的两个 exe（`*-setup.exe`、`*-portable.exe`），可再附上 `release/*.blockmap`（增量更新用，可不上传）。

5. 发布即可。下载页建议注明：Windows x64、免安装版直接双击运行、安装版支持自定义目录。

> 提示：Release 附件单文件建议 < 100 MB（v1.1.0 产物：portable 约 78.1 MB，setup 约 78.3 MB）。代码签名证书非必需，未签名时 Windows SmartScreen 会提示“未知发布者”，选择“仍要运行”即可。

---

## 技术栈与目录概览

- **前端**：Vue 3 + Vite 5 + Vue Router（hash 模式）+ Element Plus（暗色主题）
- **游戏**：Canvas 2D 自研引擎（固定步长循环、输入、相机、WebAudio 合成音效）
- **桌面**：Electron 33 + electron-builder 25（NSIS + Portable）
- **结构**：参考若依的分层思想——配置与业务分离、玩法插件式注册、UI 与游戏逻辑解耦

```
lingshu-arcade/
├─ electron/              # 主进程与 IPC（桌面壳）
│  ├─ main.js             # 创建窗口、加载 dist 或开发地址
│  ├─ preload.cjs         # 只暴露最小 API 给渲染进程
│  └─ ipc/                # store.js（存档） / window.js（窗口控制）
├─ scripts/
│  ├─ dev.mjs             # Electron + Vite 一键开发
│  └─ make-icon.mjs       # 纯 Node 生成 build/icon.ico / icon.png
├─ src/
│  ├─ api/                # 桌面能力桥接、排行榜读写
│  ├─ config/             # 全局设置（音量/震屏/自动暂停）
│  ├─ core/               # 引擎：GameLoop / Input / Camera / Sound / math
│  ├─ games/              # 玩法插件：registry.js + survival/ + dodge/ + snake/ + platformer/
│  ├─ components/         # GameCanvas（引擎宿主）/ GameHud
│  ├─ views/              # HomeView（大厅）/ GameView（对局与结算）
│  ├─ router/ styles/     # 路由与全局样式
├─ build/icon.ico         # 应用图标（由脚本生成）
├─ electron-builder.yml   # 打包配置
└─ docs/                  # 二次开发文档
```

更细的说明见：

- [整体架构与目录职责](docs/architecture.md)
- [游戏循环：rAF、状态机、碰撞、渲染分层](docs/game-loop.md)
- [如何新增玩法 / 敌人 / 强化卡](docs/extend-game.md)
- [贪吃蛇玩法：机制、参数与扩展](docs/snake.md)
- [平台跳跃玩法：手感参数、关卡与敌人](docs/platformer.md)
- [Electron 主进程与渲染进程通信边界](docs/electron-ipc.md)
- [打包配置详解与失败排查](docs/packaging.md)
- [项目进度与收尾说明（v1.1.0）](docs/PROGRESS.md)

---

## 常见问题

| 现象 | 处理 |
| --- | --- |
| `npm install` 卡在 Electron 下载 | 设置 `ELECTRON_MIRROR`（见上文），或删掉 `node_modules` 重装 |
| 打包时卡在 `winCodeSign / nsis` 下载 | 设置 `ELECTRON_BUILDER_BINARIES_MIRROR` |
| 想换应用图标 | 改 `scripts/make-icon.mjs` 后执行 `npm run icon`，再重新打包 |
| 打包后白屏 | 确认 `vite.config.js` 中 `base: './'`；确认 `dist/index.html` 在 asar 内；用 `release/win-unpacked` 版开 DevTools 排查 |
| 存档在哪 | Electron 下为 `%APPDATA%/灵枢街机/store.json`；浏览器下为 `localStorage` |
| 没有声音 | 浏览器要求首次点击/按键后才能播放，点一下画面即可解锁音频 |

## License

MIT