threejs-game-generator-skill

Three.js 游戏生成器

将游戏简报或未完成的 Three.js 场景变成一款小巧完整的浏览器游戏。先打造一个令人满意、可玩的循环，创作原创方向，沿用用户现有的技术栈，并在真实浏览器中验证结果。

选择工作模式

• **新游戏：**创建符合需求且易于维护的最小项目。若尚无技术栈，默认使用 Three.js 和 Vite。
• **现有游戏：**保留包管理器、架构、路由、资源、控制方式和正常运行的系统。只修改实现所需结果所必需的部分。
• **场景转游戏：**保留有用的场景，然后添加明确的目标、玩家可执行的动作、反馈、失败或完成条件、重启和进度机制。
• **润色：**修改前先分析性能并试玩当前版本。按以下顺序修复反馈、摄像机、控制方式、节奏、性能和状态转换方面的问题。

除非用户明确要求，否则不要发布内容、购买资源、调用付费服务或修改外部系统。

确定游戏约定

如果简报不够明确，请推断缺失内容，但不要擅自把原型扩展成大型成品。

实现前先简要明确以下约定：

1. **幻想体验：**玩家应感受到自己在做什么。
2. **核心循环：**可重复的动作、响应、奖励和升级。
3. **胜利、失败或完成：**一局如何结束，玩家如何重新开始。
4. **摄像机和控制方式：**视角、移动模式、输入设备和触屏行为。
5. **视觉主旨：**一种与游戏机制相关、易于识别的美术方向。
6. **范围：**能够体现核心循环的最小内容集，以及明确暂缓的功能。

当用户提及现有作品名称时，只借鉴高层次的交互理念。角色、环境、布局、UI、名称、音频和美术均须原创。

按需阅读参考资料

• 设置或修改游戏循环、渲染器、控制方式、摄像机、碰撞、加载、持久化、对象生命周期或性能时，阅读 engine-patterns.md。
• 选择灯光、材质、程序化几何体、资源风格、氛围、UI 样式、阴影或质量等级时，阅读 visuals.md。
• 游戏需要音乐、反馈音效、空间音频、用户手势激活或混音时，阅读 audio-recipes.md。
• 简报需要可行的机制组合、摄像机与控制映射、内容预算或类型专项风险检查时，阅读 genres.md。

不要默认加载所有参考资料。

工作流程

1. 检查工作区

确认以下内容：

• 包管理器、脚本、入口、Three.js 版本、附加组件和构建工具；
• 当前场景图、渲染器、摄像机、输入、状态管理、物理、资源、UI 和音频；
• 生产构建命令及现有测试；
• 必须保留的本地修改。

尽可能运行当前项目。编辑前记录可见故障和浏览器控制台错误。不要仅仅为了使用偏好的脚手架而替换正常运行的项目。

2. 验证垂直切片

先构建最小完整循环，再扩展内容：

• 一个可操控的玩家角色或主要交互；
• 一个目标和一个有意义的障碍；
• 针对成功、受伤、收集或进度的可见反馈；
• 开始、进行中、暂停、完成／失败和重启状态；
• 一段 30–180 秒、能够体现预期体验的游戏过程。

在比例、移动、摄像机和节奏正常之前，使用灰盒几何体。没有可完成循环的精美场景，不算游戏。

3. 打好稳定的基础

参照 engine-patterns.md 中的项目模式。保持以下不变量：

• 使用一个渲染器和一个权威动画循环；
• 移动不受帧率影响，并限制时间增量；或在需要确定性时使用固定模拟步长；
• 使用明确的游戏状态，而不是零散的布尔值；
• 将输入采样为动作，让键盘、指针、游戏手柄和触控共用游戏逻辑；
• 一次性确定世界单位和坐标约定，并始终保持一致；
• 限制设备像素比，并实现可同时更新渲染器和摄像机的尺寸调整流程；
• 重复使用几何体和材质，并有计划地释放 GPU 资源；
• 除非必须进行 3D 放置，否则使用 HTML UI 展示易读的菜单、设置和 HUD；
• 加载资源时提供进度和失败状态；
• 不在客户端代码中存放机密信息。

只有在机制确实需要刚体模拟时，才添加物理引擎。对于街机式移动，如果简单的球体、立方体、胶囊体、射线检测或空间分区已经够用，就使用这些方案。

4. 打磨游戏手感

协同调整输入、移动、摄像机和反馈：

• 控制应即时响应，并且在低帧率和高帧率下都保持可预测；
• 摄像机跟随应采用阻尼和有限的前视效果，而不是直接跟随玩家变换；
• 碰撞应带来清晰可辨的结果，而不是悄无声息地阻挡；
• 根据游戏类型，为动作设计合适的预备、冲击和恢复阶段；
• 屏幕震动、受击停顿、粒子、拖尾和后期处理应适度，并能在开启减少动态效果或降低画质时正常禁用；
• 触控目标和虚拟控件必须适应实际视口，且不能遮挡关键游戏区域。

只有在核心循环玩起来令人愉快后，才添加次要系统。

5. 为一个世界确定美术方向

阅读 visuals.md。定义一套精简的调色板、光照模型、形状语言、材质系列和氛围。优先打造连贯、低复杂度的世界，而不是混搭互不相关的高细节资源。

确保颜色纹理使用正确的色彩空间，限制开销大的阴影，避免逐帧分配内存，并在降低游戏清晰度之前先降低像素比或减少特效。为所有外部资源注明来源并记录其许可证。

6. 按需添加音频和持久化功能

如果项目包含音频，请阅读 audio-recipes.md。只有在用户手势触发后才启动音频，提供静音和音量控制，并确保关键反馈在无声时仍然易于理解。

只持久化有用的状态，例如设置、最高分、已解锁关卡或检查点。为存储的数据添加版本信息，并在数据缺失或无效时安全恢复。

7. 验证实际游戏

先运行生产构建并修复所有错误，然后在浏览器中测试构建版本或开发版本。

检查：

• 开始 → 游玩 → 暂停／继续 → 胜利／失败 → 重新开始的流程无需重新加载即可正常运行；
• 所有已说明的控制方式均可使用，包括承诺支持的触控操作；
• 调整窗口大小、改变屏幕方向、切到后台或失去焦点都不会导致状态损坏；
• 浏览器控制台没有未捕获的错误或缺失的资源；
• UI 易于阅读，并支持键盘操作；
• 音频启动和静音行为正确；
• 存档数据在重新加载后仍然保留，无效存档不会导致崩溃；
• 最繁忙的场景在目标设备类别上仍能保持响应；
• 减少动态效果和低画质模式会移除开销大的特效，但不会隐藏必要反馈。

至少完整游玩一局。仅自动构建成功并不足够。

质量标准

• 陌生人无需阅读源代码，就能理解游戏目标和控制方式。
• 玩家很快就能进行首次有意义的互动。
• 游戏具有完整的循环和重新开始流程，而不只是一个场景或技术演示。
• 摄像机、移动、碰撞和反馈如同一个整体般协调。
• 美术方向鲜明且富有原创性。
• 性能会逐步下降，而不是突然变得无法游玩。
• 项目结构清晰易懂，便于扩展。

避免

• 重现受版权保护的角色、关卡、UI、音乐或品牌素材；
• 尚未证明有必要，就安装庞大的引擎或物理系统；
• 用单个文件囊括渲染、输入、状态、UI、音频和所有实体；
• 将移动直接绑定到帧数；
• 在热循环中分配向量、材质、几何体或加载器；
• 不受限制地使用粒子、光源、阴影投射物或设备像素比；
• 启用指针锁定却不提供退出方式，或提供触控控制却没有桌面端备用方案；
• 用空白画布掩盖加载失败、WebGL 不受支持或凭据缺失等问题；
• 围绕尚未完成的机制，制作精致的标题画面。

交接

首先说明如何运行游戏。然后报告：

• 已实现的核心循环和控制映射；
• 构建和试玩命令及其结果；
• 素材来源和许可证；
• 浏览器/设备限制；
• 有意排除在范围之外、推迟实现的功能。