# 像素跳跃大冒险 · 多世代合集

一款**纯静态、零依赖、零构建**的横版平台跳跃游戏，用 Canvas 2D 与原生 JavaScript 写成，可直接部署到 EdgeOne Pages / Cloudflare Pages / 任意静态托管。

四个世代主题包、**8 张主关 + 16 张链式隐藏关（共 24 关）**：经典草原与地下、沙漠与雪原、圆丘与熔岩、霓虹夜城与终章城堡守卫。每张主关都藏着一道紫色隐径门，通往「隐径 I」，里面还有一道门通向高难度的「隐径 II 绝境」。包含大小形态、能量花光球、无敌星、踩敌与踢壳连锁、顶砖块出道具、隐藏块、单向平台、移动平台、弹簧、检查点、计时与旗杆通关、Boss 战，以及键盘与触屏操作。

**素材声明**：所有像素画面由代码绘制，音乐与音效由 WebAudio 实时合成，角色、名称、关卡均为原创，未使用任何第三方游戏素材、角色形象或音乐。玩法与关卡结构属于对经典横版平台游戏的致敬式实现。

## 直接运行

纯静态站点用一个静态服务器即可（不要用 `file://` 打开来测网络关卡分片，浏览器会拦截本地 fetch；不过前两关有内嵌兜底，仍可直接双击试玩）：

```bash
cd mali
python -m http.server 8080
# 浏览器打开 http://127.0.0.1:8080/
```

## 操作

| 动作 | 按键 |
| --- | --- |
| 左右移动 | 方向键 / A D |
| 跳跃（按住跳更高） | 上 / W / 空格 |
| 冲刺 | Shift |
| 发射能量光球 | X / J / Z |
| 暂停 | P / Esc |
| 静音 | M |

手机与平板会自动显示虚拟方向键与动作键。金币每 100 枚换 1 条命；踩乌龟头变壳，再踢出去可连锁得分；检查点会自动保存复活位置。

## 项目结构

```
mali/
├── index.html            入口（最后加载所有依赖）
├── style.css             界面样式
├── editor.html           关卡编辑器（独立页面）
├── js/
│   ├── config.js         关卡源配置、localStorage 存档
│   ├── bundled.js        生成器产出：内嵌 manifest + 前两关（file:// 兜底）
│   ├── levels.js         分片加载器：manifest、按关 fetch、预取、多级回退
│   ├── audio.js          原创合成音效与 8 段芯片音乐
│   ├── art.js            8 套主题调色板与像素绘制
│   ├── engine.js         瓦片物理、玩家/敌人/道具/Boss/隐径门/相机/渲染
│   └── game.js           界面状态机、输入、主循环、隐径解锁
├── levels/
│   ├── manifest.json     24 关索引（主关 + 隐藏关条目）
│   └── <level-id>.json   每关一个独立分片（约 1.9-3.6 KB）
├── tools/gen-levels.mjs  关卡分片生成器（主关清单 + 自动派生 2 层隐藏关）
├── tools/smoke-test.mjs  无浏览器运行时冒烟测试
├── .well-known/
│   └── pki-validation/fileauth.txt   SSL 域名所有权验证文件（证书续签会再校验，勿删）
└── _headers              Cloudflare Pages 静态响应头
```

首屏前端约 90 KB（未压缩，无外部请求），24 个关卡分片合计约 65 KB。**关卡内容再大也不会增加首屏体积**：只有进入某关时才拉取该关 JSON，并后台预取下一张主关与该关的隐藏关。

## 关卡分片与网络加载机制

1. 启动时读取关卡根目录下的 `manifest.json`（默认同源 `levels/`）。
2. 进入关卡时按 `entry.file` 拉取**该关单独的 JSON**，结果进内存缓存。
3. 加载成功后后台**预取下一张主关 + 本关的隐藏关分片**，通关或发现隐径门时可瞬间进入。
4. 失败回退链：远端 URL → 同源 `levels/` → 内嵌兜底（前两关）→ 友好错误提示（含 CORS 检查建议）。
5. 远端 manifest 默认与本地关卡**追加合并**（用于把后续关卡放到 R2）；若远端 manifest 顶部带 `"replace": true`，则完全替换本地索引。关卡条目也支持绝对 `url` 字段。

HUD 右侧实时显示当前关卡来源：本站分片 / 远端 CDN / R2 / 内嵌兜底。

## 隐藏关机制

每张主关带 2 张链式隐藏关，共 16 张独立分片：

```
主关 ──W──> 隐径 I ──W──> 隐径 II 绝境 ──> 通关
```

- **发现方式**：地图里的 `W` 是紫色发光隐径门，通常藏在约 42% 处的高处单向云台上，需要主动跳上去探索，旁边有金币排引导。触碰后**保留当前分数、金币、生命与形态**，直接进入下一层。
- **保底解锁**：通关主关也会解锁「隐径 I」，通关「隐径 I」会解锁「隐径 II」，即使没找到门也能从「关卡选择」直接进入。解锁状态存在 `localStorage`（`pq.progress.secrets`）。
- **选关显示**：未解锁的隐藏关显示 `??? 隐径 I/II 未发现` 且不可点击；解锁后显示真名、难度星级与 `HARDCORE` 标记。
- **难度设计**：
  - 隐径 I：更暗的地下/洞穴/城堡主题，时间约主关 62%、长度约 66%，地形池换成高难度段，补给减少。
  - **隐径 II 绝境（第二个隐藏关）**：独立的 `hardcore` 地形池——坑宽 4-5 格（接近跳跃极限）、连续岩浆与 3-5 连尖刺、2 格窄移动平台、飞行怪与敌群密度翻倍、补给点直接替换为敌人、时间约主关 48%、难度固定 5 星。
- **数据字段**：关卡 JSON 的 `hidden` / `parent` / `secretIndex` / `hardcore` / `secretNext` 描述层级；manifest 条目同样带这些字段，供选关排序与解锁判断。
- **扩展**：在 `tools/gen-levels.mjs` 的 `LEVELS` 里新增主关后重新运行生成器，会自动派生它的两层隐藏关；也可用 `editor.html` 手绘，设置「关卡类型 / 所属主关 ID / 通往隐藏关 ID」再导出。

## 把后续关卡放到 Cloudflare R2（或任意 CDN / 自建服务器）

1. 在 R2 建桶（例如 `mali-levels`），开启公开访问：`r2.dev` 子域或绑定自定义域。
2. 把 `levels/manifest.json` 和所有 `<id>.json` 上传到同一目录，例如 `https://pub-xxxx.r2.dev/mario-levels/`。
3. 配置 CORS，允许游戏域名跨域 GET（R2 桶的 CORS 策略）：

```json
[
  {
    "AllowedOrigins": ["*"],
    "AllowedMethods": ["GET", "HEAD"],
    "AllowedHeaders": ["*"],
    "MaxAgeSeconds": 3600
  }
]
```

若用自建服务器，返回头加 `Access-Control-Allow-Origin: *` 即可；同源部署不需要 CORS。

4. 打开游戏 → 「关卡源设置」→ 填入该目录 URL（结尾带 `/`）→ 「保存并测试连接」。界面会显示索引来源与远端追加的关卡数。
5. 之后新关卡只需上传 JSON 并更新远端 `manifest.json`，**前端无需重新构建或重新部署**。

`manifest.json` 条目格式：

```json
{
  "version": 2,
  "packs": [{ "id": "neon", "name": "霓虹自制世代", "desc": "...", "theme": "neon", "badge": "04" }],
  "levels": [
    { "id": "neon-4-1", "pack": "neon", "name": "霓虹 4-1", "theme": "neon",
      "file": "neon-4-1.json", "time": 360, "difficulty": 4, "hint": "...",
      "hidden": false, "parent": null, "secretIndex": 0, "hardcore": false,
      "secretNext": "neon-4-1-s1" },
    { "id": "neon-4-1-s1", "pack": "neon", "name": "霓虹 4-1 · 隐径 I", "theme": "castle",
      "file": "neon-4-1-s1.json", "time": 223, "difficulty": 5,
      "hidden": true, "parent": "neon-4-1", "secretIndex": 1, "hardcore": false,
      "secretNext": "neon-4-1-s2" },
    { "id": "neon-4-1-s2", "pack": "neon", "name": "霓虹 4-1 · 隐径 II 绝境", "theme": "neon",
      "file": "neon-4-1-s2.json", "time": 173, "difficulty": 5,
      "hidden": true, "parent": "neon-4-1", "secretIndex": 2, "hardcore": true,
      "secretNext": null }
  ]
}
```

关卡 JSON 的 `map` 是等宽字符网格（`height` 行 × `width` 列），字符含义见编辑器页面底部说明。也可以直接用 `editor.html` 画完导出，或运行 `node tools/gen-levels.mjs` 程序化生成整套分片。

## 部署到 EdgeOne Pages

本项目是纯静态目录，`index.html` 就在根目录，直接部署这个目录即可（项目类型选 static，无构建命令）。可用 WorkBuddy 的 EdgeOne 连接器一键部署，或用 CLI：

```bash
export PAGES_SOURCE=skills
edgeone makers deploy -n mali --json
```

部署返回的访问 URL 含鉴权查询参数，需要完整复制后在浏览器打开。长期公开访问建议在控制台绑定已备案的自定义域名。

## 自定义域名 xiangsu.0-w.cn 与 SSL 证书

> 线上项目名为 `mali`。EdgeOne CLI 与 WorkBuddy 的 EdgeOne 连接器只提供部署能力（init / dev / link / deploy / create），**没有域名绑定或证书管理命令**；DNS 解析权也在域名服务商侧，因此下面两步需要在控制台与域名商处完成。绑定后前端无需重新部署。

### 1. 控制台添加域名并申请免费证书

1. 打开中国站控制台 `https://console.cloud.tencent.com/edgeone/pages?tab=projects`，进入项目 `mali`。
2. 「项目设置」→「域名管理」→「添加自定义域名」，填入 `xiangsu.0-w.cn`。
3. 勾选「自动生成免费证书」（EdgeOne 自动申请、自动续签、自动部署）；如果已有证书，改选「SSL 托管证书」。
4. 记下页面给出的**主机记录**与**记录值**（CNAME 目标，形如 `*.pages.dnsoe6.com`），下一步要用。

### 2. 修改 DNS

当前诊断（2026-11-13）：

| 记录 | 现状 | 需要处理 |
| --- | --- | --- |
| `xiangsu.0-w.cn` | A `110.41.144.220`、AAAA `2407:c080:7ef:ffff::6e29:90dc` | 删除这两条，否则 CNAME 不会生效、域名验证会失败 |
| `0-w.cn` | 已 CNAME 到 `0-w.cn.pages.dnsoe6.com` | 保持不动，说明该域此前已接入过 EdgeOne Pages |

在域名解析控制台添加：

```
类型：CNAME
主机记录：xiangsu
记录值：以控制台第 1 步显示的值为准
```

域名托管在腾讯云 DNSPod 时可在控制台「一键添加 CNAME 解析」；否则到你的域名服务商手动添加，等待解析生效。

### 3. 验证与证书部署

回到域名管理点击「验证」→ DNS 验证通过后等待证书部署完成（通常几分钟），之后即可通过 `https://xiangsu.0-w.cn/` 访问。

```bash
nslookup xiangsu.0-w.cn          # 应返回 CNAME 而不是 A/AAAA
curl -I https://xiangsu.0-w.cn/  # 应返回 200，且证书有效
```

### 文件验证（已完成）

证书颁发机构要求通过 `http://xiangsu.0-w.cn/.well-known/pki-validation/fileauth.txt` 读取校验串。该文件放在项目根目录 `.well-known/pki-validation/fileauth.txt`，随站点一起部署，**必须部署到生产环境**（`edgeone pages deploy . -n mali -e production`）才会被自定义域名读到；仅预览部署不会更新域名内容。

返回内容为 64 字节纯文本，与 CA 提供的 `fileauth.txt` 逐字节一致：

```
202611141349125f7qfh911x8hi0mftr7y4o7bv0vjyt1u3kzu2vi3plo5lfy0j7
```

证书续签时 CA 可能再次校验，**请勿删除该目录**；CA 换发新校验串时直接覆盖同名文件并重新生产部署即可。

排错要点：若域名返回的仍是旧校验串或新路径 404，通常是「域名还指向旧部署」或「边缘缓存未过期」。前者等 2-5 分钟收敛，后者在控制台做一次缓存刷新（路径 `/.well-known/pki-validation/fileauth.txt`）即可。

### 备案提示

本项目部署在中国站（region: china）。若加速区域包含中国大陆，`.cn` 域名必须已完成 ICP 备案；未备案时请选择「不含中国大陆」的加速区域，或先完成备案再绑定。

## 部署到 Cloudflare Pages

两种方式，都是零构建：

- **Git 连接**：把本目录推到仓库，CF Pages 里 Framework preset 选 None，Build command 留空，Build output directory 填 `/`（或把文件放在仓库根目录），直接部署。
- **Wrangler CLI**：

```bash
npx wrangler pages deploy . --project-name mali
```

`_headers` 已为 `levels/*.json` 配置 `Access-Control-Allow-Origin: *` 与缓存头，方便把同源关卡分片给其他域名的前端复用（例如另一台服务器上的游戏壳）。若不跨域，可以删掉这个文件。

## 扩展与二次开发

- 改关卡数值/长度：`tools/gen-levels.mjs` 顶部的 `PACKS` 与 `LEVELS`（只列 8 张主关），重新运行会自动派生 16 张隐藏关并重建全部分片与 `js/bundled.js`；`SECRET_THEME` / `DEEP_THEME` 控制两层隐藏关主题，`HARDCORE` 数组控制绝境地形池。
- 新增主题：`js/art.js` 的 `THEMES` 加一套调色板，`js/audio.js` 的 `SONGS` 加一段原创循环，生成器里引用新主题名。
- 新增机制：`js/engine.js` 的 `ENTITY` 表与 `World.update*`；`W` 隐径门在 `Level` / `checkTriggers` / `Art.warp` 与编辑器字符表里保持一致。
- 视觉与音效全部是代码生成，替换风格不需要任何美术资源。
