Three.js Prozeduraler Low-Poly-Asset-Generator
Diese Harness-Edition setzt einen Workspace und Node.js voraus. Verwenden Sie die gebündelten Builder und CLI-Gates, um Beweise aus dem tatsächlichen Asset zu sammeln.
Erstellen Sie jedes Asset (einzeln oder zusammengesetzt) als reine, seed-basierte Funktion. Die Live-Vorschau und der Standalone-Code-Export rufen dieselbe Funktion auf, sodass das, was der Benutzer sieht, auch das ist, was exportiert wird.
Oberflächendetail: Beginnen Sie mit einem Vollmaterial oder Vertexfarben. Fügen Sie eine Bildkarte nur für ein angefordertes oder sichtbares Detail hinzu, das eine solche benötigt. Verwenden Sie den Bildgenerator der Sitzung, wenn Originalgrafik die richtige Wahl ist, und behalten Sie dessen Ausgabe als feste Eingabe für den Builder bei.
Vorschauwahl: Wenn der Benutzer nach einer Vorschau fragt, ohne einen Modus zu wählen, bieten Sie Schnelle Vorschau (Orbit, Schwenken, Texturen prüfen, eingebettete Clips abspielen oder durchsuchen) und Vollvorschau (editierbare Parameter, Rig-Inspektion, Animationserstellung oder Ausdrücke). Teilen Sie ein schnelles Ergebnis, falls bereits vorhanden, und verwenden Sie den angeforderten Modus. Siehe references/studio-preview.md.
Ziel: three ≥ r170 als ES-Module, geprüft gegen die offiziellen Migrationshinweise bis r187 (§12 in references/export.md).
Code befindet sich in src/, nicht in der Dokumentation. Führen Sie aus, lesen Sie nicht erneut: tsx src/<name>.test.ts (reine Tests benötigen kein three). Referenzdateien listen die API jedes Moduls auf.
Referenzbild gegeben? Lesen Sie references/reference-matching.md VOR dem Schreiben von Code und führen Sie dessen Schleife nach jedem Build-Schritt aus (§15).
Wo als nächstes lesen
| Sie arbeiten an | Lesen Sie | Code |
|---|---|---|
| Materialien, Flat Shading, prozedurale oder bildgenerierte Texturen, Vertex-Jitter (§4, §5) | references/look.md | src/lowpoly.ts, src/jitter.ts |
| Benutzerdefinierte Geometrie, Windung, gespiegelte Teile, Overlays (§6, §7) | references/geometry.md | src/geometry.ts, src/overlay.ts |
| Kreatur, Rumpf, Flügel, reiner Dreieckskernel (§6.2, §6.3) | references/creatures.md | src/tri.ts, src/organic.ts |
| Alles, was animiert, humanoid, extrudiert, Textur (§6.4 bis §6.7) | references/rigging-biped.md | src/rig.ts, src/biped.ts, src/texture.ts |
| Flaches oder klotziges Aussehen, Atlas, Fase, AO, Sockets (§6.8) | references/detail.md | src/detail.ts, src/detailThree.ts |
| Mehrere Unter-Assets in einem (§8) | references/composite.md | |
| Erdung, Entsorgung, Neubauten, Lichter (§9, §10) | references/lifecycle.md | src/lifecycle.ts |
| Code-Export, Three.js-Versionen (§11, §12) | references/export.md | src/fingerprint.ts |
Eine .glb-Datei des Assets (§16) | references/glb-export.md | scripts/export-glb.ts |
Ist es zu schwer, Plattformbudget, LOD detail (§17) | references/budget.md | scripts/mesh-stats.ts, src/lod.ts |
| Rig, Animationsclips, Drift, Ausdrücke (§18) | references/rig-check.md | scripts/rig-check.ts |
| Schneller GLB-Viewer oder Vollvorschau-Studio | references/studio-preview.md | Schnelle Vorschau HTML |
| Vollständiges kleines Beispiel | references/examples.md | |
| Bevor Sie ein Asset als fertig melden: QA-Gates, Überprüfungsbild (§13) | references/qa-gates.md | scripts/qa-asset.ts |
0. Konventionen (einmal festlegen, überall anwenden)
| Thema | Regel |
|---|---|
| Einheiten | 1 Einheit = 1 Meter |
| Achsen | Y nach oben, rechtshändig |
| Vorwärts | +Z (wie bei glTF und Object3D.lookAt) |
| Seiten | Mit Vorwärts +Z und Oben +Y ist die rechte Seite des Assets −X und die linke Seite +X (rechts = vorwärts × oben) |
| Drehpunkt | Ursprung im Fußabdruckmittelpunkt, tiefster Punkt bei Y = 0 (siehe §9) |
| Flächennamen | Benennen Sie Flächen nach Achsen (+X-Fläche, Oberseite), niemals nach Backbord/Steuerbord/Links/Rechts, damit eine Regel nicht den Achsen widersprechen kann |
| Symmetrie | Bauen Sie eine Seite, spiegeln Sie die Kopie durch PartBuilder.add oder mirrorTris (§6.1). Ein nacktes applyMatrix4 mit negativer Skalierung lässt die Windung innen-außen zurück |
Warum das wichtig ist: die Paarung „Bug = +Z“ mit „Steuerbord = +X“ ist gespiegelt, und ein daraus gebautes Schiff hat vertauschte Seiten. Mit Vorwärts +Z ist Steuerbord −X und Backbord +X.
1. Eine Pipeline, eine Quelle der Wahrheit
Parameterschema (Vorgaben, Bereiche) → resolveParams() → build…Asset() → THREE.Group
- Vorgaben und Bereiche leben nur im Schema.
build…Asset(rawParams)ruftresolveParamsselbst auf. Drei konkurrierende Vorgaben (params.seed || 12345, Schemadefault: 42, Composite?? 101) führen dazu, dass Vorschau, Voreinstellungen und exportierter Code nicht übereinstimmen. build…Assetist rein: gleiche aufgelöste Parameter ergeben identische Geometrie. KeinMath.random,Date.now, DOM-Zugriff oder veränderlicher Zustand auf Modulebene.- Importieren Sie
THREEnormal. Injizieren Sie keineTHREEInstance: Helfer verwenden den Modulimport, daher funktioniert die Injektion nur halb und verbirgt Fehler. Der Exportschritt liefert die Importzeile (§11). - Geben Sie jedem Builder und jeder Parameterliste einen eindeutigen Namen (
buildTreeAsset,treeParameters). Ein generischesbuildAssetkollidiert, sobald ein Composite zwei Generatoren importiert. - Halten Sie für benutzerdefinierte Geometrie (Kreaturen, Rümpfe, Flügel) die Shape-Logik in reinen Funktionen über einfache Dreiecks-Arrays und lassen Sie THREE das Ergebnis am Ende wrappen (§6.2). Nur-Primitive-Props können direkt auf
PartBuilderbleiben.
Typen: src/types.ts (ParamDef, AssetGeneratorSchema).
Ausgearbeitetes Beispiel (Baum): references/examples.md.
2. Determinismus
Reproduzierbare Ausgabe ist der ganze Sinn eines Seeds, also schützen Sie ihn:
- Verwenden Sie
??, niemals||, für Seeds und jeden numerischen Fallback.seed || 12345verwandelt Seed0stillschweigend in12345. - Geben Sie jeder Funktion ihren eigenen verzweigten Stream. Bei einem gemeinsamen
rngverschiebt das Ändern vonsegmentsoder das Umschalten vonhasFruitsjede spätere Zufallszahl und mischt nicht zusammenhängende Teile des Assets neu. - Iterieren Sie in einer festen Reihenfolge (Arrays, nicht Objektschlüssel unbekannter Reihenfolge, nicht
Setgemischter Einfügungen).
Code: src/prng.ts. API:
export function hashString(str: string)export function createPRNG(seed = 1)export type Rng = ReturnType<typeof createPRNG>;
3. Parameter
resolveParams wendet Vorgaben an, erzwingt Typen, begrenzt auf min/max, rastet auf step ein und lehnt schlechte Farben und Auswahlen ab. Verwenden Sie es in der Benutzeroberfläche, in Voreinstellungen und in build…Asset, sodass kein Verbraucher NaN oder Geometrie außerhalb des Bereichs erzeugen kann.
Code: src/params.ts. API:
-
export function resolveParams(schema: { parameters: ParamDef[] }, input: Record<string, unknown> = {}) -
Wenden Sie nach der Auflösung abgeleitete Einschränkungen an, damit Schiebereglerkombinationen keine degenerierten Formen erzeugen können (z. B.
trunkRadius = Math.min(trunkRadius, crownRadius * 0.6)). -
Halten Sie das
seed-Maximum bei 99999 oder höher. Composite-Builder leiten Sub-Seeds alsfork(label).seed % 100000ab; ein kleineres Maximum würde sie alle auf den gleichen Wert begrenzen. -
Umschalter (
hasFruits,hasTurrets) ändern, was gebaut wird, niemals, welche Zufallszahlen die anderen Teile erhalten (§2). -
Detail-Umschalter (
aoStrength,bevel,atlasOn) sind gewöhnliche Parameter. Sie ändern, was der Detaildurchgang hinzufügt, niemals, welche Zufallszahlen andere Teile erhalten. -
Atlas-Stream wird verzweigt. Generieren Sie Atlanten aus
rng.fork('atlas'), sodass das Umschalten vonatlasOnjeden anderen Teil unverändert lässt (references/detail.md).
13. Checkliste (pro Asset abhaken, nicht vorab abgehakt ausliefern)
Führen Sie die Gates aus, dann schauen Sie. npx tsx scripts/qa-asset.ts --module ./kernel.ts --export buildXTris --symmetric für einen reinen Kernel, oder --tris tris.json für das finale geerdete Asset (Verwendung und Gate-Liste: references/qa-gates.md). Es gibt Q1 bis Q10 aus, schreibt review.png und endet mit einer @@RESULT-Zeile. Beheben Sie das erste fehlgeschlagene Gate und führen Sie es erneut aus.
Fertig-Regel. Melden Sie ein Asset niemals als fertig, bis qa-asset beim aktuellen Build bestanden wurde (oder jedes fehlgeschlagene Gate mit seinem Grund benannt ist), review.png mit dem Ansichtswerkzeug geöffnet wurde und pro Panel eine Zeile sagt, was gesehen wurde, und alles, was als UNVERIFIED oder not checked aufgeführt ist, in der Antwort wiederholt wird. Beenden Sie mit der Gate-Tabelle des letzten Laufs.
Determinismus und Parameter
- Vorgaben und Bereiche existieren nur im Schema;
build…AssetruftresolveParamsauf - Seeds verwenden
??; Seed0funktioniert; keinMath.randomoderDate.now - Jedes Merkmal hat seinen eigenen verzweigten Stream; Umschalter mischen keine anderen Teile neu
- Abgeleitete Einschränkungen verhindern degenerierte Formen; Sub-Seeds passen in den Seed-Bereich
Referenz (nur wenn der Benutzer ein Bild gegeben hat)
-
ref-spec.mdeinmal geschrieben,ref.jsonerstellt, Mask-PNG überprüft;ref-comparenach jedem Build-Schritt ausgeführt; Gate-Tabelle (§15) ist in der Antwort
Geometrie und Aussehen
- Achsen folgen §0; Flächen durch Achsen beschrieben; rechts = −X wenn vorwärts = +Z
- Benutzerdefinierte Geometrie hat positives
signedVolume, auch nach dem Spiegeln;DoubleSidenur bei Null-Dicken-Blättern - Gespiegelte Teile gehen durch
add()/addTrisodermirrorTris, niemals durch ein nacktes negatives-Skalierungs-applyMatrix4 - Benutzerdefinierte Geometrie- und Kreaturenformen leben in reinen Dreieckskernels mit Node-Tests (Determinismus, signiertes Volumen, Stromisolierung)
- Teile gehen durch
bakeFlat+paint; pro-Dreieck-Farbfunktionen sind rein - Jitter wird vor
add()angewendet, nahtverschweißt, mit neu berechneten Begrenzungsvolumen - Metallteile haben eine Umgebungskarte oder eine reduzierte
metalness - Overlays verwenden einen konstanten Abstandsversatz und eine kleine Anhebung gegen Z-Fighting
Rigging, Humanoids, Texturen (nur wenn sie zutreffen)
- Bewegliche Teile sind Knochen von
RigBuilder, in Ruhepose erstellt; statische Teile bleiben zusammengeführt; Knochen ≤ etwa 12 - Links-/Rechts-Knochen stammen von
mirrorBone+ einer Spiegelmatrix; Clips verwendenAnimationMixerauf der Rig-Wurzel - Gliedmaßenketten gehen durch
twoBoneIKoder Festpunktketten; Füße und Hände haben explizite Vorwärts-/Oben-Richtung - Extrudierte und loftierte Teile haben positives
signedVolume, auch nach dem Spiegeln - UV ist aus, es sei denn, eine Textur wird verwendet; mit einer Textur wird
PartBuilder({ uv })für jeden Teil dieses Materials gesetzt unddisposeAssetgibtmapfrei
Detaildurchgang (nur wenn er zutrifft)
- Atlas-Zellen folgen der Konvention (Zelle 0 oben links); jeder Teil eines texturierten Materials hat UV; Roughness-/Bump-Maps sind
NoColorSpacemitroughness: 1 - Atlas wird aus einem verzweigten Stream (
seededAtlas) generiert oder als Parameter injiziert; der Builder lädt niemals Dateien oder greift auf das DOM zu - Gefaste und skulptierte Teile haben positives
signedVolume; Skulpturbeträge halten Radien > 0 - AO wird einmal angewendet (
aoShadepro Teil für Rigs,applyAOfür statische Zusammenführungen) und niemals dunkler als die 0,35-Untergrenze - Kleine Details stammen von
raycastTris/scatterOnSurface+placeTrismitsink; gespiegelte Seite verwendetmirrorHit
Composite
- Eindeutige exportierte Buildernamen; Parameter namensräumlich und mit
pickParamsgeteilt - Platzierung verwendet Fußabdrücke, feste Prioritätsreihenfolge und begrenzte Versuche
- Übersprungene Elemente sind deterministisch; wiederholte Objekte werden geklont oder instanziiert
QA (jedes Asset)
-
scripts/qa-asset.tsExit 0 beim aktuellen Build;review.pngangesehen, ein Befund pro Panel; UNVERIFIED-Elemente aufgelistet; Gate-Tabelle in der Antwort
Lebenszyklus und Export
- Wrappergruppe erdet das Asset bei Y = 0;
disposeAssetwird bei jedem Neubau aufgerufen - Meshes sind benannt; Dreiecksanzahl ist innerhalb des Budgets
- Exporter verwendet einen echten TS-Transpiler, enthält Helfer einmal und hat null Importe außer
three(three/addonsnur, wennmergeGeometriesverwendet wird) - GLB angefordert: Wählen Sie den Exportpfad in §16. Melden Sie die Datei, Prüfungen, die an ihren Bytes durchgeführt wurden, und alle ungeprüften visuellen oder Importstufen.
- Plattform gegeben oder
detailhinzugefügt:scripts/mesh-stats.ts(--lodsfür LOD) Exit 0, Profil und Art benannt,not checkedwiederholt;detail-Standard 2 belässt das vorhandene Asset unverändert - Exportziel (Modul, Importmap, klassisches Global) stimmt mit dem Ort überein, an dem der Code ausgeführt wird
- Paritätstest bestanden:
generate(params)und das exportierte Modul ergeben denselben Fingerabdruck
14. Minimales einzelnes Asset (wenn ein volles Schema übertrieben ist)
Die ~290 Zeilen eines ersten Assets bestehen meist aus fester Infrastruktur (prng.ts, lowpoly.ts, params.ts), nicht aus Kosten pro Asset. Schreiben Sie diese einmal als gemeinsame Module und betten Sie sie niemals inline in eine Asset-Datei ein. Überspringen Sie für ein einmaliges Prop das Schema und resolveParams, behalten Sie den PRNG (Determinismus ist trotzdem wichtig) und exportieren Sie nur mit den tatsächlich verwendeten Helfern (helpers: [rawPrng, rawLowpoly]). Ein vollständiges Asset umfasst dann etwa 30 Zeilen:
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')); // Pro-Fläche-Farbe, eigener Stream
for (const s of [-1, 1]) // Eckleisten
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);
}
Fördern Sie es zur vollen Schemaform (§1), sobald es Schieberegler, Voreinstellungen erhält oder innerhalb eines Composites verwendet wird.
15. Referenzabgleich (wenn der Benutzer ein Bild, einen Screenshot oder eine Skizze angibt)
Vollständige Prozedur und Skripte: references/reference-matching.md. Die Regeln, in der Reihenfolge:
- Einmal aufnehmen. Betrachten Sie das Referenzbild einmal, schreiben Sie
ref-spec.md(max 15 Zeilen: Ansicht, gemessene Proportionen, Teile, Palette, 3 charakteristische Merkmale, außerhalb des Umfangs), führen Siescripts/ref-intake.tsaus, betrachten Sie das Mask-PNG einmal. Lesen Sie danach das Bild nie wieder: Arbeiten Sie von der Spezifikation undref.json. - Grob zu fein bauen, nach jedem Schritt vergleichen. Ein Blockout (G1 Proportionen, G2 Aspekt) → B Silhouette (G2 IoU ≥ 0,85 pro Ansicht) → C Farbe (G3 Palette) → D Detail (G4 charakteristische Merkmale). Führen Sie
scripts/ref-compare.tsnach jedem Schritt aus; es dauert unter einer Sekunde. - Zahlen vor Bildern. Beheben Sie nur das ERSTE fehlgeschlagene Gate pro Runde, ändern Sie eine Parametergruppe, vergleichen Sie erneut
…
[vollständig übersetzt]