Первая 3D-сцена на Three.js: куб, свет и управление мышью

Для первой сцены Three.js нужны scene, camera и renderer, а видимый свет требует материала, который на него реагирует. Добавим куб, пол, два источника света и OrbitControls. Затем исправим resize и animation loop, чтобы сцена не растягивалась и не тратила ресурсы через случайный setInterval.

3D-страница может быть пустой даже при правильном кубе: камера стоит внутри объекта, материал не реагирует на свет или render ни разу не вызван. В этой статье вы соберёте интерактивная 3D-сцена, которую можно вращать мышью. Финальный результат можно проверить без догадок: куб отбрасывает тень на пол, OrbitControls меняет камеру, resize сохраняет пропорции.

Из каких объектов состоит Three.js сцена

Scene является контейнером. Camera не рисует, а задаёт проекцию. Renderer получает оба объекта и выводит canvas. Mesh соединяет BoxGeometry и MeshStandardMaterial. OrbitControls меняет position камеры и target. Для Three.js держите этапы раздельно: ввод, проверка, основное действие и вывод. Такой маршрут позволяет остановиться в конкретной точке, увидеть фактические данные и исправить одну причину вместо случайной перестановки строк.

Пустой экран разбирается по цепочке: canvas, камера, объект, материал, свет и render. У Three.js каждый этап оставляет наблюдаемый след, поэтому следующий шаг начинается только после проверки предыдущего.

От входных данных до видимого результата. Renderer соединяет мир и точку наблюдения

Пишем куб, свет и OrbitControls

Создайте проект npm create vite@latest three-scene -- --template vanilla, установите npm install three и запустите npm run dev. OrbitControls является addon и импортируется отдельно из three/addons/controls/OrbitControls.js. Не копируйте старые примеры с scripts/CDN вперемешку с npm-модулями.

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

const canvas = document.querySelector("#scene");
const scene = new THREE.Scene();
scene.background = new THREE.Color(0x0f172a);

const camera = new THREE.PerspectiveCamera(55, 1, 0.1, 100);
camera.position.set(3, 2.4, 4.5);

const renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
renderer.shadowMap.enabled = true;

const cube = new THREE.Mesh(
  new THREE.BoxGeometry(1.6, 1.6, 1.6),
  new THREE.MeshStandardMaterial({ color: 0x6371ff })
);
cube.position.y = 0.8;
cube.castShadow = true;
scene.add(cube);

const floor = new THREE.Mesh(
  new THREE.PlaneGeometry(12, 12),
  new THREE.MeshStandardMaterial({ color: 0x334155 })
);
floor.rotation.x = -Math.PI / 2;
floor.receiveShadow = true;
scene.add(floor);

scene.add(new THREE.AmbientLight(0xffffff, 0.7));
const sun = new THREE.DirectionalLight(0xffffff, 2.5);
sun.position.set(3, 6, 4);
sun.castShadow = true;
scene.add(sun);

const controls = new OrbitControls(camera, canvas);
controls.enableDamping = true;
controls.target.set(0, 0.8, 0);

function resize() {
  const width = canvas.clientWidth;
  const height = canvas.clientHeight;
  renderer.setSize(width, height, false);
  camera.aspect = width / height;
  camera.updateProjectionMatrix();
}

renderer.setAnimationLoop(() => {
  resize();
  cube.rotation.y += 0.006;
  controls.update();
  renderer.render(scene, camera);
});

Resize обновляет и размер renderer, и camera.aspect. Если изменить только CSS, изображение станет размытым или геометрически искажённым. Пример Three.js специально ограничен одним пользовательским сценарием, чтобы назначение каждой строки оставалось видимым.

Что отличает устойчивый проект от случайного запуска. Каждый объект имеет ясную роль

Как геометрия, материал и mesh соединяются

Geometry хранит вершины, material описывает поверхность, Mesh объединяет их и получает transform. PerspectiveCamera использует field of view, aspect, near и far. Объекты за плоскостями clipping не рисуются. MeshStandardMaterial участвует в физически правдоподобном освещении и нуждается в light. OrbitControls слушает события canvas и меняет camera. enableDamping требует controls.update в каждом кадре. setAnimationLoop синхронизирует render с браузером и поддерживает XR-сценарии.

Каждый новый mesh увеличивает работу CPU и GPU. Повторяющиеся объекты лучше объединять через InstancedMesh. Огромные текстуры занимают видеопамять, даже если файл сжат. Тени требуют дополнительных проходов рендера и ограниченной shadow camera. Resize не обязан вызывать setSize на каждом кадре, если размер не изменился: в production сравнивайте drawing buffer или используйте ResizeObserver. Dispose geometry, material и texture при удалении долгоживущих сцен.

Проверяем камеру, resize и animation loop

Запустите сцену и обойдите куб мышью. Уберите AmbientLight и посмотрите на тёмные стороны, затем верните его. Замените MeshStandardMaterial на MeshBasicMaterial и объясните исчезновение влияния света. Измените camera.aspect намеренно и увидьте искажение. Добавьте SphereGeometry рядом с кубом, но переиспользуйте один material. После этого включите и выключите shadowMap, сравните изображение и нагрузку.

Первая сцена считается понятой, когда вы можете диагностировать пустой экран без случайного копирования новых строк. После этой проверки измените одно правило Three.js и заранее запишите ожидаемый результат. Так копирование превращается в понимание.

Четыре проверки перед следующим шагом. Пустой экран диагностируется по цепочке

Как развивать 3D-сцену без потери производительности

Дальше добавьте texture только после понимания UV и color space. Для загрузки моделей используйте GLTFLoader и показывайте progress. Разделите создание сцены и animation loop на функции. Добавьте GUI для света, чтобы видеть влияние параметров. Перед сложными постэффектами измерьте кадры и память. Если сцена является декоративным фоном, предусмотрите reduced motion и статичную альтернативу для слабого устройства.

Как изучить тему в Кодике

Повторите объекты, классы, события и animation loop JavaScript, затем свяжите их с координатами и векторами. В Кодике сначала восстановите чистую логику без фреймворка, затем верните библиотеку и интерфейс Three.js.

Сначала научитесь двигать один куб и camera, потом загружайте модели и эффекты. Финальная проверка для Three.js: закрыть статью, объяснить путь данных и добавить одну функцию без копирования готового блока.

Что получится в итоге

Куб освещён, отбрасывает тень, вращается в animation loop, а камера управляется мышью без искажения resize.