Швидкий довідник Cannon-es API

🌍 World

CANNON.World — контейнер верхнього рівня: гравітація, broadphase, солвер і списки тіл/constraints/contact materials живуть у ньому. Викликайте world.step(dt) раз на кадр анімації, щоб просунути симуляцію.

import * as CANNON from 'cannon-es';

const world = new CANNON.World({
  gravity: new CANNON.Vec3(0, -9.82, 0),
});
world.broadphase = new CANNON.SAPBroadphase(world);
world.solver.iterations = 10;

// Виклик step() з фіксованим кроком у циклі рендеру
const fixedTimeStep = 1 / 60;
function animate() {
  requestAnimationFrame(animate);
  world.step(fixedTimeStep);
  renderer.render(scene, camera);
}

📦 Body

CANNON.Body представляє одне тверде тіло: масу, позицію, кватерніон (орієнтацію), швидкість, кутову швидкість і одну чи кілька приєднаних форм. Тіло з mass: 0 — статичне — нескінченна маса, ніколи не рухається, але бере участь у колізіях.

const body = new CANNON.Body({
  mass: 1,
  position: new CANNON.Vec3(0, 5, 0),
  shape: new CANNON.Sphere(0.5),
  linearDamping: 0.01,
});
body.applyForce(new CANNON.Vec3(0, 0, 50), body.position);
body.applyImpulse(new CANNON.Vec3(5, 0, 0), body.position);
world.addBody(body);

🔷 Форми (Shapes)

Одне Body може нести кілька форм (складені тіла), кожна з опціональним локальним offset і orientation через body.addShape(shape, offset, quaternion).

🧪 Материали та ContactMaterial

Material — це просто іменована мітка на формі/тілі; фактичні числа тертя та пружності живуть у ContactMaterial, який поєднує два материали разом.

const ice = new CANNON.Material('ice');
const rubber = new CANNON.Material('rubber');

const iceRubberContact = new CANNON.ContactMaterial(ice, rubber, {
  friction: 0.02,      // низьке — вільно ковзає
  restitution: 0.3,    // 0 = без відскоку, 1 = ідеально пружний
  contactEquationStiffness: 1e8,
  contactEquationRelaxation: 3,
});
world.addContactMaterial(iceRubberContact);

const puck = new CANNON.Body({ mass: 1, material: rubber, shape: new CANNON.Cylinder(0.4,0.4,0.1,16) });
const rink = new CANNON.Body({ mass: 0, material: ice, shape: new CANNON.Plane() });

🔗 Constraints (обмеження)

Constraints (шарніри) обмежують відносний рух двох тіл. Усі constraints додаються до світу через world.addConstraint(c).

// Маятник: шарнір, що з'єднує ящик з фіксованою точкою підвісу
const anchor = new CANNON.Body({ mass: 0 });
anchor.position.set(0, 5, 0);
world.addBody(anchor);

const hinge = new CANNON.HingeConstraint(anchor, bobBody, {
  pivotA: new CANNON.Vec3(0, 0, 0),
  pivotB: new CANNON.Vec3(0, 1.5, 0),
  axisA:  new CANNON.Vec3(0, 0, 1),
  axisB:  new CANNON.Vec3(0, 0, 1),
});
world.addConstraint(hinge);

🎯 Групи та маски колізій

Кожна форма несе collisionFilterGroup (до якої групи вона належить) і collisionFilterMask (з якими групами вона має перевірятись) — обидва бітові маски. Дві форми зіштовхуються тільки якщо (A.group & B.mask) і (B.group & A.mask) обидва ненульові.

const GROUP_PLAYER  = 1;   // 0b0001
const GROUP_ENEMY   = 2;   // 0b0010
const GROUP_TERRAIN = 4;   // 0b0100
const GROUP_TRIGGER = 8;   // 0b1000 — без фізичної реакції, лише події

playerBody.collisionFilterGroup = GROUP_PLAYER;
playerBody.collisionFilterMask  = GROUP_ENEMY | GROUP_TERRAIN | GROUP_TRIGGER;

// Вороги зіштовхуються з рельєфом, але проходять крізь одне одного
enemyBody.collisionFilterGroup = GROUP_ENEMY;
enemyBody.collisionFilterMask  = GROUP_PLAYER | GROUP_TERRAIN;

📡 Події

playerBody.addEventListener('collide', (e) => {
  const impactSpeed = e.contact.getImpactVelocityAlongNormal();
  if (impactSpeed > 5) playLandingSound(impactSpeed);
});

⚙️ Синхронізація Cannon-es ↔ Three.js

Cannon-es не має власної концепції рендерингу — щокадру копіюйте position і quaternion кожного тіла напряму у відповідний Three.js mesh. Обидві бібліотеки використовують однакову конвенцію осей і структуру кватерніона, тож жодних перетворень не потрібно.

const bodies = []; // { body: CANNON.Body, mesh: THREE.Mesh }

function addBox(size, mass, position) {
  const shape = new CANNON.Box(new CANNON.Vec3(size.x/2, size.y/2, size.z/2));
  const body  = new CANNON.Body({ mass, shape, position: new CANNON.Vec3(...position) });
  world.addBody(body);

  const mesh = new THREE.Mesh(
    new THREE.BoxGeometry(size.x, size.y, size.z),
    new THREE.MeshStandardMaterial({ color: 0x60a5fa }),
  );
  scene.add(mesh);

  bodies.push({ body, mesh });
  return body;
}

function animate() {
  requestAnimationFrame(animate);
  world.step(1/60);

  // Синхронізувати кожен меш з фізичним станом його тіла
  for (const { body, mesh } of bodies) {
    mesh.position.copy(body.position);
    mesh.quaternion.copy(body.quaternion);
  }

  renderer.render(scene, camera);
}

⚠️ Типові помилки

• Додавання Trimesh/Heightfield до динамічного тіла: неопуклі форми мовчки поводяться неправильно (або не зіштовхуються взагалі), якщо тіло не має mass: 0.
• Забути скинути сили: сили, застосовані через applyForce, накопичуються і скидаються автоматично щокроку world.step() — але ручні цикли інтегрування, що пропускають step(), накопичуватимуть силу нескінченно.
• Тонкі швидкорухомі тіла тунелюють крізь стіни: підвищіть world.solver.iterations, увімкніть ccdSpeedThreshold/ccdSweptSphereRadius, або розбийте симуляцію на під-кроки (див. туторіал про фізичний рушій).
• Тремтячі стеки: підвищіть кількість ітерацій солвера (15–20), увімкніть world.allowSleep, і перевірте, чи contactEquationStiffness не занадто високий для вашого кроку часу — надто жорсткі контакти можуть «перестрибувати» і осцилювати.
• Масштабування Three.js мешу без масштабування Cannon форми: форми cannon-es не мають властивості scale — закладайте масштаб у розміри форми при створенні (наприклад, множте половини розмірів Box), а не через трансформацію мешу.