lil-gui w praktyce - budujemy panel sterowania sceną Three.js

W pierwszej części poznaliśmy podstawy biblioteki lil-gui. Dowiedzieliśmy się, jak tworzyć suwaki, pola wyboru, listy rozwijane, selektory kolorów oraz grupować kontrolki za pomocą folderów. To jednak dopiero początek możliwości tej biblioteki. W rzeczywistych aplikacjach lil-gui nie służy wyłącznie do zmiany pojedynczych liczb. Najczęściej pełni rolę kompletnego panelu sterowania, umożliwiającego modyfikację parametrów sceny 3D, materiałów, świateł, animacji czy kamer bez konieczności edycji kodu źródłowego. W tej części tutoriala zbudujemy niewielką aplikację demonstracyjną, która pozwoli sterować sceną Three.js w czasie rzeczywistym. Nasza aplikacja będzie umożliwiała:

• zmianę geometrii obiektu,
• zmianę koloru materiału,
• przełączanie trybu Wireframe,
• regulację parametrów materiału,
• sterowanie animacją,
• zmianę intensywności świateł,
• pokazywanie i ukrywanie pomocników sceny,
• przywracanie ustawień domyślnych jednym kliknięciem.

Import bibliotek

<script type="importmap">
{
    "imports":{
        "three":"https://cdn.jsdelivr.net/npm/[email protected]/build/three.module.js",
        "three/addons/":"https://cdn.jsdelivr.net/npm/[email protected]/examples/jsm/",
        "lil-gui":"https://cdn.jsdelivr.net/npm/[email protected]/+esm"
    }
}
</script>

import * as THREE from "three";
import { OrbitControls } from "three/addons/controls/OrbitControls.js";
import GUI from "lil-gui";

Tworzenie renderera

const renderer = new THREE.WebGLRenderer({
    antialias:true
});

renderer.setPixelRatio(window.devicePixelRatio);

renderer.setSize(
    window.innerWidth,
    window.innerHeight
);

renderer.shadowMap.enabled = true;

document.body.appendChild(renderer.domElement);

Tworzenie sceny

const scene = new THREE.Scene();
scene.background = new THREE.Color(0x30343f);

Kamera

const camera =
new THREE.PerspectiveCamera(
    60,
    window.innerWidth / window.innerHeight,
    0.1,
    100
);

camera.position.set(
    4,
    3,
    5
);

OrbitControls

const controls =
new OrbitControls(
    camera,
    renderer.domElement
);

controls.enableDamping = true;

controls.update();

Dodawanie pomocników sceny

const grid = new THREE.GridHelper(
    12,
    12
);

scene.add(grid);

const axes = new THREE.AxesHelper(2);

scene.add(axes);

Dodawanie światła

• światło otoczenia (Ambient Light),
• światło kierunkowe (Directional Light).

const ambientLight =
new THREE.AmbientLight(
    0xffffff,
    1
);

scene.add(ambientLight);

const directionalLight =
new THREE.DirectionalLight(
    0xffffff,
    2
);

directionalLight.position.set(
    4,
    6,
    3
);

scene.add(directionalLight);

directionalLight.castShadow = true;

Tworzenie geometrii

function createGeometry(type) {
    switch(type){
        case "Sphere":
            return new THREE.SphereGeometry(
                1,
                48,
                32
            );
        case "Torus":
            return new THREE.TorusGeometry(
                0.8,
                0.3,
                24,
                120
            );
        case "Torus Knot":
            return new THREE.TorusKnotGeometry(
                0.7,
                0.25,
                160,
                24
            );
        default:
            return new THREE.BoxGeometry(
                1.8,
                1.8,
                1.8
            );
    }
}

Dlaczego funkcja zamiast jednej geometrii?

const geometry = new THREE.BoxGeometry();

mesh.geometry = createGeometry("Sphere");

Tworzenie materiału

const material =
new THREE.MeshStandardMaterial({
    color:"#44aaff",
    metalness:0.3,
    roughness:0.4,
    transparent:true,
    opacity:1
});

• color - kolor powierzchni
• metalness - stopień metaliczności materiału
• roughness - chropowatość powierzchni
• transparent - umożliwia zmianę przezroczystości
• opacity - poziom przezroczystości

Tworzenie siatki (Mesh)

const mesh = new THREE.Mesh(
    createGeometry("Cube"),
    material
);

mesh.castShadow = true;

scene.add(mesh);

Dodajemy lil-gui

Dlaczego potrzebujemy obiektu settings?

gui.add(material, "metalness", 0, 1);
gui.add(material, "roughness", 0, 1);
gui.add(mesh.rotation, "y", 0, Math.PI * 2);
gui.add(ambientLight, "intensity", 0, 5);

Tworzymy obiekt settings

const settings = {
    geometry: "Cube",
    color: "#44aaff",
    wireframe: false,
    metalness: 0.3,
    roughness: 0.4,
    opacity: 1,
    rotate: true,
    rotationSpeed: 1,
    ambientIntensity: 1,
    directionalIntensity: 2,
    showGrid: true,
    showAxes: true,
    reset() {}
};

Tworzymy panel GUI

const gui =
new GUI({
    title: "Material Editor"
});

Dlaczego warto korzystać z folderów?

Tworzenie pierwszego folderu

const objectFolder = gui.addFolder("Obiekt");

Lista rozwijana

objectFolder
.add(
    settings,
    "geometry",
    [
        "Cube",
        "Sphere",
        "Torus",
        "Torus Knot"
    ]
)
.name("Geometria");

Reagowanie na zmianę wartości

.onChange(value => {
    mesh.geometry.dispose();
    mesh.geometry = createGeometry(value);
});

Dlaczego wywołujemy dispose()?

mesh.geometry = new THREE.SphereGeometry(...);

mesh.geometry = createGeometry(value);

• BoxGeometry,
• SphereGeometry,
• TorusGeometry,
• TorusKnotGeometry.

Dodajemy wybór koloru

objectFolder
.addColor(settings, "color")
.name("Kolor")
.onChange(value => {
    material.color.set(value);
});

material.color.set(value);

Dodajemy przełącznik Wireframe

objectFolder
.add(settings, "wireframe")
.name("Wireframe")
.onChange(value => {
    material.wireframe = value;
});

Sterowanie właściwościami materiału

const materialFolder = gui.addFolder("Materiał");

materialFolder
.add(settings, "metalness", 0, 1, 0.01)
.name("Metalness")
.onChange(value => {
    material.metalness = value;
});

materialFolder
.add(settings, "roughness", 0, 1, 0.01)
.name("Roughness")
.onChange(value => {
    material.roughness = value;
});

materialFolder
.add(settings, "opacity", 0, 1, 0.01)
.name("Opacity")
.onChange(value => {
    material.opacity = value;
});

Dlaczego wykorzystujemy opacityonChange()?

.onChange(value => {
    material.roughness = value;
});

gui.add(material, "roughness", 0, 1);

• wszystkie ustawienia aplikacji znajdują się w jednym miejscu,
• łatwo je zapisać do pliku,
• łatwo przywrócić wartości domyślne,
• można później zaimplementować eksport i import konfiguracji.

const animationFolder = gui.addFolder("Animacja");

animationFolder.add(settings, "rotate").name("Obrót");

Pętla renderująca

if (settings.rotate) {
    mesh.rotation.y += delta * settings.rotationSpeed;
}

animationFolder
.add(
    settings,
    "rotationSpeed",
    0,
    5,
    0.1
)
.name("Prędkość");

mesh.rotation.y += delta * settings.rotationSpeed;

Dlaczego wykorzystujemy Clock?

const delta = clock.getDelta();

Folder Światła

const lightsFolder = gui.addFolder("Światła");

lightsFolder
.add(
    settings,
    "ambientIntensity",
    0,
    5,
    0.1
)
.name("Ambient")
.onChange(value => {
    ambientLight.intensity = value;
});

lightsFolder
.add(
    settings,
    "directionalIntensity",
    0,
    5,
    0.1
)
.name("Directional")
.onChange(value => {
    directionalLight.intensity = value;
});

Sterowanie elementami pomocniczymi

• GridHelper,
• AxesHelper.

const helpersFolder = gui.addFolder("Pomocnicy");

GridHelper

helpersFolder
.add(settings,"showGrid")
.name("Grid")
.onChange(value => {
    grid.visible = value;
});

grid.visible = false;

• nie usuwa go ze sceny,
• nie zwalnia pamięci,
• nie niszczy geometrii.

AxesHelper

helpersFolder
.add(settings,"showAxes")
.name("Axes")
.onChange(value => {
    axes.visible = value;
});

Folder "Akcje"

• Reset,
• Randomize,
• Export,
• Save,
• Screenshot,
• Download.

Przywracanie ustawień

settings.geometry = "Cube";
settings.color = "#44aaff";
settings.wireframe = false;
settings.metalness = 0.3;
settings.roughness = 0.4;
settings.opacity = 1;
settings.rotate = true;
settings.rotationSpeed = 1;
settings.ambientIntensity = 1;
settings.directionalIntensity = 2;
settings.showGrid = true;
settings.showAxes = true;

mesh.geometry.dispose();
mesh.geometry = createGeometry("Cube");

material.color.set(settings.color);
material.wireframe = false;
material.metalness = settings.metalness;
material.roughness = settings.roughness;
material.opacity = settings.opacity;

ambientLight.intensity = settings.ambientIntensity;
directionalLight.intensity = settings.directionalIntensity;

grid.visible = true;
axes.visible = true;

gui.controllersRecursive()

gui.controllersRecursive().forEach(controller => {
    controller.updateDisplay();
});

const actionsFolder = gui.addFolder("Akcje");

actionsFolder
.add(settings,"reset")
.name("Reset Settings");

• liczba → tworzy suwak,
• boolean → tworzy checkbox,
• tablica → tworzy listę rozwijaną,
• kolor → tworzy selektor koloru,
• funkcja → tworzy przycisk.

Dobre praktyki

Grupuj kontrolki tematycznie

Nie modyfikuj sceny bezpośrednio z wielu miejsc

• zapisać konfigurację,
• odtworzyć ją,
• zresetować,
• eksportować do pliku.

Pamiętaj o dispose()

Aktualizuj kontrolki po zmianach programowych

controller.updateDisplay();

gui.controllersRecursive().forEach(controller => {
    controller.updateDisplay();
});