FERRETGame engine over Babylon.js
Ferret

Rigid bodies, kernels, materials

Skill ferret-physics-bodies · download all skills · SKILL.md

When to use#

Making things collide, choosing a kernel, defining materials, or writing a level's physics block.

Choosing a kernel#

LightKernel: small, no joints beyond rod, rope and spring, dynamic spheres only (boxes are not supported as dynamic bodies). Havok (loadHavok, havokKernel, in @ferret/physics-havok): full rigid bodies, joints, sweeps; per-pair material tables are not read there. Capabilities that need real rigid bodies say so.

Steps#

  1. Add RigidBody (shape, mass or density, kind dynamic|static|kinematic, material) to entities.
  2. Define materials as data: friction, restitution, density, strengths. A missing value means "does not apply" (no tensileStrength = unbreakable).
  3. Pair and combine rules for two materials meeting; validate with validateMaterials.
  4. Layers and masks for what hits what; triggers for zones; raycasts for queries.
  5. In a level: manifest physics with capabilities, materials, pairs, gravity, constraints (node names), fractured bodies.

Check afterwards#

physics.materials prints what the host sees; body.state shows each body; the level's physics block validates before shipping.

What usually goes wrong#

  • A box falls through a plane on the light kernel: use a sphere or Havok.
  • A hinge or ball joint throws on the light kernel.
  • Thin fast bodies tunnel: raise substeps.
  • Mass wildly wrong: it is density times shape volume; check units (metres).
  • Physics of the previous level lingers: it was applied at world scope; use beginLevel.

Files#

  • reference/bodies-and-kernels.md — Rigid bodies in Ferret: the light and Havok kernels, shapes, body kinds, joints and their forces, contact events, and choosing between the two.
  • reference/materials.md — Physical materials as data: the properties, what a missing value means, combine rules and pair tables, validation, and how capabilities read them.
  • reference/level-block.md — The physics block of a level manifest: capabilities, materials, pair and combine rules, gravity, constraints and pre-fractured bodies, and what happens when the level loads and unloads.
  • reference/api-physics-havok.md — every export of @ferret/physics-havok with signature and doc comment