Community画像github.com

threejs-asset-generator

Three.js r170+向けのプロシージャル生成によるローポリ3Dアセットジェネレーターです。シード値に基づく決定論的なビルダー、パラメータスキーマ、フラットシェーディングの頂点カラーメッシュ、正しい巻き方向のカスタムジオメトリ、ミラーパーツ、リギングされた二足歩行およびクリーチャーカーネル、コンポジット、テクスチャ、スタンドアロンコードエクスポート、リファレンス画像との一致を特徴とします。glTFファイルの読み込みには対応していません。

threejs-asset-generator とは?

このスキルは、Three.js (r170以上) で動作する、プロシージャル生成によるローポリ3Dアセットを構築するための包括的なフレームワークです。主な特徴として、シード値による決定論的な生成、フラットシェーディングと頂点カラーを使用したメッシュ、正しい巻き方向のカスタムジオメトリ、ミラーパーツ、リギングされた二足歩行やクリーチャー、複数のサブアセットからなるコンポジット、テクスチャマッピング、スタンドアロンコードのエクスポート機能、そしてリファレンス画像との一致を検証する機能を備えています。このスキルは、Claude CodeやCursorなどのAIエージェントで使用することを想定して設計されており、開発者はスキルの指示に従って、一貫性のある高品質な3Dアセットを効率的に生成できます。また、QAゲートやリファレンスマッチング機能により、生成されたアセットの品質を自動的に検証できます。

対応~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に質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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.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
1つのアセット内の複数のサブアセット(§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 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。ルールは順に:

  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を実行します。1秒もかかりません。
  3. 画像の前に数値。 ラウンドごとに最初に失敗したゲートのみを修正し、1つのパラメータグループを変更し、再度比較します。

…

[翻訳のため一部省略]

関連スキル