# 植物大战僵尸拼音版

**Repository Path**: echooooooo/pinyin-fusion

## Basic Information

- **Project Name**: 植物大战僵尸拼音版
- **Description**: 来自李翔在湘西的无私奉献
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 拼音融合大作战 · 模块化工程

小学语文「声母 / 介母 / 韵母」融合闯关游戏。原为单文件 382 KB HTML，
现已拆分为**可维护的多模块源码**，交付物仍是**零依赖单文件**，双击即玩。

> 面向课堂：老师收到 HTML → 双击打开 → 就能上课。全程无需联网、无需服务器。

**本次拆解的硬约束：功能临时不变。** 交付物与原版的等价性由 4 条可复跑判据守住，
当前结论：**判据 1~4 全部通过**（详见 `docs/split-report.md` §6）。

---

## 快速开始

```bash
npm install          # 装 esbuild + acorn（两个 devDependency）
npm run build        # src/ → dist/拼音融合大作战.html
npm run verify       # 切割完整性 + 等价性验收
npm run serve        # 起本地服务器，直接在浏览器里跑 ESM 源码
npm run probe -- <html>   # CDP 探针：读运行中游戏的状态
```

交付给用户的是 **`dist/拼音融合大作战.html`** —— 单个文件，双击即玩。

从原文件重建整棵源码树（一步到位，含完整性校验）：

```bash
bash tools/rebuild.sh
```

---

## 目录结构

```
outputs/pinyin-fusion/
├── src/                    模块化源码（ESM，浏览器可直接 import）
│   ├── index.html          DOM 骨架（从原文件自动提取，逐字一致）
│   ├── styles/             表现层：base / fonts / cards / hud / screens
│   ├── core/               引擎层：零依赖 WebGL2 运行时（对外依赖 0）
│   │   ├── math.js         常量、缓动、随机、矩阵、网格生成
│   │   ├── scene.js        SceneNode / Material / MeshEntity / SpriteEntity
│   │   ├── shader.js       ShaderProgram 封装
│   │   ├── particles.js    GPU 粒子系统
│   │   ├── renderer.js     渲染器（WebGL2、阴影、Bloom、后期合成）
│   │   └── shaders/        13 个 GLSL 常量，各自独立成文件
│   ├── data/               数据层：纯数据 + 跨模块注册表
│   │   ├── registry.js     唯一跨模块通信通道（qe，惰性 getter）
│   │   ├── pinyin.js       音节表、拼读规则、校验
│   │   ├── tones.js        带调音节→汉字映射
│   │   └── chars.js        汉字词库、关卡配置与文案
│   ├── game/               游戏层：玩法逻辑
│   │   ├── init.js         引擎初始化、材质预设、贴图注册
│   │   ├── textures.js     canvas 程序化贴图
│   │   ├── models.js       植物/道具模型工厂
│   │   ├── entities.js     糊涂怪、字牌、割草机、弹丸、光束、环境
│   │   └── controller.js   主控类（玩法流程、输入、战斗、关卡状态）
│   ├── ui/                 界面层：DOM 辅助、6 个 screen
│   │   ├── dom.js
│   │   └── screens.js
│   ├── audio/              音频层：WebAudio 音效、BGM、语音朗读
│   └── boot/               启动：视口适配、字体等待、引擎启动、主循环
├── build.mjs               构建：src/ → 单文件 dist/
├── dist/                   交付物（构建产物）
├── reference/              原版黄金参照（入库，sha256 与桌面原文件一致）
├── tests/equivalence/      等价性验收（基线 / 对比器 / 噪声测量，可复跑）
├── tools/                  拆分管线与验收工具（7 步重建 + 依赖分析 + 探针）
└── docs/                   逆向规格、架构决策、拆分报告
```

规模：**31 个 JS 模块 + 5 个 CSS 文件**，5,246 行有效代码，178 个导出符号。

---

## 设计约束（为什么是这样）

### 交付物必须是单文件
本游戏给小学老师在触屏白板上使用，收到 HTML 后**双击打开**，没有服务器。

实测：`file://` 下 `<script type="module">` 被 CORS 拦截，脚本**完全不执行**：

| 条件 | 结果 |
|---|---|
| `file://` 无参数 | 未执行 |
| `file://` + `--allow-file-access-from-files` | 执行 |

用户双击没有那个参数 → 所以**源码用 ES Module 组织，交付时拼回单作用域再压缩**。
这是 ADR-001 / ADR-008 的完整推理。

### 构建是「拼接回单作用域」而不是「ESM 打包」
原游戏存在**跨模块被改写的可变状态**（伪随机种子 `ie`：init.js 定义、entities.js 重置）。
ESM 的 import 是只读绑定，`esbuild --bundle` 会直接报 `Cannot assign to import "ie"`；
绕开它就得改业务代码 —— 那会破坏「功能临时不变」。

所以构建期按**原始物理顺序**把模块拼回同一个作用域，与原版逐位等价。
`src/` 里的 import/export 保留为**声明性依赖清单**，构建期强校验（断链即构建失败）。

### 模块间唯一通信通道是 `registry`
沿用原代码已有的 `qe` 注册表模式（getter 定义，惰性求值）。
好处：依赖方向可静态扫描、边界不会腐化。详见 ADR-002。

### 类名方法名不改，变量名本轮也不改
原代码变量名被混淆成 i/t/e/s，但函数名类名完整保留（`fuseMedial`、`killZombie`…）。
本轮刻意**不做变量改名** —— 混淆代码里同名变量极多，改错一个就静默改变行为，
与「功能临时不变」冲突。改名列为下阶段项，工具已就绪（ADR-003 / ADR-013）。

### CSS 分文件但必须保序
按职责把 177 个 CSS 块分进 5 个文件是工程目标，但**分文件会打乱层叠顺序**。
每块带 `/*@ord:N*/` 原始序号标记，构建时全局按 N 排序合并 —— 177/177 块顺序与原版一致。
详见 ADR-011。

---

## 等价性验收

「功能临时不变」不是承诺，是**可复跑的判据**。

```bash
# 切割完整性（源码层）：重组结果与原文件逐行 sha256 一致
node tools/verify_split.mjs

# 等价性验收（运行层）
node tests/equivalence/collect.mjs --file reference/original-拼音融合大作战.html --out tests/equivalence/baseline
node tests/equivalence/collect.mjs --file reference/original-拼音融合大作战.html --out tests/equivalence/baseline-noise
node tests/equivalence/compare.mjs \
  --baseline tests/equivalence/baseline \
  --noise    tests/equivalence/baseline,tests/equivalence/baseline-noise \
  --file     dist/拼音融合大作战.html
```

判据与当前实测：

| # | 判据 | 手段 | 实测 |
|---|---|---|---|
| 1 | `file://` 直开无报错 | 无头 Chrome 加载，检查 `#load` 已移除、`#err` 未出现、console 无 error | 0 error / 0 异常 / WebGL2 可用 ✅ |
| 2 | 运行态探针一致 | `window.__game` 的 55 个字段逐项比对 | 2 视口 × 5 场景 = **550 项全等** ✅ |
| 3 | DOM 结构一致 | `#ui` 子树归一化 + 6 个 screen 子树 sha256 + 31 项关键元素 | 全部相等 ✅ |
| 4 | 截图一致 | 固定视口截图差异量化（噪声相对阈值） | 差异 **0.000%~0.042%**，噪声基线 0.066%，dHash/aHash 全 0 ✅ |
| 5 | 依赖方向合规 | `core/` 不得引用 game/data/ui/audio；依赖图无环 | core/ 对外依赖 0；DAG ✅ |
| 6 | 命名已语义化 | 顶层单字母变量已改 | ⏳ 下阶段项（ADR-013） |

场景覆盖（受信任的鼠标点击走真实用户路径）：
`title` → `levels` → `help` → `intro-lv1` → `play-lv1`，视口 `1280x720` 与 `390x844`。

**判据 4 的阈值不是拍脑袋的**：截图前注入确定性 `Math.random` + 冻结 CSS 动画 +
冻结游戏时间（`window.__dtCap`）+ 相机吸附，把「原版 vs 原版」的天然噪声从 26.6% 压到 0.066%，
阈值再由该噪声推导。详见 ADR-012。

---

## 文档

| 文件 | 内容 |
|---|---|
| `docs/reverse-spec.md` | 逆向规格书：模块边界表（含精确行号）、通信契约、命名规范、验收判据 |
| `docs/architecture-decisions.md` | 13 条 ADR：每条含背景 / 决策 / 后果 / 实测依据 |
| `docs/split-report.md` | **拆分报告**：模块清单、五个关键技术决策、判据实测数据、后续项 |

---

## 技术栈

| 项 | 选择 | 说明 |
|---|---|---|
| 渲染 | WebGL2 原生 | 自研引擎，**无 Three.js 等第三方运行时依赖** |
| 构建 | esbuild 0.28.2 | 仅用于压缩（不 bundle） |
| 分析 | acorn 8 | 仅用于构建期 AST 分析（符号识别、精确 dedent、CSS 保序校验） |
| 音频 | WebAudio | 程序化合成音效与 BGM |
| 贴图 | Canvas 2D 程序化生成 | 无外部图片资源 |
| 字体 | base64 内嵌 WOFF | CNF（中文标题）/ PYF（拼音） |

整个游戏**零外部资源依赖**：无 http 链接、无外链图片，字体全内联，纹理全程序化生成。