web-game-foundations

Web 游戏基础架构

概述

在开始实现之前，使用此技能确立不可妥协的架构。浏览器游戏若将模拟、渲染、UI、资源加载和输入处理混杂在一起，性能和可维护性会迅速退化。

默认规则：模拟状态由渲染器之外的模块负责；除非有明确理由，否则不要强行将浏览器 UI 放入画布；发布的 3D 资源默认采用 GLB 或 glTF 2.0，而不是临时拼凑的模型格式。

适用场景

• 用户尚未确定引擎或渲染器的选择
• 任务涉及模块边界、模块结构、状态归属或资源策略
• 多个专业技能需要共享同一套架构框架

不要停留在此处的场景

• 运行时路线明确采用 Phaser
• 运行时路线明确采用原生 Three.js
• 运行时路线明确采用 React Three Fiber
• 任务纯粹涉及已发布的 3D 资源

技术栈明确后，转交给运行时或资源专业技能。

架构规则

1. 将模拟与渲染分开。
   • 模拟负责实体、回合、计时器、碰撞、进度和可保存状态。
   • 渲染器负责场景组合、动画播放、摄像机、粒子和输入接线。
2. 明确输入映射。
   • 定义 move、confirm、cancel、ability-1 和 pause 等操作。
   • 在一个地方将物理输入映射到操作。
3. 将资源加载视为一等系统。
   • 使用稳定的清单键。
   • 按领域分组：角色、环境、UI、音频、特效。
   • 对于 3D 内容，统一使用 GLB 或 glTF 2.0，除非所选引擎生态系统要求在上游使用其他格式。
4. 提前划定存档、调试和性能边界。
   • 保存可序列化的模拟状态，而非渲染器对象。
   • 确保调试叠加层和性能探针易于切换。
5. 默认使用 DOM 叠加层呈现菜单和 HUD。
   • 使用画布或 WebGL 处理游戏区域。
   • 使用 DOM 处理文字较多的 HUD、菜单、设置和对无障碍要求较高的控件。
   • 在 3D 场景中，将常驻 UI 的预算控制在较小范围，确保场景清晰易读且可交互。
6. 尽早统一 3D 运行时约定。
   • 统一单位、原点、轴心点和命名约定。
   • 在开始运行时集成之前，决定如何创建碰撞代理、LOD 和烘焙光照数据。

引擎选择

• 对于使用精灵、瓦片地图、俯视或侧视动作、回合制网格以及经典浏览器街机流程的 2D 游戏，默认选择 Phaser。
• 对于需要直接控制场景、摄像机、渲染器和循环，且使用原生 TypeScript 或 Vite 的明确 3D 场景，默认选择原生 Three.js。
• 对于在 React 应用中运行，且需要声明式组合、共享应用状态或以 React 为先的 UI 协调的 3D 场景，默认选择 React Three Fiber。
• 仅在着色器密集型或以渲染器为先的项目中使用原始 WebGL，以免引擎抽象造成阻碍。
• 将 Babylon.js 和 PlayCanvas 作为备选引擎路线，而非默认代码生成目标。

请参阅 ../../references/engine-selection.md 中的默认决策表。

实现清单

编写核心代码前，先定义以下内容：

• 玩家幻想和主要操作
• 核心循环以及失败或重置状态
• 摄像机模型
• 输入操作映射表
• 模拟模块
• 渲染器模块
• 资源清单布局
• 3D 资源格式和优化规则
• HUD 和菜单界面
• 存档数据边界
• 调试和性能界面

反模式

• 将游戏规则直接混入场景回调
• 将渲染器视为游戏状态的唯一事实来源
• 默认将所有 HUD 和菜单 UI 都放进画布
• 让资源文件名取代清单键成为公开 API
• 将未经优化的 3D 资源直接从 DCC 工具发布到浏览器
• 在没有明确输入边界的情况下混合摄像机控制状态与菜单或模态框状态
• 每次游戏类型变化都重新构建架构

参考资料

• 引擎选择：../../references/engine-selection.md
• Phaser 结构：../../references/phaser-architecture.md
• Three.js 结构：../../references/three-webgl-architecture.md
• Three.js 生态系统技术栈：../../references/threejs-stack.md
• React Three Fiber 技术栈：../../references/react-three-fiber-stack.md
• 3D 资源交付：../../references/web-3d-asset-pipeline.md