CannonDebugger: визуализация коллайдеров

Cannon.js — популярная физическая библиотека для JavaScript, которая позволяет создавать динамическое поведение объектов в 3D-пространстве. Для разработки и отладки часто требуется визуализировать физические тела, их форму и положение, чтобы убедиться, что коллайдеры работают корректно. Для этого используется расширение CannonDebugger, обеспечивающее связь между физическим миром и графической сценой на основе Three.js.

Подключение CannonDebugger

Для работы необходимы:

  • Cannon.js
  • Three.js
  • CannonDebugger (обычно подключается отдельным скриптом или через npm)

Пример подключения через npm:

import * as THREE from 'three';
import * as CANNON from 'cannon-es';
import CannonDebugger from 'cannon-es-debugger';

После подключения создается физический мир:

const world = new CANNON.World({
    gravity: new CANNON.Vec3(0, -9.82, 0)
});

И графическая сцена Three.js:

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer();
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

Инициализация CannonDebugger

CannonDebugger создает визуальные представления коллайдеров на основе геометрии Cannon.js. Инициализация происходит следующим образом:

const cannonDebugger = new CannonDebugger(scene, world, {
    color: 0x00ff00,       // Цвет линий коллайдеров
    scale: 1,              // Масштаб визуализации
    opacity: 0.3,          // Прозрачность
    autoUpdate: true       // Автоматическое обновление на каждый кадр
});

Ключевые параметры:

  • color — позволяет задать цвет каркаса коллайдера.
  • scale — изменяет размер визуальной модели относительно реального коллайдера.
  • opacity — настраивает прозрачность, полезно при наложении нескольких объектов.
  • autoUpdate — автоматически синхронизирует положение и вращение с физическим миром.

Визуализация различных форм

CannonDebugger поддерживает большинство примитивных форм Cannon.js:

  1. Box
const boxShape = new CANNON.Box(new CANNON.Vec3(1, 1, 1));
const boxBody = new CANNON.Body({ mass: 1 });
boxBody.addShape(boxShape);
boxBody.position.set(0, 5, 0);
world.addBody(boxBody);

CannonDebugger автоматически отобразит каркас куба на сцене Three.js.

  1. Sphere
const sphereShape = new CANNON.Sphere(1);
const sphereBody = new CANNON.Body({ mass: 1 });
sphereBody.addShape(sphereShape);
sphereBody.position.set(2, 5, 0);
world.addBody(sphereBody);

Отображается как сферический каркас.

  1. Cylinder и ConvexPolyhedron

Все сложные формы, включая цилиндры и полиэдры, поддерживаются через те же методы. CannonDebugger создает точное отображение в виде линий, что позволяет визуально отследить столкновения.

Обновление сцены и синхронизация

Если autoUpdate выключен, визуализацию нужно обновлять вручную:

function animate() {
    requestAnimationFrame(animate);

    world.step(1 / 60); // Шаг физики

    cannonDebugger.update(); // Обновление визуализации

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

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

Настройка производительности

  • Отключение autoUpdate уменьшает нагрузку, если объекты редко движутся.
  • Масштаб и прозрачность помогают визуально различать пересекающиеся коллайдеры.
  • Цветовая дифференциация ускоряет отладку сложных сцен с множеством тел.

Советы по использованию

  • Использовать CannonDebugger только в режиме разработки, не на боевых сценах.
  • Для сложных форм рекомендуется включать wireframe визуализацию в Three.js, чтобы видеть пересечения.
  • При работе с множеством динамических тел комбинировать визуализацию с инструментами отладки Cannon.js (body.id, contactMaterial) для анализа столкновений.

CannonDebugger является мощным инструментом для отладки физики в реальном времени, позволяя точно видеть, как расположены коллайдеры, как они взаимодействуют и как на них влияют силы и столкновения.

Оглавление