Anatomy Three.js

Anatomy Three.js — Interaktive 3D-Technikfiguren

Baue interaktive isometrische 3D-Technikillustrationen in Three.js + GLSL. Jede Figur erklärt eine technische Idee als physisches Tischinstrument oder Schnittmodell, das man auf einen Schreibtisch stellen könnte: eine schwere, gefaste Grundplatte auf gedrehten Füßen, domänenspezifische Gehäuse und Gestänge, ein heroischer interner Rotor oder ein bewegliches Subjekt, direkt ziehbare 3D-Steuerelemente und speziell für diese Maschine gebaute Instrumente sowie ein benutzerdefinierter GLSL-Shader, der streng auf das physikalische Medium (Feuer, Plasma, Fluid, Abwind, Strahl) innerhalb der Maschine beschränkt ist.

Anstatt eine 1.500-zeilige monolithische HTML-Datei zu schreiben und 3D-Koordinaten im Kopf zu erraten, einigst du dich zunächst mit dem Benutzer über den Apparat und die Interaktionen (Stufe 0), dann baust du jede Figur in sechs isolierten Stufen innerhalb von figures/<slug>/, unterstützt von der unveränderlichen kit/-Engine und bei jedem Schritt durch ein zweistufiges 3D-Raum- und orthografisches Visual-Harness verifiziert.

---

Verzeichnisstruktur

anatomy-threejs/
├── SKILL.md                    # Stufe-0-Kurzfassung + 6-Stufen-Workflow & Agenten-Einstiegspunkt
├── kit/                        # UNVERÄNDERLICHE ENGINE — von hier importieren; niemals pro Figur bearbeiten
│   ├── shaders.mjs             # 5 Themen, 4-Ton + Deckel-Cel-Shader, invertierte Hülle, Falten
│   ├── primitives.mjs          # Achsbewusste Platten, Zylinder, Zahnräder, Schrauben, Rändel, Striche
│   ├── registry.mjs            # Recorder3D: .group(), .part(), .anchor(), .tube(), .interactable(), .tag()
│   ├── audit3d.mjs             # Kopflose Node-3D-Raumprüfung (Kollisionen, Schwebeteile, Bohrungen, Rohre)
│   ├── runtime.mjs             # Orthografisches Rig, Raycast-3D-Drag, benutzerdefinierte Steuerungen, Federn, __ANATOMY_DEBUG__
│   ├── bundle.mjs              # Kompiliert Figur-Module in eine einzige eigenständige HTML-Datei
│   └── shell.html              # Responsive Karten-Chrome, 5-Theme-CSS-Variablen, funktionsbewusste Steuerungen
├── scripts/
│   ├── inspect.mjs             # Kopfloses Chrome (CDP) 2x2 orthografischer Blueprint & Gelenk-Overlay
│   ├── drive.mjs               # Interaktiver Kontaktbogen + Helden-Standbilder + mobile 390px-Überprüfung
│   └── chrome-port.mjs         # Zero-Dependency WebSocket + PNG-Stitcher für kopfloses Chrome
├── references/
│   ├── craft-3d.md             # 3D-Koordinatensystem, Tonhierarchie, maßgeschneiderte Steuerungen, Anti-Patterns
│   ├── kit-3d.md               # API-Referenz für Recorder3D, Primitive, Shader und Laufzeit
│   └── verify-3d.md            # Wie man [COLLISION], [FLOATING], [TUBE KINK] und orthografische Ansichten interpretiert und behebt
└── figures/
    └── <slug>/                 # Dein Arbeitsbereich für eine Figur (z. B. figures/wankel-engine/)
        ├── model.mjs           # Stufe 1: Reine Mathematik, Abmessungen, SPEC.features, SPEC.controls, Anker
        ├── base.mjs            # Stufe 2: Grundplatte, Füße, Halo, Lineal, Messingplakette
        ├── structure.mjs       # Stufe 3: Sockel, Rahmen/Gehäuse, Anschlüsse, Befestigungen
        ├── subject.mjs         # Stufe 4: Bewegliche Kernbaugruppe (Rotor, Schaufeln, Dichtungen, Zahnräder)
        ├── mechanism.mjs       # Stufe 5: Maßgeschneiderte Steuerungen, Instrumente, 3D-Interaktionen, Rohre, updateKinematics()
        ├── shader.mjs          # Stufe 6: Benutzerdefinierter GLSL-Shader, beschränkt auf das aktive physikalische Medium
        ├── build.mjs           # CLI-Einstieg: --test-model, --audit und vollständiges HTML-Bundle
        └── dist/
            └── <slug>.html     # Kompilierte eigenständige interaktive Figur

Regel 1 — kit/ niemals neu schreiben: Die Three.js-Kamera, Cel-Shader, Raycast-Drag-Handler, Federlöser, DOM-Chrome und Debug-Harness leben in kit/. Deine Figurendateien definieren nur Domänenmathematik, 3D-Teile, Kinematik, Interaktionen und den benutzerdefinierten Medium-Shader.

Regel 2 — Lese die Referenzen, bevor du Geometrie schreibst:

• Lese references/craft-3d.md vor Stufe 0/1, um das physische Rig, maßgeschneiderte Steuerungen, Feature-Flags, die Tonhierarchie und den 3D-Koordinatenrahmen zu entwerfen.
• Lese references/kit-3d.md vor Stufe 2 für die exakten Signaturen von Recorder3D und kit/primitives.mjs.
• Lese references/verify-3d.md, wenn --audit, inspect.mjs oder drive.mjs ein Problem meldet.

---

Stufe 0 — Apparat- und Interaktionskurzbeschreibung (Vor dem Bauen abstimmen)

Bevor du Dateien erstellst oder Stufe-1-Code schreibst, schlage dem Benutzer eine präzise Apparat- und Interaktionskurzbeschreibung vor und stimme ab, was die Maschine tut und wie der Leser damit spielt (warte nur, wenn der Benutzer ausdrücklich sagt, sofort ohne Fragen zu bauen):

1. Tischapparat & Heldensubjekt: Benenne den physischen Mechanismus und welche einzelne Baugruppe den lit-Akzent trägt.
2. Direkte 3D-Manipulation (reg.interactable): Identifiziere, welche 3D-Baugruppen oder Steuerungen der Leser direkt im Ansichtsfenster greifen und ziehen kann (z.B. Ziehen einer Taumelscheibe zum Neigen/Anheben und Beobachten der Rotorblattverstellung, Verschieben eines Noniusschlittens, Ziehen eines Gestängehebels), auch während die Drehung/Simulation pausiert ist.
3. Domänenspezifische Steuerungen & Telemetrie (SPEC.controls): Wähle Tischhardware und Steuerbalken-Schieberegler, die zu dieser Maschine gehören (z.B. 2-Achsen-Cyclic-Stick, Collective-Pitch-Quadrant, Winkelmesserbogen, Mikrometertrommel, Noniusskala, Manometerrohr). Kopiere niemals den Drehknopf, das Bourdon-Manometer oder die Hydraulikbox einer anderen Figur, es sei denn, das Subjekt verwendet dieses Instrument tatsächlich.
4. Ansichtsmodi (SPEC.features): Entscheide explizit, welche optionalen Modi ihren Platz verdienen:
   • explode: Aktiviere (true) nur für geschlossene konzentrische Maschinen mit gestapelten axialen Schichten (z.B. Motoren, Getriebe, Pumpen). Setze explode: false für offene mechanische Gestänge, Taumelscheiben, optische Bänke oder Oberflächengestelle, bei denen das Trennen von Teilen die Gestängegeometrie zerstört und Unordnung schafft.
   • cutaway: Aktiviere (true), wenn ein Außengehäuse bewegliche Innenteile verbirgt; setze false für offene Rahmenmechanismen.
   • shader: Aktiviere (true), wenn ein begrenztes physikalisches Medium (Verbrennungsgas, Rotorabwind, Strahl, Fluidströmung) den Mechanismus verdeutlicht.

Stufe-0-Tor: Benutzer bestätigt oder verfeinert die Kurzbeschreibung (oder weist ausdrücklich einen sofortigen nicht-interaktiven Bau an).

---

Der Sechs-Stufen-Workflow

Führe diese Stufen der Reihe nach aus. Jede Stufe endet mit einem Verifikations-Tor — führe den Befehl aus, behebe alle Fehler und überprüfe das gerenderte PNG visuell mit deinem Dateilesewerkzeug, bevor du zur nächsten Stufe übergehst.

Stufe 1 — Modell & Kinematik (model.mjs + build.mjs)

Übersetze die vereinbarte Kurzbeschreibung in ein reines physikalisches Mathematikmodul, bevor du Three.js berührst:

1. Kodiere die physikalische Metapher in figures/<slug>/model.mjs:
   • SPEC.features: { explode: boolean, cutaway: boolean, shader: boolean, crank: boolean } passend zu Stufe 0.
   • SPEC.interactionHint: Kurzer Hinweis, der unten links angezeigt wird und dem Benutzer sagt, welche 3D-Teile er direkt ziehen kann (z.B. "Ziehe Taumelscheibe, Stick oder Collective-Hebel").
   • SPEC.controls: Array domänenspezifischer Schieberegler-Steuerungen ({ id, label, min, max, step, initial, title }). runtime.mjs rendert diese in der Steuerungsleiste, glättet sie mit Federn und übergibt sie an updateKinematics und formatReadout.
   • SPEC.auditPoses & SPEC.drivePoses: Domänenrepräsentative Posen (extreme Steuerwinkel, pausierte Manipulation, Cutaway-/Themenprüfungen), die von --audit und scripts/drive.mjs verwendet werden. Lasse Explosionsposen weg, wenn features.explode === false.
   • SPEC: Alle kritischen Maße (BASE_W, BASE_D, BASE_H, BASE_Y, topSurfaceY, isoElevDeg: 30, isoAzimDeg: -36, initialZoom, initialPanY, minVertSpan, minHorizSpan).
   • ANCHORS: Benannte [x, y, z]-Montagekoordinaten auf der Grundplatte (plaqueCenter, rulerCenter und deine maßgeschneiderten Steuerungs-/Instrumentenanker der Figur). Denke daran, dass in der kanonischen Isometrie (30° Höhe, -36° Azimut) die +Z-Kante die vordere Schürze und -X, +Z / +X, +Z die freien vorderen Ecken sind.
   • Reine Zustands- und Kinematikfunktionen (keine Three.js-Importe), gesteuert durch theta und die Live-params aus SPEC.controls.
   • formatReadout({ theta, effectiveRpm, params }) gibt { readout, phase }-Strings für die Telemetrieleiste zurück.
2. Baue das Grundgerüst figures/<slug>/build.mjs (Referenz: figures/wankel-engine/build.mjs oder figures/helicopter-swashplate/build.mjs) und passe Titel, Untertitel, initialen Messwert und Legende an.

Stufe-1-Tor:

node figures/<slug>/build.mjs --test-model

Bestandskriterien: Beendet mit 0 und alle Anker sind endlich und der Messwert/Zustand über einen vollständigen $0 \dots 6\pi$-Zyklus verifiziert.

---

Stufe 2 — Die Basis (base.mjs)

Baue die schwere Bezugsgrundplatte, die das gesamte Instrument erdet:

1. Erstelle base.group (stage: "base").
2. Füge den weichen Bodenschatten (makeHaloMesh) bei BASE_Y - 0.24 hinzu.
3. Füge base.plate mit buildSlabGeometry(BASE_W, BASE_D, BASE_H, { radius: 0.26, bevel: true, bevelSize: 0.025, bevelThickness: 0.025 }) mit ramp: "lo", mountOn: "ground" hinzu. Beachte, dass topSurfaceY = BASE_Y + BASE_H + 0.025 die obere Fasenstärke berücksichtigt, sodass auf topSurfaceY montierte Teile bündig auf der Oberseite aufliegen, ohne einzusinken.
4. Registriere alle Montageanker der Grundplatte über reg.anchor(id, x, y, z, baseGroup), damit Stufen 3 und 5 direkt auf base.plate einrasten.
5. Füge eingelegte Umfangsrillen (makePlanOutline), 4 gedrehte Eckfüße (base.foot.collar.i + base.foot.pad.i) mit oberen Senklochschrauben (makeScrewDetail), eine Maßskala (base.ruler + makeRulerTicks) und eine genietete brass-Spezifikationsplakette (base.plaque) auf der sichtbaren vorderen Schürze (+Z) mit einer gravierten Markierung (reg.tag("tag-plate", ...)) hinzu.

Stufe-2-Tor:

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --isolate base --ortho --out figures/<slug>/dist/inspect-base.png

Lies inspect-base.png, um zu überprüfen, ob die Füße sauber unter der Grundplatte sitzen und die Messingplakette + Lineal auf der vorderen Schürze nicht verdeckt sind.

---

Stufe 3 — Die Struktur (structure.mjs)

Baue die stationären lasttragenden Stützen, den Hauptrahmen oder das Schnittgehäuse, Anschlüsse/Verteiler und Befestigungen:

1. Montiere Stützsockel oder Getriebegehäuse auf base.plate mit geflanschten Basen, Schraubendetails, verjüngten Säulen und Lagersätteln.
2. Baue das Hauptgehäuse oder den Rahmen (ramp: "mid", outline: "hi"). Lasse die Vorderseite (+Z) offen oder mit einer Schnittabdeckung (cutawayHide: true) versehen, sodass Innenmechanismen aus der kanonischen isometrischen Kamera vollständig sichtbar bleiben, wenn features.cutaway aktiviert ist.
3. Füge domänenspezifische Anschlüsse, Aktorgehäuse oder stationäre Halterungen hinzu, die sauber nach außen zeigen. Registriere 3D-Anschluss-/Klemmenanker mit ihren lokalen äußeren Anschlussnormalen (reg.anchor("plug.leading.tip", 0, 0.68, 0, spGroup, { dir: [0, 1, 0] })) innerhalb jeder lokalen Untergruppe, damit Stufe-5-Rohre an ihre exakten Weltpositionen einrasten und koaxial ein-/austreten.
4. Setze explode: [ex, ey, ez]-Vektoren auf entfernbare Untergruppen nur, wenn SPEC.features.explode true ist und der Apparat geschlossene konzentrische Schichten hat, die axial getrennt werden sollen.

Stufe-3-Tor:

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --isolate base,structure --ortho --out figures/<slug>/dist/inspect-structure.png

Lies inspect-structure.png (TOP, FRONT, RIGHT, CANONICAL ISO): überprüfe, ob Anschlüsse nach außen zeigen, Sockel sowohl die Grundplatte als auch das Gehäuse ohne Überschneidung berühren und nichts schwebt.

---

Stufe 4 — Das Subjekt (subject.mjs)

Baue die heroische interne Baugruppe, die den visuellen Fokus beherrscht:

1. Weise ramp: "hi" dem primären beweglichen Körper (z.B. Rotorkörper, Nabenjoch) zu, ramp: "lit" aktiven Arbeitselementen (rotor.apexSeal.i, blade.airfoil.*) und ramp: "brass" Präzisionsgetrieben und Drehpunkten.
2. Erstelle verschachtelte kinematische Gruppen (orbit -> spin oder azimuth -> flap -> pitch), sodass hierarchische Bewegungen sauber ohne Euler-Gimbal-Lock komponiert werden.
3. Übergib insideBoreOf und boreClearanceFn an Teile, die sich in einer Bohrung bewegen, damit audit3d.mjs mathematisch null Wanddurchdringung bei jeder geprüften Pose verifiziert.
4. Füge maschinell bearbeitete Taschen, Flächennuten, Sparnähte oder Schraubenmuster hinzu, sodass Bewegungen unverkennbar sind.

Stufe-4-Tor:

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --isolate subject --ortho --out figures/<slug>/dist/inspect-subject.png

Lies inspect-subject.png, um zu bestätigen, dass die Silhouette, Fasen und Gelenke des Subjekts aus jedem Winkel klar lesbar sind.

---

Stufe 5 — Mechanismus, Maßgeschneiderte Steuerungen & Direkte 3D-Interaktion (mechanism.mjs)

Verbinde das Subjekt mit domänenspezifischen Bedienelementen, Telemetrieinstrumenten, direkter 3D-Ziehinteraktion und Leitungsführung:

1. Baue domänenspezifische Steuerungen an ihren ANCHORS aus Stufe 0/1 (z.B. ein 2-Achsen-Gimbal-Cyclic-Stick, einen gekerbten Collective-Pitch-Quadrantenhebel, eine Noniusschraube oder eine gerändelte Gasdrehtrommel). Kopiere niemals den gerändelten Knopf oder Verteilerblock einer anderen Figur, wenn die Maschine ihre eigene Steuerungshardware erfordert.
2. Baue domänenspezifische Telemetrie (z.B. einen gekrümmten Blattanstellwinkel-Messbogen, eine lineare Verschiebungsskala, ein Manometerrohr oder ein Messuhr), positioniert vorne in +Z oder außerhalb der Hauptsilhouette in CANONICAL ISO.
3. Registriere direkte 3D-Manipulation mit reg.interactable(targetId, { cursor, hint, onDrag }) am primären Mechanismus und/oder physischen Hebeln, sodass der Benutzer 3D-Teile direkt im Ansichtsfenster über setParam(...) ziehen kann, auch wenn die Drehung pausiert ist (RPM = 0 oder PAUSED).
4. Führe alle Rohre und Kabel mit reg.tube(id, fromAnchorId, waypoints, toAnchorId, opts):
   • Frage reg.getAnchorWorldPos(anchorId) und reg.getAnchorWorldDir(anchorId) ab, um glatte 3D-Bogen-Wegpunkte zu bauen (length / chord >= 1.12), die sauber an benachbarten Teilen vorbeischwingen und koaxial entlang der äußeren Normalen jedes Anschlusses ein-/austreten.
5. Baue den Antriebsstrang und die Gelenkgestänge. Übergib cutawayHide: true an vorderseitige Gehäuseabdeckungen oder Verkleidungen, die den internen Mechanismus verbergen.

Stufe-5-Tor:

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --isolate mechanism --ortho --out figures/<slug>/dist/inspect-mechanism.png
node scripts/drive.mjs figures/<slug>/dist/<slug>.html

Lies inspect-mechanism.png, um zu überprüfen: (1) maßgeschneiderte Steuerungen sitzen aufrecht und sind auf der Vorderseite zugänglich, (2) Telemetrieanzeigen sind lesbar und zeigen formatReadout-Werte, (3) 3D-Interaktions-Hitboxen überlappen ihre visuellen Teile korrekt, (4) Rohre beginnen/krümmen/enden sauber mit der richtigen Bogenkrümmung und (5) Gelenkkinematik erzeugt eine schlüssige Bewegung ohne Überschneidung.

---

Stufe 6 — Medium-Shader (shader.mjs)

Füge ein benutzerdefiniertes GLSL fs (Fragment-Shader)-Modul hinzu, das auf eine volumetrische oder oberflächengebundene Region beschränkt ist, die ein physikalisches Medium darstellt, das die Maschine antreibt oder umgibt:

1. Entscheide, ob ein Shader notwendig ist: Wenn die Maschine kein begrenztes sichtbares Medium (Verbrennung, Plasma, Fluidströmung, Abwind, Strahl) enthält, setze SPEC.features.shader: false und überspringe Stufe 6 vollständig.
2. Definiere einen minimalen fs-Shader, der von shader.mjs exportiert wird. Die Shader-Engine kit/shaders.mjs hält den Szenenknoten mediumMesh, auf den du zugreifen kannst (setze userData.mediumVisible = false, um es auszublenden).
3. Lasse das Medium von Steuerungsparametern abhängen (z.B. params.throttle skaliert Flammenhöhe, params.collective ändert Abwinddichte), um zu zeigen, dass der Benutzer Maschinenzustand und Mediumsverhalten zusammen beeinflusst.
4. Halte Shader streng innerhalb der offenen Hohlräume/Schnittflächen der Maschine; lasse Medium niemals durch das Gehäuse austreten oder die oberen Abdeckungsebenen überlappen. Die orthografische Inspektion sollte das Medium nur innerhalb des definierten Arbeitsbereichs zeigen.

Stufe-6-Tor:

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --ortho --out figures/<slug>/dist/inspect-shader.png

Lies inspect-shader.png, um zu bestätigen: (1) Medium erscheint nur innerhalb des Maschinenhohlraums, (2) Shader-artefakte oder Übertritte sind in keiner orthografischen Ansicht sichtbar und (3) das Medium ändert sich glaubwürdig mit den Steuerungsparametern.

---

Endgültiges HTML-Bundle & Qualitätssicherung

Sobald alle 6 Stufen die Verifikations-Tore bestanden haben, erstelle das fertige eigenständige HTML:

node figures/<slug>/build.mjs --bundle

Ausgabe: figures/<slug>/dist/<slug>.html — eine einzelne, vollständige interaktive HTML-Datei (~800 KB–1,2 MB), die auf jedem modernen Browser (Chrome, Firefox, Safari, Edge) läuft, ohne externe Abhängigkeiten.

Ein Vollständiger Figuren-Build umfasst:

• ~30–50 registrierte Teile über 3 Tonstufen + Akzent
• 5 Themen (Dunkel, Hell, Papier, Meer, Tint), auswählbar über das Chrome-Symbol
• Realzeit-Telemetrieleiste, die formatReadout()-Strings anzeigt
• 1–3 reg.interactable() Ziele für direkte 3D-Manipulation
• Domänenspezifische Steuerungen mit Feder-glatter Eingabe
• Optionales explode (axiale Schichtentrennung), cutaway (Gehäuseschnitte) und shader (Medium)
• 4.096 × 4.096 Vollformat-Screenshots durch scripts/drive.mjs

Letzte Überprüfung vor dem Einreichen:

1. Öffne das HTML in derselben Code-Kontext-Umgebung mit deinem Dateilesewerkzeug.
2. Rufe alle 5 Themen auf und bestätige, dass sich Hintergrund-, Platten-, Linien- und Schriftfarben wie erwartet ändern.
3. Greife und ziehe jedes reg.interactable()-Ziel, um zu bestätigen, dass das Ziehen funktioniert und die Telemetrie sich entsprechend aktualisiert.
4. Aktiviere/deaktiviere explode und cutaway, um zu prüfen, ob Teile sauber getrennt sind und Gehäuse den Innenraum nicht übermäßig verbergen.
5. Führe einen letzten --audit-Durchlauf aus, der bei 0 Problemen ausgegeben wird, bevor die Figur als fertig gemeldet wird.

---

Schnellstart (Neue Figur)

# 1. Erstelle das Figurenverzeichnis
mkdir -p figures/<slug>/

# 2. Erstelle model.mjs (reine Math API definieren: Maße, Anker, SPEC.features, SPEC.controls, Kinematik)
cat <<'MODEL' > figures/<slug>/model.mjs
  // Stage 1 — Reine Math-Definitionen (kein Three.js). Siehe references/craft-3d.md.
  // Referenz: figures/wankel-engine/model.mjs
  export const SPEC = { features: { explode: false, cutaway: true, shader: false, crank: true }, ... };
  export const ANCHORS = { plaqueCenter: [0, 0.1, 0.57], ... };
  // ...
MODEL

# 3. Baue das Grundgerüst build.mjs
cat <<'BUILD' > figures/<slug>/build.mjs
  import { bundleToDisk } from "../../../kit/bundle.mjs";
  bundleToDisk({ slug: "<slug>", title: "Dein Titel", subtitle: "Deine faszinierende Maschine", initialReadout: "0.0", ... });
BUILD

# 4. Jede Stufe erstellen & verifizieren
# node figures/<slug>/build.mjs --test-model   Stage 1
# node figures/<slug>/build.mjs --audit        Stages 2–6
# node scripts/inspect.mjs .../<slug>.html --ortho   visuelle Inspektion
# node scripts/drive.mjs .../<slug>.html       Kontaktbogen + Stills

Profi-Tipp: Lese immer alle drei Referenzdateien, bevor du Geometrie schreibst. Die häufigsten Fehler sind falsche Ankerhöhen, die Teile in die Grundplatte einsinken lassen oder übersehene Kollisionen in Explosionsposen.