Community程式設計與開發github.com

photoreal-game

用於從程式碼建構可遊玩、照片級真實感的 3D 遊戲(WebGL、WebGPU、Three.js、Unity、Unreal 或任何引擎)——不限於射擊遊戲,涵蓋任何類型。

photoreal-game 是什麼?

這項技能提供了一套系統化、引擎無關的工作流程,用於將程式碼生成的 3D 場景轉變為可遊玩、照片級真實感的遊戲。它將遊戲開發劃分為八個可執行閘門(產品、普查、燈光、碰撞、遊玩測試、行動裝置、外觀),確保即使是低成本模型也能透過實作驗證產生完整的遊戲。此技能源自於打造知名單檔射擊遊戲《Saltline》的生產紀律,並將其封裝為可重複的步驟,優先考慮可運作的產品層(選單、設定、儲存、HUD),而非純粹的美術細節。它透過填寫預先定義的表格(如美術方向、零件清單、光照配置)來運行,強調漸進式改進,一次只變更一個部分,然後執行所有閘門,如果新的視覺效果破壞了遊戲功能則會還原。此技能支援任何引擎或框架,需要 Node.js 22+ 和 Python 3.10+ 來執行驗證工具,並遵循嚴格的規則,禁止模型進行自我評估——所有判斷都必須透過自動化檢查來驗證。

相容平台✓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 場景轉變為簡短、可遊玩,且看起來像照片般的遊戲的程序。目標是遊戲,而非靜態圖、技術展示或導覽:一個擁有指令(verb)、一個會回應的系統、一種勝利方式,以及一種失敗方式的玩家。

此處不預設任何遊戲類型。主題決定了指令——一個貨櫃場暗示要在換班前搬運貨物;一個工作坊暗示要修理機器;一個樓梯間暗示要不被發現地逃出去。射擊遊戲只是眾多實例之一,只有當主題要求時,同樣的程序才會產出它們。

此程序與工具無關。它假設一個可以編輯檔案、執行指令和檢查圖片的代理程式。以下內容不依賴任何特定的引擎、函式庫版本或供應商產品。

起源與重要性。 此技能的存在是為了解答《Saltline》所提出的問題——這是一個大小為 1,423,668 位元組的單檔瀏覽器射擊遊戲,使用 Claude Fable 5.2 製作,且沒有任何外部資源。有趣的部分不在於其大小,而在於該模型編寫了產生器。此技能將該生產紀律封裝為可執行的閘門,以便低成本模型(例如 DeepSeek V4.1 Flash)也能被要求達到同樣的標準。結果不是同樣的遊戲;而是同樣的紀律——而證據記錄在儲存庫的案例研究中。

附帶的工具組(harness)是可選但建議使用的:它讓這些閘門變得可執行,而不僅僅是理想。它需要 Node.js 22+、附帶 Pillow 的 Python 3.10+,以及一個 Chrome/Chromium 執行檔(如果不在標準路徑,則需設定環境變數 CHROME_PATH)。技能文字本身沒有依賴關係。

如何與低成本模型一起執行

此技能的編寫方式是讓弱模型也能執行它:每個重要的判斷都委派給檢查,而模型的工作是填寫表格並套用排名最高的修正。請嚴格遵守以下規則。

  1. 不要設計架構。 從一個已經具備以下元素的骨架開始:渲染工具組、頁面合約(__READY、__STATS、__SCENE、__AUDIT、__COLLIDERS、__BOUNDS、__TESTMOVE、__TEST、__PRODUCT)、後處理鏈、一個完整的遊戲外殼(標題、設定、暫停、存檔、觸控、HUD 標記)以及一個空的零件表。複製它,然後填寫表格。每次執行時發明的架構是弱模型失敗的地方。
  2. 填寫,不要發明。 工作產出為六個表格:產品(外殼 + 內容)、美術方向、零件(尺寸 + 部件 + 貼花)、表面(漫射/粗糙度/法線)、燈光(位置 + 燈具)以及遊戲循環(指令/系統/回饋/失敗/測試)。
  3. 先產品,再外觀。 產品 → 普查 → 燈光 → 碰撞 → 遊玩測試 → 行動裝置 → 外觀。一個漂亮但沒有設定、沒有第二種敵人角色、沒有目標標記或觸控路徑的畫面,並非完成了一輪。
  4. 每輪只做一個變更,然後執行所有閘門。 一輪只有在沒有閘門退步時才有效。會破壞產品或遊戲循環的視覺增益將被還原。
  5. 永遠不要自我評估。 如果一個閘門與你的意見不一致,閘門獲勝。如果一個閘門錯了,用一個反例來修正它——絕不要繞過它。
  6. 在達到預算或高原期時停止,以先到者為準,並報告最差的相機和失敗的閘門列表。

遵循這六條規則的模型以極低的成本產出可比較的輸出;跳過規則 5 的模型會產生看似合理但實際退步的結果。

交付合約

只有當以下工件都存在且所有閘門都為綠色時,一次執行才算完成:

工件檢查
一個自包含的 HTML,無網路請求在網路功能停用時載入
公開頁面合約(__READY、__STATS、__SCENE、__AUDIT、__COLLIDERS、__BOUNDS、__TESTMOVE、__TEST、__GAME、__PRODUCT)工具組能讀取它們
完整的遊戲外殼選單、設定、暫停、存檔、觸控、HUD 層級架構、結束/重新開始
內容廣度≥2 個敵人/可互動角色、≥2 種工具、≥1 個目標鏈、≥3 個章節(beats)
普查報告覆蓋率 = 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;開始遊戲必須顯示它;設定、暫停和結束畫面必須可透過 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°)通常既能提供形體,又能提供一個可與之對比的受光區域。
  • 在零件清單之前選擇燈光場景。不要因為夜晚、雨天或工業室內能隱藏缺失的細節就預設使用它們。夜晚只是一個選項;背光的黎明或明亮的室內更難,而且通常更令人信服。
場景主光補光 / 基於圖像的光照大氣標誌性材質
夜間工業冷的低-中主光,實用光源天空環境,暖色光池指數衰減,天空色潮濕地面,自發光燈具
陰天日光寬廣的天空主光,35–60°強烈的基於圖像的光照薄薄的空氣透視霧面混凝土,水坑
黃金時刻 / 背光主題後方的低暖色主光冷色天空補光長長的薄霧,邊緣光潮濕瀝青,玻璃,金屬
晴朗正午高主光,硬陰影天空補光 + 反彈最少沙子,石頭,油漆
室內實用光源窗戶 + 少數暖色光源窗戶/天空環境光線束,灰塵木頭,布料,金屬
地下 / 人造光實用光源 + 自發光低環境光體積光潮濕混凝土,標誌

一個背光的場景並不「容易」:它會暴露裁切的高光、色偏和模糊的剪影。修正曝光和高光滾降...

...(原文被截斷)

相關技能