Sleeping & Stability

In most scenes almost everything is at rest almost all the time: a pile of crates nobody has touched, a ragdoll that has finished falling. Simulating them costs as much as simulating things that move, and it also makes them jitter. Sleeping removes resting bodies from the simulation until something disturbs them. After this lesson your program will decide, frame by frame, which bodies are asleep, and it will do it per group of touching bodies instead of per body.

When is a body at rest?

A body that is merely slow for one frame is not resting: a ball at the top of its arc has speed near zero for an instant. A body rests when its speed stays below a threshold for a continuous duration. Keep a timer per body:

• each step the body is awake and its speed is >= threshold: the timer is reset to 0;
• each step it is awake and its speed is < threshold: add the step length dt to the timer.

Box2D's defaults are a threshold of about 0.01 m/s and a duration of 0.5 s. The timer needs a reset, not a decrement: one fast frame wipes the history.

One body is not enough: islands

Imagine a stack of three boxes. The top box is still wobbling; the two below have been calm for a second. If the lower boxes sleep by themselves, they stop reacting to the top box, which then sinks through them. Bodies that touch each other must sleep and wake together.

Group bodies into islands: two bodies are in the same island if a chain of contacts or joints connects them. In this exercise contacts are persistent links between body numbers. An island may go to sleep only when every body in it has been below the threshold for the full duration. One restless body keeps its whole island awake.

Worked trace: threshold 0.2, duration 1, bodies 0 and 1 linked, dt = 0.5 each frame, speeds (0.1, 0.9), then (0.1, 0.1), (0.1, 0.1), (0.1, 0.1):

frame   timers after   island all >= 1?   states
  1     (0.5, 0)            no               A A
  2     (1.0, 0.5)          no               A A      body 0 alone would sleep here
  3     (1.5, 1.0)          yes              S S
  4     asleep: speeds are ignored           S S

Body 0 was calm early, yet it stayed awake until body 1 had also been calm for the full duration.

Waking up

Sleep is only safe because waking is reliable. Wake an island when:

• a new contact appears between a sleeping body and an awake one (a crate lands on the sleeping stack);
• game code touches a sleeping body (applies a force, moves it, deletes its support).

Waking resets the timers of every body in the island to 0, so the island has to stay calm for the full duration again before it can sleep. Gravity must never wake anything: it acts on resting bodies every frame, so a gravity trigger would wake the whole world immediately.

A sleeping body is not simulated, so its reported speed carries no information. Ignore it until the body is woken.

Stability, briefly

Sleeping is also a stability tool: a resting stack that is never integrated cannot jitter. Beyond sleeping, engines keep stacks steady with more solver iterations, warm starting (reuse last frame's impulses as the first guess), and small sub-steps for stiff systems. Fast bodies tunnel through thin obstacles regardless; that is the subject of the final lesson.

Common mistakes

• Putting each body to sleep on its own timer. Stacks sink and bridges collapse.
• Decrementing the timer instead of resetting it.
• Letting a sleeping body's speed (or the timer) change while it sleeps.
• Using > where the rule says >=: a speed exactly at the threshold counts as moving.
• Waking only the touched body instead of its whole island.

Your exercise

The starter reads the script and prints one line of A/S per frame; it gives you an island helper. You write update, which advances the timers and puts islands to sleep, and wake_island. The most likely mistake is sleeping bodies one by one.