Sim Env Builder

Was macht Sim Env Builder?

Ziel: Aus einer Beschreibung eine funktionierende, physikalisch korrekte und gut aussehende simulierte Umgebung in möglichst wenigen Benutzerinteraktionen liefern (idealerweise: Anfrage -> eine Bestätigung -> fertig). Qualitätsanspruch: Jeder Smoke-Test besteht, und Sie haben sich die Renderings angesehen – sie entsprechen der Anfrage.

SKILL_DIR unten = das Verzeichnis dieser Datei. Python-Helfer befinden sich in SKILL_DIR/scripts/simkit.

Phase 0 – Einrichtung (1 Minute)

PY=$(bash SKILL_DIR/scripts/setup_env.sh)       # Python mit mujoco, trimesh, usd-core, gymnasium
$PY SKILL_DIR/scripts/check_platform.py           # OS, GPU, Isaac-Verfügbarkeit

Wählen Sie den Umgebungsordner: ./<kurzer_snake_name>/ im aktuellen Verzeichnis, außer der Benutzer hat einen benannt.

Phase 1 – Backend wählen (siehe reference/backend_choice.md)

Isaac Sim benötigt eine NVIDIA RTX GPU unter Linux/Windows. MuJoCo läuft überall.

• MuJoCo: Standard. Kontaktreiche Manipulation und Fortbewegung, schnelle Iteration, CPU/Laptop/macOS, kleine bis mittlere Szenen, modellbasierte Regelung, reproduzierbare Forschung, MJX/Warp für GPU-RL.
• Isaac Sim: Fotorealistisches RTX-Rendering oder synthetische Daten (Replicator), RTX-Lidar/Kamera-Sensor-Realismus, tausende parallele Umgebungen in Isaac Lab, große USD/Omniverse-Szenen, Benutzer ist bereits auf Isaac.
• Wenn Isaac die bessere Wahl wäre, aber isaac_runnable_here falsch ist, sagen Sie das in der Bestätigung und bieten Sie an: Bau + vollständiger Test in MuJoCo hier UND Export einer USD-Bühne + Isaac-Smoke-Skript für den GPU-Rechner (reference/isaac.md). Beanspruchen Sie niemals Isaac-Ergebnisse, die Sie nicht selbst ausgeführt haben.

Phase 2 – Vor dem Bau mit dem Benutzer bestätigen (reference/confirmation.md)

1. Führen Sie zuerst einen kurzen Asset-Scan durch, damit die Aufgabenbeschreibung fundiert ist: ein find_assets-Aufruf (Poly Pizza MCP), der jede Objektrolle auflistet, 1-3 Abfragen pro Rolle.
2. Senden Sie EINE kurze Beschreibung (Vorlage in reference/confirmation.md): Backend + Begründung, was in der Szene sein wird, der Roboter/Agent und seine Steuerungsschnittstelle, welche Assets von Poly Pizza vs. prozedural stammen, wichtige Physik (Schwerkraft, Reibung, Zeitschritt), Ergebnisse und 2-4 Fragen, die jeweils Ihre empfohlene Voreinstellung enthalten.
3. Fragen Sie mit AskUserQuestion, falls dieses Werkzeug existiert. Andernfalls beenden Sie Ihren Zug mit der Beschreibung als Nachricht und warten Sie. Bauen Sie nicht, bevor der Benutzer antwortet. Ausnahme: Der Benutzer hat gesagt, nicht zu fragen / „bau es einfach“ -> schreiben Sie die Annahmen in SPEC.md und fahren Sie fort.
4. Halten Sie die bestätigten Entscheidungen in <env>/SPEC.md fest (Vorlage in reference/confirmation.md).

Phase 3 – Assets: Poly Pizza zuerst, prozeduraler Fallback (reference/assets.md)

Für jede Objektrolle:

1. find_assets / search_models -> lesen Sie das Ergebnis (gefunden / schwach / nicht gefunden).
2. gefunden oder schwach -> preview_models([...ids]) und ANSCHAUEN: Richtiges Objekt? Stil konsistent? Lehnen Sie Spielzeug, Cartoons in realistischen Szenen, Multi-Objekt-Bündel, falsche Größenklasse ab.
3. Akzeptieren -> download_model(id, "<absoluter Umgebungspfad>/assets/polypizza", "<Rolle>") (Credits werden automatisch in assets/polypizza/CREDITS.md erfasst).
4. nicht gefunden, abgelehnt oder Download-Fehler -> prozedural: simkit.procedural-Rezepte (Bäume, Gebäude, Möbel, Straßendekoration, Tore, Geschirr, Gelände...) oder eigene aus Primitiven / lathe / extrude / rock zusammensetzen. Lassen Sie niemals ein angefordertes Objekt weg.
5. Schreiben Sie <env>/assets/ASSETS.md: Rolle | Quelle (Poly Pizza ID + Titel + Lizenz, oder prozedurales Rezept) | echte Größe | Begründung. Wenn der Titel eines Modells von der Rolle abweicht („Parkbank“ als Picknicktisch verwendet), sagen Sie das und warum es trotzdem passt – oder suchen Sie erneut / gehen Sie prozedural vor. Notieren Sie auch ABGELEHNTE Kandidaten (ID + Grund: „Cartoon-Stil“, „Bündel von 12 Objekten“), damit die Suche nachvollziehbar bleibt, auch wenn am Ende alles prozedural ist. Poly-Pizza-Modelle sind statische Netze: Gelenkroboter und Fahrzeuge stammen aus simkit.robots (Sie können sie mit einem Poly-Pizza-Netz als visuelle Geom verkleiden).

Phase 4 – Bauen (reference/robots.md, templates/)

mkdir -p <env> && cp -r SKILL_DIR/scripts/simkit <env>/simkit       # ausgelagert: Umgebung ist in sich geschlossen
cp SKILL_DIR/templates/build_env.py SKILL_DIR/templates/env.py SKILL_DIR/templates/view.py <env>/   # bearbeiten Sie die ersten beiden

• build_env.py generiert alles deterministisch (geseedet) -> scene.xml. Verwenden Sie simkit.scene.Scene (Himmel, Boden, Lichter, Ziel-Kameras, Abschnitte für rohes MJCF), simkit.assets.glb_to_mujoco(glb, env, name, target={"height": m}, yaw_deg=..) für Poly-Pizza-Modelle (echte Größe, Z-up, farbgetrennte Teile, Box/Hülle/Teile-Kollision), simkit.procedural für Fallbacks und Gelände, simkit.robots für getestete Roboter (Quadrocopter, Auto, Differenzialantrieb, Arm + Greifer, Vierbeiner) und deren Regler.
• Maßstab in der realen Welt ist Pflicht (Größentabelle in reference/assets.md). Dinge ruhen auf ihrer Auflagefläche.
• Jede vom Benutzer genannte Objektklasse muss in der Übersicht klar sichtbar und in lesbarer Größe sein (ein „felsiger Pfad“ braucht sichtbare Steine, keine 7-cm-Pünktchen; „raues Gelände“ braucht in Robotergröße sichtbare Unebenheiten). Der Smoke-Test listet Pünktchen unter hints auf.
• Mindestens 2 benannte Kameras: eine Übersichts- und eine auf das Motiv gerichtete (der Roboter/das Aufgabenobjekt füllt etwa 30-50 % des Bildes; robotermontiert, falls vorhanden). Feste Sensorkameras dürfen nicht durch die Ruheposition des Roboters blockiert werden (Smoke meldet > 15 % Abdeckung).
• world.py (wenn die Szene eigene Dynamik hat): make_world(model) -> world(model, data), aufgerufen VOR jedem Physikschritt von Smoke, Examiner, Showcase, env.py, view.py und dem Dashboard. Auftrieb/Luftwiderstand, Wind, Förderbänder, Ampelschaltungen, scripted Fußgänger und NPC-Fahrzeuge leben hier, niemals in controller.py (ein passiver Test oder eine RL-Policy würde sonst eine Welt ausführen, in der Boote sinken und Lichter nie wechseln). Aufgabenprüfungen, die die Simulation schrittweise ausführen, müssen dies ebenfalls aufrufen.
• controller.py: eine scripted Demo-Policy (make_controller(model) -> ctrl(model, data)), die zeigt, dass die Umgebung ihren Zweck erfüllt (Drohne fliegt durch Tore, Auto fährt die Route, Arm erreicht das Objekt...). Setzen Sie DEMO_SECONDS = <Länge der vollständigen Demo> auf Modulebene: Der Smoke-Test filmt und prüft dann die GANZE Demo (heben, tragen, ablegen / jedes Tor), nicht nur die ersten 4 Sekunden.
• task_checks.py: Funktionen check_<name>(model, data) -> {"status", "value", "expect", "details"} für aufgabenbezogene Physik. Eine Prüfung pro Erfolgskriterium, das der Benutzer genannt oder bestätigt hat (benennen Sie es nach seinen Worten: „Füße im Kontakt“ -> check_feet_in_contact), plus Spawn-Plausibilität (Roboter startet auf seiner Auflagefläche). Mindestens 2. Schreiben Sie die Schwellenwerte UND die genaue Definition jeder Metrik (Referenzpunkt, Einheiten: „Rover-Basis-Mitte bis Lander-Mitte, Meter“) VOR dem ersten Durchlauf in SPEC.md und behalten Sie sie bei: Ein knappes Verfehlen bedeutet, den Regler/die Szene zu korrigieren, niemals die Prüfung zu lockern (jede Schwellenwertänderung muss unter „Änderungen am bestätigten Plan“ erscheinen). Eine Prüfung, die innerhalb von 15 % ihres Grenzwerts besteht, wird mit ihrer Marge gemeldet („Neigung 25,8 Grad vs. 30-Grad-Limit“). Jedes von Ihnen behauptete Verhalten (Hindernisverlangsamung, Ampelschaltung, Auftrieb, Greiferhalt) braucht eine Prüfung, die es ausübt, z. B. ein Hindernis in den Weg legen und behaupten, dass der Roboter anhält. Jede wichtige physikalische Eigenschaft der Szene erhält eine gemessene Prüfung mit einem physikalischen Ziel: die Rollverzögerung eines Balls, die Wasserlinie eines Bootes, die Steigfähigkeit eines Rovers, die Fallzeit bei niedriger Schwerkraft, die Greifkraft. Ein erforderlicher Sensor erhält ebenfalls eine Prüfung: Rendern Sie die Roboterkamera während der Demo und behaupten Sie ein nicht-leeres Bild, das die Aufgabe zeigt (z. B. Baumreihen voraus); für Lidar behaupten Sie sinnvolle Entfernungen. Führen Sie jede Aufgabenprüfung sowohl auf dem scripted Rollout als auch auf 2-3 gestörten (anderer Seed, Startpose, Anfangsgeschwindigkeit, Lichtphase) aus – eine Prüfung, die nur für einen genauen Rollout gilt, beweist wenig. Greifprüfungen erfordern Kontakt zwischen BEIDEN Fingerauflagen und dem Objekt während des gesamten Hebens und Tragens (lesen Sie data.contact), nicht nur „das Objekt ging hoch“.
• Kollider: einfach und ehrlich. Bäume: Stammkollider, Kronen nur visuell, es sei denn, der Benutzer möchte Kronentreffer. Multirotoren: Armkapseln oder eine Hülle, nicht ein Kasten, der die Propeller verschluckt. Nicht-konvexe Requisiten (Mikroskop, Stuhl, Bogen, Regal) erhalten collision="parts" oder einige Primitive; eine konvexe Hülle um sie herum blockiert sichtbar leeren Raum (siehe collision_sheet.png).
• env.py: Gymnasium-artiges reset/step/render mit Aufgabenbeobachtung, Belohnungsstub, Terminierung. Sein __main__-Selbsttest treibt die Umgebung DURCH die Umgebungs-API mit dem Demo-Regler (oder einer Referenz-Policy) und gibt aus, ob das Aufgaben-Ziel erreicht wurde – Beweis, dass das Ziel erreichbar ist.
• Debug-/Kamerastarrkörper und Marker: Geom-Gruppe 4-5 (niemals gerendert), nicht in Datenkameras.
• Aufgehängte Dinge (Deckenleuchten, Hängeschilder, Wandregale): benennen Sie sie mounted_* oder hanging_*, damit die Schwebekörper-Prüfung sie überspringt.
• Beleuchtung: neutrales Weiß (keine gefärbten Lichter); höchstens 2-3 zusätzliche Lichter; prüfen Sie, dass eine weiße Wand in den Renderings weiß-grau bleibt.
• Keine unangeforderten Dekorationen über das hinaus, was die Szene korrekt lesbar macht; listen Sie optionale Extras in der Beschreibung auf, damit der Benutzer zustimmen kann.
• Zeitrahmen: notieren Sie die Zeit, wenn Sie mit dem Bau beginnen (date). Bonus-/Stretch-Items („Falten ist ein Bonus“) kommen erst, nachdem alle Muss-Kriterien bestanden sind, und werden zuerst gestrichen. Wenn Sie etwa 60 Minuten im Bau sind, hören Sie auf, das zu tun, was noch übrig ist: Machen Sie REPORT.md und README-Ergebnisse endgültig und berichten Sie (gestrichene Items auflisten). Ein Build, der nie berichtet, ist schlimmer als einer mit einer bekannten Lücke.
• Budget: Sobald jedes Muss existiert und alle Prüfungen bestanden sind, hören Sie auf, Extras hinzuzufügen – schließen Sie die visuelle Prüfung, README und Bericht ab. Extras kommen in die README als Ideen.
• Führen Sie $PY build_env.py nach jeder Änderung aus; Kompilierungsfehler enthalten Zeilennummern.

Phase 5 – Smoke-Tests (reference/smoke_tests.md). Alle drei sind erforderlich.

cd <env> && $PY -m simkit.smoke scene.xml --out smoke --controller controller.py --task-checks task_checks.py

1. Rendertest – Jede benannte Kamera + automatische Ansichten rendern nicht-leere, beleuchtete, detaillierte Bilder; Segmentierung zeigt, welche Objekte sichtbar sind (nicht gesehene Objekte werden markiert).
2. Physik-Prüfer – Löser/Kontakte/Reibung/Schwerkraft-Sonden mit den eigenen Einstellungen der Szene, Rollout-Stabilität, Penetration, Durchfallen, Setzung, Stellglied-Schrittantworten, Determiniertheit, Zeitschritt-Empfindlichkeit, Echtzeit-Faktor, Layout (schwebende / eingesunkene / durchdringende Requisiten), plus Ihre Aufgabenprüfungen.
3. Visuelle Prüfung – SIE müssen smoke/contact_sheet.png, smoke/filmstrip.png, smoke/collision_sheet.png und die Nahaufnahmen in smoke/renders/ öffnen und betrachten (Read-Werkzeug), dann die Checkliste in smoke/visual_check.md mit konkreten Beobachtungen ausfüllen. Beheben Sie jeden FEHLER. Untersuchen Sie jede WARNUNG (beheben Sie sie oder erklären Sie in der README, warum sie erwartet wird). Bauen Sie neu und führen Sie erneut aus, bis das Urteil BESTANDEN / BESTANDEN_MIT_WARNUNGEN-ERKLÄRT ist UND die visuelle Prüfung ehrlich überall „ja“ ist. Erwarten Sie 2-3 Iterationen; das erste Rendern ist selten richtig. Führen Sie auch $PY env.py aus (zufällige Aktionen, endliche Beobachtungen).

Phase 6 – Isaac Sim Ergebnis (nur wenn Isaac gewählt wurde; reference/isaac.md)

$PY -m simkit.usd_export scene.xml isaac/scene.usda (Export + lokale Validierung), kopieren Sie SKILL_DIR/templates/isaac_smoke.py nach isaac/, dokumentieren Sie, wie es auf dem GPU-Rechner ausgeführt wird. Geben Sie klar an, was ausgeführt wurde und was nicht.

Phase 7 – Ausliefern

<env>/README.md: Was in der Szene ist, wie man sie ausführt (Bau, Smoke, Umgebung, Viewer: $PY view.py, die den Demo-Regler live ausführt; einfaches mujoco.viewer zeigt nur passive Physik), Kameras, Stellglieder, Regler, Aufgabenprüfungen, Asset-Credits, bekannte Einschränkungen. Abschließende Nachricht an den Benutzer: Urteilszeile, was gebaut wurde, welche Assets von Poly Pizza vs. prozedural stammen, Smoke-Ergebnisse, Pfade zu smoke/showcase.mp4 (das Video, das man sich ansieht), Kontaktbogen und Filmstreifen, alles nicht Erledigte oder nicht Verifizierte, und eine Liste „Änderungen am bestätigten Plan“ (ausgetauschte Assets oder Lizenzen, geänderte Größen/Anzahlen, gestrichene Extras) – leer, wenn keine, aber immer vorhanden. Kopieren Sie jede Zahl (bestandene Prüfungen, Punktzahlen, Fehler) aus smoke/smoke_report.json und physics_report.json; fügen Sie deren summary_line wörtlich ein („Smoke BESTANDEN: Prüfer 19 bestanden / 0 warn / 0 fehl; Aufgabenprüfungen 9/9 bestanden; Rendering ok“) und schreiben Sie niemals Zählungen aus dem Gedächtnis. Beginnen Sie <env>/REPORT.md, sobald der erste Smoke-Durchlauf abgeschlossen ist, und aktualisieren Sie ihn nach jeder Korrektur, sodass eine unterbrochene Sitzung dennoch einen Bericht hinterlässt; die endgültige Nachricht ist seine letzte Version.

Ergebnis-Layout (genau beibehalten; Werkzeuge und Dashboards hängen davon ab)

<env>/
  SPEC.md  README.md  REPORT.md  build_env.py  scene.xml  env.py  view.py  controller.py  task_checks.py
  world.py                      (nur wenn die Szene eigene Dynamik hat)
  simkit/                       ausgelagerte Helfer
  assets/polypizza/*.glb  assets/polypizza/CREDITS.md  assets/polypizza/polypizza_assets.json
  assets/meshes/  assets/procedural/  assets/ASSETS.md
  smoke/  (showcase.mp4 contact_sheet.png filmstrip.png collision_sheet.png renders/ rollout.mp4
           physics_report.json render_report.json smoke_report.json env_manifest.json
           SMOKE.md visual_check.md)
  isaac/  (nur für Isaac: scene.usda, isaac_smoke.py, README section)

Hart erarbeitete Regeln (jede hat bereits einen echten Build zerstört)

• Bleiben Sie innerhalb des bestätigten Umfangs. Die Demo zeigt, worauf der Benutzer sich geeinigt hat (z. B. „Stehen reicht“ bedeutet einen stabilen Stand, nicht einen neuen Fortbewegungsregler). Verwenden Sie die Zeit für die Szene, die Assets, die Prüfungen und die visuelle Überprüfung; listen Sie Dehnungsideen in der README auf.
• <visual>-Einstellungen: sc.set_visual("map", znear=.., zfar=..) usw. Jedes Element darf einmal vorkommen.
• Berechnen Sie niemals von Hand Kamerakoordinaten xyaxes: verwenden Sie Scene.camera(name, pos, target) / simkit.scene.lookat.
• Schreiben Sie niemals von Hand Keyframe-qpos-Listen: setzen Sie scene.home[joint] = value (Roboter tun das für Sie); Scene.write baut den home-Keyframe nach Gelenknamen und setzt den Positionsstellglied-Steuerbefehl entsprechend.
• Flache/dünne Netze benötigen inertia="shell" (glb_to_mujoco macht das). Visuelle Geom: contype=0 conaffinity=0 group=2 mass=0; Kollisionsproxys in Gruppe 3.
• Ein Roboter, der an die Welt geschweißt ist, kollidiert mit seiner eigenen Basis: Fügen Sie ein <exclude> für Basis/erstes Glied hinzu.
• Positive Werte...

[gekürzt für die Übersetzung]