Three.js プロシージャル生成ローポリアセットジェネレーター
このハーネスエディションは、ワークスペースとNode.jsを前提としています。バンドルされたビルダーとCLIゲートを使用して、実際のアセットから証拠を収集します。
すべてのアセット(単一またはコンポジット)を純粋でシード値に基づく関数として構築します。ライブプレビューとスタンドアロンコードエクスポートは同じ関数を呼び出すため、ユーザーが見たものがそのままエクスポートされます。
サーフェスの詳細: ソリッドマテリアルまたは頂点カラーから始めます。画像マップは、要求された、または可視化が必要な詳細に対してのみ追加します。オリジナルのアートワークが適切な場合は、セッションの画像ジェネレーターを使用し、その出力をビルダーへの固定入力として保持します。
プレビューの選択: ユーザーがモードを指定せずにプレビューを要求した場合、高速プレビュー(オービット、パン、テクスチャ確認、埋め込みクリップの再生またはスクラブ)とフルプレビュー(編集可能なパラメータ、リグ検査、アニメーション作成、または表情)を提供します。既に利用可能な高速結果がある場合はそれを共有し、要求されたモードを使用します。references/studio-preview.mdを参照してください。
ターゲット: three ≥ r170、ESモジュールとして。公式のマイグレーションノート(references/export.mdの§12)を通じてr187まで確認済み。
コードは 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 |
| 1つのアセット内の複数のサブアセット(§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 face、top)、ポート/スターボード/左/右では決して命名しない。これにより、ルールが軸と矛盾しない |
| 対称性 | 片側を構築し、PartBuilder.addまたはmirrorTris(§6.1)を使用してコピーをミラーリングする。負のスケールを持つ生のapplyMatrix4は、巻き方向を裏返しのままにする |
なぜこれが重要か:「bow = +Z」と「starboard = +X」をペアにすることは鏡像であり、そのペアから構築された船は側面が入れ替わります。前方+Zの場合、スターボードは−X、ポートは+Xです。
1. 1つのパイプライン、1つの真実の源
パラメータスキーマ(デフォルト値、範囲)→ resolveParams() → build…Asset() → THREE.Group
- デフォルト値と範囲はスキーマのみに存在します。
build…Asset(rawParams)はそれ自体でresolveParamsを呼び出します。3つの競合するデフォルト値(params.seed || 12345、スキーマdefault: 42、コンポジット?? 101)は、プレビュー、プリセット、およびエクスポートされたコードの不一致を引き起こします。 build…Assetは純粋です。同じ解決済みパラメータは同一のジオメトリを生成します。Math.random、Date.now、DOMアクセス、モジュールレベルの可変状態は使用しません。THREEは通常通りインポートします。THREEInstanceを注入しないでください。ヘルパーはモジュールインポートを使用するため、注入は半分しか機能せず、バグを隠します。エクスポートステップでインポート行を提供します(§11)。- すべてのビルダーとパラメータリストに一意の名前を付けます(
buildTreeAsset、treeParameters)。ジェネリックなbuildAssetは、コンポジットが2つのジェネレーターをインポートするとすぐに衝突します。 - カスタムジオメトリ(クリーチャー、ハル、ウィング)の場合、形状ロジックをプレーンなトライアングル配列上の純粋関数に保ち、THREEに最後に結果をラップさせます(§6.2)。プリミティブのみのプロパティは、直接
PartBuilder上に残すことができます。
型:src/types.ts(ParamDef、AssetGeneratorSchema)。
実例(ツリー):references/examples.md。
2. 決定論
再現可能な出力がシードのすべての目的なので、それを保護します:
- シードおよび任意の数値のフォールバックには、
||ではなく??を使用します。seed || 12345は、シード0を静かに12345に変換します。 - 各機能に独自のフォークされたストリームを与えます。1つの共有
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がビューツールで開かれ、パネルごとに1行ずつ見られた内容が記述され、UNVERIFIEDまたはnot checkedとしてリストされたすべてが回答に繰り返されるまで、アセットが完了したと報告しないでください。最後の実行のゲートテーブルで終了します。
決定論とパラメータ
- デフォルト値と範囲はスキーマのみに存在します。
build…AssetはresolveParamsを呼び出します - シードは
??を使用します。シード0は機能します。Math.randomやDate.nowは使用しません - 各機能には独自のフォークされたストリームがあります。トグルは他の部分をシャッフルしません
- 派生制約は縮退形状を防ぎます。サブシードはシード範囲内に収まります
リファレンス(ユーザーが画像を提供した場合のみ)
-
ref-spec.mdが一度作成され、ref.jsonが作成され、マスクPNGが確認されました。ref-compareがすべてのビルドステップ後に実行されます。ゲートテーブル(§15)が回答に含まれています
ジオメトリと外観
- 軸は§0に従います。面は軸で記述されます。前方=+Zの場合、右=−Xです
- カスタムジオメトリは正の
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があります。ラフネス/バンプマップは
roughness: 1のNoColorSpaceです - アトラスはフォークされたストリーム(
seededAtlas)から生成されるか、パラメータとして注入されます。ビルダーはファイルをロードしたり、DOMに触れたりしません - 面取りおよび彫刻されたパーツは正の
signedVolumeを持ちます。彫刻量は半径>0を維持します - AOは1回適用され(リグの場合はパーツごとに
aoShade、静的マージの場合はapplyAO)、0.35のフロアより暗くなることはありません - 小さな詳細は
raycastTris/scatterOnSurface+sink付きのplaceTrisから取得されます。ミラーリングされた側はmirrorHitを使用します
コンポジット
- 一意のエクスポートされたビルダー名。パラメータは名前空間化され、
pickParamsでスライスされます - 配置はフットプリント、固定優先順位、および制限付き試行を使用します
- スキップされたアイテムは決定論的です。繰り返されるオブジェクトはクローンまたはインスタンス化されます
QA(すべてのアセット)
-
scripts/qa-asset.tsが現在のビルドでexit 0。review.pngが表示され、パネルごとに1つの所見。UNVERIFIEDアイテムがリストされています。回答にゲートテーブルが含まれています
ライフサイクルとエクスポート
- ラッパーグループはアセットをY = 0にグラウンディングします。
disposeAssetはすべてのリビルドで呼び出されます - メッシュには名前が付けられています。トライアングル数は予算内です
- エクスポーターは実際のTSトランスパイラを使用し、ヘルパーを1回含み、
three(mergeGeometriesが使用される場合のみthree/addons)を除いてインポートがゼロです - GLBが要求された場合:§16でエクスポートパスを選択します。ファイル、そのバイトに対して実行されたチェック、および未チェックのビジュアルまたはインポートステージを報告します。
- プラットフォームが指定された、または
detailが追加された場合:scripts/mesh-stats.ts(LODの場合は--lods)がexit 0し、プロファイルと種類が名前付けされ、not checkedが繰り返されます。detailデフォルトの2は既存のアセットを変更しません - エクスポートターゲット(モジュール、インポートマップ、クラシックグローバル)は、コードが実行される場所と一致します
- パリティテストがパスします:
generate(params)とエクスポートされたモジュールは同じフィンガープリントを提供します
14. 最小限の単一アセット(完全なスキーマが過剰な場合)
最初のアセットの約290行は、ほとんどが固定インフラストラクチャ(prng.ts、lowpoly.ts、params.ts)であり、アセットごとのコストではありません。これらを共有モジュールとして一度作成し、アセットファイルにインライン化しないでください。1回限りの小道具の場合、スキーマと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を実行します。1秒もかかりません。 - 画像の前に数値。 ラウンドごとに最初に失敗したゲートのみを修正し、1つのパラメータグループを変更し、再度比較します。
…
[翻訳のため一部省略]