FERRETGame engine over Babylon.js
Ferret

Actuators and bindings

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

When to use#

An oar that pushes a boat, a mill shaft that turns forever, a winch that jams under load, a lever that starts a conveyor, a gust that kicks a flag, a rower whose animation says when the blade is in the water.

The model#

An actuator says where a force acts (a node, a point), what it is (force, impulse, torque, motor, spin, blade) and how it runs (a profile over time, a body's angle, another actuator's phase or a sensor), times a run-time command. Bindings set the command from input actions, interactables, zones and events; events and numbers come back to the game and to animations.

Steps#

  1. Enable actuators (and rotors for blades and wheels).
  2. Add actuators to physics.actuators or with edit.physics.actuator.set; a point off the centre of mass turns the body.
  3. Add physics.bindings (or edit.physics.binding.set): action + hold | press | toggle | axis, interactable, zone, or event + match + on | off | toggle | press | set.
  4. For animation: an animate binding writes phase, command, power ... to a graph parameter or fires a trigger; an anim:notify event binding lets the animation switch the force.
  5. Commands: actuator.command | on | off | fire | state, edit.physics.actuator.*, edit.physics.binding.*.

Check afterwards#

actuator.state { name } shows force, power, work and phase; the body's momentum changes by F·dt; cap.bindings() shows binding errors.

What usually goes wrong#

  • Nothing moves: command is 0 (the default of a bound actuator in the examples), the actuator is off, or the node has no body.
  • A binding does nothing: no input service, a wrong action name, or an event match that the payload does not satisfy.
  • A kinematic body gets a force: only spin acts on a kinematic body.
  • A second force on a vessel needs a vesselTarget; the actuator names the target by node.

Files#

  • reference/actuators.md — Forces, impulses, torques and motors at chosen points of chosen bodies, on a schedule (constant, for a time, periodic, by a curve) over time, a body's angle, another actuator's phase or a sensor; by hand, by data and over MCP.
  • reference/rotors.md — N blades, paddles or buckets around an axis that turn the local wind or water, or the weight of water, into a torque on a body or a drivetrain shaft; and the blade actuator, a plate swept through a medium.
  • reference/api-physics-actuators.md — every export of @ferret/physics-actuators with signature and doc comment
  • reference/api-physics-rotor.md — every export of @ferret/physics-rotor with signature and doc comment
  • reference/commands.md — 30 commands of these packages with their arguments