Introduction to Babylon.js: A Powerful Web Game Engine, undefined

Physics Bodies

Add physics properties to meshes to make them interact with the physics world:

// Physics V2 uses PhysicsAggregate for convenience (combines body + shape)

// Create a static ground plane
const ground = BABYLON.MeshBuilder.CreateGround("ground", {width: 50, height: 50}, scene);
const groundAggregate = new BABYLON.PhysicsAggregate(
    ground,
    BABYLON.PhysicsShapeType.BOX, // Collision shape type
    { mass: 0, restitution: 0.3, friction: 0.3 }, // mass 0 = static object
    scene
);

// Create a dynamic sphere
const sphere = BABYLON.MeshBuilder.CreateSphere("sphere", {diameter: 2}, scene);
sphere.position.y = 10; // Start above ground
const sphereAggregate = new BABYLON.PhysicsAggregate(
    sphere,
    BABYLON.PhysicsShapeType.SPHERE,
    { mass: 1, restitution: 0.7, friction: 0.1 }, // mass > 0 = dynamic object
    scene
);

// Create a dynamic box
const box = BABYLON.MeshBuilder.CreateBox("box", {size: 2}, scene);
box.position = new BABYLON.Vector3(0, 15, 0);
const boxAggregate = new BABYLON.PhysicsAggregate(
    box,
    BABYLON.PhysicsShapeType.BOX,
    { mass: 2, restitution: 0.2, friction: 0.4 },
    scene
);

Shape Types (Physics V2)

Different collision shape types for different needs:

Physics V2 provides several shape types via PhysicsShapeType:

BOX: Simple box collision - efficient for rectangular objects
SPHERE: Spherical collision - most efficient, good for round objects
CYLINDER: Cylindrical collision - for tubes, pillars, etc.
CAPSULE: Capsule collision - ideal for character controllers
MESH: Uses actual mesh geometry - most accurate but computationally expensive
HEIGHTFIELD: Efficient for terrain - uses height data for collision
CONVEX_HULL: Creates simplified collision from mesh vertices - good balance
CONTAINER: For compound shapes with child shapes

For performance, always use the simplest collision shape that adequately represents your object.

// Complex mesh with accurate collision
const complexMesh = BABYLON.MeshBuilder.CreateTorusKnot("tk", {}, scene);
complexMesh.position.y = 10;

// Options for different collision types
// 1. Exact mesh collision (expensive)
new BABYLON.PhysicsAggregate(
    complexMesh, BABYLON.PhysicsShapeType.MESH,
    { mass: 3, restitution: 0.4 }, scene
);

// 2. Convex hull (better performance)
new BABYLON.PhysicsAggregate(
    complexMesh, BABYLON.PhysicsShapeType.CONVEX_HULL,
    { mass: 3, restitution: 0.4 }, scene
);

// 3. Simple approximation (best performance)
new BABYLON.PhysicsAggregate(
    complexMesh, BABYLON.PhysicsShapeType.SPHERE,
    { mass: 3, restitution: 0.4 }, scene
);

Compound Bodies

Create complex physics objects from multiple shapes using PhysicsShapeContainer in Physics V2:

// Create a compound shape (e.g., a dumbbell) using Physics V2
const dumbbell = new BABYLON.Mesh("dumbbell", scene);
dumbbell.position.y = 10;

// Create child meshes for visualization
const bar = BABYLON.MeshBuilder.CreateCylinder("bar", {
    height: 5, diameter: 0.5
}, scene);
bar.parent = dumbbell;

const leftWeight = BABYLON.MeshBuilder.CreateSphere("leftWeight", { diameter: 2 }, scene);
leftWeight.position.x = -2.5;
leftWeight.parent = dumbbell;

const rightWeight = BABYLON.MeshBuilder.CreateSphere("rightWeight", { diameter: 2 }, scene);
rightWeight.position.x = 2.5;
rightWeight.parent = dumbbell;

// Create a compound shape using PhysicsShapeContainer
const containerShape = new BABYLON.PhysicsShapeContainer(scene);

// Add child shapes with local transforms
const barShape = new BABYLON.PhysicsShapeCylinder(
    new BABYLON.Vector3(0, -2.5, 0),
    new BABYLON.Vector3(0, 2.5, 0),
    0.25, scene
);
containerShape.addChild(barShape);

const leftSphereShape = new BABYLON.PhysicsShapeSphere(
    new BABYLON.Vector3(-2.5, 0, 0), 1, scene
);
containerShape.addChild(leftSphereShape);

const rightSphereShape = new BABYLON.PhysicsShapeSphere(
    new BABYLON.Vector3(2.5, 0, 0), 1, scene
);
containerShape.addChild(rightSphereShape);

// Create body with the compound shape
const body = new BABYLON.PhysicsBody(dumbbell, BABYLON.PhysicsMotionType.DYNAMIC, false, scene);
body.shape = containerShape;
body.setMassProperties({ mass: 10 });