FERRETGame engine over Babylon.js
Ferret

The capability host

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

When to use#

Turning a capability on, setting its values for one place, loading a level's physics, or writing a new capability.

The model#

PhysicsHost runs capabilities, each in its own package (gravity, media, friction, impact, strength, stretch, terrain, explosion, heat, chemistry, nuclear, combustion, electric, machine, vehicles, liquids, links). A game loads only what it registers. Each runs in a fixed phase of the step. Values are scoped: world, level, zone, entity; the narrowest wins. Dependencies are declared in requires.

Steps#

  1. const host = world.addService(new PhysicsHost({ kernel, capabilities })) (kernel: LightKernel or Havok, see ferret-physics-bodies).
  2. host.register(cap) once, then host.enable('name') in dependency order (or configure with a list).
  3. Set values: host.config('strength').set('world' | 'entity' | ..., 'toughness', 10, id); read with config.get(key, ctx) to see what wins.
  4. A level brings its own physics: the manifest physics block applied by beginLevel, undone by endLevel.
  5. From outside: physics.info, physics.enable, physics.configure, physics.materials.

Check afterwards#

physics.info lists the capabilities on and the step time; one body behaves as the capability says in a headless test.

What usually goes wrong#

  • capability "x" is already registered or no capability "x": register once; the error lists the registered names.
  • needs "y" switched on first: enable in dependency order.
  • A value seems ignored: a narrower scope overrides it.
  • A body does not fall: gravity off, body static, gravityScale 0 or exempt.
  • The node does not follow its body: rotate: false or a transformed parent.

Files#

  • reference/host.md — How a game turns realistic physics on: registering and enabling capabilities, the order of the step, scoped values, commands, and how to write a capability of your own.
  • reference/overview.md — Realism as capabilities a game switches on, the host and kernels, scoped values, the fixed phases, budgets and tiers.
  • reference/capabilities.md — Every physics capability: the package, its registered name, its phase and what it adds.
  • reference/api-physics.md — every export of @ferret/physics with signature and doc comment
  • reference/commands.md — 7 commands of these packages with their arguments