Guide · Playable HTML · v6.7+

可玩 HTML 小游戏

在 AI 对话面板里说一句话玩法，Agent 就写出一整个纯 Node（esbuild）工程：几何、贴图、材质、音效、关卡全部由代码程序化生成，宿主在本机 cook 成单文件，点卡片上的「试玩」即在浏览器里开玩。适合玩法草案与素材打样，不替代 Unity / Godot。

1. 它是什么

从 v6.7 起，这条链路由对话面板驱动（图内不再有「可玩 HTML 生成 / 可玩 HTML」节点）：

步骤	谁做	产出
写需求	你在对话里说一句话玩法	一句话玩法（Agent 自己整理成工程需求）
落工程	工具 `gameplay_prepare_project`	`Cache/GamePlayJobs/…/project`（package.json / build.mjs / src/core / src/assets 骨架）
写代码	Agent 用它自己的文件工具改 `src/**`	程序化资产 + 玩法（几何 / Canvas 贴图 / 音效 / 关卡）
构建	工具 `gameplay_build`（宿主跑 npm）	`dist/single.html` 单文件
试玩	对话产物卡上的「试玩」	系统默认程序（浏览器）里开玩；同时自动登记一个 gamePlay 资产

需要已配置文本模型（推荐 DeepSeek；也可用其它兼容提供商）与本机 Node / npm（cook 用）。生成走对话面板里的 dsh Agent，npm 只由宿主执行，不要在工程目录里抢跑。

2. 在 AI 对话里怎么做

打开右侧 AI 对话面板（模式选 Craft），直接说玩法即可，例如：

低多边形太空站走廊里捡能量块，WASD 移动，鼠标转向，捡满 10 个过关；用 Three.js

Agent 会依次调用三个工具：

gameplay_prepare_project：落下脚手架（可指定 mode: 2d | 3d | auto 与游戏名）。
它自己写 src/assets/**（程序化资产）与 src/game/**（玩法）。
gameplay_build：宿主执行 npm install + node build.mjs，返回 jobId；用 gameplay_job_status 轮询到 done。

构建完成后对话流里出现一张游戏卡，卡上只有一个「试玩」按钮，点击直接用系统默认程序打开游戏。

2D 还是 3D 由你一句话里的意思决定；想稳定出 3D 就明确说「用 Three.js」。资产层约定（目录结构、defineAsset 契约、贴图与音效配方）写在内置技能 gameplay-proc-assets 里，Agent 会自己加载。

3. 资产全部由代码生成

这是这条路线的核心：不下载素材、不调用付费生成接口，一切都在生成的工程里合成——所以零额度、秒级出资产、同一种子可复现、风格天然自洽。

src/core/rng.js：种子随机（改一个字符即换一整套资产）。
src/core/palette.js：一套自洽配色，贴图 / 材质 / 灯光共用。
src/core/registry.js：defineAsset({ id, kind, build }) 注册表。
src/assets/geometry/：BufferGeometry 造形体（挤出 / 旋转 / 合并 / 实例化）。
src/assets/texture/：Canvas 2D 画贴图（条纹 / 噪点 / 渐变），返回可当 CanvasTexture 用的画布。
src/assets/audio/：WebAudio 合成音效（振荡器 + 滤波 + 包络）。
src/assets/level/：关卡布局由种子推导。

4. 生成 → 构建 → 试玩

生成：对话里说玩法；日志里能看到 Agent 反复改 src/**。选 3D 时脚手架会带 three 依赖与 3D 样例入口。
构建：gameplay_build 起手，对话里先出现一张「运行中」的工具卡；日志出现 npm install、node build.mjs、单文件体积即成功。构建成功后宿主还会自动跑一次试玩门禁——把游戏在隐藏窗口里真跑几秒，抓未捕获异常 / 加载失败 / 黑屏 / 画面静止，结论在 gameplay_job_status 的 smoke 字段；smoke.ok === false 时 Agent 会按报告再改一轮。
试玩：点游戏卡上的「试玩」——自包含的单文件用浏览器打开，能全屏、能开 DevTools；若产物不自包含（用了 ES 模块或相对引用），会自动退回应用内试玩窗口并说明原因。
资产库也能玩：构建成功会自动建一个 gamePlay 资产，在资产库里双击（或右键「试玩」）走应用内沙盒窗口。

5. 迭代与工程目录

接着说「再暗一点 / 加个跳跃音效 / 换个种子」即可：Agent 只改 src/assets/** 与 src/game/**，再 gameplay_build 一次。
同一个工程重复构建复用同一条作业与同一个资产，卡片原地更新——不会把对话和资产库刷成一串重复条目。
磁盘位置：工程根下 Cache/GamePlayJobs/<jobId>/project/，单文件在 dist/single.html。

6. 常见问题

构建报 npm / build 失败？

确认本机 PATH 有 Node.js / npm；用 gameplay_job_status 看日志尾部与 error。也可进 Cache/GamePlayJobs/…/project 手动 npm run build 对照。

点「试玩」没开浏览器 / 开出来是编辑器？

「试玩」用的是系统默认程序；若把 .html 关联到了编辑器，就会打开编辑器。这种情况改用资产库里的应用内试玩窗口即可。

游戏在浏览器里白屏，应用内却正常？

说明产物不是自包含的：file:// 下浏览器会拒绝执行 type="module" 脚本，也读不到相对的兄弟文件。让 Agent 保持 index.template.html 的内联经典脚本（别加 type="module"、别引相对文件）即可。

画面黑屏或着色器报错？

先看 gameplay_job_status 的 smoke：构建成功后宿主会自动在隐藏窗口里跑一次试玩门禁，未捕获异常 / 加载失败 / 整屏黑 / 一帧都没渲染都会写进 smoke.errors，画面几秒不动则进 smoke.warnings。把报告交给 Agent 让它再改一轮即可。

如果门禁是通过的、只是画面不理想：复杂自定义 WebGL（如 dFdx）对 WebGL1/2 扩展较敏感，可要求改用 Three 标准材质。这是原型链路，门禁只保证「跑得起来、画面在动」，不保证任意着色器都好看。

图里原来的「可玩 HTML 生成 / 可玩 HTML」节点呢？

已下线：游戏生成改为对话驱动。旧工程里的生成节点会迁成备注节点（保留玩法需求原文）并提示改用对话；旧的「可玩 HTML」资产节点保留可用（能显示、能双击试玩），但不再出现在右键菜单里。

和影视成片有什么关系？

没有强绑定。可玩 HTML 是轻量玩法原型；短剧 / 广告成片仍走节点图 + 时间线 / 导演台。见手册 §8 节点图与短剧制作教程。