CommunityImagegithub.com

générateur-d-assets-threejs

Génère procéduralement des assets 3D low-poly dans Three.js r170+ avec des constructeurs déterministes basés sur une graine, des schémas de paramètres, des maillages à couleurs par sommet et arêtes vives, des géométries personnalisées, des pièces en miroir, des squelettes bipèdes et de créatures, des composites, des textures, une exportation de code autonome et la correspondance avec une image de référence. Ne sert pas à charger des fichiers glTF.

Qu'est-ce que générateur-d-assets-threejs ?

Ce skill est un générateur procédural d'actifs 3D low-poly pour Three.js (version r170 et supérieure). Il est particulièrement utile pour les développeurs et artistes techniques qui souhaitent créer des actifs 3D reproductibles et déterministes, idéal pour la génération de contenu procédural, les jeux de type 'voxel' ou low-poly, ou pour expérimenter avec Three.js. Le skill prend en charge une large gamme de fonctionnalités : la génération de géométries personnalisées (avec des enroulements corrects, des pièces en miroir, et des parties rigides), la création de créatures et de bipèdes avec des systèmes de squelette, les textures procédurales, l'exportation de code autonome, et la correspondance avec une image de référence pour la reproduction visuelle. Il s'appuie sur un pipeline basé sur des constructeurs purs qui prennent une graine déterministe, garantissant que les mêmes paramètres produisent toujours exactement le même rendu. Les actifs sont construits comme des fonctions pures utilisant un générateur de nombres aléatoires déterministe. Le skill inclut des scripts d'assurance qualité (gates) pour valider la géométrie, les couleurs, les contraintes de paramètres et l'exportation de code, ce qui en fait un outil professionnel et fiable pour les projets de développement nécessitant des actifs 3D cohérents.

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

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Générateur d'Actifs Low-Poly Procéduraux pour Three.js

Cette édition de harnais suppose un espace de travail et Node.js. Utilisez les constructeurs fournis et les portes CLI pour collecter des preuves sur l'actif réel.

Construisez chaque actif (simple ou composite) comme une fonction pure et basée sur une graine. L'aperçu en direct et l'exportation de code autonome appellent cette même fonction, donc ce que l'utilisateur voit est ce qu'il exporte.

Détail de surface : Commencez par un matériau solide ou des couleurs par sommet. Ajoutez une carte d'image uniquement pour un détail demandé ou visible qui en a besoin. Utilisez le générateur d'images de la session lorsque l'œuvre originale est la bonne solution, puis conservez sa sortie comme entrée fixe du constructeur.

Choix de l'aperçu : Lorsque l'utilisateur demande un aperçu sans choisir de mode, proposez Aperçu Rapide (orbite, panoramique, vérifiez les textures, lisez ou scrutez les clips intégrés) et Aperçu Complet (paramètres modifiables, inspection du squelette, création d'animations, ou expressions). Partagez un résultat rapide s'il est déjà disponible et utilisez le mode demandé. Voir references/studio-preview.md.

Cible : three ≥ r170 en tant que modules ES, vérifié par rapport aux notes de migration officielles jusqu'à r187 (§12 dans references/export.md).

Le code est dans src/, pas dans la documentation. Exécutez, ne relisez pas : tsx src/<nom>.test.ts (les tests purs n'ont pas besoin de three). Les fichiers de référence listent l'API de chaque module.

Image de référence donnée ? Lisez references/reference-matching.md AVANT d'écrire du code et exécutez sa boucle après chaque étape de construction (§15).

Où lire ensuite

Vous faitesLisezCode
Matériaux, ombrage plat, textures procédurales ou générées par image, jitter de sommets (§4, §5)references/look.mdsrc/lowpoly.ts, src/jitter.ts
Géométrie personnalisée, enroulement, pièces en miroir, superpositions (§6, §7)references/geometry.mdsrc/geometry.ts, src/overlay.ts
Créature, coque, aile, noyau de triangle pur (§6.2, §6.3)references/creatures.mdsrc/tri.ts, src/organic.ts
Tout ce qui s'anime, humanoïde, extrusion, texture (§6.4 à §6.7)references/rigging-biped.mdsrc/rig.ts, src/biped.ts, src/texture.ts
Aspect plat ou bloc, atlas, chanfrein, AO, sockets (§6.8)references/detail.mdsrc/detail.ts, src/detailThree.ts
Plusieurs sous-actifs en un (§8)references/composite.md
Mise à la terre, suppression, reconstructions, lumières (§9, §10)references/lifecycle.mdsrc/lifecycle.ts
Exportation de code, versions de Three.js (§11, §12)references/export.mdsrc/fingerprint.ts
Un fichier .glb de l'actif (§16)references/glb-export.mdscripts/export-glb.ts
Est-ce trop lourd, budget de plateforme, LOD detail (§17)references/budget.mdscripts/mesh-stats.ts, src/lod.ts
Squelette, clips d'animation, dérive, expressions (§18)references/rig-check.mdscripts/rig-check.ts
Aperçu GLB rapide ou studio d'aperçu completreferences/studio-preview.mdAperçu rapide HTML
Exemple complet et petitreferences/examples.md
Avant de dire qu'un actif est terminé : portes QA, image de révision (§13)references/qa-gates.mdscripts/qa-asset.ts

0. Conventions (décider une fois, appliquer partout)

SujetRègle
Unités1 unité = 1 mètre
AxesY vers le haut, système droitier
Avant+Z (comme glTF et Object3D.lookAt)
CôtésAvec avant = +Z et haut = +Y, la droite de l'actif est −X et sa gauche est +X (droite = avant × haut)
PivotOrigine au centre de l'empreinte, point le plus bas à Y = 0 (voir §9)
Noms des facesNommez les faces par axe (face +X, dessus), jamais par bâbord/tribord/gauche/droite, afin qu'une règle ne puisse pas contredire les axes
SymétrieConstruisez un côté, miroir de la copie via PartBuilder.add ou mirrorTris (§6.1). Un simple applyMatrix4 avec une échelle négative laisse l'enroulement à l'envers

Pourquoi c'est important : associer "proue = +Z" avec "tribord = +X" est inversé, et un navire construit avec cette association a ses côtés échangés. Avec avant = +Z, tribord est −X et bâbord est +X.

1. Un seul pipeline, une seule source de vérité

schéma de paramètres (valeurs par défaut, plages) → resolveParams() → build…Asset() → THREE.Group
  • Les valeurs par défaut et les plages vivent uniquement dans le schéma. build…Asset(rawParams) appelle resolveParams lui-même. Trois valeurs par défaut concurrentes (params.seed || 12345, schema default: 42, composite ?? 101) font que l'aperçu, les préréglages et le code exporté ne sont pas d'accord.
  • build…Asset est pure : les mêmes paramètres résolus donnent une géométrie identique. Pas de Math.random, Date.now, accès DOM ou état mutable au niveau du module.
  • Importez THREE normalement. N'injectez pas de THREEInstance : les aides utilisent l'import du module, donc l'injection ne fonctionne qu'à moitié et cache les bogues. L'étape d'exportation fournit la ligne d'import (§11).
  • Donnez à chaque constructeur et liste de paramètres un nom unique (buildTreeAsset, treeParameters). Un buildAsset générique entre en collision dès qu'un composite importe deux générateurs.
  • Pour les géométries personnalisées (créatures, coques, ailes), gardez la logique de forme dans des fonctions pures sur des tableaux de triangles simples et laissez THREE envelopper le résultat à la fin (§6.2). Les propriétés à base de primitives peuvent rester directement sur PartBuilder.

Types : src/types.ts (ParamDef, AssetGeneratorSchema).

Exemple commenté (arbre) : references/examples.md.

2. Déterminisme

La sortie reproductible est le but même d'une graine, alors protégez-la :

  • Utilisez ??, jamais ||, pour les graines et toute valeur de repli numérique. seed || 12345 transforme silencieusement la graine 0 en 12345.
  • Donnez à chaque fonctionnalité son propre flux bifurqué. Avec un seul rng partagé, changer segments ou basculer hasFruits décale chaque nombre aléatoire ultérieur et remanie des parties non liées de l'actif.
  • Itérez dans un ordre fixe (tableaux, pas de clés d'objet d'ordre inconnu, pas de Set d'insertion mixte).

Code : src/prng.ts. API :

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

3. Paramètres

resolveParams applique les valeurs par défaut, convertit les types, limite à min/max, ajuste à step, et rejette les mauvaises couleurs et sélections. Utilisez-le dans l'interface utilisateur, dans les préréglages et dans build…Asset, de sorte qu'aucun consommateur ne puisse produire de NaN ou de géométrie hors plage.

Code : src/params.ts. API :

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

  • Après résolution, appliquez des contraintes dérivées afin que les combinaisons de curseurs ne puissent pas produire de formes dégénérées (par exemple trunkRadius = Math.min(trunkRadius, crownRadius * 0.6)).

  • Gardez la graine seed max à 99999 ou plus. Les constructeurs composites dérivent des sous-graines comme fork(label).seed % 100000 ; un max plus petit les limiterait tous à la même valeur.

  • Les bascules (hasFruits, hasTurrets) changent ce qui est construit, jamais les nombres aléatoires que les autres parties reçoivent (§2).

  • Les bascules de détail (aoStrength, bevel, atlasOn) sont des paramètres ordinaires. Elles modifient ce que la passe de détail ajoute, jamais les nombres aléatoires que les autres parties reçoivent.

  • Le flux de l'atlas est bifurqué. Générez des atlas à partir de rng.fork('atlas'), afin que basculer atlasOn laisse toutes les autres parties inchangées (references/detail.md).

13. Liste de contrôle (cocher par actif, ne pas expédier pré-coché)

Exécutez les portes, puis regardez. npx tsx scripts/qa-asset.ts --module ./kernel.ts --export buildXTris --symmetric pour un noyau pur, ou --tris tris.json pour l'actif final mis à la terre (utilisation et liste des portes : references/qa-gates.md). Il imprime Q1 à Q10, écrit review.png et se termine par une ligne @@RESULT. Corrigez la première porte qui échoue et relancez.

Règle de fin. Ne rapportez jamais un actif comme terminé tant que qa-asset n'a pas réussi sur la construction actuelle (ou que chaque porte ayant échoué n'est pas nommée avec sa raison), que review.png n'a pas été ouvert avec l'outil de visualisation et qu'une ligne par panneau indique ce qui a été vu, et que tout ce qui est listé comme NON VÉRIFIÉ ou non vérifié n'est pas répété dans la réponse. Terminez par le tableau des portes de la dernière exécution.

Déterminisme et paramètres

  • Les valeurs par défaut et les plages existent uniquement dans le schéma ; build…Asset appelle resolveParams
  • Les graines utilisent ?? ; la graine 0 fonctionne ; pas de Math.random ou Date.now
  • Chaque fonctionnalité a son propre flux bifurqué ; les bascules ne remanient pas les autres parties
  • Les contraintes dérivées empêchent les formes dégénérées ; les sous-graines correspondent à la plage de graines

Référence (uniquement lorsque l'utilisateur a donné une image)

  • ref-spec.md écrit une fois, ref.json créé, PNG du masque vérifié ; ref-compare exécuté après chaque étape de construction ; le tableau des portes (§15) est dans la réponse

Géométrie et aspect

  • Les axes suivent le §0 ; les faces décrites par axe ; droite = −X lorsque avant = +Z
  • La géométrie personnalisée a un signedVolume positif, également après mise en miroir ; DoubleSide uniquement sur les feuilles d'épaisseur nulle
  • Les parties mises en miroir passent par add()/addTris ou mirrorTris, jamais par un simple applyMatrix4 avec échelle négative
  • Les formes de géométrie personnalisée et de créature vivent dans des noyaux de triangle purs avec des tests Node (déterminisme, volume signé, isolation du flux)
  • Les parties passent par bakeFlat + paint ; les fonctions de couleur par triangle sont pures
  • Le jitter est appliqué avant add(), soudé aux coutures, avec des volumes limites recalculés
  • Les parties métalliques ont une carte d'environnement ou une metalness réduite
  • Les superpositions utilisent un retrait à distance constante et un petit soulèvement contre le z-fighting

Squelette, humanoïdes, textures (uniquement lorsqu'ils s'appliquent)

  • Les parties mobiles sont des os de RigBuilder, créés en pose de repos ; les parties statiques restent fusionnées ; os ≤ environ 12
  • Les os gauche/droit proviennent de mirrorBone + une matrice miroir ; les clips utilisent AnimationMixer sur la racine du squelette
  • Les chaînes de membres passent par twoBoneIK ou des chaînes à points fixes ; les pieds et les mains ont un avant/haut explicite
  • Les parties extrudées et profilées ont un signedVolume positif, également après mise en miroir
  • L'UV est désactivé sauf si une texture est utilisée ; avec une texture, PartBuilder({ uv }) est défini pour chaque partie de ce matériau et disposeAsset libère map

Passe de détail (uniquement lorsqu'elle s'applique)

  • Les cellules de l'atlas suivent la convention (cellule 0 en haut à gauche) ; chaque partie d'un matériau texturé a des uv ; les cartes de rugosité/bump sont NoColorSpace avec roughness: 1
  • L'atlas est généré à partir d'un flux bifurqué (seededAtlas), ou injecté comme paramètre ; le constructeur ne charge jamais de fichiers ni ne touche au DOM
  • Les parties chanfreinées et sculptées ont un signedVolume positif ; les quantités de sculpture maintiennent des rayons > 0
  • L'AO est appliquée une fois (aoShade par partie pour les squelettes, applyAO pour les fusions statiques) et jamais plus sombre que le seuil de 0.35
  • Les petits détails proviennent de raycastTris/scatterOnSurface + placeTris avec sink ; le côté miroir utilise mirrorHit

Composite

  • Noms de constructeurs exportés uniques ; paramètres nommés et découpés avec pickParams
  • Le placement utilise les empreintes, un ordre de priorité fixe et des tentatives limitées
  • Les éléments ignorés sont déterministes ; les objets répétés sont clonés ou instanciés

QA (chaque actif)

  • scripts/qa-asset.ts exit 0 sur la construction actuelle ; review.png consulté, une constatation par panneau ; éléments NON VÉRIFIÉS listés ; tableau des portes dans la réponse

Cycle de vie et exportation

  • Le groupe d'emballage met l'actif à la terre à Y = 0 ; disposeAsset est appelé lors de chaque reconstruction
  • Les maillages sont nommés ; le nombre de triangles est dans le budget
  • L'exportateur utilise un véritable transpileur TS, inclut les aides une fois et a zéro import sauf three (three/addons uniquement si mergeGeometries est utilisé)
  • Si GLB est demandé : choisissez le chemin d'exportation au §16. Rapportez le fichier, les vérifications effectuées sur ses octets et toutes les étapes visuelles ou d'import non vérifiées.
  • Plateforme donnée ou detail ajouté : scripts/mesh-stats.ts (--lods pour LOD) exit 0, profil et type nommés, non vérifié répété ; la valeur par défaut de detail à 2 laisse l'actif existant inchangé
  • La cible d'exportation (module, import map, global classique) correspond à l'endroit où le code s'exécutera
  • Le test de parité réussit : generate(params) et le module exporté donnent la même empreinte digitale

14. Actif simple minimal (quand un schéma complet est excessif)

Les ~290 lignes d'un premier actif sont principalement de l'infrastructure fixe (prng.ts, lowpoly.ts, params.ts), pas un coût par actif. Écrivez-les une fois en tant que modules partagés et ne les inlinez jamais dans un fichier d'actif. Pour un accessoire unique, ignorez le schéma et resolveParams, gardez le PRNG (le déterminisme compte toujours), et exportez avec seulement les aides réellement utilisées (helpers: [rawPrng, rawLowpoly]). Un actif complet fait alors environ 30 lignes :

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'));   // couleur par face, propre flux
  for (const s of [-1, 1])                                                                       // coins de caisse
    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);
}

Promouvez-le vers le formulaire de schéma complet (§1) dès qu'il obtient des curseurs, des préréglages, ou est utilisé à l'intérieur d'un composite.

15. Correspondance de référence (lorsque l'utilisateur donne une image, une capture d'écran ou un croquis)

Procédure complète et scripts : references/reference-matching.md. Les règles, dans l'ordre :

  1. Réception une fois. Visualisez la référence une fois, écrivez ref-spec.md (max 15 lignes : orientation, proportions mesurées, parties, palette, 3 caractéristiques distinctives, hors de portée), exécutez scripts/ref-intake.ts, regardez le PNG du masque une fois. Après cela, ne relisez jamais l'image : travaillez à partir de la spécification et de ref.json.
  2. Construisez du grossier au fin, comparez après chaque étape. Un blocage (proportions G1, aspect G2) → silhouette B (IoU G2 ≥ 0.85 par vue) → couleur C (palette G3) → détail D (caractéristiques distinctives G4). Exécutez scripts/ref-compare.ts après chaque étape ; cela prend moins d'une seconde.
  3. Les chiffres avant les images. Corrigez uniquement la PREMIÈRE porte qui échoue par tour, changez un groupe de paramètres, comparez à nouveau

…

[Le contenu a été tronqué pour la traduction]

Skills associés