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.md | src/lowpoly.ts, src/jitter.ts |
| 自訂幾何、纏繞、鏡像零件、覆蓋層(第 6、7 節) | references/geometry.md | src/geometry.ts, src/overlay.ts |
| 生物、船體、機翼、純三角形核心(第 6.2、6.3 節) | references/creatures.md | src/tri.ts, src/organic.ts |
| 任何動畫、人形、擠出、紋理(第 6.4 至 6.7 節) | references/rigging-biped.md | src/rig.ts, src/biped.ts, src/texture.ts |
| 平面或塊狀外觀、圖集、導角、AO、插槽(第 6.8 節) | references/detail.md | src/detail.ts, src/detailThree.ts |
| 一個複合體中的多個子資產(第 8 節) | references/composite.md | |
| 接地、銷毀、重建、燈光(第 9、10 節) | references/lifecycle.md | src/lifecycle.ts |
| 程式碼匯出、Three.js 版本(第 11、12 節) | references/export.md | src/fingerprint.ts |
資產的 .glb 檔案(第 16 節) | references/glb-export.md | scripts/export-glb.ts |
是否太重、平台預算、LOD detail(第 17 節) | references/budget.md | scripts/mesh-stats.ts, src/lod.ts |
| 骨架、動畫片段、漂移、表情(第 18 節) | references/rig-check.md | scripts/rig-check.ts |
| 快速 GLB 檢視器或完整預覽工作室 | references/studio-preview.md | 快速預覽 HTML |
| 完整小型範例 | references/examples.md | |
| 在說資產完成之前:QA 閘道、審查影像(第 13 節) | references/qa-gates.md | scripts/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。規則依序為:
- 攝入一次。 查看參考一次,撰寫
ref-spec.md(最多 15 行:朝向、測量比例、零件、色盤、3 個標誌性特徵、超出範圍),執行scripts/ref-intake.ts,查看遮罩 PNG 一次。之後,絕不重新讀取影像:根據規格和ref.json工作。 - 由粗到細建構,每一步後比較。 粗略草稿(G1 比例、G2 外觀)→ B 輪廓(每個視角的 G2 IoU ≥ 0.85)→ C 顏色(G3 色盤)→ D 細節(G4 標誌性特徵)。在每一步之後執行
scripts/ref-compare.ts;它只需不到一秒鐘。 - 數字先於圖片。 每輪僅修正第一個失敗的閘道,更改一個參數組,再次比較
… [為翻譯而截斷]