Communitygithub.com

VectoJS Three

Nutze dieses Skill, um eine Live-VectoJS-2D-Oberfläche auf eine Three.js-Textur zu legen und 3D-Zeigereingaben zurück in die VectoJS-Szene zu leiten.

Was ist VectoJS Three?

Dieser Skill ermöglicht es Entwicklern, eine voll funktionsfähige VectoJS-2D-Benutzeroberfläche auf eine Three.js-Textur zu projizieren und 3D-Zeigereingaben (z. B. Pointer, Wheel) aus der 3D-Szene zurück in die VectoJS-Logik zu routen. Unterstützt werden die AI-Agenten-Plattformen Codex, Claude Code, Cursor und GitHub Copilot. Der Skill integriert sich über den `ThreeAdapter`, der die VectoJS-Szene als Offscreen-Canvas rendert und die Textur über ein Mesh in die Three.js-Szene einbringt. Wichtig sind das korrekte Raycasting mit UV-Koordinaten und die Vermeidung häufiger Fehler wie das Vergessen von `updateIntersection` oder die Verwendung von Bildschirmkoordinaten anstelle von UVs. Der Skill dokumentiert auch versionsabhängige Gotchas (z. B. Rendering-Kosten in three ≤ 0.1.3, native Eingabelimitierungen in Texturen, Linienbreitenbeschränkungen) und gibt konkrete Korrekturen in einer Tabelle der häufigen Fehler an.

Funktioniert mit✓Claude Code✓Codex CLI✓Cursor
npx skills add vectojs/vectojs-skills

In Ihrer bevorzugten KI fragen

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

Dokumentation

Was macht VectoJS Three?

Verwende diesen Skill, um eine Live-VectoJS-2D-Oberfläche auf eine Three.js-Textur zu legen und 3D-Zeigereingaben zurück in die VectoJS-Szene zu leiten.

Integrationsablauf

  1. Installiere @vectojs/core, @vectojs/three, three und ggf. @vectojs/ui, wenn UI-Komponenten verwendet werden.
  2. Erstelle einen ThreeAdapter pro VectoJS-Panel-Textur.
  3. Füge VectoJS-Entitäten zu adapter.vectoScene hinzu und starte dann die innere Szene.
  4. Füge adapter.mesh oder die Adapter-Textur/das Material zur hostenden Three.js-Szene hinzu.
  5. Führe in der hostenden Pointer-/Wheel-Schleife Raycasting gegen das Adapter-Mesh durch und rufe adapter.updateIntersection(...) auf.
  6. Rufe adapter.dispose() auf, wenn das Panel entfernt wird.

Lies references/three-recipes.md für Code-Ausschnitte.

Einschränkungen

  • Die Standardausgabe ist eine flache texturierte Ebene, kein DOM, das in 3D gerendert wird.
  • Das logische VectoJS-Hit-Testing bleibt 2D, selbst wenn das Mesh im Weltraum transformiert wird.
  • Die Host-Anwendung besitzt die Kamera, den Renderer, die Steuerung, die XR-Sitzung, den Raycaster und die Occlusion-Regeln.
  • Raycast-UVs sollten auf die logischen width/height des Adapters abbilden; verwende nicht die Backing-Store-Größe für Layout-Berechnungen.
  • Die Texturauflösung beeinflusst Schärfe und Upload-Kosten. Wähle Abmessungen entsprechend der Betrachtungsentfernung.

Häufige Fehler

FehlerKorrektur
Hinzufügen eines Offscreen-Adapter-Canvas zum DOMFüge adapter.mesh zu Three.js hinzu; das Canvas dient als Textur-Backing.
Vergessen von updateIntersectionLeite Host-Raycaster-Ereignisse bei jedem Pointer-/Wheel-Ereignis an den Adapter weiter.
Verwenden von BildschirmkoordinatenVerwende Raycast-UVs über ThreeAdapter.
Beibehalten entsorgter TexturenRufe adapter.dispose() auf und entferne Host-Referenzen.
Erwarten vollständiger DOM-Barrierefreiheit in XRBehandle das 3D-Panel als Canvas-Textur; stelle Host-seitige Semantik bereit, wo nötig.

Versions- und Backend-Gotchas (quellgeprüft)

  • three ≤ 0.1.3: ThreeRenderer.flush() führte einen vollständigen GL-Renderdurchlauf aus, und die Szene spülte um jeden nicht-gebatchen Knoten – die Framekosten wuchsen O(N²) mit der Anzahl der Entitäten. three 0.1.4 rendert einmal pro Frame über den present()-Hook; aktualisiere vor dem Profiling.
  • Native Eingabe in einer Textur ist begrenzt. Der Adapter-Canvas ist offscreen, daher sind die projizierten Barrierefreiheitselemente der Szene nie mit dem Dokument verbunden; updateIntersection fällt auf VectoJS' eigenen Ereignisdispatch zurück. Buttons/Hover/Wheel funktionieren; vollständige native IME/Textbearbeitung nicht – halte Texteingabe außerhalb des 3D-Panels oder akzeptiere vereinfachte Eingabe.
  • stroke()-Linienbreite ist effektiv 1px auf den meisten Plattformen (LineBasicMaterial.linewidth ist eine bekannte WebGL-Einschränkung). Zeichne dicke Linien stattdessen als gefüllte Formen.
  • ThreeRenderer.drawImage allokiert eine Textur pro Aufruf pro Frame (freigegeben bei clear()); verwende wo möglich eine Quell-Canvas wieder. fillText ist ab three 0.1.4 gecacht (LRU mit Schlüssel aus Schrift|Farbe|Text, 256 Einträge) – bei ≤ 0.1.3 hatte es die gleichen Kosten pro Aufruf, daher bevorzuge dort MSDFTextEntity.

Verwandte Skills