---
id: web-3d-game
name: Web 3D Game
version: 1.0.0
description: |
  设计、实现并验证无需外部网络或安装依赖即可运行的浏览器 3D 游戏。
  当用户要求制作可玩的 WebGL 游戏、3D 关卡、交互式 3D Demo 或需要实际启动和游玩验收时使用。
tags:
  - WebGL
  - 3D 游戏
  - 浏览器
  - 交互原型
---

# 浏览器 3D 游戏

目标不是静态页面或“看起来像 3D”的插画，而是一个能启动、能操作、有明确目标和反馈、经过实际游玩验证的 3D 游戏。

## 开始前

1. 先检查工作区，不覆盖用户已有文件。若目录非空，创建独立子目录。
2. 若会话提供游戏设计、关卡或资产类 MCP 工具，必须先调用适用工具，并将其结果转化为实现约束。不得声称调用了未实际调用的工具。
3. 明确一个短小但完整的玩法循环：移动或跳跃、收集或躲避、达成目标、胜利或失败、重新开始。
4. 默认制作单人、离线、键盘可玩的游戏。除非用户明确要求，不加入账号、遥测、广告、远程资源或联网功能。

## 技术边界

- 默认使用原生 HTML、CSS、JavaScript 和 WebGL2。可以在项目内实现小型向量/矩阵辅助函数，但不得引用 CDN、远程字体、远程贴图或运行时网络请求。
- 不要求 `npm install`。若需要本地服务器，使用 Node.js 标准库编写 `server.mjs`，仅绑定 `127.0.0.1`，并限制在游戏目录内提供静态文件。
- WebGL2 不可用时显示可读错误，不得用空白画布静默失败。
- 使用透视投影、深度测试、可辨识的相机运动和至少一种明暗或雾效，确保场景是真实 3D 渲染，而不是 Canvas 2D 伪装。
- 游戏循环使用 `requestAnimationFrame`，限制异常大的 delta time；窗口尺寸和 device pixel ratio 变化时正确调整画布。
- 不读取工作区外文件，不执行下载脚本，不把密钥、环境变量或本机路径写入游戏。

## 最小项目结构

创建并说明下列文件。可按实际需要拆分更多本地模块，但所有引用必须留在项目目录：

- `index.html`：画布、HUD、开始/暂停/结束界面和键盘说明。
- `styles.css`：响应式布局、清晰焦点、可读对比度和状态反馈。
- `game.js`：渲染、输入、物理/碰撞、规则、音画反馈和测试接口。
- `server.mjs`：无依赖本地静态服务器，或在 README 中说明为何可直接打开。
- `README.md`：启动命令、URL、控制方式、目标、文件结构和已执行的验收。

## 可玩性要求

游戏至少包含：

- WASD 与方向键的等价移动；需要跳跃时支持 Space。
- 明确的玩家实体、地面/平台、边界和相机跟随。
- 至少一个有空间位置的目标集合，以及一个会改变游戏状态的障碍、计时或敌对机制。
- HUD 显示目标进度和当前状态。
- 收集、受击、解锁、胜利和失败中的适用反馈，可使用几何动画、颜色、屏幕提示和 Web Audio 合成音效。
- 开始、暂停/继续、胜利或失败后的重新开始路径。
- 页面失焦时清理按键状态，防止输入卡住。
- 不依赖刷新页面即可重开一局。

首次进入页面不得因为浏览器音频策略而报错。仅在用户首次交互后创建或恢复 AudioContext。

## 可测试接口

在不改变正常玩法的前提下公开一个只读为主的测试表面：

```js
window.__GOODBUDDY_GAME__ = {
  version: 1,
  getState() {
    return {
      status: 'ready',
      score: 0,
      target: 5,
      player: { x: 0, y: 0, z: 0 }
    }
  },
  setInput(action, active) {},
  reset() {}
}
```

- `status` 至少区分 `ready`、`playing`、`won` 和适用的 `lost`/`paused`。
- `getState()` 只返回有界、可序列化的游戏状态，不返回 WebGL 对象或隐私数据。
- `setInput()` 接受与真实按键相同的动作语义，用于自动化游玩，不得直接加分或跳过规则。
- `reset()` 与界面中的重开按钮走同一条状态重置路径。

## 实现顺序

1. 建立静态项目和启动方式，先确认页面可访问。
2. 完成着色器编译、网格、透视相机、深度测试和 resize。
3. 完成玩家控制、碰撞和相机跟随。
4. 加入目标、障碍和完整状态机。
5. 加入 HUD、开始/结束界面、视觉和音频反馈。
6. 加入测试接口和 README。
7. 启动本地服务器并实际游玩，不只检查源代码。

## 验收门禁

完成前必须验证：

1. 启动命令能从全新终端成功运行，且只监听 loopback。
2. 页面加载后没有 uncaught exception、着色器错误、404 或外部网络请求。
3. 真实键盘可以开始、移动、完成核心目标并触发胜利或失败。
4. 碰撞不会让玩家稳定穿过地面、边界或关键障碍。
5. HUD 进度与 `window.__GOODBUDDY_GAME__.getState()` 一致。
6. 使用 `setInput()` 也能通过同一玩法规则推进游戏，`reset()` 能恢复初始状态。
7. 至少测试一次 resize 和页面失焦后的输入恢复。
8. README 记录实际执行过的命令与结果，不把计划写成已验证事实。

若受当前环境限制无法启动浏览器或完成某项验证，明确列出未验证项和阻塞原因；不得将“文件已生成”表述为“游戏已可玩”。