Débogage en temps réel avec Leva

1. Qu'est-ce que Leva et pourquoi l'utiliser ?

Leva est une librairie qui ajoute une interface graphique (GUI) de contrôle directement dans votre application. Elle fait partie de l'écosystème pmndrs (Poimandres), le même collectif qui maintient React Three Fiber et Drei, ce qui garantit une intégration parfaite.

Plutôt que de longs discours, voyons Leva en action :

L'avantage est clair : vous pouvez ajuster des dizaines de paramètres en quelques secondes pour trouver le réglage parfait, que ce soit pour la couleur d'un matériau, l'intensité d'une lumière ou la position d'une caméra. C'est un gain de temps considérable.

2. Mise en place : useControls

Intégrer Leva est incroyablement simple. Commençons par installer la librairie dans votre projet :

npm install leva

L'outil principal que Leva nous fournit est un hook React : useControls. Ce hook va remplacer les useState que nous utilisions pour les propriétés que nous souhaitons rendre modifiables.

Pour découvrir son fonctionnement, la vidéo suivante est un excellent point de départ.

Atelier : Votre premier contrôle

Prenons un exemple simple. Imaginez ce composant Cube :

// Avant Leva
import { useState } from 'react';

function MyScene() {
  const [color, setColor] = useState('orange');

  return (
    <mesh>
      <boxGeometry />
      <meshStandardMaterial color={color} />
    </mesh>
  );
}

Pour rendre la couleur contrôlable avec Leva, il suffit de remplacer useState par useControls :

// Après Leva
import { useControls } from 'leva';

function MyScene() {
  // 1. Appelez useControls avec un objet décrivant vos contrôles
  const { color } = useControls({
    color: 'orange', // Leva va créer un sélecteur de couleur
  });

  // 2. Utilisez la valeur retournée comme avant
  return (
    <mesh>
      <boxGeometry />
      <meshStandardMaterial color={color} />
    </mesh>
  );
}

C'est tout ! En rechargeant votre page, un panneau de contrôle apparaîtra automatiquement, vous permettant de changer la couleur du cube en temps réel.

3. Explorer les différents types de contrôles

La force de Leva est sa capacité à déduire le type de contrôle à afficher en fonction de la valeur que vous lui donnez.

• Une chaîne de caractères au format hexadécimal ('#ff0000') devient un sélecteur de couleur.
• Un booléen (true ou false) devient une case à cocher.
• Un nombre (1.5) devient un curseur (slider) ou un champ numérique.
• Un tableau de nombres ([x, y, z]) devient un contrôle de vecteur.

Pour plus de précision, vous pouvez passer un objet de configuration au lieu d'une simple valeur.

const { scale, visible, position } = useControls({
  // Curseur avec min, max et pas
  scale: { value: 1, min: 0.5, max: 2, step: 0.01 },
  // Case à cocher
  visible: true,
  // Contrôle de vecteur pour la position
  position: { value: [0, 1, -1], step: 0.1 }
});

La vidéo suivante illustre parfaitement la création de ces différents types de contrôles.

4. Organiser le panneau et ajouter des actions

Lorsque le nombre de paramètres augmente, votre panneau peut vite devenir désordonné. Leva permet de les organiser dans des dossiers. De plus, vous pouvez ajouter des boutons pour déclencher des actions spécifiques, comme réinitialiser une position.

Cela se fait en important folder et button depuis la librairie leva.

Voici un exemple qui combine ces concepts :

import { useRef } from 'react';
import { useControls, folder, button } from 'leva';

function ControllableCube() {
  const meshRef = useRef();

  const { scale, color } = useControls({
    'Cube Transform': folder({
      scale: { value: 1, min: 0.5, max: 2 },
    }),
    'Cube Material': folder({
      color: 'orange',
    }),
    'Actions': folder({
      // Un bouton qui utilise une ref pour agir sur l'objet
      Reset: button(() => {
        meshRef.current.position.set(0, 0, 0);
        meshRef.current.rotation.set(0, 0, 0);
      }),
    }),
  });

  return (
    <mesh ref={meshRef} scale={scale}>
      <boxGeometry />
      <meshStandardMaterial color={color} />
    </mesh>
  );
}

5. Une pratique professionnelle : Cacher Leva en production

Leva est un outil de développement. Il ne doit pas être visible pour l'utilisateur final de votre application. Heureusement, il est très simple de le cacher pour le build de production.

Il suffit d'importer le composant <Leva /> et de le rendre conditionnellement en fonction de l'environnement.

// Dans votre fichier principal, par exemple App.js
import { Leva } from 'leva';

export default function App() {
  return (
    <>
      {/* Leva ne sera affiché qu'en mode développement */}
      <Leva collapsed hidden={process.env.NODE_ENV === 'production'} />

      <Canvas>{/* ... votre scène ... */}</Canvas>
    </>
  );
}

L'option collapsed est également utile pour que le panneau ne prenne pas toute la place au chargement.

Conclusion

Vous venez d'ajouter un des outils les plus puissants à votre arsenal de développeur 3D. Leva transforme le processus de réglage et de débogage d'une corvée en une activité créative et instantanée.

Points clés à retenir :

• Leva fournit une interface graphique pour modifier les paramètres de votre scène en temps réel.
• Le hook useControls est le point d'entrée principal. Il remplace useState pour les valeurs que vous souhaitez contrôler.
• Leva déduit intelligemment le type de contrôle (slider, couleur, case à cocher) à partir de la valeur fournie.
• Utilisez folder pour organiser vos contrôles et button pour déclencher des actions (souvent avec une ref).
• Pensez toujours à cacher Leva en production avec le composant <Leva hidden={process.env.NODE_ENV === 'production'} />.

Aperçu de la prochaine leçon :
Maintenant que nous savons contrôler notre scène depuis le code (leçon précédente) et la déboguer en temps réel avec Leva (cette leçon), nous allons nous pencher sur une communication plus poussée entre la 3D et la 2D. Dans la prochaine leçon, nous verrons comment faire en sorte que des actions dans la scène 3D (comme cliquer sur un objet) puissent mettre à jour l'interface utilisateur 2D (par exemple, afficher des informations sur l'objet cliqué dans un panneau latéral HTML).