Community编程与开发github.com

photoreal-game

用于从代码构建可玩、照片级真实的 3D 游戏(WebGL、WebGPU、Three.js、Unity、Unreal 或任何引擎),涵盖任何类型(不仅是射击游戏):运输、修理、潜行、探索、驾驶、管理。

photoreal-game 是什么?

该技能提供了一套系统化的程序,用于将代码生成的 3D 场景转化为可玩的、具有照片级真实感的短小游戏。其核心目标是创建一款完整的游戏,而不仅仅是一个静态场景、技术演示或导览。它包含可执行的门控检查(gates),通过节点(verification harness)验证产品完整性、光照、碰撞和游戏循环等关键方面。该技能工具无关,可以应用于任何引擎(如 Three.js、Unity、Unreal),并且专为低预算模型(如 DeepSeek V4.1 Flash)设计,通过将判断委托给检查,确保即使模型能力有限也能产出高质量。它会逐步指导用户填写产品、艺术方向、套件、表面、光照和循环等表格,并遵循严格的规则(如每次只做一项更改、永不自我评估),最终生成一个可交付的 HTML 文件,包含完整的游戏外壳(菜单、设置、暂停、保存、触控)和至少一个可完成的任务链。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/NorwinYu/photoreal-game/tree/HEAD

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

从代码生成照片级真实的 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)。技能文本本身没有依赖项。

如何用低成本模型运行此技能

该技能的编写方式使得弱模型也能执行:每个重要的判断都委托给检查,模型的工作是填充表格并应用排名最高的修复方案。请严格遵守以下规则。

  1. 不要设计架构。 从一个已经包含以下内容的骨架开始:渲染框架、页面契约(__READY, __STATS, __SCENE, __AUDIT, __COLLIDERS, __BOUNDS, __TESTMOVE, __TEST, __PRODUCT)、后处理链、已完成的游戏外壳(标题、设置、暂停、保存、触控、HUD 标记)以及一个空的套件表格。复制它,然后填充表格。每次运行时发明的架构是弱模型失败的地方。
  2. 填充,不要发明。 工作产物是六个表格:产品(外壳 + 内容)、艺术指导、套件(尺寸 + 部件 + 贴花)、表面(反照率/粗糙度/法线)、光照(位置 + 灯具)和循环(动词/系统/反馈/失败/测试)。
  3. 先产品,后外观。 product → census → lights → collide → playtest → mobile → look。一个美丽但没有设置、没有第二个敌人角色、没有目标标记或没有触控路径的帧,不是一个完成的轮次。
  4. 每轮只做一项更改,然后运行所有门控。 一个轮次仅在没有门控退步时有效。破坏产品或循环的视觉增益将被撤销。
  5. 永远不要自我评估。 如果门控与你的意见不一致,门控获胜。如果门控是错误的,用一个反例修复门控——永远不要绕过它。
  6. 在预算或平台期止步,以先到者为准,并报告最差的摄像机和失败的门控列表。

遵循这六条规则的模型可以以极低的成本产生可比较的输出;跳过规则 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 个节拍
敌人/交互对象角色23–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. 光照 —— 一个具有明确方向、颜色和高度的单一主光源,外加用于反射和补光的环境。
  2. 材质 —— 粗糙度、法线和污渍的变化,而不仅仅是颜色。
  3. 构图和密度 —— 多个尺度和深度的物体,具有清晰的焦点和可读的尺度线索。
  4. 图像形成 —— 抗锯齿、色调映射、泛光、颗粒、暗角。
  5. 几何细节 —— 最后的手段,并且仅当它在屏幕上占几个像素时才有效。

两个值得明确说明的结果:

  • 小于大约两个像素的细节会被抗锯齿移除,不会对图像产生贡献。在该尺度上增加多边形数量是浪费的。
  • 一个场景可以有正确的曝光,但仍然看起来空旷。空旷是一个密度问题,而不是调色问题。

对于完成的游戏还有三个结果:

  • 一帧是必要但不充分的。产品层——标题主艺术、设置、暂停、保存、触控、目标标记、电台/字幕、内容广度——在玩家注意到光照之前就被评判了。
  • 五个杠杆与主题无关。它们适用于白天的港口、明亮的室内、雪地或风格化的竞技场。夜间/下雨/雾是一个场景,而不是默认设置。
  • 帧评分是对于一个参考外观的指南针。它无法区分一个完成的游戏和一个漂亮的演示。

工作流程

每一步都有一个输出。在没有它之前不要开始下一步。

步骤 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.40.90.80高粗糙度,高法线
新漆金属~0.30.10.10低粗糙度 = 镜面反射
湿玻璃~0.050.000镜面透射(如果支持)
干燥沥青~0.30.90.30接近漫反射
湿沥青~0.20.30.20更高的镜面反射和折射率
发光的金属~0.81.000.5主要来自自发光

步骤 5 —— 照亮

输出:位置 + 灯具。每个光源必须有一个物理上合理的灯具(天空、灯杆、窗户等)。不要生成漂浮的光源。

名称类型颜色强度位置灯具
太阳方向光暖色1.0角度 (30°, 20°)天空
灯杆 1聚光灯冷白0.3(5, 8, 3)灯杆夹具
环境 IBL环境天蓝色0.05环境天空穹顶

步骤 6 —— 构建循环

输出:一个定义游戏玩法的表格:玩家动词、系统如何响应、玩家如何获得反馈、如何失败、以及如何获胜。

元素内容示例
动词玩家做什么驾驶叉车、装载货车、躲避机械臂
系统什么检查动词碰撞检测 + 定时的事件序列
反馈玩家如何知道物体移动/碰撞、HUD 更新、声音、屏幕震动
失败如何重新开始计时器归零或损坏超过 5 次
获胜游戏何时结束完成 3 次装载 +

等 |

步骤 7 —— 游戏测试

运行框架。对于每个失败的检查:

  1. 读取错误消息。
  2. 隔离原因(产品?内容?碰撞?光照?)。
  3. 如果需要,检查 DOM,记录当前状态。
  4. 应用失败的顶部排名修复。如果第一次修复失败,应用下一个。
  5. 重新运行所有门控。不要部分重新运行。

步骤 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:初始版本,包含照片级真实感配置文件。

相关技能