--- name: guizang-game-skill license: AGPL-3.0 description: 用 AI 生成素材(Tripo 等 3D 模型、即梦等图片与配音、Suno 等配乐)加 three.js,做一个能在浏览器里跑、最后打包成单个 HTML 的 3D 动作游戏的完整流程和踩坑清单。只要用户想做网页 3D 游戏、WebGL 游戏、three.js 游戏、俯视角或魂类动作游戏、带 Boss 战的 demo,或者提到"打击感""技能特效""掉落物""单文件分发""用 AI 生成模型做游戏",哪怕没说"用这个 skill",都应该先读它再动手。Build a polished browser 3D action game (three.js / WebGL, isometric soulslike, boss fight) with AI-generated assets and ship it as one HTML file. --- # 网页 3D 动作游戏:从零到单文件 这份流程来自一次完整的实战:一个仙侠题材、斜俯视角、有小怪战和 Boss 战的网页动作游戏,最后打包成约 30MB 的单个 HTML。中间走了很多弯路,下面的每一条都对应一次真实的返工。 核心判断只有一个:**这类项目失败的原因几乎从来不是代码写不出来,而是没人看过画面、没人听过声音、没人真的按过键。** 所以整份流程的重心是"怎么让每一步都被验证"和"哪些东西不要自己从零写"。 ## 开工前必须和用户对齐的四件事 1. **参考物**。让用户给参考视频或游戏,并且自己认真看、逐条拆解(镜头、技能节奏、界面风格)。没有参考就做出来的第一版,用户的评价通常是"和参考有半毛钱关系吗"。 2. **视角和玩法范围**。斜俯视角比第三人称省非常多的工作量,画面也更容易显得精致。范围建议:一个场景、一段小怪战、一个 Boss。 3. **可用的生成工具和积分**。问清楚有哪些命令行工具可用(3D 模型、图片、配音、配乐),每次花费多少。**用户主动提供工具时立刻接上**,不要坚持自己用几何体拼。 4. **先调研再动手**。用户说"先调研"是认真的。把调研结论和分阶段计划写成文档,让用户确认后再开工。 ## 阶段顺序(每阶段结束都要让用户看到东西) | 阶段 | 产出 | 验收方式 | |---|---|---| | 0 调研与设定 | 调研文档、设定、分阶段计划 | 用户确认 | | 1 渲染底座 | 能看的空场景:HDR、雾、泛光、调色 | 截图给用户 | | 2 场景 | 地面、植被、道具摆放 | 截图,先过静态图再做动态 | | 3 角色与动作 | 模型、骨骼、招式 | 单独的展示页,近景截图 | | 4 战斗 | 可玩的战斗 | 用户试玩 | | 5 演出与 Boss | 过场、Boss 招式 | 用户试玩 | | 6 界面、音乐、语音 | 完整包装 | 用户试玩并听 | | 7 打磨与打包 | 单文件 | 用户双击打开 | 每个阶段结束把没解决的问题写进一个待办清单文件,并且**如实区分"验证过"和"只是不报错"**。 按需读这些参考文件: - `references/assets.md` — 生成 3D 模型、图片、配音、配乐的具体做法和省钱办法。开始做任何素材前读。 - `references/characters-animation.md` — 生成的角色模型怎么接、动作怎么做才不僵。做角色前读。 - `references/combat-feel.md` — 打击感、格挡弹反、怪物设计、镜头。做战斗前读。 - `references/vfx-ui-audio.md` — 技能特效、掉落物、界面、音量。做特效和界面前读。 - `references/pitfalls.md` — 按症状查的踩坑清单。遇到怪问题时先查这里。 - `references/packaging.md` — 压缩资源并打包成单个 HTML。配套 `scripts/build_single_html.mjs`。 可以直接拿去用的脚本: - `scripts/input.js` — 不怕丢失松键事件的键鼠输入,带 F3 调试面板。项目一开始就用它,别自己重写输入。 - `scripts/serve.mjs` — 本地静态服务器。 - `scripts/build_single_html.mjs` — 压缩资源并内嵌成单个 HTML 的打包脚本(按 `references/packaging.md` 改路径)。 ## 贯穿始终的工作方式 **能用现成的就不要自己写。** 模型用生成工具或免费素材库,贴图用 CC0 材质库,音效用 CC0 音效包,配乐让用户用音乐模型出。自己写的合成音效和几何体模型,用户一眼(一耳)就能认出来是凑合的。 **素材先出图再出模型。** 文字直接生成 3D 的质量明显差。稳定的做法是:图片模型出一张"单个物体、纯色背景、无特效"的设定图,再用图生 3D。图片便宜,可以多出几张挑。 **每一步都要真的看。** 写完着色器、动作、特效之后,在浏览器里载入、截图、放大看。不要因为"语法检查过了"就汇报完成。具体方法见下一节。 **花钱前报价,花完报数。** 生成工具通常有报价命令。视频类模型比图片、配音贵一到两个数量级,同一个目标优先找便宜的专用模型(例如配音不要走视频模型)。 **用户的反馈要按原话逐条落实,然后再查资料。** 用户说"特效很僵""打击感差"时,不要凭感觉调参数,去查这个领域的常规做法,把结论写进调研文档再改。 ## 怎么自己验证(没有人盯着屏幕的时候) 浏览器标签页隐藏时不会跑动画帧,所以需要一套不依赖实时渲染的调试钩子。项目一开始就加上: ```js G.step = (n = 60, dt = 1/60) => { for (let i = 0; i < n; i++) frame(0, dt); }; // 手动推进 n 帧(含渲染) G.upd = (n = 30, dt = 1/60) => { for (let i = 0; i < n; i++) updatePlayer(dt); }; // 只跑移动逻辑,快 G.press = (...codes) => codes.forEach(c => pressed.add(c)); // 模拟一次按键 G.keys, G.mouse, G.pl(), G.fx, G.spawn(kind, pos) // 暴露状态和生成器 ``` 再配几个网址参数:`?stage=court` 直接进某一关,`?auto` 跳过标题,`?god` 无敌,`?show=char` 打开单独的角色展示页。 用法:推进若干帧 → 读状态数值 → 截图 → 放大局部。几条经验: - **结论靠数值,截图只做辅助。** 截图偶尔是旧画面;状态数值不会骗人。 - **带渲染的 `G.step` 很慢**,一次调用别超过一千帧,大规模扫描(例如全图找卡点)用只跑逻辑的 `G.upd`。 - **自动测试默认静音**,否则用户会听到后台一直在响。测完把页面切回标题画面。 - **改完代码必须在浏览器里实际载入一次并看控制台**,语法检查不够(见 `references/pitfalls.md` 的"游戏打不开")。 ## 汇报的规矩 用户不看代码,只看你怎么说。每次汇报: - 先说结论:改了什么、现在是什么状态。 - 明确分开三类:实际看到或听到验证过的、只确认不报错的、没法验证需要用户试的。 - 找不到原因就直说找不到,并给用户一个抓现场的办法(例如按 F3 显示调试面板再截图)。一次有效的截图比十轮猜测有用。 - 报出这一轮花掉的积分。 ## 这类项目最常见的七个翻车点 1. 第一版自己用几何体和合成音拼,被整体推翻重做。 2. 角色动作靠猜关节角度,姿势扭曲。应该指定手脚目标位置,用两段骨骼解算。 3. 特效是"一张贴图盖在面片上"。应该用贴合运动轨迹的网格、滚动噪声、随时间侵蚀。 4. 玩家和怪"各打各的"。缺攻击吸附、双方顿帧、受击分级、身体碰撞。 5. 泛光下特效过曝成白块。高动态颜色峰值控制在 2 到 3。 6. 为了修一个按键问题加的"保险"反而造成新的按键问题。输入处理只做最少的事。 7. 交付前才发现依赖外网、体积上百兆。打包脚本要在中期就建好。