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 faites | Lisez | Code |
|---|---|---|
| Matériaux, ombrage plat, textures procédurales ou générées par image, jitter de sommets (§4, §5) | references/look.md | src/lowpoly.ts, src/jitter.ts |
| Géométrie personnalisée, enroulement, pièces en miroir, superpositions (§6, §7) | references/geometry.md | src/geometry.ts, src/overlay.ts |
| Créature, coque, aile, noyau de triangle pur (§6.2, §6.3) | references/creatures.md | src/tri.ts, src/organic.ts |
| Tout ce qui s'anime, humanoïde, extrusion, texture (§6.4 à §6.7) | references/rigging-biped.md | src/rig.ts, src/biped.ts, src/texture.ts |
| Aspect plat ou bloc, atlas, chanfrein, AO, sockets (§6.8) | references/detail.md | src/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.md | src/lifecycle.ts |
| Exportation de code, versions de Three.js (§11, §12) | references/export.md | src/fingerprint.ts |
Un fichier .glb de l'actif (§16) | references/glb-export.md | scripts/export-glb.ts |
Est-ce trop lourd, budget de plateforme, LOD detail (§17) | references/budget.md | scripts/mesh-stats.ts, src/lod.ts |
| Squelette, clips d'animation, dérive, expressions (§18) | references/rig-check.md | scripts/rig-check.ts |
| Aperçu GLB rapide ou studio d'aperçu complet | references/studio-preview.md | Aperçu rapide HTML |
| Exemple complet et petit | references/examples.md | |
| Avant de dire qu'un actif est terminé : portes QA, image de révision (§13) | references/qa-gates.md | scripts/qa-asset.ts |
0. Conventions (décider une fois, appliquer partout)
| Sujet | Règle |
|---|---|
| Unités | 1 unité = 1 mètre |
| Axes | Y vers le haut, système droitier |
| Avant | +Z (comme glTF et Object3D.lookAt) |
| Côtés | Avec avant = +Z et haut = +Y, la droite de l'actif est −X et sa gauche est +X (droite = avant × haut) |
| Pivot | Origine au centre de l'empreinte, point le plus bas à Y = 0 (voir §9) |
| Noms des faces | Nommez 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étrie | Construisez 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)appelleresolveParamslui-même. Trois valeurs par défaut concurrentes (params.seed || 12345, schemadefault: 42, composite?? 101) font que l'aperçu, les préréglages et le code exporté ne sont pas d'accord. build…Assetest pure : les mêmes paramètres résolus donnent une géométrie identique. Pas deMath.random,Date.now, accès DOM ou état mutable au niveau du module.- Importez
THREEnormalement. N'injectez pas deTHREEInstance: 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). UnbuildAssetgé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 || 12345transforme silencieusement la graine0en12345. - Donnez à chaque fonctionnalité son propre flux bifurqué. Avec un seul
rngpartagé, changersegmentsou basculerhasFruitsdé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
Setd'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
seedmax à 99999 ou plus. Les constructeurs composites dérivent des sous-graines commefork(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 basculeratlasOnlaisse 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…AssetappelleresolveParams - Les graines utilisent
??; la graine0fonctionne ; pas deMath.randomouDate.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.jsoncréé, PNG du masque vérifié ;ref-compareexé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
signedVolumepositif, également après mise en miroir ;DoubleSideuniquement sur les feuilles d'épaisseur nulle - Les parties mises en miroir passent par
add()/addTrisoumirrorTris, jamais par un simpleapplyMatrix4avec é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
metalnessré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 utilisentAnimationMixersur la racine du squelette - Les chaînes de membres passent par
twoBoneIKou des chaînes à points fixes ; les pieds et les mains ont un avant/haut explicite - Les parties extrudées et profilées ont un
signedVolumepositif, é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 etdisposeAssetlibèremap
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
NoColorSpaceavecroughness: 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
signedVolumepositif ; les quantités de sculpture maintiennent des rayons > 0 - L'AO est appliquée une fois (
aoShadepar partie pour les squelettes,applyAOpour les fusions statiques) et jamais plus sombre que le seuil de 0.35 - Les petits détails proviennent de
raycastTris/scatterOnSurface+placeTrisavecsink; le côté miroir utilisemirrorHit
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.tsexit 0 sur la construction actuelle ;review.pngconsulté, 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 ;
disposeAssetest 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/addonsuniquement simergeGeometriesest 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
detailajouté :scripts/mesh-stats.ts(--lodspour LOD) exit 0, profil et type nommés,non vérifiérépété ; la valeur par défaut dedetailà 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 :
- 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écutezscripts/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 deref.json. - 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.tsaprès chaque étape ; cela prend moins d'une seconde. - 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]