KI 3D Editor

Live-Demo: https://ki-3d-editor.onrender.com (Render Free-Tier: schläft nach ~15 Min. Inaktivität, erster Aufruf ~1 Min.; Nutzerdaten in data/users.json sind ohne persistente Disk nicht dauerhaft)

Browserbasierter 3D-Spiele-Editor mit KI-Befehlen – gebaut mit Vite + React + TypeScript, three.js (über @react-three/fiber und @react-three/drei) und Zustand.

Funktionen

• 3D-Viewport mit Raster, Orbit/Fly-Kamera, Schatten, Mehrfachauswahl, Transform-Gizmos (Welt/Lokal), Snapping
• Hierarchie mit Eltern-Kind (parentId), Drag&Drop, Sichtbarkeit/Sperren, Ebenen/Tags
• Import GLB/GLTF/OBJ (+ Texturen/HDR/Audio), Asset-Browser (IndexedDB)
• PBR-Materialien, Nebel, Environment, erweiterte Lichter
• Play-Modus mit Rapier-Physik und Sandbox-Skripten (optional Sucrase-TS)
• Timeline, Audio-Quellen, Visual-Scripting-MVP, Komponenten (CharacterController, …)
• Befehlspalette (Strg+K), Kontextmenü, Verlauf, Onboarding, FPS-Badge
• Export spielbares HTML-ZIP, Screenshot, Vercel-Proxy (vercel.json, server/ai-proxy.mjs)
• KI: Offline-Parser, Chat-Ops, Agent-Tool-Loop, Prompt-Bibliothek, Level-Gen, Text-zu-3D-Stub
• Speichern/Laden JSON + Autosave (localStorage + IndexedDB)

Landingpage & Konten

• / – Landingpage (Hero, Kurzbeschreibung, Funktionen, Screenshot-Galerie mit Lightbox)
• /registrieren, /login – Registrierung und Anmeldung (Deutsch)
• /app – der Editor, nur nach Login (sonst Weiterleitung zu /login?next=/app); unten rechts Benutzer + „Abmelden"
• Projekte (IndexedDB) werden pro Benutzer getrennt gespeichert

Auth-System (selbst gehostet, server/auth.mjs, keine externen Dienste):

Endpunkt	Methode	Zweck
/api/auth/register	POST {email, password, name?}	Konto anlegen + anmelden
/api/auth/login	POST {email, password}	Anmelden
/api/auth/logout	POST	Session widerrufen, Cookie löschen
/api/auth/me	GET	aktueller Benutzer oder 401

• Passwörter mit bcrypt (Kostenfaktor 12) gehasht, nie im Klartext gespeichert
• Session-ID HMAC-signiert (AUTH_SECRET) im httpOnly-Cookie (SameSite=Lax, in Produktion Secure), 7 Tage gültig, serverseitig widerrufbar
• Validierung: gültige E-Mail, Passwort 8–128 Zeichen mit Buchstabe + Ziffer
• Rate-Limit: 5 Fehlversuche pro IP+E-Mail / 15 min (danach 429), 10 Registrierungen pro IP / h
• Nur application/json-POSTs (CSRF-Schutz), Weiterleitungsziel nur intern (kein Open Redirect)
• /api/ai und /api/meshy nur für angemeldete Benutzer
• Speicher: JSON-Datei data/users.json (in .gitignore)

Umgebungsvariablen:

Variable	Pflicht	Beschreibung
AUTH_SECRET	in Produktion ja	langes Zufalls-Secret, z. B. openssl rand -hex 32. Fehlt es, wird pro Start ein zufälliges erzeugt (Sessions gehen bei Neustart verloren)
AUTH_DB_FILE	nein	Pfad der Benutzerdatei (Standard data/users.json)
NODE_ENV=production	–	setzt Secure am Cookie (HTTPS nötig)
PORT	nein	Port des Produktionsservers (Standard 8787)

Starten

npm install
npm run dev        # http://localhost:5173
npm run build      # Produktions-Build nach dist/
npm run preview    # Build lokal ansehen (ohne Auth-API)

# Produktion (Frontend + Auth + KI-Proxy in einem Node-Server)
npm run build
AUTH_SECRET=$(openssl rand -hex 32) NODE_ENV=production PORT=8787 npm start

Tests

npm test            # Vitest-Unit-Tests für src/lib (Validierung, Operationen, Offline-Parser, KI-Client, Speichern)
npm run e2e         # Playwright-E2E-Tests (Editor + Auth/Landingpage) gegen den Dev-Server (startet ihn bei Bedarf selbst)
npm run screenshot  # erzeugt screenshot-qa.png + screenshot-landing(-mobile).png
npm run typecheck   # tsc -b
npm run check       # Typecheck + Unit-Tests + Build

Die E2E-Tests nutzen ein lokal installiertes Chrome (/usr/bin/google-chrome oder CHROME_PATH), sonst vorher npx playwright install chromium. Die KI wird dabei über einen gemockten OpenAI-kompatiblen Endpunkt getestet (gültige, kaputte und bösartige Antworten). Im Dev-Modus stellt der Editor dafür window.__ki3d bereit (nicht im Produktions-Build).

Tastenkürzel

Taste	Aktion
W / E / R	Bewegen / Drehen / Skalieren
Strg+Z / Strg+Y (oder Strg+Umschalt+Z)	Rückgängig / Wiederholen
Strg+D	Duplizieren
Entf / Backspace	Löschen
Esc	Auswahl aufheben
Linke Maus / Rechte Maus / Mausrad	Auswählen & Orbit / Schwenken / Zoom

KI einrichten

Oben rechts auf ⚙ Einstellungen klicken, Basis-URL, Modell und API-Schlüssel eintragen. Die Daten werden nur im localStorage deines Browsers gespeichert und direkt vom Browser an den Endpunkt gesendet (POST {Basis-URL}/chat/completions).

Ohne Schlüssel (oder mit Häkchen „nur Offline-Parser“) versteht der Editor u. a.:

• erstelle 5 rote Würfel im Kreis · füge 3 blaue Kugeln in einer Reihe hinzu · add 4 yellow cylinders in a grid
• erstelle einen Boden · füge ein Licht hinzu
• mach die Würfel grün · färbe Auswahl gelb
• verschiebe Auswahl nach oben · Auswahl größer / kleiner · drehe Auswahl 90 grad
• lösche die Kugeln · lösche Auswahl · lösche alles

Schlägt ein KI-Aufruf fehl, wird automatisch der Offline-Parser versucht.

Operationsformat

{
  "operations": [
    { "op": "add", "type": "box", "name": "Turm", "position": [0, 1, 0], "scale": [1, 2, 1], "color": "#ff0000" },
    { "op": "update", "target": "Turm", "rotation": [0, 45, 0] },
    { "op": "delete", "target": "all:sphere" }
  ],
  "message": "Kurze Zusammenfassung"
}

target kann eine ID, ein Name, selected, all oder all:<typ> sein. Rotationen sind in Grad.

Projektstruktur

src/
  App.tsx                  Layout (Werkzeugleiste, Panels, Statusleiste)
  store.ts                 Zustand-Store: Objekte, Auswahl, Undo/Redo
  hooks.ts                 Tastenkürzel & Autosave
  types.ts                 Typen & Bezeichnungen
  components/
    Viewport.tsx           three.js-Szene, Gizmos, Auswahl
    Toolbar.tsx            Primitive, Modi, Speichern/Laden, Undo/Redo
    HierarchyPanel.tsx     Szenenliste
    PropertiesPanel.tsx    Eigenschaften
    AIPanel.tsx            KI-Befehlsfeld
    SettingsDialog.tsx     KI-Einstellungen
  lib/
    ai.ts                  OpenAI-kompatibler Client + System-Prompt
    sceneOps.ts            Validierung & Anwendung der Operationen
    fallbackParser.ts      Offline-Parser
    validate.ts            Farben, Vektoren, Grenzwerte
    persistence.ts         JSON-Export/-Import, Autosave
    objects.ts, id.ts      Objekt-Fabrik, IDs

Bekannte Einschränkungen

• Der API-Schlüssel liegt im Browser (localStorage) – nur für lokale/private Nutzung gedacht. Manche Anbieter blockieren direkte Browser-Aufrufe (CORS); dann einen Proxy oder einen lokalen Server (Ollama: OLLAMA_ORIGINS=*) verwenden.
• Nur Einzelauswahl, keine Gruppen/Hierarchie-Verschachtelung, keine Texturen/Modelle (GLTF-Import), kein Play-Modus/Skripting.
• Objekte am Boden lassen sich per Klick auswählen – große Ebenen können daher Klicks „abfangen“.
• Das Bundle ist ~1,2 MB (three.js); Code-Splitting folgt später.
• Maximal 2000 Objekte und 16 Lichter pro Szene (Punktlichter werfen keine Schatten).
• Während eines Gizmo-Drags aktualisiert sich das Eigenschaften-Panel erst beim Loslassen.

KI-Proxy (Server)

Für Produktion den API-Schlüssel nicht im Browser halten:

AI_API_KEY=sk-... AI_BASE_URL=https://api.openai.com/v1 AI_MODEL=gpt-4o-mini node server/ai-proxy.mjs
# oder im Vite-Dev: gleiche Env-Variablen → Middleware /api/ai

Optional MESHY_API_KEY für Text-zu-3D. Ohne Key erzeugt der Editor Demo-Meshes.

Siehe auch VERBESSERUNGEN-2.md (Status aller 100 Punkte) und screenshot-batch2.png.

Aktueller Stand (Verbesserungen-2)

Siehe VERBESSERUNGEN-2.md: 100 ✅ · 0 🟡 · 0 ❌. Darunter u.a. Multi-Viewport (Ortho), Shader-Graph-MVP, WebGPU-Flag, Instancing-Gras, Kamera-Pfad, Musik-Mixer, Lip-Sync-Jaw, HUD/Dialog/Inventar, Szenen-Tabs, Rapier-Joints, WebLLM-Flag, Collab-BroadcastChannel, Poly Haven, Speech-Commands, KI-NPC, Kosten-Schätzung, GitHub-ZIP/Gist, lokale Rollen, prozedurale KI-Helfer (API optional).

Welten & Asset-Bibliothek

• 140 CC0-Modelle (Kenney Nature Kit, City Kit Suburban/Commercial/Roads) als meshopt-komprimierte GLB unter public/assets/<kategorie>/ (~2,4 MB), PBR-Texturen von Poly Haven (CC0). Lizenzen: public/assets/CREDITS.md, LICENSE-kenney-*.txt. Vorschaubilder: npm run thumbs (im Editor-Renderer erzeugt).
• Bibliothek links: Kategorien, Suche, Klick/Drag&Drop zum Platzieren, Shift+Klick für den Streu-Pinsel (Pinsel/Radieren, Radius, Dichte).
• Welten-Presets: Bergtal, Kleinstadt, Dorf, Wüste/Canyon, Insel – prozedurales Heightmap-Terrain (Noise, Textur-Blending nach Höhe/Neigung), Wasser, Himmel, instanzierte Vegetation mit Chunk-LOD, Spline-Straßen.
• KI/Offline-Parser: „erstelle einen Wald mit Bergen“, „baue eine Stadt“, „pflanze 50 Tannen“, „baue 4 Häuser“.
• Screenshots: npm run screenshot:world → screenshot-preset-*.png, screenshot-assets.png.

Gegenstände (CC0, Kenney)

344 neue Objekte in 11 Kategorien: Möbel, Essen, Waffen, Werkzeuge, Kisten, Fahrzeuge, Sammelobjekte (mit Pickup + Rotation), Fantasy/Dungeon, Sci-Fi, Licht, Zäune & Schilder. Offline-Parser versteht z. B. „platziere 10 Münzen“ oder „stelle einen Tisch mit Stühlen auf“. Screenshot: npx playwright test e2e/screenshot-items.spec.ts.

Deployment (Render)

Web Service (Node, Free): Build npm ci --include=dev && npm run build, Start npm start, Env AUTH_SECRET (zufällig), AUTH_DB_FILE=data/users.json. Smoke-Test: LIVE_URL=https://ki-3d-editor.onrender.com npx playwright test e2e/live.spec.ts.