从代码生成照片级真实的 3D 游戏
一种将代码生成的 3D 场景转化为可玩的、具有照片级真实感的短小游戏的方法。目标是构建一个游戏,而不是静态图像、技术演示或导览:玩家拥有一个动词,系统做出回应,有获胜的方式,也有失败的方式。
这里没有任何内容假设游戏类型。主题决定动词——一个集装箱堆场暗示在轮班结束前运输货物;一个车间暗示修理机器;一个楼梯间暗示不被发现地离开。射击游戏只是众多实例之一,并且只有当主题要求时,相同的程序才会生成它们。
该程序与工具无关。它假设一个能够编辑文件、运行命令和检查图像的智能体。以下内容不依赖于特定的引擎、库版本或供应商产品。
起源与意义。 这个技能的存在是为了回答 Saltline 提出的一个问题——一款 1,423,668 字节的单文件浏览器射击游戏,零外部资源,使用 Claude Fable 5.2 制作。有趣的部分不在于大小,而在于模型编写了生成器。这个技能将这种生产纪律封装成可执行的门控,因此一个低成本的模型(例如 DeepSeek V4.1 Flash)可以被要求达到相同的标准。结果不是相同的游戏,而是相同的纪律——证据记录在仓库的案例研究中。
捆绑的验证框架是可选的,但推荐使用:它使门控变得可运行,而不仅仅是理想化的。它需要 Node.js 22+、带有 Pillow 的 Python 3.10+,以及一个 Chrome/Chromium 二进制文件(如果不在标准位置,需要设置 CHROME_PATH)。技能文本本身没有依赖项。
如何用低成本模型运行此技能
该技能的编写方式使得弱模型也能执行:每个重要的判断都委托给检查,模型的工作是填充表格并应用排名最高的修复方案。请严格遵守以下规则。
- 不要设计架构。 从一个已经包含以下内容的骨架开始:渲染框架、页面契约(
__READY,__STATS,__SCENE,__AUDIT,__COLLIDERS,__BOUNDS,__TESTMOVE,__TEST,__PRODUCT)、后处理链、已完成的游戏外壳(标题、设置、暂停、保存、触控、HUD 标记)以及一个空的套件表格。复制它,然后填充表格。每次运行时发明的架构是弱模型失败的地方。 - 填充,不要发明。 工作产物是六个表格:产品(外壳 + 内容)、艺术指导、套件(尺寸 + 部件 + 贴花)、表面(反照率/粗糙度/法线)、光照(位置 + 灯具)和循环(动词/系统/反馈/失败/测试)。
- 先产品,后外观。
product → census → lights → collide → playtest → mobile → look。一个美丽但没有设置、没有第二个敌人角色、没有目标标记或没有触控路径的帧,不是一个完成的轮次。 - 每轮只做一项更改,然后运行所有门控。 一个轮次仅在没有门控退步时有效。破坏产品或循环的视觉增益将被撤销。
- 永远不要自我评估。 如果门控与你的意见不一致,门控获胜。如果门控是错误的,用一个反例修复门控——永远不要绕过它。
- 在预算或平台期止步,以先到者为准,并报告最差的摄像机和失败的门控列表。
遵循这六条规则的模型可以以极低的成本产生可比较的输出;跳过规则 5 的模型会产生看似合理的回归。
可交付物契约
只有当以下内容都存在并且所有门控都通过时,一轮运行才算完成:
| 制品 | 检查 |
|---|---|
| 一个自包含的 HTML,无网络请求 | 在网络禁用的状态下加载 |
暴露的页面契约(__READY, __STATS, __SCENE, __AUDIT, __COLLIDERS, __BOUNDS, __TESTMOVE, __TEST, __GAME, __PRODUCT) | 框架能够读取它们 |
| 已完成的游戏外壳 | 菜单、设置、暂停、保存、触控、HUD 层级、结束/重启 |
| 内容广度 | ≥2 个敌人/交互对象角色,≥2 个工具,≥1 个目标链,≥3 个节拍 |
| 普查报告 | 覆盖率 = 100%,零失败 |
| 光照审计 | 每个光源都锚定到一个灯具 |
| 碰撞报告 | 零穿透,零超出边界,碰撞体一致性 100% |
| 游戏测试 | 循环可完成,失败路径可达,重启正常工作 |
| 移动端报告 | 390×844 布局,无水平溢出,存在触控控件 |
| 针对 3–6 个主题对象的盒子报告 | 每个指标 >= 参考值的 0.8 |
| 帧评分 | 已报告,但绝不用于覆盖门控 |
完成产品契约
一个可玩的帧不等于一个完成的游戏。循环门控保护行为;产品门控保护外壳、内容广度和第一印象。在页面中声明以下内容,以便 harness/product.mjs 可以检查它而无需读取模型的意图。
| 制品 | 最低要求 |
|---|---|
| 屏幕 | 菜单、游戏中、暂停、设置、失败、胜利 |
| 标题画面 | 加载时可见;HUD 隐藏;标题、前提、开始、设置/控件 |
| 设置 | 灵敏度、音量、视野、反转 Y 轴、质量(或等效集合) |
| 持久化 | 一个键在重新加载后保留(最佳分数/进度/设置) |
| 输入 | 键盘 + 鼠标 + 触控;当指针锁定失败时,有备选瞄准方式 |
| 目标 | ≥1 个链,带有 ≥3 个节拍以及世界标记/指南针 |
| 角色 | ≥2 个敌人/障碍物/交互对象角色,不能只是重新着色 |
| 工具 | ≥2:一个主要动词和一个次要动词(武器/工具/能力) |
| HUD | 目标+进度、生存、武器/弹药、上下文提示、指南针/标记、字幕 |
| 音频 | 静音 + ≥6 个状态变更事件 |
| 摄像机 | 在 __PRODUCT.cameras 中包含主视角和特写静态摄像机 |
| 性能 | 声明的调用/三角形/光源预算,在开始后测量 |
| 移动端 | 390×844,无水平溢出;触控控件可触及 |
垂直切片的内容预算
在任何美术处理之前填写此表。一个垂直切片是一次 3–8 分钟的会话,包含一个完整的目标链、两个角色、一个标志性系统和一个经过设计的外壳。它比演示片段小,但比技术演示大。
| 插槽 | 垂直切片 | 完成的小型游戏 |
|---|---|---|
| 目标 | 1 个链,3 个节拍 | 1–3 个链,5–8 个节拍 |
| 敌人/交互对象角色 | 2 | 3–5 + 一个高潮 |
| 武器/工具 | 2(主要 + 次要) | 3–5 |
| 玩家动词 | 移动、瞄准、射击、装填 | + 蹲伏/跳跃/交互/能力 |
| 世界 | 一个地点,3 个深度层次 | 2–3 个相连的空间 |
| 外壳 | 标题、暂停、设置、结束 | + 保存、质量、触控 |
| 会话 | 3–8 分钟 | 10–30 分钟 |
清单是一个声明;门控检查 DOM 行为和声明的数量。不要声明页面没有实现的内容。
window.__PRODUCT = {
title: { name: '游戏标题', start: '#start', hud: '#hud', hudHiddenOnTitle: true },
screens: ['menu', 'playing', 'paused', 'settings', 'lost', 'won'],
ui: { start: '#start', hud: '#hud', pause: '#pause', settings: '#settings', end: '#end', touch: '#touch' },
settings: ['sensitivity', 'volume', 'fov', 'invertY', 'quality'],
persistence: ['game.best'],
input: { keyboard: true, mouse: true, touch: true },
content: {
objectives: [{ id: 'objective-1', title: '目标', steps: 3 }],
roles: ['role-a', 'role-b'],
tools: ['tool-a', 'tool-b'],
beats: ['intro', 'contact', 'mid', 'climax', 'win'],
},
hud: ['objective', 'compass', 'health', 'ammo', 'prompt', 'subtitles'],
audio: { events: 10, mute: true },
perf: { maxCalls: 700, maxTris: 400000, maxLights: 14 },
cameras: [
{ name: 'hero', cam: [0.5, 1.7, 10, -2.6, 1.3, -10] },
{ name: 'close', cam: [-6.4, 1.4, 5.2, -9.9, 1.0, 2.2] },
],
test: { start: 'start', pause: 'pause', resume: 'resume', settings: 'openSettings', save: 'save' },
};
标准的 __TEST 动作(允许额外动作):start、pause、resume、openSettings、closeSettings、save、state。它们必须在没有指针锁定的情况下工作,并返回一个 JSON 安全的快照。标题画面必须隐藏 HUD;开始必须显示 HUD;设置、暂停和结束画面必须可通过 DOM 检查。
何时使用
- 场景在几何上是正确的,但看起来平坦、塑料感或“生成感”。
- 渲染必须匹配参考照片、概念或艺术指导。
- 需要以可控的方式改进光照、材质或构图。
- 长时间的生成需要在多次迭代中保持连贯性。
何时不使用
- 刻意风格化的输出(平直着色、赛璐珞、图表式、类似 UI)。它们需要一致的抽象,而不是物理上的逼真度。该程序可以迁移,但替换照片级真实配置文件和外观门控为风格一致的配置文件;一个根据照片配置文件衡量的风格化场景,其失败是结构性的,而非质量上的。
- 精度任务(CAD、工程图),其中可读性优先于真实感。
- 没有摄像机的场景:数据可视化、节点图、UI。
问题模型
感知到的真实感来自五个杠杆。按此顺序应用它们;随着你向下移动列表,努力回报率急剧下降。
- 光照 —— 一个具有明确方向、颜色和高度的单一主光源,外加用于反射和补光的环境。
- 材质 —— 粗糙度、法线和污渍的变化,而不仅仅是颜色。
- 构图和密度 —— 多个尺度和深度的物体,具有清晰的焦点和可读的尺度线索。
- 图像形成 —— 抗锯齿、色调映射、泛光、颗粒、暗角。
- 几何细节 —— 最后的手段,并且仅当它在屏幕上占几个像素时才有效。
两个值得明确说明的结果:
- 小于大约两个像素的细节会被抗锯齿移除,不会对图像产生贡献。在该尺度上增加多边形数量是浪费的。
- 一个场景可以有正确的曝光,但仍然看起来空旷。空旷是一个密度问题,而不是调色问题。
对于完成的游戏还有三个结果:
- 一帧是必要但不充分的。产品层——标题主艺术、设置、暂停、保存、触控、目标标记、电台/字幕、内容广度——在玩家注意到光照之前就被评判了。
- 五个杠杆与主题无关。它们适用于白天的港口、明亮的室内、雪地或风格化的竞技场。夜间/下雨/雾是一个场景,而不是默认设置。
- 帧评分是对于一个参考外观的指南针。它无法区分一个完成的游戏和一个漂亮的演示。
工作流程
每一步都有一个输出。在没有它之前不要开始下一步。
步骤 1 —— 使渲染可观察(建议在任何场景工作之前进行)
制作一个可重复的方法来捕获一帧并检查它。
输出:一个返回图像,并且理想情况下返回一些数字的命令。
如果你的环境已经有一个截图工具,请使用它。如果没有,请构建一个可用的最小工具:
- 针对本地静态服务器启动一个无头浏览器。
- 等待来自页面的就绪信号(见下面的契约),然后捕获。
- 可选地计算图像统计信息:曝光直方图、裁剪、颜色数量、边缘密度。
使捕获确定性的页面契约:
window.__READY = true; // 在渲染几帧后设置
window.__STATS = { calls, triangles }; // 可选的渲染器计数器
// 可选的查询参数
// ?shot=1 隐藏 UI
// ?cam=x,y,z,tx,ty,tz 固定摄像机
// ?seed=N 固定随机种子
规则:
- 每次比较都使用固定的摄像机、固定种子和固定视口。
- 将每次捕获存储在一个版本化的名称下;永远不要覆盖前一次的。
- 如果没有可用的指标,保留图像并并排比较。视觉比较就足够了;指标只加速归因过程。
步骤 2 —— 编写艺术指导简报
输出:一个简短的表格。每一行都必须具体到可以实现。
| 决策 | 内容 |
|---|---|
| 主题 | 帧是关于什么的,在什么尺度上 |
| 时间和天气 | 决定雾、反射强度、对比度 |
| 主光源 | 方向、高度、色温、强度 |
| 天空和环境 | 阴影补光的颜色 |
| 材质系列 | 存在哪些表面,有多粗糙,有多湿润 |
| 焦点 | 眼睛应该首先落在哪里 |
| 约束 | 绝对不能出现的内容(例如纯白色、平坦地面、晴朗天空) |
指导:
- 选择一个主导的光照故事。额外的光源是补光、反弹或实用光源,并且必须处于从属地位。
- 在添加细节之前约束主题。减少可见复杂性的条件——夜晚、下雨、雾、灰尘、背光、工业或室内环境——是合法且有效的选择,而不是捷径。
- 有意识地选择主光源高度。阴影长度与
height / tan(elevation)成正比:低主光源会产生长阴影,可能使整个前景处于阴影中,这看起来像“没有阴影”。中等高度(大约 20–30°)通常能同时提供形状和可供对比的照亮区域。 - 在套件之前选择光照场景。不要默认使用夜晚、下雨或工业室内,因为它们隐藏了缺失的细节。夜晚是一个选项;背光的黎明或明亮的室内更困难,通常也更令人信服。
| 场景 | 主光源 | 补光 / IBL | 空气 | 标志性材质 |
|---|---|---|---|---|
| 夜间工业 | 冷色低-中主光源、实用光源 | 天空环境、暖色光斑 | 指数衰减、天空色 | 湿地面、发光灯具 |
| 阴天日光 | 广阔天空主光源,35–60° | 强 IBL | 薄空气透视 | 哑光混凝土、水坑 |
| 黄金时刻 / 背光 | 主题后面的低暖色主光源 | 冷色天空补光 | 长雾、边缘光 | 湿沥青、玻璃、金属 |
| 晴朗正午 | 高主光源、硬阴影 | 天空补光 + 反弹 | 最小 | 沙子、石头、油漆 |
| 室内实用光源 | 窗户 + 少数暖色光源 | 窗户/天空环境 | 光束、灰尘 | 木头、织物、金属 |
| 地下 / 人造光 | 实用光源 + 自发光 | 低环境光 | 体积光 | 湿混凝土、标志 |
背光场景并不“更容易”:它会暴露裁剪的高光、色偏和脆弱的剪影。修复曝光和高光衰减比隐藏它们更有效。
步骤 3 —— 为你的场景填充套件表格
输出:一个包含尺寸、深度层次、可识别的部件和贴花的表格。在步骤 4 之前不要填充材质。
| 行 | 内容 | 示例(主题:集装箱堆场) |
|---|---|---|
| 参考图像 | 概念或参考照片的链接 | yard_reference_moody_dawn.png |
| 空间 | 多少个单元 × 多少深度层 | 5×3 层,共 15 个网格单元 |
| 焦点 | 世界坐标 | (10, 0, 15) |
| 元素 | 部件及其可识别的形状 | 集装箱 40 英尺型、叉车、龙门、灯杆、地面、栅栏 |
| 材质贴花 | 形状上的区域标签 | 锈迹、标志、泥土、水泥、玻璃 |
| 摄像机 | 主视角 + 特写 | hero: [0.5, 1.7, 10] look [0, 0, 0] |
步骤 4 —— 添加材质
输出:一个包含反照率、粗糙度、法线以及可选的自发光和透明度参数的行。使用与套件步骤中相同的部件名称。
对于照片级真实感,使用物理原则渲染值:
| 材质 | 反照率 | 粗糙度 | 法线强度 | 自发光 | 注释 |
|---|---|---|---|---|---|
| 生锈金属 | ~0.4 | 0.9 | 0.8 | 0 | 高粗糙度,高法线 |
| 新漆金属 | ~0.3 | 0.1 | 0.1 | 0 | 低粗糙度 = 镜面反射 |
| 湿玻璃 | ~0.05 | 0.0 | 0 | 0 | 镜面透射(如果支持) |
| 干燥沥青 | ~0.3 | 0.9 | 0.3 | 0 | 接近漫反射 |
| 湿沥青 | ~0.2 | 0.3 | 0.2 | 0 | 更高的镜面反射和折射率 |
| 发光的金属 | ~0.8 | 1.0 | 0 | 0.5 | 主要来自自发光 |
步骤 5 —— 照亮
输出:位置 + 灯具。每个光源必须有一个物理上合理的灯具(天空、灯杆、窗户等)。不要生成漂浮的光源。
| 名称 | 类型 | 颜色 | 强度 | 位置 | 灯具 |
|---|---|---|---|---|---|
| 太阳 | 方向光 | 暖色 | 1.0 | 角度 (30°, 20°) | 天空 |
| 灯杆 1 | 聚光灯 | 冷白 | 0.3 | (5, 8, 3) | 灯杆夹具 |
| 环境 IBL | 环境 | 天蓝色 | 0.05 | 环境 | 天空穹顶 |
步骤 6 —— 构建循环
输出:一个定义游戏玩法的表格:玩家动词、系统如何响应、玩家如何获得反馈、如何失败、以及如何获胜。
| 元素 | 内容 | 示例 |
|---|---|---|
| 动词 | 玩家做什么 | 驾驶叉车、装载货车、躲避机械臂 |
| 系统 | 什么检查动词 | 碰撞检测 + 定时的事件序列 |
| 反馈 | 玩家如何知道 | 物体移动/碰撞、HUD 更新、声音、屏幕震动 |
| 失败 | 如何重新开始 | 计时器归零或损坏超过 5 次 |
| 获胜 | 游戏何时结束 | 完成 3 次装载 + |
等 |
步骤 7 —— 游戏测试
运行框架。对于每个失败的检查:
- 读取错误消息。
- 隔离原因(产品?内容?碰撞?光照?)。
- 如果需要,检查 DOM,记录当前状态。
- 应用失败的顶部排名修复。如果第一次修复失败,应用下一个。
- 重新运行所有门控。不要部分重新运行。
步骤 8 —— 移动端报告
在 390×844 视口中运行。验证没有水平溢出并且存在触控控件。如果不是,应用修复。
步骤 9 —— 外观门控
最终比较:在固定的摄像机位置和种子下,将当前帧与参考图像进行比较。对 3–6 个主题对象运行外观检查,每个指标 >= 0.8 的参考值。
引用的实验记录
| 实验 | 主题 | 结果 |
|---|---|---|
| Saltline (Claude Fable 5.2, 2025) | 码头枪战 | 1426K 字节,零外部资源 |
| 参考射击游戏 (DeepSeek V4.1 Flash, 2026) | 车库 | 已通过所有门控;产品 + 光照 + 循环 |
| 生成货运游戏 (DeepSeek V4.1 Flash, 2026) | 集装箱堆场 | 正在构建;为照片级真实感优化时间 |
挂钩连接
框架使用以下挂钩:
harness/product.mjs读取window.__PRODUCT。harness/audit.mjs检查__AUDIT。harness/play.mjs通过__TESTMOVE和__TEST模拟玩家。harness/collide.mjs解析__COLLIDERS和__BOUNDS。harness/look.mjs比较截图并计算指标。
每个挂钩可以通过 node harness/look.mjs 或从框架入口点运行,并且所有挂钩都在调用 harness/index.mjs 时运行。
变更日志
- 2026-04-10:新增
__TEST和__TESTMOVE港口契约。 - 2026-04-09:初始版本,包含照片级真实感配置文件。