3D Joints¶

A pinned chain and a hinged door, built from PinJoint3D and HingeJoint3D.

Tags: 3d

Demonstrates:

PinJoint3D: a chain of PhysicsBody3D(DYNAMIC) spheres held at a fixed separation from the one above, hanging off a static anchor
HingeJoint3D: a door panel that turns about a vertical axis when shoved, and stays upright while it turns
PhysicsBody3D(STATIC) as the fixed anchor and hinge post: the solver reads them and never writes them, so neither ever moves
The PhysicsWorld solves every constraint automatically each fixed step

What the default backend gives you: this scene builds its PhysicsRoot without naming a backend, and a gameplay-affecting 3D solver is never picked up just by being installed – it stays name-addressable. So unless something names a 3D-capable backend explicitly (PhysicsRoot(backend=...), or the physics_backend project setting) the scene runs on the builtin solver. Both joints hold their pivot in the frame of the body carrying it, which is what makes the two behave the way their shapes suggest:

the chain swings. The 4 m/s sideways kick the top bead is given in on_ready carries it through an arc 0.65 units wide over the first four seconds, the beads below taking enough of the energy to halve that arc by the third second.
the pushed door orbits the post rather than turning about its own centre. It reaches 179 deg, and its centre sweeps the full half-circle round the hinge (x 3.00..5.00, z -1.00..1.00).

Installing simvx-physics-jolt and building the root as PhysicsRoot(name="World", backend="jolt") changes the residue rather than the behaviour: the same door sweeps the same half-circle, and the same kick opens the chain’s arc to 0.87 units, because Jolt carries a real inertia tensor where the pure-Python solver stands in the inverse mass for it and converges in fewer iterations.

Controls: Space or click - Push the door Left/Right keys or horizontal drag - Orbit camera R - Reset scene Escape - Quit

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

Source¶

"""3D Joints: A pinned chain and a hinged door, built from PinJoint3D and HingeJoint3D.

# /// simvx
# web = { width = 1280, height = 720 }
# ///

Demonstrates:
  - PinJoint3D: a chain of PhysicsBody3D(DYNAMIC) spheres held at a fixed
    separation from the one above, hanging off a static anchor
  - HingeJoint3D: a door panel that turns about a vertical axis when shoved,
    and stays upright while it turns
  - PhysicsBody3D(STATIC) as the fixed anchor and hinge post: the solver reads
    them and never writes them, so neither ever moves
  - The PhysicsWorld solves every constraint automatically each fixed step

What the default backend gives you: this scene builds its ``PhysicsRoot`` without
naming a backend, and a gameplay-affecting 3D solver is never picked up just by
being installed -- it stays name-addressable. So unless something names a
3D-capable backend explicitly (``PhysicsRoot(backend=...)``, or the
``physics_backend`` project setting) the scene runs on the builtin solver. Both
joints hold their pivot in the frame of the body carrying it, which is what makes
the two behave the way their shapes suggest:

  - the chain swings. The 4 m/s sideways kick the top bead is given in
    ``on_ready`` carries it through an arc 0.65 units wide over the first four
    seconds, the beads below taking enough of the energy to halve that arc by the
    third second.
  - the pushed door orbits the post rather than turning about its own centre. It
    reaches 179 deg, and its centre sweeps the full half-circle round the hinge
    (x 3.00..5.00, z -1.00..1.00).

Installing ``simvx-physics-jolt`` and building the root as
``PhysicsRoot(name="World", backend="jolt")`` changes the residue rather than the
behaviour: the same door sweeps the same half-circle, and the same kick opens the
chain's arc to 0.87 units, because Jolt carries a real inertia tensor where the
pure-Python solver stands in the inverse mass for it and converges in fewer
iterations.

Controls:
    Space or click  - Push the door
    Left/Right keys or horizontal drag - Orbit camera
    R               - Reset scene
    Escape          - Quit

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

import math

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

CHAIN_LEN = 4
LINK_DIST = 1.2


class JointsDemo(Node):
    input_actions = {
        "push_door": [Key.SPACE],
        "reset": [Key.R],
        "orbit_left": [Key.LEFT],
        "orbit_right": [Key.RIGHT],
        "quit": [Key.ESCAPE],
    }

    def on_ready(self):
        # One isolated 3D world (Y-up, default gravity).
        self._root = self.add_child(PhysicsRoot(name="World"))

        # Camera
        self._cam = self.add_child(
            Camera3D(
                name="Camera",
                position=Vec3(0, 4, 14),
                look_at=Vec3(0, 2, 0),
                fov=55.0,
            )
        )
        self._orbit = 0.0
        self._drag_dist = 0.0

        # Light
        light = self.add_child(DirectionalLight3D(name="Sun"))
        light.look_at(Vec3(-1, -2, -1))

        # Ground (visual only)
        ground = self.add_child(MeshInstance3D(name="Ground", mesh=Mesh.cube()))
        ground.material = Material(colour=(0.3, 0.35, 0.3), roughness=0.9)
        ground.scale = Vec3(20, 0.1, 20)
        ground.position = Vec3(0, -0.05, 0)

        # --- Pendulum chain (left side) ---
        anchor_pos = Vec3(-4.0, 6.0, 0.0)

        # Fixed anchor (static body). Disjoint mask so beads never self-collide.
        self._chain_anchor = self._make_body(
            "ChainAnchor",
            BodyMode.STATIC,
            anchor_pos,
            radius=0.15,
            colour=(1.0, 0.3, 0.3, 1.0),
            mask=0x0,
        )

        # Chain bodies, each pinned to the one above at the upper pivot.
        self._chain_bodies: list[PhysicsBody3D] = []
        self._chain_start: list[Vec3] = []
        prev = self._chain_anchor
        prev_pos = anchor_pos
        for i in range(CHAIN_LEN):
            pos = Vec3(anchor_pos.x, anchor_pos.y - LINK_DIST * (i + 1), anchor_pos.z)
            body = self._make_body(
                f"ChainBody{i}",
                BodyMode.DYNAMIC,
                pos,
                radius=0.25,
                colour=(0.3, 0.6, 1.0, 1.0),
                mask=0x0,
            )
            self._chain_bodies.append(body)
            self._chain_start.append(pos)
            self._root.add_child(PinJoint3D(body_a=prev, body_b=body, anchor=prev_pos))
            prev = body
            prev_pos = pos

        # Give the first ball a sideways kick so the chain swings.
        self._chain_bodies[0].velocity = Vec3(4.0, 0, 0)

        # Anchor post (visual only)
        post = self.add_child(MeshInstance3D(name="AnchorPost", mesh=Mesh.cylinder(radius=0.08, height=1.0)))
        post.material = Material(colour=(0.5, 0.5, 0.5), roughness=0.6)
        post.position = Vec3(anchor_pos.x, anchor_pos.y + 0.5, anchor_pos.z)

        # --- Hinge door (right side) ---
        hinge_pos = Vec3(4, 2, 0)

        # Door post (static body at the hinge position).
        self._door_post = self._make_body(
            "DoorPostBody",
            BodyMode.STATIC,
            hinge_pos,
            radius=0.12,
            colour=(0.6, 0.6, 0.6, 1.0),
            mask=0x0,
            visible=False,
        )

        # Door body (dynamic, offset from the hinge), a box panel.
        self._door_start = Vec3(hinge_pos.x + 1.0, hinge_pos.y, hinge_pos.z)
        self._door_body = PhysicsBody3D(
            name="DoorBody",
            mode=BodyMode.DYNAMIC,
            mass=5.0,
            position=self._door_start,
            collision_mask=0x0,
        )
        self._door_body.add_child(CollisionShape3D(shape=BoxShape3D(half_extents=Vec3(1.0, 1.75, 0.06))))
        self._door_body.add_child(
            MeshInstance3D(
                name="DoorVis",
                mesh=Mesh.cube(),
                material=Material(colour=(0.7, 0.4, 0.15), roughness=0.6),
                scale=Vec3(2.0, 3.5, 0.12),
            )
        )
        self._root.add_child(self._door_body)

        # Hinge joint -- rotates about the vertical Y axis at the hinge pivot.
        self._root.add_child(
            HingeJoint3D(
                body_a=self._door_post,
                body_b=self._door_body,
                anchor=hinge_pos,
                axis=Vec3(0, 1, 0),
            )
        )

        # Door post visual.
        dp = self.add_child(MeshInstance3D(name="DoorPost", mesh=Mesh.cylinder(radius=0.1, height=4.0)))
        dp.material = Material(colour=(0.6, 0.6, 0.6), roughness=0.5)
        dp.position = hinge_pos

        # HUD
        self.add_child(
            Text2D(
                name="HUD",
                text="3D Joints: Space/click=push door | arrows/drag=orbit | R=reset | ESC=quit",
                position=(10, 10),
                font_scale=1.2,
            )
        )

    def _make_body(self, name, mode, pos, *, radius, colour, mask, visible=True):
        """Build a sphere PhysicsBody3D with a collider + visual, add to the world."""
        body = PhysicsBody3D(name=name, mode=mode, mass=1.0, position=pos, collision_mask=mask)
        body.add_child(CollisionShape3D(shape=SphereShape3D(radius=radius)))
        if visible:
            body.add_child(
                MeshInstance3D(
                    mesh=Mesh.sphere(radius=radius),
                    material=Material(colour=colour, roughness=0.3, metallic=0.5),
                )
            )
        self._root.add_child(body)
        return body

    def _reset(self):
        # A full pose reset is four writes per body: position and rotation put the
        # node back (each assignment teleports the simulated body), velocity and
        # spin clear the momentum the solver would otherwise keep integrating.
        for body, pos in zip(self._chain_bodies, self._chain_start, strict=True):
            body.position = Vec3(pos.x, pos.y, pos.z)
            body.rotation = Quat()
            body.velocity = Vec3()
            body.spin = Vec3()
        self._chain_bodies[0].velocity = Vec3(4.0, 0, 0)
        self._door_body.position = Vec3(self._door_start.x, self._door_start.y, self._door_start.z)
        self._door_body.rotation = Quat()
        self._door_body.velocity = Vec3()
        self._door_body.spin = Vec3()

    def on_update(self, dt: float):
        if Input.is_action_just_pressed("quit"):
            self.app.quit()
            return
        if Input.is_action_just_pressed("reset"):
            self._reset()

        push_door = Input.is_action_just_pressed("push_door")

        # Mouse/touch: horizontal drag orbits, a tap (click without dragging) pushes the door.
        if Input.is_mouse_button_pressed(MouseButton.LEFT):
            dx = float(Input.mouse_delta.x)
            self._drag_dist += abs(dx)
            self._orbit -= dx * 0.005
        if Input.is_mouse_button_just_released(MouseButton.LEFT):
            push_door = push_door or self._drag_dist < 6.0
            self._drag_dist = 0.0

        # Push door: give it a sideways shove (the hinge converts it to swing).
        if push_door:
            self._door_body.velocity = Vec3(0, 0, 6.0)

        # Camera orbit
        if Input.is_action_pressed("orbit_left"):
            self._orbit -= 1.5 * dt
        if Input.is_action_pressed("orbit_right"):
            self._orbit += 1.5 * dt
        r = 14.0
        self._cam.position = Vec3(math.sin(self._orbit) * r, 4, math.cos(self._orbit) * r)
        self._cam.look_at(Vec3(0, 2, 0))


def _selftest() -> bool:
    """Headless: run the real scene offscreen and check what its joints claim to do.

    One offscreen pass with the door pushed through the same named action a player
    presses, so the constraint solve is reached the way the demo reaches it. Frames
    are 1/60 s. Every quantity is sampled on every frame rather than at the end, so
    a constraint that holds for a while and then lets go fails here instead of
    being stepped over.
    """
    from simvx.core.testing import InputSimulator
    from simvx.graphics.testing import assert_not_blank, save_png

    PUSH = 90  # by now the chain has settled, and the door has never been touched
    RESET = 200  # R, once the door has swung well past a right angle
    FRAMES = 220

    app = App(title="3D Joints", width=1280, height=720, visible=False)
    scene = JointsDemo(name="JointsDemo")
    sim = InputSimulator()

    # How far the tip hangs when every pin in the chain holds its rest separation.
    chain_span = CHAIN_LEN * LINK_DIST

    links: list[float] = []  # separation of each consecutive pinned pair
    drops: list[float] = []  # how far the last bead hangs below the anchor
    radii: list[float] = []  # door centre to hinge post
    sweep: list[tuple[float, float]] = []  # where the door's centre sat, in x and z
    kicked: list[float] = []  # the top bead's x, which the on_ready kick sets swinging
    sags: list[float] = []  # how far the door has dropped relative to its hinge
    uprights: list[float] = []  # the door's own up axis, projected onto world up
    turns: list[float] = []  # the door's swing about the hinge axis, in degrees
    strays: list[float] = []  # how far either static body has moved since it was built
    homes: dict[str, tuple[float, ...]] = {}
    restored: dict[str, object] = {}

    def where(node: PhysicsBody3D) -> tuple[float, ...]:
        return tuple(float(v) for v in node.position)

    def apart(a: tuple[float, ...], b: tuple[float, ...]) -> float:
        return max(abs(u - v) for u, v in zip(a, b, strict=True))

    def on_frame(idx: int, _t: float) -> bool:
        anchor, post, door = scene._chain_anchor, scene._door_post, scene._door_body
        if idx == 0:
            homes["anchor"], homes["post"] = where(anchor), where(post)

        previous = anchor.position
        for bead in scene._chain_bodies:
            links.append(float((bead.position - previous).length()))
            previous = bead.position
        drops.append(float(anchor.position.y - scene._chain_bodies[-1].position.y))
        strays.append(max(apart(where(anchor), homes["anchor"]), apart(where(post), homes["post"])))

        # The door's own axes turned into world space: where its face points (the
        # swing) and where its top points, which the hinge's angular lock holds at
        # world up so that turning about the hinge axis is the only freedom left.
        facing = door.rotation * Vec3(1.0, 0.0, 0.0)
        radii.append(float((door.position - post.position).length()))
        sweep.append((float(door.position.x), float(door.position.z)))
        kicked.append(float(scene._chain_bodies[0].position.x))
        sags.append(abs(float(door.position.y - post.position.y)))
        uprights.append(float((door.rotation * Vec3(0.0, 1.0, 0.0)).y))
        turns.append(math.degrees(math.atan2(float(facing.z), float(facing.x))))

        if idx == PUSH:
            sim.press_key(Key.SPACE)
        elif idx == PUSH + 1:
            sim.release_key(Key.SPACE)
        elif idx == RESET:
            sim.press_key(Key.R)
        elif idx == RESET + 1:
            # on_frame runs before the tick, so the R pressed on the frame before
            # has already been read: this samples the scene just after the reset.
            sim.release_key(Key.R)
            restored["chain"] = [where(b) for b in scene._chain_bodies]
            restored["door"] = where(door)
            restored["turn"] = turns[-1]
        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/joints3d_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).__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}")

    # Each PinJoint3D holds its pair at the separation it was built with. The beads
    # are ordinary dynamic bodies with nothing underneath them, so the separation is
    # the constraint and nothing else; the residue is the solver's own softness.
    worst_link = max(abs(d - LINK_DIST) for d in links)
    check(
        "every pinned link keeps its rest separation",
        worst_link < LINK_DIST * 0.05,
        f"worst link is {worst_link:.4f} off {LINK_DIST} ({worst_link / LINK_DIST * 100:.1f}%)",
    )

    # And the chain hangs from its anchor rather than falling away from it: the tip
    # stays inside the reach the pins give it for the whole run, where an unpinned
    # bead would have dropped tens of metres in the same time.
    check(
        "the chain hangs its full length below the static anchor",
        chain_span * 0.9 < min(drops) and max(drops) < chain_span * 1.05,
        f"tip hangs {min(drops):.3f}..{max(drops):.3f} below it (the chain is {chain_span:.1f} long)",
    )

    # Both ends of the demo are pinned to STATIC bodies, which the simulation reads
    # and never writes: they hold whatever the scene built them at.
    check("the static anchor and hinge post never move", max(strays) == 0.0, f"largest movement {max(strays):.6f}")

    # Nothing touched the door before the push, so anything it does afterwards is
    # the push's doing rather than gravity's or the solver's.
    still = max(abs(t) for t in turns[: PUSH + 1])
    check("the door hangs still until it is pushed", still < 0.001, f"turned {still:.6f} deg before the push")

    # The chain is a pendulum, not a rod: the kick the top bead is given in
    # on_ready traces an arc, rather than nudging a chain frozen where it was
    # built. Four seconds, before the beads below have taken the energy out of it.
    arc = max(kicked[: 4 * 60]) - min(kicked[: 4 * 60])
    check("the kicked chain swings rather than hanging rigid", arc > 0.4, f"the top bead's arc is {arc:.3f} wide")

    # A hinge is a pin plus an angular lock that removes the two off-axis rotational
    # freedoms, so a sideways shove turns the panel about the hinge axis and about
    # no other: its own up axis never leaves world up.
    swung = max(abs(t) for t in turns)
    check("the pushed door swings past a right angle", swung > 90.0, f"reached {swung:.1f} deg from its closed face")
    off_axis = max(abs(1.0 - u) for u in uprights)
    check(
        "it turns about the hinge axis and no other",
        off_axis < 1e-3,
        f"the door's up axis is {off_axis:.2e} off world up at worst",
    )

    # The pin half holds the panel on its post throughout: a 6 m/s shove neither
    # carries it off along the shove nor drops it off the hinge, where a free body
    # would have travelled metres in each direction.
    swing_radius = max(abs(r - radii[0]) for r in radii)
    check(
        "the door stays hung on its hinge post",
        swing_radius < 0.02 and max(sags) < 0.02,
        f"hinge radius moved {swing_radius:.4f} and the door sagged {max(sags):.4f}",
    )

    # And it goes ROUND the post rather than turning on the spot: the hinge holds
    # its anchor in the post's frame, so the panel's centre sweeps the half circle
    # its 179 deg of turn implies (the post is at x = 4, z = 0, one unit away).
    xs = [x for x, _ in sweep]
    zs = [z for _, z in sweep]
    check(
        "and its centre orbits the post through the half-circle",
        max(xs) - min(xs) > 1.9 and max(zs) - min(zs) > 1.9,
        f"the centre covered x {min(xs):.2f}..{max(xs):.2f}, z {min(zs):.2f}..{max(zs):.2f}",
    )

    # R restores position, orientation and the momentum the solver would otherwise
    # keep integrating. The expectation is the scene's own start poses, so moving a
    # body in the scene above moves this with it rather than breaking it.
    chain_home = [tuple(float(v) for v in p) for p in scene._chain_start]
    door_home = tuple(float(v) for v in scene._door_start)
    chain_back = max(apart(a, b) for a, b in zip(restored["chain"], chain_home, strict=True))
    door_back = apart(restored["door"], door_home)
    check(
        "R returns the chain and the door to their start pose",
        chain_back < 1e-3 and door_back < 1e-3 and abs(restored["turn"]) < 1e-3,
        f"chain off by {chain_back:.6f}, door off by {door_back:.6f} at {restored['turn']:.6f} deg",
    )

    print("screenshot: /tmp/joints3d_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="3D Joints Demo", width=1280, height=720).run(JointsDemo())