Инструменты разработчика и отладка сцены

В Three.js сцена является центральным объектом, который содержит все визуальные элементы: камеры, объекты, свет и вспомогательные элементы. Создание сцены выполняется с помощью класса THREE.Scene:

const scene = new THREE.Scene();

После инициализации сцены можно добавлять объекты через метод scene.add(). Все объекты сцены наследуются от THREE.Object3D, что позволяет применять к ним трансформации, такие как позиция, масштаб и вращение.

const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshStandardMaterial({ color: 0x00ff00 });
const cube = new THREE.Mesh(geometry, material);
scene.add(cube);

Камеры и управление

Для визуализации сцены требуется камера. Наиболее часто используется THREE.PerspectiveCamera, обеспечивающая перспективное изображение:

const camera = new THREE.PerspectiveCamera(
    75, window.innerWidth / window.innerHeight, 0.1, 1000
);
camera.position.set(0, 2, 5);

Управление камерой для отладки сцены удобно осуществлять с помощью THREE.OrbitControls из официального модуля examples/jsm/controls/OrbitControls.js. Этот контроллер позволяет вращать, масштабировать и панорамировать сцену интерактивно:

import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
const controls = new OrbitControls(camera, renderer.domElement);
controls.update();

Рендерер и настройка отладки

Основной рендерер — THREE.WebGLRenderer. Для удобства отладки рекомендуется включать следующие параметры:

  • antialias: true — сглаживание краёв геометрии.
  • physicallyCorrectLights: true — корректное физическое освещение.
  • shadowMap.enabled = true — отображение теней для объектов сцены.
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.shadowMap.enabled = true;
renderer.physicallyCorrectLights = true;
document.body.appendChild(renderer.domElement);

Визуализация осей и сетки

Для отладки сцены полезно использовать вспомогательные объекты: оси и сетку. THREE.AxesHelper и THREE.GridHelper позволяют ориентироваться в пространстве и контролировать масштаб объектов.

const axesHelper = new THREE.AxesHelper(5);
scene.add(axesHelper);

const gridHelper = new THREE.GridHelper(10, 10);
scene.add(gridHelper);

Оси обозначают направление координат: X — красный, Y — зелёный, Z — синий.

Инструменты инспекции объектов

Каждый объект сцены можно инспектировать через консоль браузера или специализированные панели отладки:

  • GUI для параметров объектов — библиотека dat.GUI или lil-gui позволяет менять свойства объектов в реальном времени:
import GUI from 'lil-gui';
const gui = new GUI();
gui.add(cube.position, 'x', -5, 5);
gui.add(cube.rotation, 'y', 0, Math.PI * 2);
gui.add(cube.scale, 'z', 0.1, 3);
  • Инспекция через DevTools — рендерер WebGLRenderer может выводить статистику о кадрах, использовании памяти и геометрии.

Использование THREE.Clock и анимации

Для отладки динамических сцен важно иметь точное управление временем. THREE.Clock позволяет отслеживать прошедшее время и корректно синхронизировать анимации.

const clock = new THREE.Clock();

function animate() {
    requestAnimationFrame(animate);
    
    const delta = clock.getDelta();
    cube.rotation.x += delta;
    cube.rotation.y += delta;

    controls.update();
    renderer.render(scene, camera);
}
animate();

Использование delta обеспечивает независимость скорости анимации от частоты кадров.

Инструменты визуализации производительности

Для оценки производительности сцены удобно подключать библиотеку stats.js, которая показывает FPS и нагрузку GPU:

import Stats from 'three/examples/jsm/libs/stats.module.js';
const stats = Stats();
document.body.appendChild(stats.dom);

function animate() {
    requestAnimationFrame(animate);
    stats.update();
    renderer.render(scene, camera);
}

Комбинация stats.js и OrbitControls позволяет наблюдать поведение сцены при интерактивной навигации и оценивать оптимизацию объектов.

Включение теней и контроль света

Отладка света и теней требует правильного включения источников света и свойств объектов:

const light = new THREE.DirectionalLight(0xffffff, 1);
light.position.set(5, 10, 5);
light.castShadow = true;
scene.add(light);

cube.castShadow = true;
cube.receiveShadow = true;

Для контроля области тени можно использовать light.shadow:

light.shadow.mapSize.width = 1024;
light.shadow.mapSize.height = 1024;
light.shadow.camera.near = 0.5;
light.shadow.camera.far = 50;

Визуализация Bounding Box и Helper

Для точной отладки коллизий и размеров объектов применяются BoxHelper и Box3Helper:

const boxHelper = new THREE.BoxHelper(cube, 0xff0000);
scene.add(boxHelper);

Это позволяет визуально проверить, правильно ли позиционирован объект и как изменяется его геометрия при трансформациях.

Логирование и отладка через события

Объекты сцены поддерживают события мыши и касания через raycasting:

const raycaster = new THREE.Raycaster();
const mouse = new THREE.Vector2();

window.addEventListener('mousemove', (event) => {
    mouse.x = (event.clientX / window.innerWidth) * 2 - 1;
    mouse.y = -(event.clientY / window.innerHeight) * 2 + 1;

    raycaster.setFromCamera(mouse, camera);
    const intersects = raycaster.intersectObjects(scene.children, true);

    if (intersects.length > 0) {
        console.log('Пересечение с объектом:', intersects[0].object);
    }
});

Raycasting позволяет отлаживать интерактивные элементы, проверять попадание курсора в объекты и взаимодействие с ними.

Совмещение инструментов

Для комплексной отладки сцены рекомендуется одновременно использовать:

  • AxesHelper и GridHelper для пространственной ориентации.
  • dat.GUI или lil-gui для динамического изменения параметров.
  • Stats.js для мониторинга производительности.
  • BoxHelper для проверки размеров и границ объектов.
  • OrbitControls для интерактивного исследования сцены.

Эта комбинация позволяет контролировать визуальные и технические аспекты сцены, выявлять ошибки трансформаций, освещения и производительности.

Оглавление