CommunityBildgithub.com

threejs-asset-generator

Generiert prozedurale Low-Poly-3D-Assets in Three.js r170+ mit determinierten, seed-basierten Buildern, Parameterschemata, Flat-Shaded-Vertex-Color-Meshes, benutzerdefinierter Geometrie mit korrekter Windung, gespiegelten Teilen, rigged Biped- und Kreaturen-Kernels, Compositen, Texturen, Standalone-Code-Export und Abgleich mit einem Referenzbild. Nicht zum Laden von glTF-Dateien.

Was ist threejs-asset-generator?

Dieser Skill ist ein spezialisierter prozeduraler Asset-Generator für Three.js r170+, der vollständig deterministisch arbeitet – jedes Asset wird durch einen Seed und ein Parameterschema definiert, sodass identische Eingaben stets identische Ausgaben liefern. Er eignet sich hervorragend für die Erstellung von Low-Poly-Charakteren, Umgebungen und Props, ohne dass manuelle Modellierung erforderlich ist. Der Workflow umfasst Builder für benutzerdefinierte Geometrie (mit korrekter Windung und gespiegelten Teilen), Flat-Shading, Vertex-Farben, Materialien und Texturen (auch prozedural oder per Bildgenerator erzeugt), Rigging (Biped und Creature), Animation Clips, Composite aus mehreren Sub-Assets sowie den Export als standalone ES-Module. Der Skill bietet zwei Vorschaumodi: eine schnelle Orbitalansicht und eine Vollansicht mit editierbaren Parametern und Rig-Inspektion. Ein besonderes Feature ist die Referenzbild-Funktion: Entwickler können ein Referenzbild (Screenshot, Skizze) angeben, woraufhin das Tool eine Spezifikation erstellt, schrittweise das Asset aufbaut und nach jedem Schritt den Fortschritt gegen das Bild prüft. Die Ausgabe erfolgt als THREE.Group, die über eine Vielzahl von Qualitätsprüfungen (über das Skript `qa-asset.ts`) validiert wird, einschließlich Tests auf Determinismus, Geometriekorrektheit, Budgeteinhaltung und korrekte Lebenszyklusverwaltung (Disposal, Rebuild).

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

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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 anLesen SieCode
Materialien, Flat Shading, prozedurale oder bildgenerierte Texturen, Vertex-Jitter (§4, §5)references/look.mdsrc/lowpoly.ts, src/jitter.ts
Benutzerdefinierte Geometrie, Windung, gespiegelte Teile, Overlays (§6, §7)references/geometry.mdsrc/geometry.ts, src/overlay.ts
Kreatur, Rumpf, Flügel, reiner Dreieckskernel (§6.2, §6.3)references/creatures.mdsrc/tri.ts, src/organic.ts
Alles, was animiert, humanoid, extrudiert, Textur (§6.4 bis §6.7)references/rigging-biped.mdsrc/rig.ts, src/biped.ts, src/texture.ts
Flaches oder klotziges Aussehen, Atlas, Fase, AO, Sockets (§6.8)references/detail.mdsrc/detail.ts, src/detailThree.ts
Mehrere Unter-Assets in einem (§8)references/composite.md
Erdung, Entsorgung, Neubauten, Lichter (§9, §10)references/lifecycle.mdsrc/lifecycle.ts
Code-Export, Three.js-Versionen (§11, §12)references/export.mdsrc/fingerprint.ts
Eine .glb-Datei des Assets (§16)references/glb-export.mdscripts/export-glb.ts
Ist es zu schwer, Plattformbudget, LOD detail (§17)references/budget.mdscripts/mesh-stats.ts, src/lod.ts
Rig, Animationsclips, Drift, Ausdrücke (§18)references/rig-check.mdscripts/rig-check.ts
Schneller GLB-Viewer oder Vollvorschau-Studioreferences/studio-preview.mdSchnelle Vorschau HTML
Vollständiges kleines Beispielreferences/examples.md
Bevor Sie ein Asset als fertig melden: QA-Gates, Überprüfungsbild (§13)references/qa-gates.mdscripts/qa-asset.ts

0. Konventionen (einmal festlegen, überall anwenden)

ThemaRegel
Einheiten1 Einheit = 1 Meter
AchsenY nach oben, rechtshändig
Vorwärts+Z (wie bei glTF und Object3D.lookAt)
SeitenMit Vorwärts +Z und Oben +Y ist die rechte Seite des Assets −X und die linke Seite +X (rechts = vorwärts × oben)
DrehpunktUrsprung im Fußabdruckmittelpunkt, tiefster Punkt bei Y = 0 (siehe §9)
FlächennamenBenennen Sie Flächen nach Achsen (+X-Fläche, Oberseite), niemals nach Backbord/Steuerbord/Links/Rechts, damit eine Regel nicht den Achsen widersprechen kann
SymmetrieBauen 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) ruft resolveParams selbst auf. Drei konkurrierende Vorgaben (params.seed || 12345, Schema default: 42, Composite ?? 101) führen dazu, dass Vorschau, Voreinstellungen und exportierter Code nicht übereinstimmen.
  • build…Asset ist rein: gleiche aufgelöste Parameter ergeben identische Geometrie. Kein Math.random, Date.now, DOM-Zugriff oder veränderlicher Zustand auf Modulebene.
  • Importieren Sie THREE normal. Injizieren Sie keine THREEInstance: 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 generisches buildAsset kollidiert, 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 PartBuilder bleiben.

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 || 12345 verwandelt Seed 0 stillschweigend in 12345.
  • Geben Sie jeder Funktion ihren eigenen verzweigten Stream. Bei einem gemeinsamen rng verschiebt das Ändern von segments oder das Umschalten von hasFruits jede 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 Set gemischter 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 als fork(label).seed % 100000 ab; 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 von atlasOn jeden 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…Asset ruft resolveParams auf
  • Seeds verwenden ??; Seed 0 funktioniert; kein Math.random oder Date.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.md einmal geschrieben, ref.json erstellt, Mask-PNG überprüft; ref-compare nach 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; DoubleSide nur bei Null-Dicken-Blättern
  • Gespiegelte Teile gehen durch add()/addTris oder mirrorTris, 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 verwenden AnimationMixer auf der Rig-Wurzel
  • Gliedmaßenketten gehen durch twoBoneIK oder 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 und disposeAsset gibt map frei

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 NoColorSpace mit roughness: 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 (aoShade pro Teil für Rigs, applyAO für statische Zusammenführungen) und niemals dunkler als die 0,35-Untergrenze
  • Kleine Details stammen von raycastTris/scatterOnSurface + placeTris mit sink; gespiegelte Seite verwendet mirrorHit

Composite

  • Eindeutige exportierte Buildernamen; Parameter namensräumlich und mit pickParams geteilt
  • 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.ts Exit 0 beim aktuellen Build; review.png angesehen, ein Befund pro Panel; UNVERIFIED-Elemente aufgelistet; Gate-Tabelle in der Antwort

Lebenszyklus und Export

  • Wrappergruppe erdet das Asset bei Y = 0; disposeAsset wird 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/addons nur, wenn mergeGeometries verwendet 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 detail hinzugefügt: scripts/mesh-stats.ts (--lods für LOD) Exit 0, Profil und Art benannt, not checked wiederholt; 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:

  1. 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 Sie scripts/ref-intake.ts aus, betrachten Sie das Mask-PNG einmal. Lesen Sie danach das Bild nie wieder: Arbeiten Sie von der Spezifikation und ref.json.
  2. 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.ts nach jedem Schritt aus; es dauert unter einer Sekunde.
  3. Zahlen vor Bildern. Beheben Sie nur das ERSTE fehlgeschlagene Gate pro Runde, ändern Sie eine Parametergruppe, vergleichen Sie erneut

…

[vollständig übersetzt]

Verwandte Skills