Body and World Knobs¶

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

Tags: physics 3d damping gravity materials

A physics knob lives where the thing it describes lives. Damping and gravity scale describe one object’s motion, so they are Properties of the PhysicsBody3D: a feather and a cannonball want different drag in the same air. Gravity, solver iterations, the sleep timer and the contact slop describe the space everything moves in, so they live on the world a PhysicsRoot owns, where one number governs every body under it::

root = self.add_child(PhysicsRoot())
root.add_child(PhysicsBody3D(shape=SphereShape3D(radius=0.4), linear_damping=2.0, gravity_scale=-0.2))
root.world.contact_slop = 0.02

Body knobs, each live when written:

linear_damping and angular_damping are the per-second rates at which a body sheds speed and spin, applied each step as v = v * max(0, 1 - damping * dt) + a * dt. 0 coasts forever. Three balls drop from one height with damping 0, 0.05 (the default) and 2.0, and the damped one falls visibly slower. The two are independent: two tops with the same kick, one with no angular damping, one with 1.5, and only one keeps spinning.
gravity_scale multiplies the world’s gravity for one body: 1 falls, 0 hangs where it is put (the tops, a pickup), negative rises (the balloon). Releasing the pickup is one write, gravity_scale = 1.0.
material takes a frozen PhysicsMaterial (friction, restitution and how they combine). It is a resource: the four crates hold one instance, and swapping it changes all four surfaces at once. To change one coefficient, assign replace(body.material, friction=0.1).

World knobs, on root.world: gravity; solver_iterations, the velocity solver’s passes every body goes through; position_iterations, the passes that drain the error left in joints (nothing here is jointed, so it changes only the readout: features/2d/joints.py shows what it acts on); sleep_time_threshold, how long a body must be still before it sleeps (the crates turn grey); and contact_slop, how far a resting contact may overlap before it is pushed apart, so a looser slop lets the crates rest deeper the next time they land (the material swap drops them again).

A world knob names no body, so changing one wakes nothing, and a sleeping pile would ignore it. The scene wakes every body itself after each change.

The rack re-drops and the tops are kicked again every few seconds. Every action has a button showing its key. Drag or use the arrow keys to orbit the camera, and scroll to zoom.

Source¶

# /// simvx
# tags = ["3d", "physics", "damping", "gravity", "materials"]
# ///
"""Body and World Knobs: damping and gravity scale per body, the rest per world.

A physics knob lives where the thing it describes lives. Damping and gravity
scale describe one object's motion, so they are Properties of the
``PhysicsBody3D``: a feather and a cannonball want different drag in the same
air. Gravity, solver iterations, the sleep timer and the contact slop describe
the space everything moves in, so they live on the world a ``PhysicsRoot`` owns,
where one number governs every body under it::

    root = self.add_child(PhysicsRoot())
    root.add_child(PhysicsBody3D(shape=SphereShape3D(radius=0.4), linear_damping=2.0, gravity_scale=-0.2))
    root.world.contact_slop = 0.02

Body knobs, each live when written:

- ``linear_damping`` and ``angular_damping`` are the per-second rates at which a
  body sheds speed and spin, applied each step as
  ``v = v * max(0, 1 - damping * dt) + a * dt``. ``0`` coasts forever. Three
  balls drop from one height with damping 0, 0.05 (the default) and 2.0, and
  the damped one falls visibly slower. The two are independent: two tops with
  the same kick, one with no angular damping, one with 1.5, and only one keeps
  spinning.
- ``gravity_scale`` multiplies the world's gravity for one body: ``1`` falls,
  ``0`` hangs where it is put (the tops, a pickup), negative rises (the
  balloon). Releasing the pickup is one write, ``gravity_scale = 1.0``.
- ``material`` takes a frozen ``PhysicsMaterial`` (friction, restitution and how
  they combine). It is a resource: the four crates hold one instance, and
  swapping it changes all four surfaces at once. To change one coefficient,
  assign ``replace(body.material, friction=0.1)``.

World knobs, on ``root.world``: ``gravity``; ``solver_iterations``, the
velocity solver's passes every body goes through; ``position_iterations``, the
passes that drain the error left in joints (nothing here is jointed, so it
changes only the readout: ``features/2d/joints.py`` shows what it acts on);
``sleep_time_threshold``, how long a body must be still before it sleeps (the
crates turn grey); and ``contact_slop``, how far a resting contact may overlap
before it is pushed apart, so a looser slop lets the crates rest deeper the
next time they land (the material swap drops them again).

A world knob names no body, so changing one wakes nothing, and a sleeping pile
would ignore it. The scene wakes every body itself after each change.

The rack re-drops and the tops are kicked again every few seconds. Every
action has a button showing its key. Drag or use the arrow keys to orbit the
camera, and scroll to zoom.
"""

import itertools

from simvx.core import (
    Anchor,
    Axis2D,
    BodyMode,
    BoxShape3D,
    Button,
    CanvasLayer,
    DirectionalLight3D,
    HBoxContainer,
    Input,
    Key,
    Label,
    Material,
    Mesh,
    MeshInstance3D,
    Node,
    OrbitCamera3D,
    PhysicsBody3D,
    PhysicsMaterial,
    PhysicsRoot,
    SphereShape3D,
    Timer,
    VBoxContainer,
    on_input,
)
from simvx.graphics import App

DROP_HEIGHT = 9.0
# The drop rack, identical but for damping: (x, damping, colour).
RACK = [(-5.0, 0.0, (0.85, 0.30, 0.25)), (-3.4, 0.05, (0.90, 0.86, 0.35)), (-1.8, 2.0, (0.55, 0.85, 0.95))]
REPLAY_PERIOD = 3.5  # long enough for the most damped ball to land
SPIN_KICK = (0.0, 9.0, 0.0)
PICKUP_HOME = (3.0, 2.6, 0.0)
BALLOON_HOME = (0.6, 1.0, 0.0)
BALLOON_CEILING = 9.0
CRATE_XS = (6.6, 8.2, 9.8, 11.4)
CRATE_DROP_Y = 2.0

GRIPPY = PhysicsMaterial(friction=0.9, restitution=0.0, friction_combine="max")
BOUNCY = PhysicsMaterial(friction=0.1, restitution=0.8, restitution_combine="max")
LOOKS = {
    GRIPPY: Material(colour=(0.45, 0.40, 0.34), roughness=0.95),
    BOUNCY: Material(colour=(0.90, 0.45, 0.70), roughness=0.25, metallic=0.1),
}
ASLEEP_LOOK = Material(colour=(0.28, 0.30, 0.36), roughness=0.9)

# Each key steps its world knob through these values; the first is the engine's default.
WORLD_KNOBS = {
    "gravity": [(0, -9.81, 0), (0, -1.62, 0), (0, 0, 0)],
    "solver_iterations": [16, 32, 4],
    "position_iterations": [3, 16, 1],
    "sleep_time_threshold": [0.5, 2.0, 0.1],
    "contact_slop": [0.001, 0.02, 0.1],
}


class Crate(PhysicsBody3D):
    """A box coloured by the surface it holds, and grey while it sleeps."""

    def __init__(self, **kwargs):
        super().__init__(shape=BoxShape3D(half_extents=(0.5, 0.5, 0.5)), **kwargs)
        self.mesh = self.add_child(MeshInstance3D(mesh=Mesh.box(1.0)))

    def on_update(self, dt):
        self.mesh.material = ASLEEP_LOOK if self.is_sleeping else LOOKS[self.material]


class BodyKnobs(Node):
    input_context = {
        "drop": [Key.KEY_1],
        "kick": [Key.KEY_2],
        "pickup": [Key.KEY_3],
        "material": [Key.KEY_4],
        "gravity": [Key.G],
        "solver_iterations": [Key.I],
        "position_iterations": [Key.P],
        "sleep_time_threshold": [Key.T],
        "contact_slop": [Key.K],
        "rebuild": [Key.R],
        "orbit": [Axis2D.ARROWS],
    }

    def on_ready(self):
        self.camera = self.add_child(OrbitCamera3D(pivot=(3, 3.5, 0), distance=20.5, yaw=0.35, pitch=-0.2))
        self.add_child(DirectionalLight3D(colour=(1.0, 0.96, 0.88), intensity=3.0, direction=(-5, -14, -10)))
        self.world_root = self.add_child(PhysicsRoot(name="World"))
        self.knobs = {knob: itertools.cycle(values) for knob, values in WORLD_KNOBS.items()}
        for knob in self.knobs:
            self.step_knob(knob)
        self.status = "three damping rates, one drop height"
        self.build()
        self.replay_timer = self.add_child(Timer(duration=REPLAY_PERIOD, one_shot=False, autostart=True))
        self.replay_timer.timeout.connect(self.replay)
        self.build_hud()

    def add_body(self, mesh: Mesh, colour, **kwargs) -> PhysicsBody3D:
        body = self.world_root.add_child(PhysicsBody3D(**kwargs))
        body.add_child(MeshInstance3D(mesh=mesh, material=Material(colour=colour, roughness=0.5)))
        return body

    def build(self):
        for body in list(self.world_root.children):
            body.destroy()
        self.add_body(
            Mesh.box((22, 1, 10)), (0.20, 0.22, 0.26), mode=BodyMode.STATIC,
            shape=BoxShape3D(half_extents=(11, 0.5, 5)), position=(3, -0.5, 0),
        )  # fmt: skip
        self.balls = [
            self.add_body(
                Mesh.sphere(0.4),
                colour,
                shape=SphereShape3D(radius=0.4),
                position=(x, DROP_HEIGHT, 0),
                linear_damping=damping,
                angular_damping=damping,
            )
            for x, damping, colour in RACK
        ]
        # Enough drag that the balloon rises at a watchable terminal speed.
        self.balloon = self.add_body(
            Mesh.sphere(0.45), (0.95, 0.35, 0.45), shape=SphereShape3D(radius=0.45), position=BALLOON_HOME,
            mass=0.2, gravity_scale=-0.2, linear_damping=2.0, can_sleep=False,
        )  # fmt: skip
        self.pickup = self.add_top(PICKUP_HOME, angular_damping=0.0, colour=(0.35, 0.90, 0.55))
        self.spinner = self.add_top((4.6, 2.6, 0), angular_damping=1.5, colour=(0.60, 0.55, 0.95))
        self.crates = [
            self.world_root.add_child(Crate(position=(x, CRATE_DROP_Y, 0), material=GRIPPY)) for x in CRATE_XS
        ]
        self.kick_tops()

    def add_top(self, position, angular_damping: float, colour) -> PhysicsBody3D:
        return self.add_body(
            Mesh.box(0.9), colour, shape=BoxShape3D(half_extents=(0.45, 0.45, 0.45)), position=position,
            gravity_scale=0.0, linear_damping=0.0, angular_damping=angular_damping, can_sleep=False,
        )  # fmt: skip

    def drop_rack(self):
        for ball in self.balls:
            ball.position = (ball.position.x, DROP_HEIGHT, 0)
            ball.velocity = (0, 0, 0)
            ball.spin = (0, 0, 0)

    def kick_tops(self):
        # The same spin for both, so only angular_damping tells them apart.
        self.pickup.spin = SPIN_KICK
        self.spinner.spin = SPIN_KICK

    def replay(self):
        self.drop_rack()
        self.kick_tops()

    def step_knob(self, knob: str):
        setattr(self.world_root.world, knob, next(self.knobs[knob]))

    @on_input("drop")
    def _on_drop(self, _event):
        self.drop_rack()
        self.replay_timer.start()
        self.status = "dropped: same height, damping 0 / 0.05 / 2.0"

    @on_input("kick")
    def _on_kick(self, _event):
        self.kick_tops()
        self.status = "both tops kicked alike; only one keeps spinning"

    @on_input("pickup")
    def _on_pickup(self, _event):
        if self.pickup.gravity_scale:
            self.pickup.gravity_scale = 0.0
            self.pickup.position = PICKUP_HOME
            self.pickup.velocity = (0, 0, 0)
            self.status = "pickup parked: gravity_scale 0"
        else:
            self.pickup.gravity_scale = 1.0
            self.status = "pickup released: gravity_scale 1"

    @on_input("material")
    def _on_material(self, _event):
        surface = BOUNCY if self.crates[0].material == GRIPPY else GRIPPY
        for crate in self.crates:
            crate.material = surface
            crate.position = (crate.position.x, CRATE_DROP_Y, 0)
            crate.velocity = (0, 0, 0)
        self.status = f"one material, four crates: all {'bouncy' if surface == BOUNCY else 'grippy'}"

    @on_input(tuple(WORLD_KNOBS))
    def _on_world_knob(self, event):
        self.step_knob(event.action)
        # A world knob wakes no body by itself, so wake them all to show its effect.
        for body in self.world_root.find_all(PhysicsBody3D):
            body.wake()
        self.status = f"{event.action}: {getattr(self.world_root.world, event.action)}"

    @on_input("rebuild")
    def _on_rebuild(self, _event):
        self.build()
        self.status = "rebuilt"

    def on_update(self, dt):
        turn = Input.value("orbit")
        self.camera.orbit(-turn.x * 1.5 * dt, turn.y * 0.8 * dt)
        if self.balloon.position.y > BALLOON_CEILING:
            self.balloon.position = BALLOON_HOME
            self.balloon.velocity = (0, 0, 0)

        world = self.world_root.world
        falls = "   ".join(f"damping {d} at {b.position.y:.2f}" for (_, d, _), b in zip(RACK, self.balls, strict=True))
        asleep = sum(crate.is_sleeping for crate in self.crates)
        rest = sum(crate.position.y for crate in self.crates) / len(self.crates)
        self.readout.text = "\n".join([
            f"ball height: {falls}   balloon {self.balloon.position.y:.2f}",
            f"spin: kept {self.pickup.spin.y:.2f}   damped {self.spinner.spin.y:.2f}",
            f"gravity {world.gravity.y:.2f}   solver_iterations {world.solver_iterations}   "
            f"position_iterations {world.position_iterations}",
            f"sleep_time_threshold {world.sleep_time_threshold}   contact_slop {world.contact_slop}",
            f"crates: {asleep}/{len(self.crates)} asleep, resting at y {rest:.3f}",
            self.status,
        ])  # fmt: skip

    def build_hud(self):
        hud = self.add_child(CanvasLayer())
        self.readout = hud.add_child(Label(anchor=Anchor.TOP_LEFT, inset=12, font_size=15))

        # Example help overlay: not part of the technique shown.
        footer = hud.add_child(VBoxContainer(anchor=Anchor.BOTTOM_LEFT, inset=12, separation=8))
        footer.add_child(Label("Drag / arrows: orbit   Scroll: zoom"))
        rows = [
            [("Drop balls", "drop"), ("Kick tops", "kick"), ("Pickup", "pickup"), ("Material", "material")],
            [("Gravity", "gravity"), ("Solver", "solver_iterations"), ("Joint passes", "position_iterations"),
             ("Sleep time", "sleep_time_threshold"), ("Slop", "contact_slop"), ("Rebuild", "rebuild")],
        ]  # fmt: skip
        for row in rows:
            bar = footer.add_child(HBoxContainer(separation=8))
            for text, action in row:
                bar.add_child(Button(text, action=action))
        # A container keeps its own size rather than growing to its content, so a
        # bottom-anchored stack is fitted by hand or it runs off the bottom edge.
        footer.size = footer.get_minimum_size()


if __name__ == "__main__":
    App(title="Body and World Knobs", width=1280, height=720).run(BodyKnobs())