| 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。中间走了很多弯路,下面的每一条都对应一次真实的返工。
核心判断只有一个:这类项目失败的原因几乎从来不是代码写不出来,而是没人看过画面、没人听过声音、没人真的按过键。 所以整份流程的重心是"怎么让每一步都被验证"和"哪些东西不要自己从零写"。
开工前必须和用户对齐的四件事
- 参考物。让用户给参考视频或游戏,并且自己认真看、逐条拆解(镜头、技能节奏、界面风格)。没有参考就做出来的第一版,用户的评价通常是"和参考有半毛钱关系吗"。
- 视角和玩法范围。斜俯视角比第三人称省非常多的工作量,画面也更容易显得精致。范围建议:一个场景、一段小怪战、一个 Boss。
- 可用的生成工具和积分。问清楚有哪些命令行工具可用(3D 模型、图片、配音、配乐),每次花费多少。用户主动提供工具时立刻接上,不要坚持自己用几何体拼。
- 先调研再动手。用户说"先调研"是认真的。把调研结论和分阶段计划写成文档,让用户确认后再开工。
阶段顺序(每阶段结束都要让用户看到东西)
| 阶段 | 产出 | 验收方式 |
|---|---|---|
| 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。图片便宜,可以多出几张挑。
每一步都要真的看。 写完着色器、动作、特效之后,在浏览器里载入、截图、放大看。不要因为"语法检查过了"就汇报完成。具体方法见下一节。
花钱前报价,花完报数。 生成工具通常有报价命令。视频类模型比图片、配音贵一到两个数量级,同一个目标优先找便宜的专用模型(例如配音不要走视频模型)。
用户的反馈要按原话逐条落实,然后再查资料。 用户说"特效很僵""打击感差"时,不要凭感觉调参数,去查这个领域的常规做法,把结论写进调研文档再改。
怎么自己验证(没有人盯着屏幕的时候)
浏览器标签页隐藏时不会跑动画帧,所以需要一套不依赖实时渲染的调试钩子。项目一开始就加上:
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 显示调试面板再截图)。一次有效的截图比十轮猜测有用。
- 报出这一轮花掉的积分。
这类项目最常见的七个翻车点
- 第一版自己用几何体和合成音拼,被整体推翻重做。
- 角色动作靠猜关节角度,姿势扭曲。应该指定手脚目标位置,用两段骨骼解算。
- 特效是"一张贴图盖在面片上"。应该用贴合运动轨迹的网格、滚动噪声、随时间侵蚀。
- 玩家和怪"各打各的"。缺攻击吸附、双方顿帧、受击分级、身体碰撞。
- 泛光下特效过曝成白块。高动态颜色峰值控制在 2 到 3。
- 为了修一个按键问题加的"保险"反而造成新的按键问题。输入处理只做最少的事。
- 交付前才发现依赖外网、体积上百兆。打包脚本要在中期就建好。
