Communitygithub.com

VectoJS Three

Compétence pour intégrer une interface VectoJS 2D dans une texture Three.js et rediriger les entrées du pointeur 3D vers la scène VectoJS.

Qu'est-ce que VectoJS Three ?

Cette compétence permet d'intégrer une interface VectoJS 2D en direct sur une texture Three.js, en redirigeant les entrées du pointeur 3D (souris, raycast) vers la scène VectoJS. Elle est utile pour créer des panneaux interactifs dans des environnements 3D (WebXR, visualisations, jeux) sans recourir au rendu DOM en 3D. La compétence s'appuie sur la classe `ThreeAdapter` de `@vectojs/three`, qui gère la création d'un maillage texturé, le routage des événements de pointeur et le nettoyage des ressources. Elle prend en charge les interactions de clic, survol et molette, mais ne permet pas la saisie de texte native complète dans une texture. Les utilisateurs doivent gérer leur propre raycaster, caméra et rendu Three.js. Les version antérieures à 0.1.4 de three présentaient des problèmes de performance O(N²) corrigés par le hook `present()`.

Compatible avec✓Claude Code✓Codex CLI✓Cursor
npx skills add vectojs/vectojs-skills

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait VectoJS Three ?

Utilisez cette compétence pour placer une interface VectoJS 2D en direct sur une texture Three.js et rediriger les entrées du pointeur 3D vers la scène VectoJS.

Workflow d'intégration

  1. Installez @vectojs/core, @vectojs/three, three, et @vectojs/ui si vous utilisez des composants d'interface.
  2. Créez un ThreeAdapter par texture de panneau VectoJS.
  3. Ajoutez des entités VectoJS à adapter.vectoScene, puis démarrez la scène interne.
  4. Ajoutez adapter.mesh ou la texture/matériau de l'adaptateur à la scène Three.js hôte.
  5. Dans la boucle de pointeur/molette hôte, effectuez un raycast contre le maillage de l'adaptateur et appelez adapter.updateIntersection(...).
  6. Appelez adapter.dispose() lors de la suppression du panneau.

Consultez references/three-recipes.md pour des extraits de code.

Contraintes

  • La sortie par défaut est un plan texturé plat, pas un rendu DOM en 3D.
  • Les tests de collision logiques VectoJS restent en 2D même lorsque le maillage est transformé dans l'espace monde.
  • L'application hôte possède la caméra, le moteur de rendu, les contrôles, la session XR, le raycaster et les règles d'occlusion.
  • Les UV du raycast doivent correspondre à la largeur/hauteur logique de l'adaptateur ; n'utilisez pas la taille du tampon de stockage pour le calcul de la mise en page.
  • La résolution de la texture affecte la netteté et le coût de téléchargement. Choisissez les dimensions en fonction de la distance de visualisation.

Erreurs courantes

ErreurCorrection
Ajouter un canevas d'adaptateur hors écran au DOMAjoutez adapter.mesh à Three.js ; le canevas sert de support à la texture.
Oublier d'appeler updateIntersectionRoutez les événements du raycaster hôte vers l'adaptateur à chaque événement de pointeur/molette.
Distribuer par coordonnées d'écranUtilisez les UV du raycast via ThreeAdapter.
Garder des textures disposées en vieAppelez adapter.dispose() et supprimez les références hôtes.
Attendre une accessibilité DOM complète dans XRTraitez le panneau 3D comme une texture de canevas ; fournissez une sémantique de niveau hôte si nécessaire.

Problèmes de version et de backend (vérifiés sur source)

  • three ≤ 0.1.3 : ThreeRenderer.flush() effectuait un rendu GL complet, et la Scene se vidait autour de chaque nœud non regroupé — le coût par trame augmentait en O(N²) en fonction du nombre d'entités. three 0.1.4 rend une fois par trame via le hook present() ; mettez à niveau avant de profiler quoi que ce soit.
  • L'entrée native dans une texture est limitée. Le canevas de l'adaptateur est hors écran, donc les éléments projetés d'accessibilité de la scène ne sont jamais connectés au document ; updateIntersection utilise le système de distribution d'événements propre à VectoJS. Les boutons, le survol et la molette fonctionnent ; la saisie de texte native complète (IME) ne fonctionne pas — gardez la saisie de texte à l'extérieur du panneau 3D ou acceptez une saisie simplifiée.
  • L'épaisseur de trait stroke() est effectivement de 1 px sur la plupart des plateformes (LineBasicMaterial.linewidth est une limitation WebGL connue). Dessinez des lignes épaisses sous forme de formes remplies à la place.
  • ThreeRenderer.drawImage alloue une texture par appel par trame (disposée lors de clear()) ; réutilisez un canevas source lorsque c'est possible. fillText est mis en cache à partir de trois 0.1.4 (LRU indexé par police|couleur|texte, 256 entrées) — sur ≤ 0.1.3, il avait le même coût par appel, donc préférez MSDFTextEntity dans ce cas.

Skills associés