Body and World Knobs

damping and gravity scale per body, the rest per world.

▶ Run in browser

Tags: physics 3d damping gravity materials

A physics knob has exactly one home, and which one follows what the knob describes. Damping and gravity scale describe THIS object’s dynamics, so they live on the body: a feather and a cannonball want different drag in the same air, and a balloon and a pickup want different gravity in the same world. Solver iterations, the sleep thresholds and the contact slop describe the space everything is in, so they live on the world, where one number governs every body.

Three balls fall side by side from the same height with three damping rates, so the only thing between them is the knob. A balloon rises on a negative gravity scale and a pickup hangs on a zero one. Two tops get the same kick and wind down at different rates, because angular damping is independent of linear damping. Four crates share ONE PhysicsMaterial: swap it and all four change surface at once, because a material is a resource many bodies hold rather than four loose numbers copied onto each.

The world knobs are live, and visibly so. Loosen contact_slop and the settled crates sink into the floor; shorten sleep_time_threshold and the pile parks sooner. Changing one wakes nothing by itself – a world knob names no body, so it cannot take support away from one – which is why the key that changes the slop wakes the crates itself, or you would watch four sleeping boxes ignore it.

Shows:

• linear_damping / angular_damping: the per-second rate at which a body sheds motion with nothing touching it, applied once per step as v = v * max(0, 1 - damping * dt) + a * dt. 0 coasts forever.

• gravity_scale: 1 falls, 0 hangs where it is put, negative rises.

• PhysicsMaterial as a shared resource: one instance, four bodies, and a live reassignment that reaches all of them.

• The world knobs on PhysicsRoot.world: gravity, solver_iterations, position_iterations, sleep_time_threshold and contact_slop.

• That the two iteration counts are different dials: the solver one governs the velocity loop every body goes through, while position_iterations drains the error left in rigid JOINTS. Nothing here is jointed, so the readout is the only place it shows – it is cycled anyway, because the knob belongs to the world beside the others and a scene that hid it would imply it did not exist. A jointed chain is what it acts on, and only on the two builtin solvers, which are the ones that run the seam’s own position pass: see examples/features/2d/joints.py and docs/core/physics_backends.md.

• That a world knob is deliberately outside the wake gate, and what a scene does about it.

Controls: 1 - drop the three balls again 2 - kick both tops again 3 - release the pickup (gravity_scale 0 -> 1), or park it again 4 - swap the material the four crates share (grippy <-> bouncy) G - world gravity: Earth / Moon / none I - solver_iterations: 4 / 8 / 32 P - position_iterations: 1 / 3 / 16 (joints only; nothing here is jointed) T - sleep_time_threshold: 0.1 / 0.5 / 2.0 s K - contact_slop: 0.001 / 0.02 / 0.1 (and wake the crates to show it) Arrows - orbit the camera R - rebuild the scene Escape - quit

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

Source

"""Body and World Knobs: damping and gravity scale per body, the rest per world.

A physics knob has exactly one home, and which one follows what the knob
describes. Damping and gravity scale describe THIS object's dynamics, so they
live on the body: a feather and a cannonball want different drag in the same air,
and a balloon and a pickup want different gravity in the same world. Solver
iterations, the sleep thresholds and the contact slop describe the space
everything is in, so they live on the world, where one number governs every body.

Three balls fall side by side from the same height with three damping rates, so
the only thing between them is the knob. A balloon rises on a negative gravity
scale and a pickup hangs on a zero one. Two tops get the same kick and wind down
at different rates, because angular damping is independent of linear damping.
Four crates share ONE ``PhysicsMaterial``: swap it and all four change surface at
once, because a material is a resource many bodies hold rather than four loose
numbers copied onto each.

The world knobs are live, and visibly so. Loosen ``contact_slop`` and the settled
crates sink into the floor; shorten ``sleep_time_threshold`` and the pile parks
sooner. Changing one wakes nothing by itself -- a world knob names no body, so it
cannot take support away from one -- which is why the key that changes the slop
wakes the crates itself, or you would watch four sleeping boxes ignore it.

Shows:
  - ``linear_damping`` / ``angular_damping``: the per-second rate at which a body
    sheds motion with nothing touching it, applied once per step as
    ``v = v * max(0, 1 - damping * dt) + a * dt``. ``0`` coasts forever.
  - ``gravity_scale``: ``1`` falls, ``0`` hangs where it is put, negative rises.
  - ``PhysicsMaterial`` as a shared resource: one instance, four bodies, and a
    live reassignment that reaches all of them.
  - The world knobs on ``PhysicsRoot.world``: ``gravity``, ``solver_iterations``,
    ``position_iterations``, ``sleep_time_threshold`` and ``contact_slop``.
  - That the two iteration counts are different dials: the solver one governs the
    velocity loop every body goes through, while ``position_iterations`` drains
    the error left in rigid JOINTS. Nothing here is jointed, so the readout is the
    only place it shows -- it is cycled anyway, because the knob belongs to the
    world beside the others and a scene that hid it would imply it did not exist.
    A jointed chain is what it acts on, and only on the two builtin solvers,
    which are the ones that run the seam's own position pass: see
    ``examples/features/2d/joints.py`` and ``docs/core/physics_backends.md``.
  - That a world knob is deliberately outside the wake gate, and what a scene
    does about it.

Controls:
    1       - drop the three balls again
    2       - kick both tops again
    3       - release the pickup (gravity_scale 0 -> 1), or park it again
    4       - swap the material the four crates share (grippy <-> bouncy)
    G       - world gravity: Earth / Moon / none
    I       - solver_iterations: 4 / 8 / 32
    P       - position_iterations: 1 / 3 / 16 (joints only; nothing here is jointed)
    T       - sleep_time_threshold: 0.1 / 0.5 / 2.0 s
    K       - contact_slop: 0.001 / 0.02 / 0.1 (and wake the crates to show it)
    Arrows  - orbit the camera
    R       - rebuild the scene
    Escape  - quit

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

# /// simvx
# tags = ["3d", "physics", "damping", "gravity", "materials"]
# ///
"""

from __future__ import annotations

import math

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

#: Height the drop rack is released from, and the three rates it compares. The
#: middle one is the seam default, so the middle ball is what an unstated body does.
_DROP_HEIGHT = 9.0
_BALL_RADIUS = 0.4
_RACK = (
    ("cannonball", -5.0, 0.0, (0.85, 0.30, 0.25, 1.0)),
    ("default", -3.4, 0.05, (0.90, 0.86, 0.35, 1.0)),
    ("feather", -1.8, 2.0, (0.55, 0.85, 0.95, 1.0)),
)

#: The balloon rises at a terminal speed its own damping sets: the upward
#: acceleration is ``-gravity_scale * g`` and the drag cancels it at
#: ``0.2 * 9.81 / 2.0`` ~ 1 m/s, which is slow enough to watch.
_BALLOON_X = 0.6
_BALLOON_START_Y = 1.0
_BALLOON_CEILING = 9.0

#: The two tops hang side by side on ``gravity_scale = 0`` and are given the same
#: kick, so the only difference between them is angular damping.
_PICKUP_X = 3.0
_SPINNER_X = 4.6
_TOP_Y = 2.6
_SPIN_KICK = Vec3(0.0, 9.0, 0.0)

#: Four crates on the ground, all holding one material resource between them.
_CRATE_XS = (6.6, 8.2, 9.8, 11.4)
_CRATE_DROP_Y = 2.0

#: The rack re-drops itself on this period, so the scene keeps showing the thing it
#: is about without anyone pressing a key. Long enough for the feather, which
#: reaches a terminal speed of ``9.81 / 2`` m/s and takes about 2.3 s to arrive.
_DROP_PERIOD = 3.5

_GRAVITIES = ((0.0, -9.81, 0.0), (0.0, -1.62, 0.0), (0.0, 0.0, 0.0))
_GRAVITY_NAMES = ("Earth", "Moon", "none")
_ITERATIONS = (4, 8, 32)
#: Joint position passes per step. Cycled beside the velocity count because both
#: live on the world; only a jointed scene sees the difference (see the docstring).
_POSITION_ITERATIONS = (1, 3, 16)
_SLEEP_TIMES = (0.1, 0.5, 2.0)
_SLOPS = (0.001, 0.02, 0.1)

#: The two surfaces the crates swap between. Each is ONE instance held by all four
#: bodies, which is the whole point of a material being a resource; it is frozen,
#: so no crate can change what the other three are made of.
_GRIPPY = PhysicsMaterial(friction=0.9, restitution=0.0, friction_combine="max")
_BOUNCY = PhysicsMaterial(friction=0.1, restitution=0.8, restitution_combine="max")

#: Backend for the scene's ``PhysicsRoot``. Named here as a literal rather than
#: left to resolve at runtime so a web export can tell which runtime to bundle:
#: set it to ``"jolt"`` to watch the same knobs on the native solver, and an
#: export picks the Jolt runtime up with it.
BACKEND = "builtin"

_GRIPPY_LOOK = Material(colour=(0.45, 0.40, 0.34, 1.0), roughness=0.95)
_BOUNCY_LOOK = Material(colour=(0.90, 0.45, 0.70, 1.0), roughness=0.25, metallic=0.1)
_ASLEEP_LOOK = Material(colour=(0.28, 0.30, 0.36, 1.0), roughness=0.9)


class BodyKnobsScene(Node):
    # The canonical, web-safe registration path: the scene tree reads this at mount
    # and re-applies it on every scene swap.
    input_actions = {
        "drop_rack": [Key.KEY_1],
        "kick_tops": [Key.KEY_2],
        "toggle_pickup": [Key.KEY_3],
        "swap_material": [Key.KEY_4],
        "cycle_gravity": [Key.G],
        "cycle_iterations": [Key.I],
        "cycle_position_iterations": [Key.P],
        "cycle_sleep_time": [Key.T],
        "cycle_slop": [Key.K],
        "orbit_left": [Key.LEFT],
        "orbit_right": [Key.RIGHT],
        "rebuild": [Key.R],
        "quit": [Key.ESCAPE],
    }

    def on_ready(self):
        self._cam_angle = 0.35
        self._cam = self.add_child(Camera3D())
        self._update_camera()

        sun = DirectionalLight3D(position=(8, 14, 10))
        sun.colour = (1.0, 0.96, 0.88)
        sun.intensity = 3.0
        sun.look_at((3, 0, 0))
        self.add_child(sun)

        self._cube = Mesh.cube()
        self._ball_mesh = Mesh.sphere()
        # An explicit root, because the world knobs are reached through the world a
        # root owns. Bodies under it simulate in that world and nothing else does.
        self._root = self.add_child(PhysicsRoot(name="World", backend=BACKEND))

        self._gravity_i, self._iterations_i, self._sleep_time_i, self._slop_i = 0, 1, 1, 0
        self._position_iterations_i = 1
        self._pickup_released = False
        self._drop_clock = 0.0
        self._built: list[PhysicsBody3D] = []
        self._crate_material = _GRIPPY
        self._message = "three damping rates, one drop height"
        self._build()

        # Two lines rather than one: the whole HUD has to stay inside the frame at
        # the size the site publishes screenshots at, not just at the window size.
        self._hud = self.add_child(
            Text2D(
                text="1 drop balls | 2 kick tops | 3 release pickup | 4 swap material",
                position=(10, 10),
                font_scale=1.2,
            )
        )
        self._hud_world = self.add_child(
            Text2D(
                text="G gravity | I solver iters | P joint iters | T sleep time | K slop | R reset",
                position=(10, 34),
                font_scale=1.2,
            )
        )
        self._body_line = self.add_child(Text2D(text="", position=(10, 58), font_scale=1.05))
        self._world_line = self.add_child(Text2D(text="", position=(10, 82), font_scale=1.05))
        self._note = self.add_child(Text2D(text="", position=(10, 106), font_scale=1.0))

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

    def _attach(self, body: PhysicsBody3D) -> PhysicsBody3D:
        """Parent a body under the root and remember it, so R can tear the scene down."""
        self._built.append(body)
        return self._root.add_child(body)

    def _ball(self, x: float, damping: float, colour: tuple[float, float, float, float]) -> PhysicsBody3D:
        body = PhysicsBody3D(
            mode=BodyMode.DYNAMIC,
            position=(x, _DROP_HEIGHT, 0.0),
            mass=1.0,
            linear_damping=damping,
            angular_damping=damping,
        )
        body.add_child(CollisionShape3D(shape=SphereShape3D(radius=_BALL_RADIUS)))
        body.add_child(
            MeshInstance3D(
                mesh=self._ball_mesh, material=Material(colour=colour, roughness=0.5), scale=Vec3(_BALL_RADIUS * 2)
            )
        )
        self._attach(body)
        return body

    def _build(self):
        for body in self._built:
            body.destroy()
        self._built = []

        ground = PhysicsBody3D(mode=BodyMode.STATIC, position=(3.0, -0.5, 0.0))
        ground.add_child(CollisionShape3D(shape=BoxShape3D(half_extents=Vec3(11.0, 0.5, 5.0))))
        ground.add_child(
            MeshInstance3D(
                mesh=self._cube,
                material=Material(colour=(0.20, 0.22, 0.26, 1.0), roughness=0.95),
                scale=(22, 1, 10),
            )
        )
        self._attach(ground)
        self._ground = ground

        # The drop rack: identical in every respect but linear_damping.
        self._balls = [self._ball(x, damping, colour) for _, x, damping, colour in _RACK]

        # A balloon: negative gravity scale, and enough drag to rise at a readable
        # speed rather than accelerating out of shot.
        self._balloon = PhysicsBody3D(
            mode=BodyMode.DYNAMIC,
            position=(_BALLOON_X, _BALLOON_START_Y, 0.0),
            mass=0.2,
            gravity_scale=-0.2,
            linear_damping=2.0,
            can_sleep=False,
        )
        self._balloon.add_child(CollisionShape3D(shape=SphereShape3D(radius=0.45)))
        self._balloon.add_child(
            MeshInstance3D(
                mesh=self._ball_mesh,
                material=Material(colour=(0.95, 0.35, 0.45, 1.0), roughness=0.3),
                scale=Vec3(0.9),
            )
        )
        self._attach(self._balloon)

        # Two tops that hang on gravity_scale 0, given the same kick. The pickup
        # keeps spinning (no angular damping); the spinner winds down.
        self._pickup = self._top(_PICKUP_X, angular_damping=0.0, colour=(0.35, 0.90, 0.55, 1.0))
        self._spinner = self._top(_SPINNER_X, angular_damping=1.5, colour=(0.60, 0.55, 0.95, 1.0))
        self._pickup_released = False
        self._kick_tops()

        # Four crates holding ONE material resource between them.
        self._crates = []
        self._crate_visuals: dict[PhysicsBody3D, MeshInstance3D] = {}
        for x in _CRATE_XS:
            crate = PhysicsBody3D(mode=BodyMode.DYNAMIC, position=(x, _CRATE_DROP_Y, 0.0), mass=1.0)
            crate.add_child(CollisionShape3D(shape=BoxShape3D(half_extents=Vec3(0.5, 0.5, 0.5))))
            crate.material = self._crate_material
            self._attach(crate)
            self._crates.append(crate)
            self._crate_visuals[crate] = crate.add_child(MeshInstance3D(mesh=self._cube, material=_GRIPPY_LOOK))
        self._apply_world_knobs()

    def _top(self, x: float, *, angular_damping: float, colour) -> PhysicsBody3D:
        body = PhysicsBody3D(
            mode=BodyMode.DYNAMIC,
            position=(x, _TOP_Y, 0.0),
            mass=1.0,
            gravity_scale=0.0,
            linear_damping=0.0,
            angular_damping=angular_damping,
            can_sleep=False,
        )
        body.add_child(CollisionShape3D(shape=BoxShape3D(half_extents=Vec3(0.45, 0.45, 0.45))))
        body.add_child(
            MeshInstance3D(mesh=self._cube, material=Material(colour=colour, roughness=0.4), scale=(0.9, 0.9, 0.9))
        )
        self._attach(body)
        return body

    def _update_camera(self):
        radius, height = 20.0, 7.5
        self._cam.position = (
            3.0 + radius * math.sin(self._cam_angle),
            height,
            radius * math.cos(self._cam_angle),
        )
        self._cam.look_at((3.0, 3.5, 0.0), up=(0, 1, 0))

    # -- the things the keys do ---------------------------------------------

    def _drop_rack(self, *, announce: bool = True):
        """Put the three balls back at the same height with no motion, and let go."""
        for ball in self._balls:
            ball.position = (float(ball.position.x), _DROP_HEIGHT, 0.0)
            ball.velocity = Vec3(0.0, 0.0, 0.0)
            ball.spin = Vec3(0.0, 0.0, 0.0)
            ball.wake()
        self._drop_clock = 0.0
        if announce:
            self._message = "dropped: same height, damping 0 / 0.05 / 2.0"

    def _kick_tops(self, *, announce: bool = True):
        """The same angular impulse to both, so only angular_damping differs."""
        for top in (self._pickup, self._spinner):
            top.spin = _SPIN_KICK
            top.wake()
        if announce:
            self._message = "both tops kicked at the same rate; only one of them keeps it"

    def _toggle_pickup(self):
        """``gravity_scale`` is what makes a pickup hang, and letting go is one write."""
        self._pickup_released = not self._pickup_released
        self._pickup.gravity_scale = 1.0 if self._pickup_released else 0.0
        if not self._pickup_released:
            self._pickup.position = (_PICKUP_X, _TOP_Y, 0.0)
            self._pickup.velocity = Vec3(0.0, 0.0, 0.0)
        self._message = (
            "pickup released (gravity_scale 1)" if self._pickup_released else "pickup parked (gravity_scale 0)"
        )

    def _swap_material(self):
        """One resource serves all four crates, so the swap is one instance, four writes.

        Assigning a material whose values differ is what reaches the simulation.
        A ``PhysicsMaterial`` is frozen, so a surface is never edited: to change
        one coefficient, assign ``replace(crate.material, friction=0.1)``.
        """
        self._crate_material = _BOUNCY if self._crate_material is _GRIPPY else _GRIPPY
        for crate in self._crates:
            crate.material = self._crate_material
            crate.position = (float(crate.position.x), _CRATE_DROP_Y, 0.0)
            crate.velocity = Vec3(0.0, 0.0, 0.0)
            crate.wake()
        surface = "bouncy" if self._crate_material is _BOUNCY else "grippy"
        self._message = f"one material, four crates: now {surface}, dropped again to show it"

    # -- world knobs --------------------------------------------------------

    def _apply_world_knobs(self):
        world = self._root.world
        world.gravity = Vec3(*_GRAVITIES[self._gravity_i])
        world.solver_iterations = _ITERATIONS[self._iterations_i]
        world.position_iterations = _POSITION_ITERATIONS[self._position_iterations_i]
        world.sleep_time_threshold = _SLEEP_TIMES[self._sleep_time_i]
        world.contact_slop = _SLOPS[self._slop_i]

    def _cycle(self, attr: str, values, index: int, *, wake_crates: bool = False) -> int:
        index = (index + 1) % len(values)
        setattr(self._root.world, attr, values[index])
        if wake_crates:
            # A world knob names no body, so the seam deliberately wakes nothing for
            # it. The crates are asleep by now and would sit at their old depth for
            # ever; waking them is the scene's job, not the seam's.
            for crate in self._crates:
                crate.wake()
        return index

    # -- 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._message = "rebuilt"
        if Input.is_action_just_pressed("drop_rack"):
            self._drop_rack()
        if Input.is_action_just_pressed("kick_tops"):
            self._kick_tops()
        if Input.is_action_just_pressed("toggle_pickup"):
            self._toggle_pickup()
        if Input.is_action_just_pressed("swap_material"):
            self._swap_material()
        if Input.is_action_just_pressed("cycle_gravity"):
            self._gravity_i = (self._gravity_i + 1) % len(_GRAVITIES)
            self._root.world.gravity = Vec3(*_GRAVITIES[self._gravity_i])
            for ball in self._balls:
                ball.wake()
            self._message = f"world gravity: {_GRAVITY_NAMES[self._gravity_i]}"
        if Input.is_action_just_pressed("cycle_iterations"):
            self._iterations_i = self._cycle("solver_iterations", _ITERATIONS, self._iterations_i)
            self._message = f"solver_iterations: {_ITERATIONS[self._iterations_i]}"
        if Input.is_action_just_pressed("cycle_position_iterations"):
            self._position_iterations_i = self._cycle(
                "position_iterations", _POSITION_ITERATIONS, self._position_iterations_i
            )
            self._message = (
                f"position_iterations: {_POSITION_ITERATIONS[self._position_iterations_i]} "
                "(joint passes; nothing in this scene is jointed)"
            )
        if Input.is_action_just_pressed("cycle_sleep_time"):
            self._sleep_time_i = self._cycle("sleep_time_threshold", _SLEEP_TIMES, self._sleep_time_i, wake_crates=True)
            self._message = (
                f"sleep_time_threshold: {_SLEEP_TIMES[self._sleep_time_i]} s (the crates were woken to show it)"
            )
        if Input.is_action_just_pressed("cycle_slop"):
            self._slop_i = self._cycle("contact_slop", _SLOPS, self._slop_i, wake_crates=True)
            self._message = f"contact_slop: {_SLOPS[self._slop_i]} (the crates were woken to sink to their new depth)"

        # The rack re-drops itself, so the difference between the three rates is on
        # screen continuously rather than once when the scene loads.
        self._drop_clock += dt
        if self._drop_clock >= _DROP_PERIOD:
            self._drop_rack(announce=False)
            self._kick_tops(announce=False)

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

        # The balloon leaves the top of the shot eventually; send it back down so the
        # scene keeps showing what a negative gravity scale does.
        if float(self._balloon.position.y) > _BALLOON_CEILING:
            self._balloon.position = (_BALLOON_X, _BALLOON_START_Y, 0.0)
            self._balloon.velocity = Vec3(0.0, 0.0, 0.0)

        for crate in self._crates:
            look = _BOUNCY_LOOK if self._crate_material is _BOUNCY else _GRIPPY_LOOK
            self._crate_visuals[crate].material = _ASLEEP_LOOK if crate.is_sleeping else look

        self._refresh_readouts()

    def _refresh_readouts(self):
        heights = " ".join(
            f"{name} {float(b.position.y):5.2f}" for (name, *_), b in zip(_RACK, self._balls, strict=True)
        )
        spin = f"spin kept {float(self._pickup.spin.y):.2f} damped {float(self._spinner.spin.y):.2f}"
        self._body_line.text = f"fall y: {heights} | {spin} | balloon {float(self._balloon.position.y):5.2f}"

        world = self._root.world
        asleep = sum(1 for c in self._crates if c.is_sleeping)
        rest = sum(float(c.position.y) for c in self._crates) / len(self._crates)
        self._world_line.text = (
            f"gravity {_GRAVITY_NAMES[self._gravity_i]} | solver_iters {world.solver_iterations} | "
            f"joint_iters {world.position_iterations} | "
            f"sleep_time {world.sleep_time_threshold} | contact_slop {world.contact_slop} | "
            f"crates {asleep}/{len(self._crates)} asleep at {rest:.3f}"
        )
        self._note.text = self._message


def _seam_fall(damping: float, seconds: float, gravity: float = -9.81, dt: float = 1.0 / 60.0) -> float:
    """The distance the seam's damping formula falls, as the contract states it."""
    v = y = 0.0
    for _ in range(int(seconds / dt)):
        v = v * max(0.0, 1.0 - damping * dt) + gravity * dt
        y += v * dt
    return y


def _selftest() -> bool:
    """Headless: render one frame, then check every knob does what the docs claim."""
    from simvx.graphics.testing import assert_not_blank, save_png

    app = App(title="Body Knobs", width=1280, height=720, visible=False)
    scene = BodyKnobsScene(name="BodyKnobsScene")
    # Captured 40 frames after an automatic re-drop, so the shot has the three
    # balls at three different heights rather than all three already landed.
    frames = app.run_headless(scene, frames=260, capture_frames=[250])
    assert_not_blank(frames[0])
    save_png(frames[0], "/tmp/physics_body_knobs_test.png")

    world = scene._root.world
    ok = True

    def advance(seconds: float) -> None:
        for _ in range(int(seconds * 60.0)):
            world.step(1.0 / 60.0)
            world.drain_contact_events()
            world.drain_overlap_events()

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

    # 1. Damping: three balls, one drop height, and the fall each rate predicts.
    scene._drop_rack()
    fall_time = 1.0
    advance(fall_time)
    for (name, _, damping, _colour), ball in zip(_RACK, scene._balls, strict=True):
        want = _DROP_HEIGHT + _seam_fall(damping, fall_time)
        got = y_of(ball)
        # 4%: Jolt damps after adding the step's acceleration rather than before, so
        # a body under sustained acceleration runs a relative damping*dt slower there.
        good = abs(got - want) <= max(0.04 * abs(want), 0.02)
        print(f"ball {name:<11} damping {damping:<5} y={got:7.3f} (seam formula {want:7.3f}) {'ok' if good else 'BAD'}")
        ok = ok and good
    ordered = y_of(scene._balls[0]) < y_of(scene._balls[1]) < y_of(scene._balls[2])
    print(f"more damping means less distance fallen: {ordered}")
    ok = ok and ordered

    # 2. gravity_scale: the balloon rose, the parked pickup did not move at all.
    balloon_y = y_of(scene._balloon)
    print(f"balloon (gravity_scale -0.2) rose to y={balloon_y:.3f} from {_BALLOON_START_Y}")
    ok = ok and balloon_y > _BALLOON_START_Y + 1.0
    pickup_y = y_of(scene._pickup)
    print(f"pickup (gravity_scale 0) sits at y={pickup_y:.3f}, placed at {_TOP_Y}")
    ok = ok and abs(pickup_y - _TOP_Y) < 0.01

    # 3. Angular damping is independent, and independent of linear damping.
    scene._kick_tops()
    advance(2.0)
    kept = abs(float(scene._pickup.spin.y))
    lost = abs(float(scene._spinner.spin.y))
    print(f"after 2 s: pickup spin {kept:.3f} (kick {_SPIN_KICK.y}), damped spinner {lost:.3f}")
    ok = ok and kept > 0.95 * float(_SPIN_KICK.y) and lost < 0.5 * kept

    # 4. Releasing the pickup is one write, and it falls.
    scene._toggle_pickup()
    advance(1.0)
    released_y = y_of(scene._pickup)
    print(f"released pickup fell to y={released_y:.3f}, from {_TOP_Y}")
    ok = ok and released_y < _TOP_Y - 1.5

    # 5. One material resource, four bodies.
    shared = all(c.material is scene._crates[0].material for c in scene._crates)
    print(f"all four crates hold the same PhysicsMaterial instance: {shared}")
    ok = ok and shared and scene._crates[0].material is _GRIPPY
    scene._swap_material()
    swapped = all(c.material is _BOUNCY for c in scene._crates)
    print(f"after one swap they all hold the bouncy one: {swapped}")
    ok = ok and swapped

    # 6. The world knobs reach the solver. contact_slop is the visible one: a looser
    #    tolerance lets a settled crate rest deeper, and it wakes nothing by itself.
    depths = {}
    for slop in (_SLOPS[0], _SLOPS[2]):
        world.contact_slop = slop
        for crate in scene._crates:
            # Back on the grippy surface: a restitution of 0.8 keeps a crate
            # micro-bouncing, and resting depth is what this half measures.
            crate.material = _GRIPPY
            crate.position = (float(crate.position.x), _CRATE_DROP_Y, 0.0)
            crate.velocity = Vec3(0.0, 0.0, 0.0)
            crate.wake()
        advance(3.0)
        depths[slop] = sum(y_of(c) for c in scene._crates) / len(scene._crates)
        print(f"contact_slop {slop}: crates rest at y={depths[slop]:.4f} (geometric 0.5)")
    sank = depths[_SLOPS[2]] < depths[_SLOPS[0]] - 0.005
    print(f"a looser slop rests deeper: {sank}")
    ok = ok and sank

    world.solver_iterations = 32
    world.sleep_time_threshold = 2.0
    read_back = world.solver_iterations == 32 and world.sleep_time_threshold == 2.0
    print(f"solver_iterations / sleep_time_threshold read back: {read_back}")
    ok = ok and read_back

    # position_iterations drains the error left in rigid JOINTS, and this scene has
    # none. So what is checked is the knob itself and the claim the docstring makes
    # about it: each value reads back, and the same drop under 1, 3 and 16 passes
    # traces the same fall. Asserting a visible change here would be asserting
    # something the solver does not do.
    falls = []
    for count in _POSITION_ITERATIONS:
        world.position_iterations = count
        if world.position_iterations != count:
            print(f"position_iterations {count} did not read back")
            ok = False
        scene._drop_rack()
        advance(0.75)
        falls.append(tuple(y_of(b) for b in scene._balls))
    same = all(all(abs(a - b) < 1e-9 for a, b in zip(fall, falls[0], strict=True)) for fall in falls)
    print(f"position_iterations {list(_POSITION_ITERATIONS)}: same drop, same fall (no joints here): {same}")
    ok = ok and same

    world.contact_slop = _SLOPS[0]
    world.sleep_time_threshold = 0.5
    for crate in scene._crates:
        crate.wake()
    advance(4.0)
    asleep = sum(1 for c in scene._crates if world.sleeping(c.handle))
    print(f"crates asleep after settling at sleep_time_threshold 0.5: {asleep}/{len(scene._crates)}")

    # 7. A world knob names no body, so it takes support from none and wakes none.
    world.contact_slop = _SLOPS[2]
    still_asleep = sum(1 for c in scene._crates if world.sleeping(c.handle))
    print(f"changing contact_slop woke none of them: {still_asleep}/{len(scene._crates)} still asleep")
    ok = ok and still_asleep == asleep

    print("screenshot: /tmp/physics_body_knobs_test.png")
    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="Body and World Knobs", width=1280, height=720)
    app.run(BodyKnobsScene())