面向 Windows 的离线单人弹球游戏。项目使用原创未来科技视觉、程序化音效和简体中文界面，在不复制原版素材的前提下，参考 Windows 版《3D Pinball: Space Cadet》的计分、任务和机关行为。
当前版本：1.0.0。Windows 11 已完成本机验证；Windows 10 是目标平台，但尚未进行独立实机认证。
- 固定 120 Hz 的确定性物理循环，高速弹球启用连续碰撞检测。
- 双独立电机挡板、蓄力活塞、六档技巧球、三方向震台和 TILT。
- 收肩式台面、底部漏斗、独立发射道、坡道层级和完整洞口路由。
- Windows 版基础计分、三球制、额外球、重玩球、倍率和本地前五名高分。
- 17 个单人任务、约 90 秒任务燃料、九级军衔和 18 格晋升进度。
- Electron 沙箱、上下文隔离、严格 CSP、窄 IPC 和运行时数据校验。
- 原创程序化 WebAudio 音效与环境音乐，不依赖网络或外部游戏资源。
从 GitHub Releases 下载 QuantumPinball.exe 和对应的 .sha256 文件，验证校验值后双击运行。程序免安装，不要求管理员权限，也不需要联网。
详细操作、设置和 SmartScreen 说明见用户指南。
| 功能 | 默认按键 |
|---|---|
| 左 / 右挡板 | Z / / |
| 活塞蓄力与释放 | Space |
| 右 / 左 / 上震台 | X / . / ? |
| 设置与暂停 | Esc |
| 物理调试层 | F9 |
| 游戏结束后重新开始 | Enter |
需要 Node.js 24、pnpm 11.19 和 Windows 开发环境。
pnpm install --frozen-lockfile
pnpm check
pnpm dev构建便携版：
pnpm package:portable完整环境、命令和调试说明见开发指南。
flowchart LR
Input[键盘输入] --> Physics[Planck.js 物理世界]
Physics --> PE[PhysicsEvent]
PE --> Map[事件映射]
Map --> GE[GameEvent]
GE --> Reducer[纯函数规则归约器]
Reducer --> State[GameState]
State --> HUD[HUD / 灯光 / 音频]
Table[TABLE 台面定义] --> Physics
Table --> Render[PixiJS 渲染]
Table --> Tests[完整性测试]
State --> Preload[受限 preload 桥]
Preload --> Store[主进程原子 JSON 存储]
物理、规则、UI 和音频遵循单向数据流。台面视觉与碰撞体共享 TABLE、PLAYFIELD_SHELL 和 PLAYFIELD_WALL_SEGMENTS，避免出现多套坐标。详细设计见架构文档。
src/main/ Electron 主进程、安全策略、IPC、持久化
src/preload/ 最小化 contextBridge
src/renderer/src/game/ PixiJS 场景、Planck.js 物理、输入和音频
src/shared/ 契约、台面/计分/任务数据、规则归约器
tests/ 单元、机制、压力和端到端流程测试
docs/ 架构、开发、测试、发布和规则文档
build/ 原创应用图标
checksums/ 已发布便携 EXE 的 SHA-256
| 文档 | 用途 |
|---|---|
| 架构设计 | 进程边界、数据流、物理循环、安全与扩展点 |
| 开发指南 | 环境、命令、目录、调试和常见修改流程 |
| 测试策略 | 自动测试分层、确定性要求和手工验收 |
| 发布手册 | 版本、构建、冒烟、校验和 GitHub Release |
| 规则研究 | 原版资料来源、差异和采用规则 |
| 台面布局 | 坐标系、区域和不得破坏的空间约束 |
| 用户指南 | 玩家操作、设置和故障恢复 |
| 测试报告 | 当前发行版的验证结果 |
| GitHub 发布清单 | 首次公开仓库前的维护者检查项 |
| 贡献指南 | 分支、提交、PR 和回归要求 |
| 安全策略 | 支持版本、漏洞报告和安全边界 |
| 变更日志 | 面向版本的用户可见变化 |
首版仅支持单人、键盘、简体中文和本地高分，不包含联网排行榜、云存档、自动更新、多人、手柄或触屏。复刻目标是规则、机制与手感，不追求与原程序逐帧浮点一致。
本项目不包含或分发原版位图、Logo、人物、音频、商标资源或 CADET.DAT。第三方依赖和规则参考见第三方说明。
项目代码与原创资源采用 MIT License 开源。原版游戏名称和相关商标归各自权利人所有；MIT License 不授予任何第三方商标或原版素材权利。
当前发行验证基线为 13 个测试文件、148 项测试。实现进度和历史里程碑见 PROGRESS.md。提交修改前请阅读贡献指南，并至少运行：
pnpm check