Whet pixel markWhet

Whet user guide, chapter 5, 2026-10-09

Motion and mechanisms

Motion runs a rig: a set of parts joined by hinges and slides, dropped, driven or filmed. It uses the MuJoCo physics engine on your computer. All sizes are in millimetres and degrees.

Use it to see what a mechanism does, how hard each joint is loaded, and whether a part clears its neighbour. It is a rigid-body simulation. Read the limits at the end before you trust a number.

Make a rig

A rig is a tree. One part is the base, and every other part hangs from it through a joint. There are three kinds of joint:

  • hinge: turns about an axis.
  • slide: moves along an axis.
  • weld: holds two parts fixed.

A rig has no loops. A pin that closes a loop, such as the rod of a slider-crank, is available as a closure.

The easiest way to get a rig is from an assembly. Use Assembly > Assemble with Rig. The rig it writes is welded to the world and has no drives and no limits. See Assemblies. The joint kinds of an assembly and of a rig are not the same list. An assembly knows revolute, slider, ball and others. A rig knows hinge, slide and weld only. A ball joint is not available in a rig.

Every part in a rig needs a density. Whet does not read it from a file, because an STL carries no material. You declare it.

Edit the rig

Choose Motion > Drives and Limits to open the rig editor. It reads the joints from a rig file. For each joint you can set:

  • a drive: a hold in N m for a hinge or N for a slide, and a target in degrees or millimetres.
  • a limit: a lower and an upper stop.
  • the base: free to fall, or fixed. You can also lift the base by a height.

The editor writes a new rig file and can run it straight away. Your first rig is never overwritten.

A drive can also follow a table of time and value rows instead of one target. A table needs at least two rows, with times rising. Commanding a value past the joint's limit is refused.

Run it

Choose Motion > Run Rig (Ctrl+R on Windows and Linux, Command+R on macOS) and pick the rig file. While it runs the window shows the name of the rig and says it is running.

Motion > Simulation Settings holds the run's conditions: seconds, seed, gravity, slope, air density or altitude, timestep and jitter. Defaults are used for any you leave alone, and the record states every condition, including the defaults.

When the run ends, the details list shows:

RowWhat it means
engine, seed, timestep, stepsWhat was run.
simulatedSeconds of simulated time.
gravity, slopeThe conditions.
droppedHow far the base ended lower than it started, in metres.
travelledDistance the base moved, in metres.
final tiltHow far the base ended from upright, in degrees.
peak contactThe hardest hit between any two parts, in newtons.
fell overYes or no.
reproducibleWhether running the same seed twice gave the same end state.

The reproducible row is measured by running the rig twice. It is not promised.

The window reads "block and ground" as the pair that touched.

Drives, limits and what they report

For each driven joint the result states the command, where the joint reached, whether it settled, and the hold it was given. If the drive pushed with its whole hold when the clock stopped and the joint was not at the target, the drive cannot hold that target. The result says so.

For each limited joint the result says which stop the joint rested on and what the stop held it with. A stop is stiff but not rigid. A joint pushed hard sits a little past it. In one check, 5 N m on a small hinge left it 0.054 degrees past a 45 degree stop.

A drive that is too stiff for the timestep is refused before the first step. The refusal names a timestep or a hold that would work. Lower the hold or the timestep.

A drive on a free base can throw the rig over if the hold is too strong for the joint. Use a modest hold and read the result. If a drive is not settled, shorten the timestep and try again.

Load through each joint

Every joint except a weld reports the load the parent puts on the child: a force in newtons and a moment in N m, about the joint's anchor, in the child's own axes. The result gives two instants for each joint, the instant of largest force and the instant of largest moment. These are not always the same instant.

Both closed-form checks, a hanging shin and a drive-held arm, agree with statics to four decimals.

The load is what rigid bodies needed from the joint. A part that would bend, or a bearing that would give, is not in it. The peak is the largest of one sample per step, so a spike shorter than a step is missed.

Watch gaps, gears and friction

A rig can watch pairs of parts. The result gives the smallest gap each pair reached and when. A gap can read slightly negative, because contacts in the engine are soft. A gap is read once per step, so two parts that crossed and parted between steps are missed.

A rig can gear two joints of the same kind. The result gives the declared ratio, the ratio measured and the slip. A coupling has no teeth, no backlash and no efficiency. A reduction here costs nothing.

A friction value can be declared per pair, 0 to 2. One check measured 0.299999 for a declared 0.3. The engine uses a pyramid friction cone, so a slide at 45 degrees to a contact's own tangent reads about 0.212 for a declared 0.3.

Playback

When a run writes poses, the viewport can play it back. Use Motion > Playback and choose Play, Pause, First Frame or Last Frame. A scrubber under the viewport moves through the frames. These items are grey when no run with poses is open, and the tooltip says so.

A long run is thinned to at most 600 frames. The last frame is always the real end of the run.

Film

Motion > Film opens the page for a film of the rig. You set the frame rate, the size, the length and the camera angle. Frames are written inside the project, and a video can be made from them. Every drive acts as in a normal run, so a driven joint moves in the film.

Without a licence a film is limited to 1920 by 1080 pixels. A licensed copy has no limit set by Whet. A picture larger than your computer's OpenGL can hold is refused by the engine in its own words.

The video is H.264 where your ffmpeg has an encoder for it, and MPEG-4 Part 2 where it has none.

Sweep

Motion > Sweep runs the same rig many times while one condition changes. You pick the condition: seed, jitter, slope, altitude or air density. You set how many runs and the range. The result says how many stayed up, how many fell, and the mean and spread of the worst lean and the peak torque. Each run states its own seed and whether it repeats.

Trial limits

Without a licence a run is limited to 5 bodies and 10 seconds of simulated time. A licensed copy is bounded by your computer and by the engine's own refusals. See Licence, trial and updates.

Limits

  • Collision uses the convex hull of each mesh. A pocket, slot or hole is solid to a contact.
  • A curved face reaches the engine as flat triangles.
  • There are no ball joints, no joint springs or damping, and no tendons. Every pair of bodies collides. The menu items for tendons, sensors and contact pairs are grey, and say so.
  • Nothing plans a gait. A drive can follow a table, and that is all. A drop test is a drop and a stand.
  • The fluid model is a simple drag model off a shape's bounding box. It is not CFD.
  • A load history is written, and nothing yet turns it into a fatigue life.
  • For a strength check of a part in a mechanism, see Strength and Heat. A joint load is not carried across automatically (to be checked).