three-webgl-game

Three WebGL 游戏

概述

当插件需要使用默认的非 React 3D 路径时，请使用此技能。这不是通用的 WebGL 建议，而是一套针对浏览器 3D 开发的明确技术栈：

• three
• TypeScript
• Vite
• GLB 或 glTF 2.0 资源
• Three.js 加载器，例如 GLTFLoader、DRACOLoader 和 KTX2Loader
• 用于物理模拟的 Rapier JS
• 用于 GPU 和帧调试的 SpectorJS
• 用于 HUD、菜单和设置的 DOM 覆盖层

当项目需要直接控制场景、相机、渲染器和游戏循环时，请使用此技能。如果应用已基于 React 构建，请改用 ../react-three-fiber-game/SKILL.md。

适用场景

• 应用使用纯 TypeScript 或 Vite，而不是以 React 为核心
• 项目需要直接、命令式地控制渲染循环
• 用户明确要求使用 Three.js
• 运行时需要类似游戏引擎的场景、相机、加载器和物理控制能力

不适用场景

• 3D 场景位于现有 React 应用中
• 主要问题是已发布资源的优化，而不是运行时代码
• 用户明确选择了 Babylon.js 或 PlayCanvas

核心规则

1. 将模拟状态保存在 Three.js 对象之外。
   • 游戏规则、AI、任务状态、计时器和进度不应保存在网格或材质中。
2. 将渲染图视为适配层。
   • 场景图、相机、材质、加载器和后期处理都是构建在模拟状态之上的视图层职责。
3. 明确控制相机行为。
   • 环绕、跟随、追逐、轨道和第一人称等模式都需要各自独立的控制边界。
4. 除非表现效果绝对依赖 WebGL，否则不要将 UI 放入 WebGL。
   • 菜单、HUD、库存和设置默认应使用 DOM。
5. 默认使用 GLB 或 glTF 2.0 作为发布模型格式。
   • 不要围绕 DCC 原生格式构建运行时。
6. 如果游戏涉及有实际意义的 3D 物理或碰撞响应，请使用 Rapier，而不是临时编写碰撞代码。
7. 首个可玩视图应保持简洁。
   • 默认只显示一个紧凑的目标或状态区域，以及临时提示。
   • 长篇说明、背景故事和控制参考应折叠起来，按需显示。
   • 正常游玩时，不要用多个权重相同的卡片框住场景。

初始脚手架体验

对于探索、移动和角色控制原型，请从简洁的界面框架开始：

• 一个贴边显示的目标标记
• 一个临时的控制提示
• 一个可选的紧凑状态栏

只有在游戏循环确实需要时，才添加较大的 UI 面板。日志、任务记录、百科全书、地图和设置等界面应按需打开，而不是默认占据视口。

推荐结构

使用 ../../references/three-webgl-architecture.md 中的模块结构，并保持以下边界清晰：

• simulation/：规则、进度、状态和 AI
• render/app/：渲染器、场景、相机、尺寸调整和上下文生命周期
• render/loaders/：GLTF、Draco、KTX2、纹理和环境加载
• render/objects/：网格实例化与释放
• render/materials/：材质设置和着色器边界
• physics/：Rapier 世界、刚体、碰撞体和模拟桥接
• ui/：DOM 覆盖层和菜单
• diagnostics/：调试开关、性能探针和捕获钩子

适用场景示例

• 探索演示
• 轻量级 3D 战斗原型
• 载具或移动原型
• 带有游戏玩法的场景驱动型产品或世界展示
• 以材质、光照或后期处理为核心的体验
• 相机移动和深度可读性至关重要的 3D 游戏

加载器、资源和后期处理

• 对于随应用发布的 3D 内容，请从 GLTFLoader 开始。
• 将 DRACOLoader 或兼容 Meshopt 的优化纳入资源管线，而不是作为临时的运行时补丁。
• 如果资源管线提供压缩纹理，请使用 KTX2Loader。
• 优先使用 Three.js 内置的渲染和后期处理工具。只有在项目确实需要时，才添加更重型的抽象层。
• 让后期处理保持可选且效果可衡量。泛光和色彩效果不应影响游戏内容的可读性。

着色器和材质指南

• 使用自定义着色器前，先从标准 Three.js 材质和正确的光照入手。
• 只有在视觉目标确实需要时，才使用自定义着色器。
• 着色器参数应由游戏状态驱动，而不是由偶然的场景变更驱动。
• 如果材质堆栈变得复杂，请将其封装在材质工厂中，而不是把着色器配置分散到各处场景代码中。

浏览器安全性

• 明确处理尺寸调整。
• 做好应对 WebGL 上下文丢失和恢复的准备。
• 对脆弱的 GPU 路径，考虑提供回退或降级模式。
• 留意纹理尺寸、几何体数量、绘制调用增长情况以及后期处理开销。
• 如果场景表现异常或帧开销不明确，请使用 SpectorJS。

范围警告

不要声称此插件能提供与 Phaser 路线同等深度的 3D 支持。它支持严肃的 3D 实现，但整体上仍以 2D 为先。

参考资料

• 共享架构：../web-game-foundations/SKILL.md
• 前端方向：../game-ui-frontend/SKILL.md
• 3D HUD 布局模式：../../references/three-hud-layout-patterns.md
• Three.js 生态系统：../../references/threejs-stack.md
• Three.js 结构：../../references/three-webgl-architecture.md
• Vanilla 入门模板：../../references/threejs-vanilla-starter.md
• GLB 加载器入门模板：../../references/gltf-loading-starter.md
• Rapier 入门模板：../../references/rapier-integration-starter.md
• 3D 资源管线：../../references/web-3d-asset-pipeline.md
• WebGL 调试与性能：../../references/webgl-debugging-and-performance.md