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. 先调研再动手。用户说"先调研"是认真的。把调研结论和分阶段计划写成文档，让用户确认后再开工。

阶段顺序（每阶段结束都要让用户看到东西）

每个阶段结束把没解决的问题写进一个待办清单文件，并且如实区分"验证过"和"只是不报错"。

按需读这些参考文件：

• 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 显示调试面板再截图）。一次有效的截图比十轮猜测有用。
• 报出这一轮花掉的积分。

这类项目最常见的七个翻车点

1. 第一版自己用几何体和合成音拼，被整体推翻重做。
2. 角色动作靠猜关节角度，姿势扭曲。应该指定手脚目标位置，用两段骨骼解算。
3. 特效是"一张贴图盖在面片上"。应该用贴合运动轨迹的网格、滚动噪声、随时间侵蚀。
4. 玩家和怪"各打各的"。缺攻击吸附、双方顿帧、受击分级、身体碰撞。
5. 泛光下特效过曝成白块。高动态颜色峰值控制在 2 到 3。
6. 为了修一个按键问题加的"保险"反而造成新的按键问题。输入处理只做最少的事。
7. 交付前才发现依赖外网、体积上百兆。打包脚本要在中期就建好。

歸藏 Game Skill

让 AI 从零做出一个能在浏览器里玩的 3D 动作游戏

English · 简体中文

上面这段是演示游戏《雾锁山门》里的实机画面。点这里直接玩，电脑和手机都能打开，不用安装。

这是什么

一个给 AI 编程助手（Claude Code、Codex 等）用的 Skill。装上之后，对它说"做一个武侠题材的俯视角 3D 动作游戏"，它会按一套走通过的流程去做：先问清楚你要什么，接上你手头的素材生成工具，自己推进画面、自己截图核对，最后把游戏打包成一个网页文件。

Skill 里写的不是理论，是我用 Fable 5.2 花一个下午做出《雾锁山门》的过程中踩过的坑，和最后留下来的做法。那次大约 6 小时、4.5 亿 Token（其中一部分是 Opus 5.5 跑的测试），很多都花在了返工和试错上。这个 Skill 的目的就是让你和你的 AI 少走这些弯路。

演示游戏：雾锁山门

一个仙侠题材的俯视角 3D 动作游戏：一个场景、一段小怪遭遇战、一场 Boss 战，有剧情和配音。所有创意都是 AI 自己定的，我只说了要做国风仙侠。

• 画面：大片随风起伏的草，分层的雾、雪和远山，覆水石台上的反光。渲染流程是在 three.js 上自己搭的，只用兼容性最好的 WebGL，所以手机、电脑、小程序类容器里都能跑
• 角色与场景：5 个带骨骼的 3D 角色、2 把武器、12 种场景道具、5 种掉落物。先用即梦出设定图，再用 Tripo 转成模型，提示词都是 AI 自己写的
• 战斗：三段连招、闪避、格挡、弹反、处决，还有饮药、御剑和大招"万剑归宗"。Boss 有二阶段、起身过场和台词
• 声音：8 条配音、配乐、环境音和音效
• 体积：原始素材将近 100MB，打包后是一个约 33MB 的 HTML，里面包含全部模型、贴图、音乐和配音

演示的三种形态，都是同一份源码打出来的：

这个 Skill 帮你做什么

直接让 AI"做个 3D 游戏"，通常会得到一个方块灰模、手感发飘、要自己搭环境才能跑的东西。装上这个 Skill 之后：

1. 开工前先问清楚。参考、视角、氛围、范围，以及你手头有哪些素材工具和多少额度。它不会闷头写一个方块模型出来，上来就把你给的工具接上
2. 自己验证，不用你反复试。第一天就装好自测工具：逐帧推进画面、直达某一关的网址参数、F3 诊断面板。它自己截图核对，再告诉你哪些看过、哪些只是没报错
3. 战斗手感有章可循。出招前摇和后摇、命中顿帧、分级击退、格挡与弹反、敌人轮流进攻而不是一拥而上、闪避能打断动作。打击感从哪来，都写进去了
4. 一份踩坑清单。方向键卡住、预设动画把角色甩离原地、泛光过曝、镜头被屋顶挡住、打包后角色缩小一半……每条都有症状、原因和做法
5. 三种打包方式。把很大的模型和素材压到很小：单个 HTML、先出画面再加载的静态站点、受限容器的离线包

安装

把这个仓库的链接发给你的 AI，让它安装即可。或者手动：

git clone https://github.com/op7418/guizang-game-skill ~/.claude/skills/guizang-game-skill

Codex 等其它工具，克隆到它们各自的 skills 目录。

然后直接说需求，比如：

做一个武侠题材的俯视角网页 3D 动作游戏，一个场景、一波小怪、一个 Boss。
我有 Tripo 和即梦可以用。

需要准备

素材工具对最终效果影响很大。我一开始让它直接用文字生成模型，质量很差；改成"先出设定图，再转 3D"之后上了一个大档次。

流程

调研与规划 → 设定与素材 → 动作 → 手感与特效 → 声音与打包

1. 调研与规划：读参考、查这类游戏的做法，写调研文档和分阶段计划
2. 设定与素材：世界观、角色设定图、图转 3D、骨骼绑定
3. 动作：平台给的预设动作不多，其余用程序算出每个姿势里手脚的位置
4. 手感与特效：按战斗手感清单逐项做，特效走"网格 + 着色器"而不是堆粒子
5. 声音与打包：音效、配音、配乐，然后压缩并打成单文件

目录

先说清楚的事

• 它不是一句话出成品。《雾锁山门》我试玩了 7 轮，每轮提 5 到 10 个问题。我不懂做游戏，只会说"动作很僵硬""打击感很差"，AI 会把这些话翻译成专业做法去查、去改。你仍然需要来回试玩提意见
• 几件事我会坚持让 AI 做：给它参考视频；要求"先调研再动手"；别让它自己造轮子，把现成的素材工具接上
• Skill 目前只在一个项目上完整走过一遍，另做过一次计划层面的对照测试。它能让方向少走弯路，不保证成品质量

许可

• Skill 本身（本仓库 main 分支的文档与脚本）：AGPL-3.0
• 演示游戏《雾锁山门》的内容（美术、模型、配音、配乐、文案，位于 gh-pages 分支）：© 2026 歸藏，保留所有权利。欢迎试玩和分享链接，未经许可请勿转载、改名再发布或商用

作者

歸藏。觉得有用的话点个 Star，也欢迎把你做出来的游戏发给我看。