CommunityCodierung & Entwicklunggithub.com

3d-builder

Spezifikationsgesteuerte Erstellung und Bearbeitung von 3D-Modellen in Blender oder FreeCAD. Alle Dateien eines Modells bleiben in models/<name>/ organisiert.

Was ist 3d-builder?

3d-builder ist ein Skill für KI-Agenten (wie Claude Code, Cursor, Codex), der die schrittweise und spezifikationsbasierte Erstellung von 3D-Modellen in Blender oder FreeCAD ermöglicht. Der Skill beginnt mit dem Schreiben einer detaillierten Spezifikation, klärt Unklarheiten durch gezielte Fragen (immer eine Frage auf einmal), zeichnet für Gebäude zunächst Grundrisse als SVG, die der Benutzer freigeben muss, und erstellt dann das Modell – entweder über einen Blender/FreeCAD MCP-Server oder ein generiertes Python-Skript. Alle Dateien eines Modells (Spezifikationen, Grundrisse, Quellmodell, Exporte) werden in einem eigenen Ordner unter models/<name>/ abgelegt. Dies verhindert wiederholte Korrekturen aufgrund von Annahmen und ist ideal für funktionale Teile, Gehäuse, Halterungen, Spiele-Assets und Gebäude. Unterstützt werden Blender und FreeCAD per MCP oder Skript-Fallback, sowie Exporte als .glb und .fbx für Spiele und Web.

Funktioniert mit~Claude Code~Codex CLI~Cursor
Part ofMobile
npx skills add https://github.com/thanikc/3d-builder/tree/HEAD/skills/3d-builder

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

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

Dokumentation

Was macht 3d-builder?

Rate bei einem 3D-Modell nicht herum. Schreibe auf, was gebaut wird, kläre Unklarheiten mit dem Benutzer, dokumentiere jede Annahme und modelliere erst dann. Ein Modell, das auf geratenen Maßen basiert, wird immer wieder korrigiert; eine Spezifikation fängt die Schätzungen ein, bevor sie zu Geometrie werden.

Der Ablauf besteht aus diesen Phasen, immer in dieser Reihenfolge: Spezifikation → Fragen → Grundrisse (nur Gebäude) → Modell. Öffne Blender oder FreeCAD nicht und schreibe keinen Modellierungscode, bevor die Spezifikation existiert und die Fragen beantwortet sind. Bei einem Gebäude muss der Benutzer zudem zuerst die Grundrisse freigegeben haben.

Projektstruktur

Ein Projekt kann mehrere Modelle enthalten, daher lebt alles, was zu einem Modell gehört, in einem eigenen Ordner:

models/
  <name>/
    specs/
      <yyyy-mm-dd-hhmmss>-<anfrage>.md   # eine Spezifikation pro Anfrage
    plans/                               # nur bei Gebäuden
      layout.json
      floor-<id>.svg
    <name>.blend | <name>.FCStd          # das Modell
    <name>.py                            # Skript-Fallback nur
    <name>.glb | <name>.fbx              # Exporte für Spiele/Web nur
.3d-builder.json                         # gespeicherte Werkzeugwahl, für das gesamte Projekt

<name> ist ein kurzer Kebab-Case-Name für das Objekt (phone-holder, router-wall-mount). Er benennt den Ordner und die Modelldateien. Alle Pfade unten sind relativ zu models/<name>/, sofern nicht anders angegeben.

Ältere Projekte verwenden möglicherweise noch die alte flache Struktur (specs/ und plans/ im Projektstamm, models/<name>.blend). Wenn du eine solche findest, arbeite damit wie gehabt und biete einmal an, die Dateien in diese Struktur zu verschieben. Verschiebe nichts ohne Rückfrage.

Phase 1: Spezifikation schreiben

  1. Wähle den <name> des Modells. Prüfe bei einem neuen Modell, ob models/<name>/ noch nicht existiert, erstelle es dann zusammen mit dem specs/-Ordner.
  2. Hole den Zeitstempel von der Systemuhr (z. B. date +%Y-%m-%d-%H%M%S), anstatt dir einen auszudenken.
  3. Erstelle specs/<yyyy-mm-dd-hhmmss>-<anfrage>.md mit der Vorlage aus references/spec-template.md. <anfrage> ist ein kurzer Kebab-Case-Name für diese Anfrage: initial für ein neues Modell oder die Änderung bei einer Bearbeitung (thicker-hook, move-kitchen-wall).

Fülle aus, was die Anfrage bereits angibt, und liste dann die offenen Punkte: alles, was die Geometrie betrifft, aber nicht spezifiziert wurde. Typische offene Punkte:

  • Gesamtabmessungen und Einheiten, und welche Maße fest vs. frei sind
  • Passung und Spiel gegenüber realen Objekten (ein 60 mm breites Telefon benötigt einen Schlitz, der etwas breiter als 60 mm ist; wie viel?)
  • Wandstärke, Verrundungen/Fasen, Lochgrößen, Schraubentypen
  • Befestigungsmethode, Ausrichtung, Belastung
  • Zweck und Fertigung (3D-Druck → Überhänge, Mindestwandstärken, flache Basis; CNC; reine Renderdarstellung; Spiel-/Web-Asset)
  • Für Spiel-/Web-Assets: Ziel-Engine, Polygon-Budget, Maßstab in Engine-Einheiten, Pivot-Position, UVs und Texturen vs. einfarbige Oberflächen, LODs, Kollisionsmesh
  • Detaillierungsgrad, Materialien (Blender), parametrische Anforderungen (FreeCAD)
  • Für Gebäude: Stockwerke, Grundfläche, Räume und ihre Größen, Treppen, Türen und Fenster. Diese werden in Phase 3 mit den Grundrissen geklärt, daher dort und nicht hier auflisten

Vorhandenes Modell bearbeiten: Finde zuerst den Ordner des Objekts unter models/. Schreibe eine neue Spezifikation für die Änderung (jede Anfrage erhält eine eigene Datei, damit der Verlauf lesbar bleibt), verweise auf die vorherige Spezifikation und lege fest, was sich ändert und was gleich bleiben muss. Lies das vorhandene Modell ein (über MCP oder das Skript, das es erstellt hat), bevor du es bearbeitest, damit die Bearbeitung vom tatsächlichen Zustand ausgeht. Bei einem Gebäude mit einem plans/-Ordner durchläuft eine Layoutänderung zuerst die Pläne (Phase 3, „Ein Gebäude bearbeiten“).

Phase 2: Klärende Fragen

Wenn die Anfrage offene Punkte enthält, frage vor der Modellierung nach. Der Benutzer weiß Dinge, die du nicht ableiten kannst (die tatsächliche Telefonbreite, wo die Wandschrauben sitzen), und eine Frage jetzt erspart einen Neuaufbau später.

Regeln:

  • Immer eine Frage gleichzeitig. Warte auf die Antwort, bevor du die nächste stellst. Ordne die Fragen nach ihrem Einfluss auf die Geometrie: zuerst Gesamtgröße und Zweck, zuletzt kosmetische Details.
  • Ja/Nein wo möglich.„Soll der Kabelschlitz mittig sein?“ ist besser als „Wo soll der Kabelschlitz sein?“.
  • Sonst Multiple Choice: zuerst die empfohlene Option mit „(empfohlen)“, dann die Alternativen, und als letzte Option eine Freitextantwort. Verwende das Fragewerkzeug des Agents (z. B. AskUserQuestion), falls vorhanden; es fügt die Freitextoption normalerweise automatisch hinzu.
  • Pakete von 5. Nach jeweils 5 Fragen frage, ob mit bis zu 5 weiteren fortgefahren werden soll, und nenne grob die Anzahl der noch offenen Punkte. Wenn der Benutzer ablehnt, höre auf zu fragen.
  • Frage nicht nach Dingen, die für dieses Modell unwichtig sind, und frage nicht, was der Benutzer bereits gesagt hat.
  • Trage jede Antwort sofort im Abschnitt Entscheidungen der Spezifikation ein, sodass die Spezifikation immer aktuell ist.

Höre auf, wenn nichts Wichtiges mehr unklar ist oder der Benutzer nicht mehr antwortet. Für jeden verbleibenden offenen Punkt entscheide selbst, wähle die sinnvolle Voreinstellung für den genannten Zweck und schreibe sie in Annahmen mit einer einzeiligen Begründung. Der Benutzer sollte die Spezifikation lesen und jede getroffene Entscheidung nachvollziehen können.

Wenn die Anfrage bereits vollständig spezifiziert ist, überspringe die Fragen und sage dies in einer Zeile.

Phase 3: Grundrisse (nur Gebäude)

Wenn das Modell ein Gebäude ist oder Räume hat, kläre das Layout vor der Modellierung auf Papier. Lese references/floorplans.md und befolge es:

  1. Besprich den Grundriss mit dem Benutzer, unter Verwendung der obigen Fragetechniken: Stockwerke, Grundfläche, Räume, Anordnung, Treppen, Türen und Fenster.
  2. Zeichne einen Vektorgrundriss für jedes Stockwerk. Schreibe plans/layout.json und generiere plans/floor-<id>.svg mit dem beigelegten scripts/draw_plans.py.
  3. Überprüfe die Pläne mit dem Benutzer und überarbeite sie, bis der Benutzer sie freigibt. Halte die Freigabe in Entscheidungen fest.

Das freigegebene layout.json ist die maßgebliche Quelle für Wände, Öffnungen, Räume und Treppen des Modells. Überspringe diese Phase bei allem, was kein Gebäude ist.

Phase 4: Modellieren

Speichere das Ergebnis als <name>.blend (Blender) oder <name>.FCStd (FreeCAD) im Ordner des Modells. Für ein Spiel- oder Web-Asset exportiere es zusätzlich neben die Quelldatei (siehe Export für Engines).

Wähle das Werkzeug

Überprüfe, welche MCP-Server konfiguriert sind: Sieh in deinen verfügbaren Werkzeugen nach Blender- oder FreeCAD-MCP-Werkzeugen (Namen enthalten normalerweise blender oder freecad).

  1. Gespeicherte Wahl: Wenn .3d-builder.json im Projektstamm existiert, verwende dessen "tool" ("blender" oder "freecad"), sofern der Benutzer nichts anderes wünscht.
  2. Genau ein MCP-Server konfiguriert: verwende dieses Werkzeug.
  3. Beide oder keiner konfiguriert: Frage den Benutzer, welches Werkzeug verwendet werden soll (eine Multiple-Choice-Frage). Empfehle FreeCAD für funktionale Teile mit präzisen Abmessungen (Halterungen, Gehäuse, alles Gedruckte oder Gefräste) und Blender für organische Formen, skulptierte oder dekorative Objekte, alles, was gerendert werden soll, sowie Spiel- und Web-Assets (FreeCADs tesselierte Meshes eignen sich schlecht für Echtzeitanwendungen).
  4. Speichere die Wahl, indem du {"tool": "blender"} oder {"tool": "freecad"} in .3d-builder.json schreibst. Halte das Werkzeug auch in der Spezifikation fest.

Erstellung über MCP (bevorzugt)

  1. Führe zuerst einen günstigen Aufruf durch (z. B. Szenen-/Dokumenteninfo abrufen). Wenn dieser fehlschlägt oder nicht innerhalb von 10 Sekunden antwortet, behandle den Server als nicht verfügbar und weiche auf den Skript-Fallback aus. Teile dem Benutzer den Grund in einem Satz mit.
  2. Erstelle das Modell Schritt für Schritt gemäß der Spezifikation. Überprüfe die Maße während der Arbeit (frage Begrenzungsrahmen oder Objekteigenschaften ab), anstatt darauf zu vertrauen, dass der Code das Getroffene korrekt umsetzt.
  3. Speichere unter dem oben genannten Pfad.

Skript-Fallback

Wenn kein MCP-Server verfügbar ist, schreibe ein eigenständiges Python-Skript, <name>.py im Ordner des Modells, das das Modell von Grund auf erstellt und <name>.blend oder <name>.FCStd neben sich selbst speichert. Setze die wichtigsten Maße als benannte Konstanten an den Anfang, damit der Benutzer sie anpassen kann. Bei einem Gebäude liest das Skript plans/layout.json und kopiert die Koordinaten nicht in den Code (siehe references/floorplans.md, „Erstelle das Modell aus dem Layout“).

Versuche dann, es im Hintergrund auszuführen, falls das Werkzeug installiert ist:

  • Blender: blender --background --python models/<name>/<name>.py
  • FreeCAD: freecadcmd models/<name>/<name>.py (auf manchen Systemen FreeCADCmd oder freecad.cmd)

Wenn es läuft, überprüfe die Ausgabe (Datei existiert, gedruckter Begrenzungsrahmen stimmt mit der Spezifikation überein). Wenn es fehlschlägt, korrigiere das Skript und führe es erneut aus. Wenn das Werkzeug nicht im PATH ist, teile dem Benutzer den genauen Befehl mit, den er ausführen muss.

Werkzeugspezifische Fallstricke und Skriptgerüste: references/blender.md, references/freecad.md. Lese die Datei für das gewählte Werkzeug, bevor du Code schreibst.

Export für Engines

Nur bei Spiel- oder Web-Assets. Behalte die .blend-Datei als editierbare Quelle und exportiere daneben:

ZielFormatDatei
Web (three.js, Babylon.js), Godot, allgemeine VerwendungglTF binary<name>.glb
Unity, UnrealFBX (oder .glb, wenn die Pipeline des Benutzers glTF importiert)<name>.fbx

Engines laufen in Echtzeit, daher muss das Asset das Budget der Spezifikation einhalten: Überprüfe die Dreiecksanzahl, wende Transformationen an, setze den Pivot wie in der Spezifikation festgelegt und stimme Maßstab und Achsen der Engine ab. Exporteinstellungen und Fallstricke: Der Abschnitt „Spiel- und Web-Assets“ in references/blender.md.

Dieser Skill liefert die Asset-Datei. Das Laden in eine Szene, das Schreiben von Engine-Skripten oder das Erstellen einer three.js-Seite liegt außerhalb seines Umfangs; wenn der Benutzer dies ebenfalls wünscht, erledige es als separaten Schritt, nachdem dieser Ablauf abgeschlossen ist.

Abschluss

  1. Überprüfe das Modell anhand der Spezifikation: Gesamtabmessungen, jedes aufgeführte Merkmal vorhanden, sowie alle Passungs- oder Spielanforderungen. Bei Spiel-/Web-Assets auch die Dreiecksanzahl im Vergleich zum Budget und den Begrenzungsrahmen der exportierten Datei in Engine-Einheiten. Bei Gebäuden auch die Überprüfung anhand der freigegebenen Pläne: Gesamtabmessungen, Wandpositionen, jede Tür und jedes Fenster sowie Geschosshöhen.
  2. Aktualisiere die Spezifikation: Setze Status auf done, trage Ausgabe ein (Dateipfade inklusive Exporte und Pläne, Werkzeug, MCP oder Skript) und notiere alles, was anders als geplant ausgefallen ist.
  3. Berichte dem Benutzer kurz: was gebaut wurde, wo die Dateien sind, und die wichtigsten Annahmen, die er möglicherweise überprüfen möchte (verweise für den Rest auf die Spezifikation).

Wenn der Benutzer danach Änderungen wünscht, behandle sie als neuen Bearbeitungsauftrag (Phase 1, „Vorhandenes Modell bearbeiten“). Kleine Folgearbeiten im selben Gespräch („etwas dicker“) können stattdessen in derselben Spezifikation unter Revisionen festgehalten werden.

Verwandte Skills