Sleeping Bodies

what wakes a settled pile, and how to edit one without waking it.

▶ Run in browser

Tags: physics 3d sleeping

A pile of crates settles on the ground and falls asleep; a sleeping body is skipped by integration and the contact solve until something disturbs it, which is what keeps a large resting scene cheap. Bodies are tinted by their live sleep state, so the pile visibly dims as it settles and lights up the moment anything reaches it.

The interesting half is what counts as a disturbance. Changing a body wakes what it was holding up: shrink the pillar under the crate on top and the crate falls, because the seam wakes its riders rather than waiting for a contact that has already gone. The same edit with wake=False moves the pillar and leaves the crate hanging in mid-air, which is the picture of what suppression buys (level streaming and pooled respawns do not re-simulate a parked scene) and what it costs (you now own the consequences).

The other direction is handing a body TO the simulation. A crate can be streamed in parked – dynamic and asleep where it stands, costing nothing until something reaches it – which is what a level chunk arriving mid-game wants instead of paying to fall into place.

A pile sleeps as a whole and wakes as a whole. Pull the bottom crate out of a stack and every crate it was holding up wakes in the same step, not just the one directly above it: the crate above is falling by the time the next collision pass runs, so a wake that reached one level would leave the rest of the stack asleep in mid-air. The HUD’s drift readout is the other side of that bargain – while a crate is asleep its pose does not change at all, which is what makes a settled scene free rather than merely quiet.

Shows:

• PhysicsBody3D.is_sleeping, wake() and sleep(): the read-back and the two explicit controls.

• can_sleep: a body that must stay simulated however long it rests.

• Re-shaping a support wakes the bodies resting on it, through the node API (assigning CollisionShape3D.shape).

• The wake=False opt-out, which lives on the world seam rather than on the node: reached through the public body.world / body.handle pair.

• The parked hand-over: a body freed into DYNAMIC and put straight back to sleep, which is what the seam does for a mode flip made with wake=False.

• Island-atomic wake: one crate taken out from under a stack wakes all of it.

• Asleep is frozen: the HUD reports how far any sleeping crate has moved since it fell asleep, which stays at zero.

• Capability.SLEEP: a backend that does not advertise it never sleeps anything, so the HUD says so instead of showing a count that cannot move.

Controls: 1 - shrink the pillar (default): the crate on top wakes and falls 2 - slide the pillar away with wake=False: the crate stays asleep 3 - slide the pillar away normally: the crate wakes and falls 4 - stream a crate in parked: it hangs where it lands until it is woken 5 - yank the bottom crate out of a stack: the whole stack wakes W / S - wake / sleep the whole pile C - toggle can_sleep on the pile Arrows - orbit the camera R - rebuild the scene Escape - quit

Run: uv run python examples/features/physics/sleeping.py Headless self-check: uv run python examples/features/physics/sleeping.py –test

Source

"""Sleeping Bodies: what wakes a settled pile, and how to edit one without waking it.

A pile of crates settles on the ground and falls asleep; a sleeping body is
skipped by integration and the contact solve until something disturbs it, which
is what keeps a large resting scene cheap. Bodies are tinted by their live sleep
state, so the pile visibly dims as it settles and lights up the moment anything
reaches it.

The interesting half is what counts as a disturbance. Changing a body wakes what
it was holding up: shrink the pillar under the crate on top and the crate falls,
because the seam wakes its riders rather than waiting for a contact that has
already gone. The same edit with ``wake=False`` moves the pillar and leaves the
crate hanging in mid-air, which is the picture of what suppression buys (level
streaming and pooled respawns do not re-simulate a parked scene) and what it
costs (you now own the consequences).

The other direction is handing a body TO the simulation. A crate can be streamed
in parked -- dynamic and asleep where it stands, costing nothing until something
reaches it -- which is what a level chunk arriving mid-game wants instead of
paying to fall into place.

A pile sleeps as a whole and wakes as a whole. Pull the bottom crate out of a
stack and every crate it was holding up wakes in the same step, not just the one
directly above it: the crate above is falling by the time the next collision pass
runs, so a wake that reached one level would leave the rest of the stack asleep in
mid-air. The HUD's drift readout is the other side of that bargain -- while a
crate is asleep its pose does not change at all, which is what makes a settled
scene free rather than merely quiet.

Shows:
  - ``PhysicsBody3D.is_sleeping``, ``wake()`` and ``sleep()``: the read-back and
    the two explicit controls.
  - ``can_sleep``: a body that must stay simulated however long it rests.
  - Re-shaping a support wakes the bodies resting on it, through the node API
    (assigning ``CollisionShape3D.shape``).
  - The ``wake=False`` opt-out, which lives on the world seam rather than on the
    node: reached through the public ``body.world`` / ``body.handle`` pair.
  - The parked hand-over: a body freed into ``DYNAMIC`` and put straight back to
    sleep, which is what the seam does for a mode flip made with ``wake=False``.
  - Island-atomic wake: one crate taken out from under a stack wakes all of it.
  - Asleep is frozen: the HUD reports how far any sleeping crate has moved since
    it fell asleep, which stays at zero.
  - ``Capability.SLEEP``: a backend that does not advertise it never sleeps
    anything, so the HUD says so instead of showing a count that cannot move.

Controls:
    1       - shrink the pillar (default): the crate on top wakes and falls
    2       - slide the pillar away with wake=False: the crate stays asleep
    3       - slide the pillar away normally: the crate wakes and falls
    4       - stream a crate in parked: it hangs where it lands until it is woken
    5       - yank the bottom crate out of a stack: the whole stack wakes
    W / S   - wake / sleep the whole pile
    C       - toggle can_sleep on the pile
    Arrows  - orbit the camera
    R       - rebuild the scene
    Escape  - quit

Run: uv run python examples/features/physics/sleeping.py
Headless self-check: uv run python examples/features/physics/sleeping.py --test

# /// simvx
# tags = ["3d", "physics", "sleeping"]
# ///
"""

from __future__ import annotations

import math

from simvx.core import (
    BodyMode,
    BoxShape3D,
    Camera3D,
    CollisionShape3D,
    DirectionalLight3D,
    Input,
    InputMap,
    Key,
    Material,
    Mesh,
    MeshInstance3D,
    Node,
    PhysicsBody3D,
    Text2D,
    Vec3,
)
from simvx.core.physics import Capability
from simvx.graphics import App

#: Where the pillar stands, and how tall it is to begin with.
_PILLAR_X = 4.0
_PILLAR_HALF_HEIGHT = 2.0
_SHRUNK_HALF_HEIGHT = 0.5
#: How far along X the pillar is slid to take it out from under the crate: clear of
#: it by a wide margin, and still in shot so you can see where it went.
_SLIDE_DISTANCE = 8.0
#: The crate that rides the pillar starts just above its top face, and settles on it.
_RIDER_Y = _PILLAR_HALF_HEIGHT * 2 + 0.55
_RIDER_REST_Y = _PILLAR_HALF_HEIGHT * 2 + 0.5
#: Where a streamed-in crate is handed over, well clear of the pile and the pillar.
_STREAM_X = -0.5
_STREAM_Y = 7.0
#: How far forward the yanked crate is pulled: clear of the stack it was under,
#: and still in shot next to it.
_YANK_Z = -6.0

_ASLEEP = Material(colour=(0.30, 0.34, 0.42, 1.0), roughness=0.9, metallic=0.0)
_AWAKE = Material(colour=(0.95, 0.72, 0.25, 1.0), emissive_colour=(0.7, 0.45, 0.05, 0.8), roughness=0.4)
#: A body that may never sleep is always drawn awake; a distinct tint says why.
_NEVER_SLEEPS = Material(colour=(0.35, 0.80, 0.95, 1.0), emissive_colour=(0.1, 0.4, 0.5, 0.6), roughness=0.4)


class SleepingScene(Node):
    def on_ready(self):
        InputMap.add_action("shrink_pillar", [Key.KEY_1])
        InputMap.add_action("slide_quietly", [Key.KEY_2])
        InputMap.add_action("slide_loudly", [Key.KEY_3])
        InputMap.add_action("stream_in", [Key.KEY_4])
        InputMap.add_action("yank_bottom", [Key.KEY_5])
        InputMap.add_action("wake_all", [Key.W])
        InputMap.add_action("sleep_all", [Key.S])
        InputMap.add_action("toggle_can_sleep", [Key.C])
        InputMap.add_action("orbit_left", [Key.LEFT])
        InputMap.add_action("orbit_right", [Key.RIGHT])
        InputMap.add_action("rebuild", [Key.R])
        InputMap.add_action("quit", [Key.ESCAPE])

        self._cam_angle = 0.7
        self._cam = self.add_child(Camera3D())
        self._update_camera()

        sun = DirectionalLight3D(position=(6, 12, 8))
        sun.colour = (1.0, 0.96, 0.85)
        sun.intensity = 3.0
        sun.look_at((0, 0, 0))
        self.add_child(sun)

        self._cube = Mesh.cube()
        self._bodies: list[PhysicsBody3D] = []
        self._stacks: list[list[PhysicsBody3D]] = []
        self._visuals: dict[PhysicsBody3D, MeshInstance3D] = {}
        # Where each crate was when it last fell asleep, so the HUD can report
        # that a sleeper's pose really does stop changing.
        self._asleep_at: dict[PhysicsBody3D, tuple[float, float, float]] = {}
        self._ground: PhysicsBody3D | None = None
        self._pillar: PhysicsBody3D | None = None
        self._pillar_shape: CollisionShape3D | None = None
        self._pillar_mesh: MeshInstance3D | None = None
        self._rider: PhysicsBody3D | None = None
        self._can_sleep = True
        self._streamed = 0
        self._build()

        self._hud = Text2D(
            text=(
                "1 shrink pillar | 2 slide it (wake=False) | 3 slide it | 4 stream one in parked | "
                "5 yank a stack's bottom crate | W/S wake/sleep | C can_sleep | R reset"
            ),
            position=(10, 10),
            font_scale=1.3,
        )
        self.add_child(self._hud)
        self._status = self.add_child(Text2D(text="", position=(10, 34), font_scale=1.1))
        self._note = self.add_child(Text2D(text="", position=(10, 58), font_scale=1.0))

    # -- scene construction -------------------------------------------------

    def _crate(self, position, *, can_sleep: bool = True, mode: BodyMode = BodyMode.DYNAMIC) -> PhysicsBody3D:
        body = PhysicsBody3D(mode=mode, position=position, mass=1.0, can_sleep=can_sleep)
        body.add_child(CollisionShape3D(shape=BoxShape3D(half_extents=Vec3(0.5, 0.5, 0.5))))
        # Kept beside the body rather than looked up each frame: the tint is
        # rewritten whenever the sleep state changes.
        self._visuals[body] = body.add_child(MeshInstance3D(mesh=self._cube, material=_AWAKE))
        self.add_child(body)
        self._bodies.append(body)
        return body

    def _build(self):
        for body in self._bodies:
            body.destroy()
        self._bodies = []
        self._stacks = []
        self._visuals = {}
        self._asleep_at = {}
        self._streamed = 0
        if self._pillar is not None:
            self._pillar.destroy()
        if self._ground is not None:
            self._ground.destroy()

        self._ground = PhysicsBody3D(mode=BodyMode.STATIC, position=(0, -0.5, 0))
        self._ground.add_child(CollisionShape3D(shape=BoxShape3D(half_extents=Vec3(14, 0.5, 14))))
        self._ground.add_child(
            MeshInstance3D(
                mesh=self._cube,
                material=Material(colour=(0.22, 0.24, 0.28, 1.0), roughness=0.95),
                scale=(28, 1, 28),
            )
        )
        self.add_child(self._ground)

        # A STATIC pillar with one crate settled on top: the support whose edits
        # the number keys drive.
        self._pillar = PhysicsBody3D(mode=BodyMode.STATIC, position=(_PILLAR_X, _PILLAR_HALF_HEIGHT, 0))
        self._pillar_shape = CollisionShape3D(shape=BoxShape3D(half_extents=Vec3(1.0, _PILLAR_HALF_HEIGHT, 1.0)))
        self._pillar.add_child(self._pillar_shape)
        # Kept, not anonymous: shrinking the collider has to shrink the box the
        # player can see, or the crate falls through a pillar that still looks solid.
        self._pillar_mesh = self._pillar.add_child(
            MeshInstance3D(
                mesh=self._cube,
                material=Material(colour=(0.45, 0.42, 0.55, 1.0), roughness=0.8),
                scale=(2, _PILLAR_HALF_HEIGHT * 2, 2),
            )
        )
        self.add_child(self._pillar)
        self._rider = self._crate((_PILLAR_X, _RIDER_Y, 0), can_sleep=self._can_sleep)

        # And a loose pile on the ground, so the sleep count has something to say.
        # Three short stacks: enough for the sleep count to move visibly as they
        # settle, few enough that each crate stays readable. Kept as stacks, not
        # just as a list, because pulling one crate out from under its own stack
        # is what shows the wake reaching all of it.
        for column in range(3):
            x = (column - 1) * 1.4 - 3.0
            self._stacks.append(
                [self._crate((x, 0.55 + level * 1.02, 0.0), can_sleep=self._can_sleep) for level in range(3)]
            )

    def _update_camera(self):
        d, height = 20.0, 8.0
        self._cam.position = (d * math.sin(self._cam_angle), height, d * math.cos(self._cam_angle))
        self._cam.look_at((0, 2.0, 0), up=(0, 1, 0))

    # -- the four disturbances the keys drive -------------------------------

    def _shrink_pillar(self):
        """Assigning a new shape wakes the bodies the old geometry was holding up."""
        self._pillar_shape.shape = BoxShape3D(half_extents=Vec3(1.0, _SHRUNK_HALF_HEIGHT, 1.0))
        self._pillar_mesh.scale = (2, _SHRUNK_HALF_HEIGHT * 2, 2)
        self._note.text = "pillar shrank: the crate on top woke and is falling"

    def _slide_pillar(self, *, wake: bool):
        """Move the pillar clear, with the wake either honoured or suppressed.

        ``wake=`` is a seam argument rather than a node property, so this reaches
        the world through the body's own public ``world`` / ``handle`` pair. Writing
        ``pillar.position`` instead would always wake, which is the right default
        for game code and the wrong one for streaming.
        """
        pose = (Vec3(_PILLAR_X + _SLIDE_DISTANCE, _PILLAR_HALF_HEIGHT, 0.0), self._pillar.world_rotation)
        self._pillar.world.set_body_transform(self._pillar.handle, pose, wake=wake)
        # The pose went to the body, so the node has not moved and the mesh hanging
        # off it has not either. Offsetting the mesh in its parent's space puts the
        # drawn pillar back on its collider without touching the node's position.
        self._pillar_mesh.position = (_SLIDE_DISTANCE, 0.0, 0.0)
        if wake:
            self._note.text = "pillar slid away: the crate woke and is falling"
        else:
            self._note.text = "pillar slid away with wake=False: the crate is still asleep, in mid-air"

    def _stream_in_crate(self):
        """Hand a crate to the simulation parked, the way a level chunk arrives.

        The node form of the seam's ``set_body_mode(mode, wake=False)``: freeing the
        body wakes it, as every write does, so it is put straight back to sleep
        before another step can run. It then hangs exactly where it was placed,
        costing nothing, until W (or anything reaching it) wakes it.
        """
        crate = self._crate((_STREAM_X + self._streamed * 1.3, _STREAM_Y, 0.0), mode=BodyMode.STATIC)
        self._streamed += 1
        crate.mode = BodyMode.DYNAMIC
        crate.sleep()
        self._note.text = "streamed a crate in parked: dynamic, asleep, and staying put until something wakes it"

    def _yank_bottom_crate(self) -> list[PhysicsBody3D]:
        """Pull the bottom crate out of a settled stack and wake all of it.

        Sleep latches per contact island and the wake follows the same island, so
        the crates above the one that left wake in the step it happens. Waking
        only what the moved crate was recorded as touching would reach one level:
        that crate is falling before the next collision pass, and the rest of the
        stack would be left asleep in mid-air with nothing under it.

        Returns the stack, bottom crate first, so a caller can check who woke.
        """
        stack = self._stacks[0]
        bottom = stack[0]
        bottom.position = (bottom.position[0], 0.55, _YANK_Z)
        self._note.text = "yanked the bottom crate out: the whole stack woke, not only the crate above it"
        return stack

    def _sleeping_pose_drift(self) -> float:
        """How far any crate has moved since it fell asleep, in metres.

        Asleep means out of the step entirely: not integrated, not solved, and not
        shifted by the contact position pass either. A crate that is awake has no
        frozen pose to compare against and drops out of the reckoning.
        """
        drift = 0.0
        for body in self._bodies:
            if not body.is_sleeping:
                self._asleep_at.pop(body, None)
                continue
            here = tuple(float(v) for v in body.position)
            drift = max(drift, math.dist(here, self._asleep_at.setdefault(body, here)))
        return drift

    def _set_can_sleep(self, enabled: bool):
        self._can_sleep = enabled
        for body in self._bodies:
            body.can_sleep = enabled
        self._note.text = f"can_sleep = {enabled} on every crate"

    # -- per-frame ----------------------------------------------------------

    def on_update(self, dt):
        if Input.is_action_just_pressed("quit"):
            self.app.quit()
            return
        if Input.is_action_just_pressed("rebuild"):
            self._build()
            self._note.text = "rebuilt"
        if Input.is_action_just_pressed("shrink_pillar"):
            self._shrink_pillar()
        if Input.is_action_just_pressed("slide_quietly"):
            self._slide_pillar(wake=False)
        if Input.is_action_just_pressed("slide_loudly"):
            self._slide_pillar(wake=True)
        if Input.is_action_just_pressed("stream_in"):
            self._stream_in_crate()
        if Input.is_action_just_pressed("yank_bottom"):
            self._yank_bottom_crate()
        if Input.is_action_just_pressed("wake_all"):
            for body in self._bodies:
                body.wake()
            self._note.text = "woke every crate by hand"
        if Input.is_action_just_pressed("sleep_all"):
            for body in self._bodies:
                body.sleep()
            self._note.text = "parked every crate by hand (a no-op where can_sleep is False)"
        if Input.is_action_just_pressed("toggle_can_sleep"):
            self._set_can_sleep(not self._can_sleep)

        self._cam_angle += Input.get_axis("orbit_left", "orbit_right") * 1.5 * dt
        self._update_camera()

        for body in self._bodies:
            visual = self._visuals[body]
            if not body.can_sleep:
                visual.material = _NEVER_SLEEPS
            else:
                visual.material = _ASLEEP if body.is_sleeping else _AWAKE

        asleep = sum(1 for b in self._bodies if b.is_sleeping)
        world = self._bodies[0].world if self._bodies else None
        if world is not None and Capability.SLEEP not in world.capabilities():
            self._status.text = (
                "this backend does not advertise Capability.SLEEP: nothing here ever sleeps "
                f"({asleep}/{len(self._bodies)})"
            )
        else:
            rider = "asleep" if self._rider.is_sleeping else "awake"
            self._status.text = (
                f"asleep: {asleep}/{len(self._bodies)} | rider on the pillar: {rider} | "
                f"can_sleep: {self._can_sleep} | sleeper drift: {self._sleeping_pose_drift() * 1000:.2f} mm"
            )


def _selftest() -> bool:
    """Headless: settle, then drive both directions of the wake gate and check them."""
    from simvx.graphics.testing import assert_not_blank, save_png

    app = App(title="Sleeping", width=1280, height=720, visible=False)
    scene = SleepingScene(name="SleepingScene")
    frames = app.run_headless(scene, frames=400, capture_frames=[399])
    assert_not_blank(frames[0])
    save_png(frames[0], "/tmp/physics_sleeping_test.png")

    settled = sum(1 for b in scene._bodies if b.is_sleeping)
    rider, world = scene._rider, scene._rider.world
    rider_y = float(world.body_transform(rider.handle)[0][1])
    print(f"settled asleep: {settled}/{len(scene._bodies)} ; rider y={rider_y:.3f}")

    # The rest is driven straight on the world: a second run_headless would rebuild
    # the scene, and nothing below needs a rendered frame.
    def advance(steps: int) -> float:
        for _ in range(steps):
            world.step(1.0 / 60.0)
            world.drain_contact_events()
            world.drain_overlap_events()
        return float(world.body_transform(rider.handle)[0][1])

    def height(body) -> float:
        return float(world.body_transform(body.handle)[0][1])

    # Asleep is frozen: a settled pile's pose stops changing altogether, rather
    # than drifting on under a position pass that still moves it.
    frozen = {b: tuple(float(v) for v in world.body_transform(b.handle)[0]) for b in scene._bodies if b.is_sleeping}
    advance(300)
    drift = max(
        (math.dist(tuple(float(v) for v in world.body_transform(b.handle)[0]), pose) for b, pose in frozen.items()),
        default=1.0,
    )
    print(f"largest pose change over 300 steps asleep: {drift:.6f}")

    # Island-atomic wake: the crates above the one pulled out wake in the same
    # step, and the stack ends up on the ground rather than hanging in the air.
    stack = scene._yank_bottom_crate()
    still_asleep = [b.is_sleeping for b in stack[1:]]
    print(f"after yanking the bottom crate, the crates above it asleep={still_asleep}")
    advance(300)
    stack_rest = [height(b) for b in stack[1:]]
    print("the stack fell to " + ", ".join(f"{y:.3f}" for y in stack_rest))

    # wake=False: the pillar leaves and the rider stays exactly where it was.
    scene._slide_pillar(wake=False)
    quiet_asleep = rider.is_sleeping
    stranded_y = advance(60)
    print(f"after wake=False slide: rider asleep={quiet_asleep} y={stranded_y:.3f}")

    # And the default: the rider wakes and falls to the ground.
    rider.wake()
    fallen_y = advance(300)
    print(f"after waking it by hand: rider y={fallen_y:.3f} asleep={rider.is_sleeping}")

    # The other direction: a crate handed over parked stays where it was placed.
    scene._stream_in_crate()
    streamed = scene._bodies[-1]
    parked_asleep = streamed.is_sleeping
    for _ in range(60):
        world.step(1.0 / 60.0)
    parked_y = float(world.body_transform(streamed.handle)[0][1])
    print(f"streamed in parked: asleep={parked_asleep} y={parked_y:.3f}")
    streamed.wake()
    for _ in range(300):
        world.step(1.0 / 60.0)
    dropped_y = float(world.body_transform(streamed.handle)[0][1])
    print(f"after waking the streamed crate: y={dropped_y:.3f}")
    print("screenshot: /tmp/physics_sleeping_test.png")

    ok = (
        settled == len(scene._bodies) - 1  # every crate but the one streamed in after the settle
        and abs(rider_y - _RIDER_REST_Y) < 0.1
        and drift < 1e-6  # asleep is frozen, not merely slow
        and not any(still_asleep)  # the whole island woke, not just the crate above
        and all(y < 1.6 for y in stack_rest)  # and it came down rather than hanging
        and quiet_asleep
        and abs(stranded_y - rider_y) < 0.01  # suppressed: it did not move at all
        and fallen_y < 1.0  # woken: it fell to the ground
        and parked_asleep
        and abs(parked_y - _STREAM_Y) < 0.01  # parked: out of the step entirely
        and dropped_y < 1.0  # and running once woken
    )
    print("SELFTEST:", "PASS" if ok else "FAIL")
    return ok


if __name__ == "__main__":
    import sys

    if "--test" in sys.argv:
        sys.exit(0 if _selftest() else 1)
    app = App(title="Sleeping Bodies", width=1280, height=720)
    app.run(SleepingScene())