Community影像github.com

threejs-asset-generator

在 Three.js r170+ 中,以種子決定性建構器、參數綱要、平面著色頂點顏色網格、自訂幾何(正確纏繞)、鏡像零件、骨架化雙足與生物核心、複合體、紋理、獨立程式碼匯出,並能比對參考影像。不適用於載入 glTF 檔案。

threejs-asset-generator 是什麼?

Three.js 程序化低多邊形資產產生器是一個專為開發者設計的 AI 代理技能,用於在 Three.js r170 及以上版本中,以種子驅動、確定性的方式程序化生成 3D 資產。該技能涵蓋了從單一物件到複合體、從平面著色到紋理貼圖、從靜態模型到骨架動畫的完整管線。它強調「純函數式」建構,確保相同參數永遠產生相同的幾何形狀,從而實現可重複性與版本控制。此技能支援多種平台,如 Claude Code、Cursor 和 Codex,並提供 CLI 閘道與 QA 檢查清單,確保資產在幾何正確性、效能與生命週期管理方面達到最高標準。其獨特之處在於能夠比對參考影像,自動調整建構以符合給定的輪廓與色盤,並能匯出乾淨、可獨立執行的 Three.js 程式碼,無需額外依賴。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Luciansvon/ThreeJS-modeling-skill/tree/HEAD/threejs-asset-generator

Installed? Explore more 影像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Three.js 程序化低多邊形資產產生器

此版本假設您已有工作區和 Node.js。使用內建的建構器和 CLI 閘道從實際資產收集證據。

將每個資產(單一或複合)建構為純淨、種子驅動的函數。即時預覽和獨立程式碼匯出都呼叫同一個函數,因此使用者所見即所得。

表面細節: 從實心材質或頂點顏色開始。僅在需要請求或可見的細節時才添加影像貼圖。當原始藝術品為合適選擇時,使用會話的影像產生器,然後將其輸出作為建構器的固定輸入。

預覽選擇: 當使用者要求預覽但未選擇模式時,提供快速預覽(軌道、平移、檢查紋理、播放或逐幀檢視嵌入片段)和完整預覽(可編輯參數、骨架檢查、動畫創作或表情)。如果已有快速結果,直接分享並使用請求的模式。請參閱 references/studio-preview.md。

目標: three ≥ r170 作為 ES 模組,並根據官方遷移說明(至 r187)進行檢查,詳見 references/export.md 第 12 節。

程式碼位於 src/,而非文件檔中。執行,而非重新讀取:tsx src/<name>.test.ts(純測試不需要 three)。參考檔案會列出每個模組的 API。

有參考影像? 在撰寫程式碼前先閱讀 references/reference-matching.md,並在每個建構步驟後執行其迴圈(第 15 節)。

接下來讀什麼

您正在做閱讀程式碼
材質、平面著色、程序或影像生成的紋理、頂點抖動(第 4、5 節)references/look.mdsrc/lowpoly.ts, src/jitter.ts
自訂幾何、纏繞、鏡像零件、覆蓋層(第 6、7 節)references/geometry.mdsrc/geometry.ts, src/overlay.ts
生物、船體、機翼、純三角形核心(第 6.2、6.3 節)references/creatures.mdsrc/tri.ts, src/organic.ts
任何動畫、人形、擠出、紋理(第 6.4 至 6.7 節)references/rigging-biped.mdsrc/rig.ts, src/biped.ts, src/texture.ts
平面或塊狀外觀、圖集、導角、AO、插槽(第 6.8 節)references/detail.mdsrc/detail.ts, src/detailThree.ts
一個複合體中的多個子資產(第 8 節)references/composite.md
接地、銷毀、重建、燈光(第 9、10 節)references/lifecycle.mdsrc/lifecycle.ts
程式碼匯出、Three.js 版本(第 11、12 節)references/export.mdsrc/fingerprint.ts
資產的 .glb 檔案(第 16 節)references/glb-export.mdscripts/export-glb.ts
是否太重、平台預算、LOD detail(第 17 節)references/budget.mdscripts/mesh-stats.ts, src/lod.ts
骨架、動畫片段、漂移、表情(第 18 節)references/rig-check.mdscripts/rig-check.ts
快速 GLB 檢視器或完整預覽工作室references/studio-preview.md快速預覽 HTML
完整小型範例references/examples.md
在說資產完成之前:QA 閘道、審查影像(第 13 節)references/qa-gates.mdscripts/qa-asset.ts

0. 慣例(決定一次,處處套用)

主題規則
單位1 單位 = 1 公尺
軸向Y 向上,右手座標系
前方+Z(與 glTF 和 Object3D.lookAt 相同)
側邊前方為 +Z,上方為 +Y,則資產的右側為 −X,左側為 +X(右側 = 前方 × 上方)
樞紐原點位於足跡中心,最低點在 Y = 0(見第 9 節)
面名稱按軸線命名面(+X 面、頂部),絕不使用 port/starboard/左/右,這樣規則就不會與軸線矛盾
對稱建構一側,透過 PartBuilder.add 或 mirrorTris 鏡像副本(第 6.1 節)。裸用 applyMatrix4 搭配負縮放會使纏繞方向內外翻轉

為什麼這很重要:將「船首 = +Z」與「右舷 = +X」配對是鏡像的,以此配對建造的船隻其側邊會互換。當前方為 +Z 時,右舷為 −X,左舷為 +X。

1. 單一管線,單一事實來源

參數綱要(預設值、範圍)→ resolveParams() → build…Asset() → THREE.Group
  • 預設值和範圍僅存在於綱要中。build…Asset(rawParams) 自己呼叫 resolveParams。三種互相競爭的預設值(params.seed || 12345、綱要 default: 42、複合 ?? 101)會使預覽、預設集和匯出的程式碼不一致。
  • build…Asset 是純函數:相同的已解析參數會產生相同的幾何形狀。沒有 Math.random、Date.now、DOM 存取或模組層級的可變狀態。
  • 正常匯入 THREE。不要注入 THREEInstance:輔助函數使用模組匯入,因此注入只能解決一半問題且會隱藏錯誤。匯出步驟會提供匯入行(第 11 節)。
  • 為每個建構器和參數列表賦予唯一名稱(buildTreeAsset、treeParameters)。通用的 buildAsset 在複合體匯入兩個產生器時會衝突。
  • 對於自訂幾何(生物、船體、機翼),將形狀邏輯保留在純函數中,作用於純三角形陣列,並讓 THREE 在最後包裹結果(第 6.2 節)。僅限圖元的屬性可以直接留在 PartBuilder 上。

類型:src/types.ts(ParamDef、AssetGeneratorSchema)。

實作範例(樹木):references/examples.md。

2. 確定性

可重複的輸出是種子的全部意義,因此要保護它:

  • 對於種子和任何數值後備,使用 ??,絕不使用 ||。seed || 12345 會默默地將種子 0 變成 12345。
  • 為每個功能提供自己的分支串流。使用一個共享的 rng,更改 segments 或切換 hasFruits 會使每個後續的隨機數發生偏移,並打亂資產不相關的部分。
  • 以固定順序迭代(陣列,而非順序未知的物件鍵,也不是混合插入順序的 Set)。

程式碼:src/prng.ts。API:

  • export function hashString(str: string)
  • export function createPRNG(seed = 1)
  • export type Rng = ReturnType<typeof createPRNG>;

3. 參數

resolveParams 套用預設值、強制轉換類型、限制在 min/max 範圍內、對齊到 step,並拒絕無效的顏色和選項。在 UI、預設集和 build…Asset 中使用它,這樣就沒有消費者能產生 NaN 或超出範圍的幾何形狀。

程式碼:src/params.ts。API:

  • export function resolveParams(schema: { parameters: ParamDef[] }, input: Record<string, unknown> = {})

  • 解析後,套用衍生約束,以免滑桿組合產生退化形狀(例如 trunkRadius = Math.min(trunkRadius, crownRadius * 0.6))。

  • 將 seed 最大值保持在 99999 或更高。複合建構器衍生子種子時為 fork(label).seed % 100000;較小的最大值會將它們全部限制為相同的值。

  • 切換開關(hasFruits、hasTurrets)會改變建構的內容,但絕不會改變其他部分收到的隨機數(第 2 節)。

  • 細節切換開關(aoStrength、bevel、atlasOn)是普通參數。它們會改變細節傳遞所添加的內容,但絕不會改變其他部分收到的隨機數。

  • 圖集串流是分支的。 從 rng.fork('atlas') 生成圖集,這樣切換 atlasOn 不會改變其他任何部分(references/detail.md)。

13. 檢查清單(每個資產勾選,出貨前不得預先勾選)

執行閘道,然後檢查。 npx tsx scripts/qa-asset.ts --module ./kernel.ts --export buildXTris --symmetric 用於純核心,或 --tris tris.json 用於最終接地資產(用法和閘道列表:references/qa-gates.md)。它會輸出 Q1 到 Q10,寫入 review.png,並以 @@RESULT 行結尾。修正第一個失敗的閘道並重新執行。

完成規則。 在 qa-asset 通過當前建構(或每個失敗閘道都附帶原因說明)、review.png 已使用檢視工具打開且每個面板都有一行說明所見內容,以及所有標記為 UNVERIFIED 或 not checked 的項目都在回答中重複之前,絕對不要報告資產已完成。以最後一次執行的閘道表作為結尾。

確定性和參數

  • 預設值和範圍僅存在於綱要中;build…Asset 呼叫 resolveParams
  • 種子使用 ??;種子 0 可運作;沒有 Math.random 或 Date.now
  • 每個功能都有自己分支的串流;切換開關不會打亂其他部分
  • 衍生約束防止退化形狀;子種子符合種子範圍

參考(僅在使用者提供影像時)

  • ref-spec.md 已撰寫一次,ref.json 已建立,遮罩 PNG 已檢查;ref-compare 在每個建構步驟後執行;閘道表(第 15 節)在回答中

幾何和外觀

  • 軸向遵循第 0 節;面按軸線描述;右側 = −X 當前方 = +Z
  • 自訂幾何具有正的 signedVolume,鏡像後亦然;僅在零厚度板材上使用 DoubleSide
  • 鏡像零件透過 add()/addTris 或 mirrorTris 進行,絕不使用裸負縮放 applyMatrix4
  • 自訂幾何和生物形狀存在於具有 Node 測試(確定性、有號體積、串流隔離)的純三角形核心中
  • 零件經過 bakeFlat + paint;每個三角形的顏色函數是純函數
  • 抖動在 add() 之前套用,縫合焊接,並重新計算邊界體積
  • 金屬零件具有環境貼圖或降低的 metalness
  • 覆蓋層使用等距內縮和微小的抬升以防止 Z 衝突

骨架、人形、紋理(僅在適用時)

  • 活動部件是來自 RigBuilder 的骨骼,在靜止姿勢下創作;靜態部件保持合併;骨骼約 ≤ 12
  • 左/右骨骼來自 mirrorBone + 鏡像矩陣;片段使用 AnimationMixer 作用於骨架根
  • 肢體鏈經過 twoBoneIK 或固定點鏈;腳和手具有明確的前方/向上
  • 擠出和放樣零件具有正的 signedVolume,鏡像後亦然
  • UV 關閉,除非使用了紋理;使用紋理時,為該材質的每個零件設置 PartBuilder({ uv }),並且 disposeAsset 會釋放 map

細節傳遞(僅在適用時)

  • 圖集儲存格遵循慣例(儲存格 0 左上角);每個使用紋理材質的零件都有 uv;粗糙度/凹凸貼圖為 NoColorSpace,roughness: 1
  • 圖集從分支串流生成(seededAtlas),或作為參數注入;建構器絕不載入檔案或觸碰 DOM
  • 導角和雕刻零件的 signedVolume 為正;雕刻量使半徑 > 0
  • AO 僅套用一次(骨架的每個零件使用 aoShade,靜態合併使用 applyAO),且絕不低於 0.35 的下限
  • 小細節來自 raycastTris/scatterOnSurface + 帶 sink 的 placeTris;鏡像側使用 mirrorHit

複合體

  • 唯一的匯出建構器名稱;參數使用 pickParams 設定命名空間和切片
  • 放置使用足跡、固定的優先順序和有限嘗試次數
  • 跳過的項目是確定性的;重複的物件被複製或實例化

QA(每個資產)

  • scripts/qa-asset.ts 在當前建構上退出碼為 0;review.png 已檢視,每個面板一個發現;UNVERIFIED 項目已列出;閘道表在回答中

生命週期和匯出

  • 包裝群組將資產接地於 Y = 0;每次重建時呼叫 disposeAsset
  • 網格已命名;三角形數量在預算內
  • 匯出器使用真實的 TS 轉譯器,僅包含一次輔助函數,且除了 three 外無其他匯入(僅在使用 mergeGeometries 時使用 three/addons)
  • 要求 GLB:選擇第 16 節中的匯出路徑。報告檔案、對其位元組執行的檢查,以及任何未經檢查的視覺或匯入階段。
  • 提供了平台或添加了 detail:scripts/mesh-stats.ts(--lods 用於 LOD)退出碼為 0,命名了設定檔和種類,重複了 not checked;detail 預設值 2 使現有資產保持不變
  • 匯出目標(模組、匯入映射、經典全域)與程式碼將執行的地方相符
  • 一致性測試通過:generate(params) 和匯出的模組給出相同的指紋

14. 最小單一資產(當完整綱要過度時)

一個初始資產的大約 290 行程式碼主要是固定基礎設施(prng.ts、lowpoly.ts、params.ts),而非每個資產的成本。將它們作為共享模組撰寫一次,永遠不要將它們內聯到資產檔案中。對於一次性道具,跳過綱要和 resolveParams,保留 PRNG(確定性仍然重要),並僅使用實際使用的輔助函數進行匯出(helpers: [rawPrng, rawLowpoly])。一個完整的資產大約 30 行:

import * as THREE from 'three';
import { createPRNG } from './prng';
import { PartBuilder, lowPolyMaterial } from './lowpoly';
import { groundAsset } from './lifecycle';

export function buildCrateAsset(raw: { seed?: number; size?: number } = {}) {
  const seed = raw.seed ?? 42, size = Math.min(Math.max(Number(raw.size ?? 1) || 1, 0.3), 3);
  const rng = createPRNG(seed).fork('planks');
  const wood = new PartBuilder();
  wood.add(new THREE.BoxGeometry(size, size, size), () => (rng() < 0.5 ? '#8a6a45' : '#7a5c3b'));   // 每個面的顏色,自己的串流
  for (const s of [-1, 1])                                                                       // 角板條
    wood.add(new THREE.BoxGeometry(size * 0.08, size * 1.02, size * 1.02), '#5b4329', new THREE.Matrix4().makeTranslation(s * size * 0.46, 0, 0));
  const content = new THREE.Group();
  content.add(wood.build(lowPolyMaterial({ roughness: 0.9 }), { name: 'crate' }));
  return groundAsset(content);
}

一旦它獲得滑桿、預設集,或被用於複合體內部,就將其升級為完整綱要形式(第 1 節)。

15. 參考比對(當使用者提供影像、螢幕截圖或草圖時)

完整程序和腳本:references/reference-matching.md。規則依序為:

  1. 攝入一次。 查看參考一次,撰寫 ref-spec.md(最多 15 行:朝向、測量比例、零件、色盤、3 個標誌性特徵、超出範圍),執行 scripts/ref-intake.ts,查看遮罩 PNG 一次。之後,絕不重新讀取影像:根據規格和 ref.json 工作。
  2. 由粗到細建構,每一步後比較。 粗略草稿(G1 比例、G2 外觀)→ B 輪廓(每個視角的 G2 IoU ≥ 0.85)→ C 顏色(G3 色盤)→ D 細節(G4 標誌性特徵)。在每一步之後執行 scripts/ref-compare.ts;它只需不到一秒鐘。
  3. 數字先於圖片。 每輪僅修正第一個失敗的閘道,更改一個參數組,再次比較

… [為翻譯而截斷]

相關技能