2D Joints

a swinging pendulum chain built from PinJoint2D constraints.

▶ Run in browser

Tags: 2d physics joints constraints

A line of dynamic balls hangs from a fixed anchor at the top of the screen. Each ball is pinned to the one above it, so the whole chain swings and settles under gravity like a rope of beads. You are watching the physics solver hold those pin constraints together every fixed step.

It is a rope with give in it, and how much depends on which solver the scene resolves. The pure-Python builtin (the fallback when pymunk is not installed) runs a handful of impulse iterations and a soft positional bias per step, which a six-link chain pulling at 1200 px/s^2 stretches faster than the bias drains: a second in, the tip already hangs 312 px below an anchor 300 px of chain away from it, and left hanging it settles there, with its worst link 7.0% long. The optional pymunk backend (PhysicsRoot2D(backend="pymunk"), and the default whenever pymunk is importable) hangs the same chain on its rest length, tip at 300 px.

The self-check below kicks the chain and prints the worst link it sees while the chain hangs and while it swings. Forcing each backend in turn, it is 10.8% on the builtin against 12.6% on pymunk, so the swing peak is very nearly a wash: the two solvers differ on the hang, not on the worst instant of a kick. What separates them is what happens next. pymunk’s stretch recedes (0.3% hanging, 14.2% at the peak, 1.7% thirty frames later) while the builtin’s does not (7.0%, 8.9%, and still 8.9% thirty frames later), and that residual is a known defect rather than a solver budget: see BUGS.md for the awake builtin solver that never drains. Running the example plainly measures whichever backend resolved, so read the backend: line the self-check prints rather than assuming.

The sag is a solver budget rather than a property of the model, and the world says how big that budget is. world.position_iterations is the number of position passes a step makes over the joints, and pressing I cycles it: on the builtin the same six-link chain settles with its worst link 10.3% long at the default 3 and 0.8% at 32, for a step that costs proportionally more. pymunk ignores it – Chipmunk has no position solver, which is exactly why its chain hangs on its rest length to begin with.

What does NOT depend on the solver is where the pivot is: each pin is held in the frame of the body carrying it, so it goes where that body goes.

What it demonstrates

• PhysicsBody2D(DYNAMIC): a dynamic body that gravity and forces act on.

• PhysicsBody2D(STATIC): an immovable body used as the fixed anchor at the top.

• PinJoint2D: pins two bodies at a single world point; they cannot separate there but rotate freely about it (chain them to build a rope).

• The Physics2DWorld solves every joint automatically: you only declare the constraints, you never integrate or correct positions by hand.

• Click-to-interact: a left click kicks the bottom ball away from the cursor so you can set the whole chain swinging.

• Physics2DWorld.position_iterations: the world’s joint-convergence dial, live on a key, with the chain’s sag as the observable.

Controls

LMB Kick the bottom ball away from the mouse I Cycle world.position_iterations: 3 / 8 / 32 (watch the chain tighten) R Reset the chain to its hanging start position ESC Quit

Run: uv run python examples/features/2d/joints.py Headless self-check: uv run python examples/features/2d/joints.py –test

Source

"""2D Joints: a swinging pendulum chain built from PinJoint2D constraints.

A line of dynamic balls hangs from a fixed anchor at the top of the screen.
Each ball is pinned to the one above it, so the whole chain swings and settles
under gravity like a rope of beads. You are watching the physics solver hold
those pin constraints together every fixed step.

It is a rope with give in it, and how much depends on which solver the scene
resolves. The pure-Python builtin (the fallback when pymunk is not installed)
runs a handful of impulse iterations and a soft positional bias per step, which a
six-link chain pulling at 1200 px/s^2 stretches faster than the bias drains: a
second in, the tip already hangs 312 px below an anchor 300 px of chain away from
it, and left hanging it settles there, with its worst link 7.0% long. The
optional pymunk backend (``PhysicsRoot2D(backend="pymunk")``, and the default
whenever pymunk is importable) hangs the same chain on its rest length, tip at
300 px.

The self-check below kicks the chain and prints the worst link it sees while the
chain hangs and while it swings. Forcing each backend in turn, it is 10.8% on the
builtin against 12.6% on pymunk, so the swing peak is very nearly a wash: the two
solvers differ on the *hang*, not on the worst instant of a kick. What separates
them is what happens next. pymunk's stretch recedes (0.3% hanging, 14.2% at the
peak, 1.7% thirty frames later) while the builtin's does not (7.0%, 8.9%, and
still 8.9% thirty frames later), and that residual is a known defect rather than
a solver budget: see ``BUGS.md`` for the awake builtin solver that never drains.
Running the example plainly measures whichever backend resolved, so read the
``backend:`` line the self-check prints rather than assuming.

The *sag* is a solver budget rather than a property of the model, and the world
says how big that budget is. ``world.position_iterations`` is the number of
position passes a step makes over the joints, and pressing ``I`` cycles it: on
the builtin the same six-link chain settles with its worst link 10.3% long at the
default ``3`` and 0.8% at ``32``, for a step that costs proportionally more.
pymunk ignores it -- Chipmunk has no position solver, which is exactly why its
chain hangs on its rest length to begin with.

What does NOT depend on the solver is where the pivot is: each pin is held in the
frame of the body carrying it, so it goes where that body goes.

# /// simvx
# tags = ["2d", "physics", "joints", "constraints"]
# web = { root = "PendulumChain", width = 800, height = 600 }
# ///

## What it demonstrates
  - PhysicsBody2D(DYNAMIC): a dynamic body that gravity and forces act on.
  - PhysicsBody2D(STATIC): an immovable body used as the fixed anchor at the top.
  - PinJoint2D: pins two bodies at a single world point; they cannot separate
    there but rotate freely about it (chain them to build a rope).
  - The Physics2DWorld solves every joint automatically: you only declare the
    constraints, you never integrate or correct positions by hand.
  - Click-to-interact: a left click kicks the bottom ball away from the cursor
    so you can set the whole chain swinging.
  - Physics2DWorld.position_iterations: the world's joint-convergence dial, live
    on a key, with the chain's sag as the observable.

## Controls
  LMB   Kick the bottom ball away from the mouse
  I     Cycle world.position_iterations: 3 / 8 / 32 (watch the chain tighten)
  R     Reset the chain to its hanging start position
  ESC   Quit

Run: uv run python examples/features/2d/joints.py
Headless self-check: uv run python examples/features/2d/joints.py --test
"""

from simvx.core import (
    BodyMode,
    CircleShape2D,
    Input,
    InputMap,
    Key,
    MouseButton,
    Node2D,
    PhysicsBody2D,
    PhysicsRoot2D,
    PinJoint2D,
    Vec2,
)
from simvx.graphics import App

WIDTH, HEIGHT = 800, 600
CHAIN_LENGTH = 6
LINK_SPACING = 50.0
BALL_RADIUS = 10.0
ANCHOR = Vec2(WIDTH / 2, 100)
# Y-down world (gravity = +Y) so the chain hangs downward on screen.
GRAVITY = Vec2(0.0, 1200.0)
#: The joint-convergence settings the I key cycles. The first is the seam default.
POSITION_PASSES = (3, 8, 32)


class PendulumChain(Node2D):
    """A chain of PhysicsBody2D nodes connected by PinJoint2D constraints."""

    dynamic = True  # the chain swings every frame (physics body positions)

    def on_ready(self):
        InputMap.add_action("apply_force", [MouseButton.LEFT])
        InputMap.add_action("reset_chain", [Key.R])
        InputMap.add_action("tighten", [Key.I])
        InputMap.add_action("quit", [Key.ESCAPE])
        self._passes_i = 0

        self._root = self.add_child(PhysicsRoot2D(name="World", gravity=GRAVITY))

        # Fixed anchor (static body). Disjoint collision masks across the chain
        # so the beads never collide as circles: only the pins act.
        self._anchor = PhysicsBody2D(
            name="Anchor",
            mode=BodyMode.STATIC,
            position=Vec2(ANCHOR.x, ANCHOR.y),
            collision_layer=0x1,
            collision_mask=0x0,
            shape=CircleShape2D(8.0),
        )
        self._root.add_child(self._anchor)

        # Chain of dynamic bodies, pinned to the one above at the upper pivot.
        self._balls: list[PhysicsBody2D] = []
        self._start_positions: list[Vec2] = []
        prev = self._anchor
        prev_pos = Vec2(ANCHOR.x, ANCHOR.y)
        for i in range(CHAIN_LENGTH):
            pos = Vec2(ANCHOR.x, ANCHOR.y + LINK_SPACING * (i + 1))
            body = PhysicsBody2D(
                name=f"Ball{i}",
                mode=BodyMode.DYNAMIC,
                mass=1.0,
                position=pos,
                collision_layer=0x1,
                collision_mask=0x0,
                shape=CircleShape2D(BALL_RADIUS),
            )
            self._root.add_child(body)
            self._balls.append(body)
            self._start_positions.append(pos)
            # Pin this body to the previous one at the previous body's pivot.
            self._root.add_child(PinJoint2D(body_a=prev, body_b=body, anchor=prev_pos))
            prev = body
            prev_pos = pos

    def _worst_link(self) -> float:
        """How far the most stretched link is from its rest length, in pixels."""
        points = [self._anchor.world_position] + [b.world_position for b in self._balls]
        worst = 0.0
        for a, b in zip(points, points[1:], strict=False):
            gap = ((b.x - a.x) ** 2 + (b.y - a.y) ** 2) ** 0.5
            worst = max(worst, abs(gap - LINK_SPACING))
        return worst

    def _reset(self):
        """Hang the chain back up exactly as it was authored.

        Rotation and spin are part of that, not decoration: a pin's anchor is
        held in the frame of the body carrying it, so a bead left rotated from
        the swing puts its pivot somewhere the rest pose does not have it, and
        the chain settles crooked from a reset that looks complete. The rig
        authors every bead upright, which is what makes zero the right value
        here rather than something to capture.
        """
        for body, pos in zip(self._balls, self._start_positions, strict=True):
            body.position = Vec2(pos.x, pos.y)
            body.velocity = Vec2()
            body.rotation = 0.0
            body.spin = 0.0

    def on_update(self, dt: float):
        if Input.is_action_just_pressed("quit"):
            self.app.quit()
            return
        if Input.is_action_just_pressed("reset_chain"):
            self._reset()
            return
        if Input.is_action_just_pressed("tighten"):
            self._passes_i = (self._passes_i + 1) % len(POSITION_PASSES)
            self._root.world_2d.position_iterations = POSITION_PASSES[self._passes_i]
            return
        if Input.is_action_just_pressed("apply_force"):
            # Kick the bottom ball away from the mouse (set its velocity directly).
            p = self._balls[-1].world_position
            mouse = Input.mouse_position
            dx, dy = p.x - mouse.x, p.y - mouse.y
            dist = max((dx * dx + dy * dy) ** 0.5, 1.0)
            speed = 600.0
            self._balls[-1].velocity = Vec2(dx / dist * speed, dy / dist * speed)

    def on_draw(self, renderer):
        # Lines between links.
        link_colour = (0.6, 0.6, 0.7, 1.0)
        anchor_pos = self._anchor.world_position
        if self._balls:
            renderer.draw_line(anchor_pos, self._balls[0].world_position, colour=link_colour)
        for i in range(len(self._balls) - 1):
            renderer.draw_line(self._balls[i].world_position, self._balls[i + 1].world_position, colour=link_colour)

        # Anchor.
        renderer.draw_circle(anchor_pos, 8, colour=(1.0, 0.3, 0.3, 1.0), filled=True)

        # Balls (gradient).
        for i, body in enumerate(self._balls):
            t = i / max(1, CHAIN_LENGTH - 1)
            colour = (0.3 + 0.5 * (1 - t), 0.6 + 0.3 * (1 - t), 1.0, 1.0)
            renderer.draw_circle(body.world_position, BALL_RADIUS, colour=colour, filled=True)

        # HUD.
        renderer.draw_text("Pendulum Chain -- PinJoint2D Demo", (10, 10), colour=(1.0, 1.0, 1.0), scale=2)
        renderer.draw_text("LMB: kick | I: position passes | R: reset | ESC: quit", (10, 50), colour=(0.71, 0.71, 0.71))
        worst = self._worst_link()
        renderer.draw_text(
            f"position_iterations {self._root.world_2d.position_iterations} | "
            f"worst link {worst / LINK_SPACING * 100:.1f}% long",
            (10, 74),
            colour=(0.71, 0.71, 0.71),
        )


#: How far a loaded link may stretch before the pin counts as having let go.
#: Calibrated to the LOOSEST solver the scene can resolve. Across the hang and
#: the kicked swing below, the pure-Python builtin's worst link reaches 10.8% and
#: pymunk's 12.6%, so neither is reliably the looser one and the bar has to clear
#: both. The measured figure is printed so a reader can see which they got.
#: Judging by a number one backend cannot make would fail a clean install.
MAX_STRETCH = 0.25


def _selftest() -> bool:
    """Headless: let the chain hang, kick it with a real click, and watch the pins.

    Every link separation is measured on every frame rather than sampled, so a
    constraint that holds while hanging and lets go under load cannot slip past.
    The stretch bounds are the solver's; the SHAPE of the hang -- straight down,
    the tip at the end of the chain, the anchor immovable -- is not, and is
    judged tightly.
    """
    from simvx.core.testing import InputSimulator
    from simvx.graphics.testing import assert_not_blank, save_png

    HUNG = 60  # the chain has settled straight down
    KICK = 70  # a left click, from off to the left of the chain
    #: The kick is an instantaneous 600px/s on one bead, which the iterative solver
    #: cannot satisfy in a single step: the bottom link stretches and comes back
    #: over the following few frames. Links are judged outside that recovery window,
    #: and the stretch inside it is bounded and watched receding separately.
    RECOVERED = KICK + 30
    RESET = 250
    RESET_SEEN = 251
    #: The chain has re-hung at the DEFAULT dial by here, so this is the sag the
    #: knob is judged against.
    DEFAULT_SETTLED = 300
    #: Two presses of I take position_iterations from 3 to 32, and the chain is
    #: given as long again to settle on the tighter budget.
    TIGHTEN = 310
    TIGHTENED_SETTLED = 410
    FRAMES = 420
    MOUSE = (100.0, 400.0)

    app = App(title="Joints2D", width=WIDTH, height=HEIGHT, visible=False)
    scene = PendulumChain(name="PendulumChain")
    sim = InputSimulator()
    seen: dict[str, object] = {}
    hang_link = 0.0  # largest separation error while the chain just hangs
    kick_link = 0.0  # and inside the kick's recovery window
    swing_link = 0.0  # and afterwards, while it swings freely
    settled_link = 0.0  # the error on the single frame the window closes on
    anchor_drift = 0.0
    swing = 0.0  # how far the tip ever travelled sideways from under the anchor

    def separations() -> list[float]:
        points = [scene._anchor.world_position] + [b.world_position for b in scene._balls]
        return [float((points[i + 1] - points[i]).length()) for i in range(len(points) - 1)]

    def on_frame(idx: int, _t: float) -> bool:
        nonlocal hang_link, kick_link, swing_link, settled_link, anchor_drift, swing
        error = max(abs(s - LINK_SPACING) for s in separations())
        # Three windows, kept apart so the kick can be judged against what the chain
        # held before it and what it holds after: the kick and the reset are both
        # instantaneous teleports, and the frames right after them are not the
        # frames that say whether a pin holds.
        if idx < KICK:
            hang_link = max(hang_link, error)
        elif idx < RECOVERED:
            kick_link = max(kick_link, error)
        elif idx < DEFAULT_SETTLED:
            swing_link = max(swing_link, error)
        if idx == RECOVERED:
            settled_link = error
        anchor_drift = max(anchor_drift, float((scene._anchor.world_position - ANCHOR).length()))
        swing = max(swing, abs(float(scene._balls[-1].world_position.x) - ANCHOR.x))

        if idx == DEFAULT_SETTLED:
            seen["default_sag"] = error
        elif idx == TIGHTENED_SETTLED:
            seen["tight_sag"] = error
            seen["passes"] = scene._root.world_2d.position_iterations

        if idx == HUNG:
            seen["hung"] = [tuple(float(v) for v in b.world_position) for b in scene._balls]
        elif idx == KICK:
            # The kick reads Input.mouse_position, so the cursor has to be somewhere
            # before the button goes down.
            sim.move_mouse(*MOUSE)
            sim.press_mouse(MouseButton.LEFT)
        elif idx == KICK + 1:
            sim.release_mouse(MouseButton.LEFT)
            seen["kick"] = tuple(float(v) for v in scene._balls[-1].velocity)
        elif idx == RESET:
            sim.press_key(Key.R)
        elif idx == RESET + 1:
            sim.release_key(Key.R)
        elif idx == RESET_SEEN + 1:
            seen["reset"] = [tuple(float(v) for v in b.world_position) for b in scene._balls]
        elif idx in (TIGHTEN, TIGHTEN + 2):
            sim.press_key(Key.I)
        elif idx in (TIGHTEN + 1, TIGHTEN + 3):
            sim.release_key(Key.I)
        return True

    frames = app.run_headless(scene, frames=FRAMES, on_frame=on_frame, capture_frames=[FRAMES - 1])
    assert_not_blank(frames[0])
    save_png(frames[0], "/tmp/joints2d_test.png")

    # Which solver these numbers came from. Every figure below is the resolved
    # backend's, and the resolution is by precedence, so a reader who does not
    # print this cannot tell whether an optional accelerator answered.
    print(f"backend: {type(scene._root.world_2d).__name__}")

    ok = True

    def check(label: str, passed: bool, detail: str) -> None:
        nonlocal ok
        ok = ok and passed
        print(f"{'ok  ' if passed else 'FAIL'} {label}: {detail}")

    # Hanging STRAIGHT down: every bead directly under the anchor, whatever the
    # solver's stretch does to how far down each of them ends up. This one is the
    # pins' doing and nothing else's, so it is judged to the pixel.
    hung = seen["hung"]
    lean = max(abs(x - ANCHOR.x) for x, _ in hung)
    check("the chain hangs straight below the anchor", lean < 1.0, f"worst bead leans {lean:.3f}px off centre")

    # And in order, each bead below the last, with the tip the chain's length down
    # give or take the stretch the solver settles at.
    nominal = CHAIN_LENGTH * LINK_SPACING
    drop = hung[-1][1] - ANCHOR.y
    descends = all(hung[i][1] < hung[i + 1][1] for i in range(CHAIN_LENGTH - 1))
    check(
        "and hangs its full length, in order",
        descends and nominal * 0.99 <= drop < nominal * (1.0 + MAX_STRETCH),
        f"the tip is {drop:.1f} below the anchor (the chain is {nominal:.0f} long)",
    )

    # The click kicks the bottom bead directly away from the cursor.
    vx, vy = seen["kick"]
    tip_x, tip_y = hung[-1]
    away = (tip_x - MOUSE[0]) * vx + (tip_y - MOUSE[1]) * vy
    check(
        "a left click kicks the bottom bead away from the cursor",
        away > 0 and abs((vx * vx + vy * vy) ** 0.5 - 600.0) < 1.0,
        f"velocity {vx:.0f},{vy:.0f} pointing away from the cursor: {away > 0}",
    )
    check("the kick sets the whole chain swinging", swing > 100.0, f"the tip swung {swing:.0f}px off centre")

    # The point of the demo: the solver holds every pin through that swing, without
    # the scene correcting a single position by hand. An unpinned bead would have
    # fallen off the bottom of the screen in the same time.
    worst_link = max(hang_link, swing_link)
    check(
        "every pin holds while the chain hangs and swings",
        worst_link < LINK_SPACING * MAX_STRETCH,
        f"worst link was {worst_link:.3f} off {LINK_SPACING:.0f} ({worst_link / LINK_SPACING * 100:.1f}%)",
    )
    # The kick is the hardest thing the constraint is asked to absorb: it stretches
    # a link beyond anything the hanging chain does, the stretch stays bounded, and
    # it is already receding by the time the window closes. How much of it has come
    # back by then is the solver's business, and printed rather than judged.
    check(
        "the kick stretches a link, and the stretch is bounded and recedes",
        kick_link > hang_link and kick_link < LINK_SPACING * (MAX_STRETCH + 0.05) and settled_link < kick_link,
        f"{hang_link / LINK_SPACING * 100:.1f}% hanging, {kick_link / LINK_SPACING * 100:.1f}% at its worst"
        f" during the kick, {settled_link / LINK_SPACING * 100:.1f}% {RECOVERED - KICK} frames later",
    )
    check("the static anchor never moved", anchor_drift < 0.001, f"largest movement {anchor_drift:.6f}")

    # R puts every bead back where it started. One physics step runs between the
    # reset and this reading, so the beads have begun to fall again by a hair.
    reset_error = max(abs(reset[1] - (ANCHOR.y + LINK_SPACING * (i + 1))) for i, reset in enumerate(seen["reset"]))
    check("R hangs the chain back up", reset_error < 3.0, f"worst bead is {reset_error:.3f} off its start")

    # And the dial the I key drives. What every backend owes is that spending more
    # of the budget never costs slack, which is what is judged; how much it BUYS is
    # the solver's, and printed. The builtin prints about 10.3% against 0.8%, which
    # is the knob doing real work. pymunk prints about 1.3% against 0.3%, and that
    # is the chain settling rather than the knob: Chipmunk has no position pass to
    # spend it on, and hangs the chain near its rest length regardless. The
    # measured pair says which backend resolved the scene.
    default_sag, tight_sag = float(seen["default_sag"]), float(seen["tight_sag"])
    check(
        "the I key reaches the world, and more position passes never loosen the chain",
        seen["passes"] == POSITION_PASSES[-1] and tight_sag <= default_sag + 1e-3,
        f"{default_sag / LINK_SPACING * 100:.1f}% at {POSITION_PASSES[0]} passes, "
        f"{tight_sag / LINK_SPACING * 100:.1f}% at {seen['passes']}",
    )

    print("screenshot: /tmp/joints2d_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(title="2D Joints -- Pendulum Chain", width=WIDTH, height=HEIGHT).run(PendulumChain())