Ludo Atlas · 引擎轨道 · Web 游戏（浏览器路线）¶
引擎轨道。定位：以浏览器为运行时的游戏开发路线，核心承诺是「发一条链接就能玩」，把分发与安装成本压到接近零。 配套：《全平台上架手册》·《技术实现手册》·《美术与音频手册》·《小游戏手册》。
1. 定位与选型¶
一句话定位：Web 游戏是以链接为分发单位的路线。玩家点开即玩，不用安装，你也不用排队等商店审核；代价是性能上限、内存与设备差异都由浏览器和用户设备说了算。
适用与不适用的边界：
| 维度 | 适合 | 不适合 |
|---|---|---|
| 项目形态 | 短会话玩法、休闲与解谜、原型与试玩版、3D 展示、教学演示 | 大包体重度 3D、依赖长期沉浸的大型作品 |
| 商业形态 | 传播与试玩转化、页面内嵌产品、广告变现、作品集 | 依赖商店曝光与买断付费为主的场景 |
| 技术预期 | 2D 与轻量 3D；接受「中端手机达标」而非「画质上限」 | 对帧率与画质有硬承诺的竞技与写实项目 |
三类工具的分野是选型的第一层判断：
| 类别 | 代表 | 本质 | 适合 | 不适合 |
|---|---|---|---|---|
| 游戏框架 | Phaser | 开箱即用的 2D 游戏框架：场景、精灵、物理、输入、音频齐备 | 完整 2D 小游戏、Game Jam、快速原型 | 需要深度自定义渲染管线 |
| 2D 渲染库 | PixiJS | 只解决高性能 2D 渲染，其余自己搭 | 自建游戏框架、界面密集的 2D 产品 | 想要现成的玩法与流程模块 |
| 3D 引擎 | Three.js / Babylon.js | 浏览器里的 3D 渲染与场景能力 | 3D 展示、轻量 3D 玩法、数据可视化 | 重度 3D 大世界与影视级管线 |
Three.js 与 Babylon.js 的取向差异：前者更接近「渲染库」，自由度高、生态大，管线自己拼装；后者更接近「成套引擎」，模块与工具齐全，起步少装配。按团队习惯选一个，不要两个同时学。
选型判断顺序：先问要不要 3D，要就进 3D 引擎；不要则再问要不要现成玩法模块，要就选游戏框架，不要就选渲染库。另外注意：Godot、Unity 等原生引擎也能导出浏览器构建，但那属于「已有项目顺带出 Web 版」的路线；Web 优先的新项目从 Web 系工具起步，包体与兼容包袱更小。
2. 生态与工程结构¶
Web 游戏本质上是一页前端应用，工程链与前端同源。其中三件事必须做对：
- 包管理与版本锁定：npm 起步；提交锁文件，团队与构建机用同一个 Node 版本，避免「我这能跑」。
- 打包器：开发态用带热更新的本地服务器（Vite 起步），生产构建产出静态文件。开发态与构建态行为可能不同，构建产物必须单独验证。
- TypeScript 强烈建议：玩法状态、资源键、事件名写错在编译期就拦下；纯 JS 起步、中期再迁移的成本很高。
目录布局按「入口、场景、系统、实体、界面、资源」分开，规模变大也稳：
src/
├── main.ts # 入口：初始化与装配
├── scenes/ # 场景与状态：标题、关卡、结算
├── systems/ # 输入、音频、存档、资源加载
├── entities/ # 游戏对象，按领域命名而非文件类型
├── ui/ # 界面与 HUD
└── assets/ # 资源与资源清单
两条纪律：资源引用集中登记在清单文件里，加载与释放都以清单为单位核对；每加一个依赖先问它为包体加了什么，前端依赖树失控是 Web 路线独有的常见事故。
3. 核心工作流¶
开发循环：本地服务器热更新，浏览器 DevTools 调试，真机验证（手机连同一网络直接打开开发地址），回到桌面继续迭代。真机验证前置到第一天，别等发布才第一次看到手机上的样子。
构建与部署：打包器把入口、脚本与资源整合成静态产物；部署前在真实目标路径下验证（子目录部署、大小写敏感、缓存命中），并按「老用户能拿到新版本」的标准验收一次更新。
发布渠道：
| 渠道 | 做法 | 适合 | 注意 |
|---|---|---|---|
| itch.io Web | 上传含入口页的压缩包，平台托管并嵌在项目页里运行 | 独立游戏、Game Jam、试玩版 | 嵌入运行下的全屏、鼠标锁定与音频解锁行为要逐项验证 |
| 自托管 | 静态托管平台或自有服务器部署构建产物 | 自有品牌、长期运营、内嵌产品 | 配置加密访问与压缩；规划缓存与版本更新策略 |
| 作为试玩版 | 正式版上架商店，Web 版只放开头一段 | 商店页获客、愿望单转化 | 主动控制内容量与性能预期，别让试玩版替正式版背差评 |
| 小游戏平台 | 微信、抖音等平台分发（国内） | 国内渠道与买量投放 | 与纯 Web 是两套工程约束，见《小游戏手册》 |
发布前检查清单：
- 首屏从打开到「可玩」的秒数，以及弱网与移动网络下的实际表现。
- 触摸全流程能走通，虚拟按键在主流机型上不错位。
- 音频在首次用户手势后正常出声，静音开关有效。
- 切后台再回来：画面恢复、计时不错乱、音频重连。
- 分享出去的标题、描述与分享图正确。
4. 关键系统惯用法¶
4.1 游戏循环与时间步¶
- 渲染挂在浏览器的逐帧回调上，逻辑与渲染分层；一切速度按「每秒」定义，运动乘时间差，禁止「每帧固定像素」。
- 物理与需要一致性的逻辑跑固定步长（常见 60Hz）：把真实时间切成固定片再更新，渲染侧做插值。这样普通屏、高刷屏与降频后的低端机行为一致。
- 屏幕刷新率不是常数，后台节流与设备降频都会改变它。调试时把帧率与时间步显示在屏幕上，别靠感觉。
4.2 输入与触摸¶
- 物理输入与逻辑动作分离：键盘、鼠标、触摸映射到同一套动作名，改键与多设备都不用动玩法代码。
- 触摸统一走指针事件（Pointer Events），一套事件路径覆盖鼠标、手指与触控笔。
- 触摸布局按屏幕比例定位，命中区域不低于常规下限（约 44-48 像素）；设计时允许多指同时按，移动与跳跃经常要一起按。
- 屏蔽浏览器默认手势（页面滚动、双击缩放、长按选择）；移动端地址栏伸缩会改变可视高度，布局按动态视口与安全区适配。
- 手机浏览器也可能外接键鼠或手柄，输入层别写死单一设备。
4.3 资源加载与生命周期¶
- 加载器与进度反馈是标配：首屏只加载「能玩起来」的最小集，其余按关卡或场景分包懒加载。
- 纹理走图集；资源句柄集中管理，遵循 §2 的清单纪律。
- 释放纪律：纹理、渲染目标等 GPU 资源不受浏览器垃圾回收管理，不用了必须显式销毁；场景切换时逐项核对清单。
4.4 音频与自动播放限制¶
- 浏览器默认阻止无用户交互的音频播放：音频初始化与解锁要绑在一次真实用户手势上，标题界面的「开始」按钮是最常见的位置。
- 页面切到后台，音频与计时会被暂停或节流；回到前台要恢复状态并重新对时。
- 移动端同时发声数与解码内存有上限：控制音频数量与体积，长音频流式加载，并提供总音量与静音开关。
4.5 存档与状态¶
- 小数据（设置、进度指针）用本地键值存储，结构化数据用 IndexedDB；隐私模式下可能受限，要有降级与提示。
- 存档存状态与版本号，不存对象引用；结构变化时写迁移逻辑，并支持导出与导入。
- 刷新页面等于冷启动：关键进度别只留在内存里。
5. 性能与优化要点¶
目标与测量：中端手机稳定 60 帧是常用底线；达不到就锁 30 帧求稳定，别在中间帧率抖动。用浏览器 DevTools 的性能与内存面板看帧时间与分配曲线；结论以真机为准，桌面浏览器数据会骗人。
渲染：
- draw call 是主线：图集与合批、减少纹理与材质切换、静态文本缓存（文本绘制很贵）。
- 分辨率控制：渲染分辨率等于布局尺寸乘设备像素比（DPR）；高分屏直接乘满会让像素量翻几倍。常见做法是给 DPR 封顶（如不超过 2）或按性能档动态缩放。
- Overdraw：大面积半透明与高密度粒子在移动端代价高，控制叠加层数。
内存：
- 纹理是最大头：大图常驻、未释放的场景纹理、频繁创建销毁的画布与渲染目标都是事故源。
- JS 侧泄漏三大来源：事件监听、定时器、闭包持引用；场景切换时注销与清理。
每帧分配与 GC：循环内不创建对象、数组、字符串与闭包；复用临时向量，子弹与特效走对象池。GC 停顿的表现就是周期性掉帧。
加载体积：首屏最小集、代码分包、资源压缩（服务端开启压缩）、图片用现代格式并限制尺寸、音频按需加载。「打开几十秒白屏」是硬伤，直接杀留存。
移动端专项：持续满帧耗电发热快，菜单与静止场景主动降帧；WebGL 上下文可能被系统回收或驱动重置，要有重建资源并恢复的逻辑；设备分档，低端机自动降画质。
6. 学习路线¶
| 阶段 | 内容 | 过关标准 |
|---|---|---|
| 1. 语言与浏览器基础 | JavaScript 与 TypeScript、DOM 与事件、DevTools 调试 | 能独立定位一个报错与一处掉帧 |
| 2. 第一个框架作品 | 用 Phaser 做一个完整小游戏：开始、游玩、结算、重开 | 发布到 itch.io，任何人点链接可玩 |
| 3. 工程化 | npm、打包器、TypeScript 全量、资源清单、构建与部署 | 一条命令产出可部署产物，手机可玩 |
| 4. 渲染进阶 | 按目标补 PixiJS（自建框架）或 Three.js / Babylon.js（3D） | 能说清自己项目的 draw call 构成与瓶颈 |
| 5. 性能与真机 | 真机矩阵、内存与加载优化、移动专项 | 中端手机稳定达标，切后台回来不崩 |
学习纪律：
- 官方文档与官方示例优先，教程只看一个来源，拒绝跳岛。
- 一个阶段只主攻一个工具；同时开三个库等于三个都不熟。
- 每个阶段都产出一个「别人能点开」的链接，没有发布的练习不算过关。
- 拆竞品时重点看加载时间与移动端表现，那才是 Web 路线的胜负手。
7. 常见坑¶
- 贴图与 GPU 资源泄漏：场景切换只丢引用不销毁纹理，GPU 内存只涨不跌，玩几关后卡死。释放以资源清单为单位逐项核对（§4.3）。
- 高分屏适配不做限制：设备像素比直接乘进渲染分辨率，移动端像素量翻数倍，掉帧发热一起来。把 DPR 封顶或按性能档动态缩放（§5）。
- 首屏加载体积失控：全部资源塞进首包，几十秒白屏。首屏最小集、按需分包、开启压缩（§5）。
- 每帧分配临时对象：循环里随手创建对象与闭包，GC 周期性停顿。复用与对象池（§5）。
- 音频没解锁就播放：首次进游戏没声音，玩家以为游戏坏了。把解锁绑在用户手势上（§4.4）。
- 按固定帧率写逻辑：每帧固定步长在高刷屏与低端机上行为不一致。时间差驱动加固定步长物理（§4.1）。
- 忽视后台切换：标签页切走再回来，时间跳变导致穿模、计时爆炸。处理页面可见性变化并对时间做钳制。
- 触摸手势冲突：页面滚动、双击缩放、长按选择抢走输入；虚拟按键命中区太小点不中。两者都要专项设计（§4.2）。
- 只测桌面浏览器：桌面 Chrome 上一切正常，iOS 与各安卓机型上音频、全屏、内存与渲染表现全变样。真机矩阵必须进流程。
- 依赖失控：一个单页游戏拖进整套前端框架与几十个依赖，包体与升级成本双爆炸。依赖最小化、版本锁定（§2）。
- 全程满帧跑：菜单与静止画面也满帧渲染，移动端掉电发热、体验崩坏。降帧与画质档位（§5）。
- 部署路径与缓存问题：子目录部署路径写死失效、大小写敏感踩坑、更新后老用户拿不到新版本。构建产物在真实部署路径下验收（§3）。