2D Physics Playground¶

rigid bodies, a character, one-way platforms, and joints.
Tags: physics 2d character joints
One scene exercising the 2D physics stack end to end. Dynamic boxes and circles fall and pile on a static segment floor, a two-link pendulum swings from pin joints, a bead slides along a groove joint, and a player-controlled character walks, jumps, and lands on a one-way platform it can also jump up through from below. An Area2D trigger zone reports every body passing through it, the character included: a CharacterBody2D is an ordinary kinematic body, so it fires the same signals a falling box does.
This is a Y-down pixel world (gravity = Vec2(0, +g), +Y rendered downward), so falling reads as falling on screen. The character’s up_direction and the one-way platform’s solid side are flipped to -Y to match.
Engine features shown:
PhysicsBody2D in DYNAMIC and STATIC modes with PhysicsMaterial friction and restitution; each body carries a CollisionShape2D plus a visual child that inherits the body transform the physics sync writes each fixed step.
CharacterBody2D driven by velocity + move_and_slide, with is_on_floor gating jumps.
A one-way platform: solid from above, pass-through from below.
Area2D body_entered / body_exited signals updating the HUD live, including the body_exited a DESTROYED body still owes: press X and the zone names what it lost.
PinJoint2D (a pendulum chain) and GrooveJoint2D (a bead pinned to a slide rail and kicked along it at start).
Controls: A / D - move the character left / right Hold click or tap - walk the character toward the pointer (mouse / touch) Space, click, tap - jump R - respawn the falling batch X - destroy whatever is inside the trigger zone Escape - quit
Run: uv run python examples/features/physics/playground2d.py Headless self-check: uv run python examples/features/physics/playground2d.py –test
Source¶

"""2D Physics Playground: rigid bodies, a character, one-way platforms, and joints.

One scene exercising the 2D physics stack end to end. Dynamic boxes and circles fall
and pile on a static segment floor, a two-link pendulum swings from pin joints, a bead
slides along a groove joint, and a player-controlled character walks, jumps, and lands
on a one-way platform it can also jump up through from below. An Area2D trigger zone
reports every body passing through it, the character included: a CharacterBody2D is an
ordinary kinematic body, so it fires the same signals a falling box does.

This is a Y-down pixel world (``gravity = Vec2(0, +g)``, +Y rendered downward), so
falling reads as falling on screen. The character's ``up_direction`` and the one-way
platform's solid side are flipped to -Y to match.

Engine features shown:
  - PhysicsBody2D in DYNAMIC and STATIC modes with PhysicsMaterial friction and
    restitution; each body carries a CollisionShape2D plus a visual child that
    inherits the body transform the physics sync writes each fixed step.
  - CharacterBody2D driven by velocity + move_and_slide, with is_on_floor gating jumps.
  - A one-way platform: solid from above, pass-through from below.
  - Area2D body_entered / body_exited signals updating the HUD live, including the
    body_exited a DESTROYED body still owes: press X and the zone names what it lost.
  - PinJoint2D (a pendulum chain) and GrooveJoint2D (a bead pinned to a slide rail and
    kicked along it at start).

Controls:
    A / D             - move the character left / right
    Hold click or tap - walk the character toward the pointer (mouse / touch)
    Space, click, tap - jump
    R                 - respawn the falling batch
    X                 - destroy whatever is inside the trigger zone
    Escape            - quit

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

# /// simvx
# tags = ["2d", "physics", "character", "joints"]
# ///
"""

from __future__ import annotations

import math

from simvx.core import (
    Area2D,
    BodyMode,
    Camera2D,
    CharacterBody2D,
    CircleShape2D,
    CollisionShape2D,
    GrooveJoint2D,
    Input,
    InputMap,
    Key,
    MouseButton,
    Node,
    Node2D,
    PhysicsBody2D,
    PhysicsMaterial,
    PhysicsRoot2D,
    PinJoint2D,
    Polygon2D,
    RectangleShape2D,
    SegmentShape2D,
    Text2D,
    Vec2,
)
from simvx.graphics import App

# Pixel-space, Y-DOWN world (the documented Y-down game path: gravity = Vec2(0, +g)
# and +Y rendered downward, so falling reads as falling on screen). World units ARE
# screen pixels and a Camera2D at the screen centre with zoom 1 gives the identity
# view (the same convention as the spaceinvaders2d demo). The physics world itself is
# axis-neutral: Y-down is this game's choice, carried by gravity and up_direction.
_WIDTH, _HEIGHT = 1280, 720
_GRAVITY = Vec2(0.0, 1400.0)  # px/s^2 downward
_FLOOR_Y = 660.0  # screen-y of the static floor (near the bottom)
_SOLID_UP = Vec2(0.0, -1.0)  # "up" on screen is -Y in this Y-down world

_COLOURS = [
    (0.90, 0.30, 0.25, 1.0),
    (0.30, 0.70, 0.95, 1.0),
    (0.95, 0.80, 0.25, 1.0),
    (0.55, 0.85, 0.35, 1.0),
    (0.80, 0.45, 0.90, 1.0),
]


class _DiscVisual(Node2D):
    """A filled disc with a spoke so its spin is visible.

    Added as a child of a PhysicsBody2D it inherits the body's pose: the physics sync
    writes the body's transform each fixed step and ``transform_points`` composes the
    whole parent chain, so the disc tracks the body it hangs off. Boxes need no custom
    node at all: they are plain ``Polygon2D`` children (see :func:`_box`).
    """

    def __init__(self, *, radius: float, colour, segments: int = 24, **kwargs: object) -> None:
        super().__init__(**kwargs)
        self._radius = float(radius)
        self._colour = colour
        self._segments = segments

    def on_draw(self, renderer):
        centre, spoke = self.transform_points([Vec2(0.0, 0.0), Vec2(self._radius, 0.0)])
        cx, cy = float(centre.x), float(centre.y)
        renderer.draw_circle((cx, cy), self._radius, colour=self._colour, filled=True, segments=self._segments)
        renderer.draw_line((cx, cy), (float(spoke.x), float(spoke.y)), colour=(0.1, 0.1, 0.1, 0.8), thickness=2.0)


def _box(hx: float, hy: float, colour) -> Polygon2D:
    return Polygon2D(polygon=[(-hx, -hy), (hx, -hy), (hx, hy), (-hx, hy)], colour=colour)


def _circle(radius: float, colour) -> _DiscVisual:
    return _DiscVisual(radius=radius, colour=colour)


class Physics2DScene(Node):
    def on_ready(self):
        InputMap.add_action("move_left", [Key.A])
        InputMap.add_action("move_right", [Key.D])
        # Left-click / tap doubles as jump (touch maps to MouseButton.LEFT on web),
        # so the demo is playable with mouse or a finger, not keyboard-only.
        InputMap.add_action("jump", [Key.SPACE, MouseButton.LEFT])
        InputMap.add_action("respawn", [Key.R])
        InputMap.add_action("vaporise", [Key.X])
        InputMap.add_action("quit", [Key.ESCAPE])

        # One isolated Y-down 2D world; every physics node below resolves to it.
        self._root2d = self.add_child(PhysicsRoot2D(name="World2D", gravity=_GRAVITY))

        # Camera at the centre of the authored frame. On a 1280x720 window that is
        # the identity pixel-space view; on anything else the zoom below scales it.
        self._cam = self._root2d.add_child(Camera2D())
        self._cam.position = Vec2(_WIDTH / 2, _HEIGHT / 2)
        self._fit_camera()

        self._build_floor()
        self._build_one_way_platform()
        self._build_trigger_area()
        self._build_pendulum()
        self._build_groove()
        self._build_character()

        self._bodies: list[PhysicsBody2D] = []
        self._spawn_batch()

        # 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 = Text2D(
            text="A/D or hold click/tap to move | Space or click/tap to jump",
            position=(10, 10),
            font_scale=1.4,
        )
        self.add_child(self._hud)
        self._hud_keys = Text2D(text="R respawn | X vaporise | ESC quit", position=(10, 38), font_scale=1.4)
        self.add_child(self._hud_keys)
        self._status = Text2D(text="", position=(10, 66), font_scale=1.0)
        self.add_child(self._status)
        self._last_trigger = ""
        self._last_exit = ""
        self._vaporised = 0
        self._trigger_status = Text2D(text="trigger: empty", position=(10, 90), font_scale=1.0)
        self.add_child(self._trigger_status)
        self._inside = 0

    def _fit_camera(self):
        """Scale the VIEW so the whole authored frame is visible on any window.

        Every world position here is part of the simulation setup -- the pendulum's
        reach, where the drops land, where the trigger sits -- so they are authored
        once at ``_WIDTH`` x ``_HEIGHT`` and never recomputed per window: the same
        run has to produce the same physics whatever it is displayed on. A smaller
        window therefore changes the camera, not the world, which is the difference
        between seeing the scene shrunk and seeing a crop of it.
        """
        self._cam.zoom = min(self.app.width / _WIDTH, self.app.height / _HEIGHT)

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

    def _build_floor(self):
        # A long STATIC segment floor (a thin 2D-only beam) with a slab visual.
        floor = PhysicsBody2D(name="Floor", mode=BodyMode.STATIC, material=PhysicsMaterial(friction=0.7))
        floor.position = Vec2(640.0, _FLOOR_Y)
        floor.add_child(CollisionShape2D(shape=SegmentShape2D(a=(-560.0, 0.0), b=(560.0, 0.0), radius=6.0)))
        floor.add_child(_box(560.0, 8.0, (0.24, 0.26, 0.30, 1.0)))
        self._root2d.add_child(floor)

    def _build_one_way_platform(self):
        # A one-way platform: solid from above (-Y up on screen), pass-through from
        # below. A box collider + slab visual; the character lands on it and can
        # jump up THROUGH it from below.
        plat = PhysicsBody2D(
            name="OneWay",
            mode=BodyMode.STATIC,
            one_way=True,
            one_way_normal=_SOLID_UP,
            material=PhysicsMaterial(friction=0.6),
        )
        plat.position = Vec2(900.0, 470.0)
        plat.add_child(CollisionShape2D(shape=RectangleShape2D(half_extents=Vec2(110.0, 8.0))))
        plat.add_child(_box(110.0, 8.0, (0.45, 0.75, 0.45, 1.0)))
        self._root2d.add_child(plat)

    def _build_trigger_area(self):
        # An Area2D zone that reports bodies entering / leaving via signals: the
        # falling drops pass through it on their way down, and so does the
        # character if it is walked into the zone (it is a kinematic body, not a
        # separate kind of peer).
        self._area = Area2D(name="Trigger")
        self._area.position = Vec2(560.0, 300.0)
        self._area.add_child(CollisionShape2D(shape=RectangleShape2D(half_extents=Vec2(120.0, 110.0))))
        self._area.add_child(_box(120.0, 110.0, (0.95, 0.85, 0.20, 0.18)))
        self._area.body_entered.connect(self._on_trigger_enter)
        self._area.body_exited.connect(self._on_trigger_exit)
        self._root2d.add_child(self._area)

    def _build_pendulum(self):
        # A two-link pendulum: a static anchor + two circles held by pin joints, so
        # it swings under gravity (PinJoint2D chain).
        anchor = PhysicsBody2D(name="PendAnchor", mode=BodyMode.STATIC)
        anchor.position = Vec2(170.0, 140.0)
        anchor.add_child(CollisionShape2D(shape=CircleShape2D(7.0)))
        anchor.add_child(_circle(7.0, (0.7, 0.7, 0.7, 1.0)))
        self._root2d.add_child(anchor)

        link1 = PhysicsBody2D(name="PendLink1", mode=BodyMode.DYNAMIC, mass=1.0)
        link1.position = Vec2(250.0, 140.0)
        link1.add_child(CollisionShape2D(shape=CircleShape2D(20.0)))
        link1.add_child(_circle(20.0, (0.30, 0.70, 0.95, 1.0)))
        self._root2d.add_child(link1)

        link2 = PhysicsBody2D(name="PendLink2", mode=BodyMode.DYNAMIC, mass=1.0)
        link2.position = Vec2(330.0, 140.0)
        link2.add_child(CollisionShape2D(shape=CircleShape2D(20.0)))
        link2.add_child(_circle(20.0, (0.80, 0.45, 0.90, 1.0)))
        self._root2d.add_child(link2)

        # Joints are added AFTER their bodies so both endpoints already exist.
        self._root2d.add_child(PinJoint2D(name="Pin1", body_a=anchor, body_b=link1, anchor=Vec2(170.0, 140.0)))
        self._root2d.add_child(PinJoint2D(name="Pin2", body_a=link1, body_b=link2, anchor=Vec2(250.0, 140.0)))

    def _build_groove(self):
        # A GrooveJoint2D slider: a static carrier holds a dynamic bead on a
        # horizontal groove; an initial sideways kick sends it sliding along the
        # line (pinned perpendicular, clamped at the ends). Disjoint collision masks
        # so the bead and carrier never collide as circles: ONLY the groove acts.
        groove_y = 230.0
        carrier = PhysicsBody2D(name="GrooveCarrier", mode=BodyMode.STATIC, collision_layer=0x1, collision_mask=0x2)
        carrier.position = Vec2(640.0, groove_y)
        carrier.add_child(CollisionShape2D(shape=CircleShape2D(7.0)))
        carrier.add_child(_circle(7.0, (0.7, 0.7, 0.7, 1.0)))
        # A visual line marking the groove segment (x in [-180, 180], carrier-local).
        carrier.add_child(_box(180.0, 2.0, (0.5, 0.5, 0.55, 1.0)))
        self._root2d.add_child(carrier)

        self._groove_bead = PhysicsBody2D(
            name="GrooveBead", mode=BodyMode.DYNAMIC, mass=1.0, collision_layer=0x1, collision_mask=0x4
        )
        self._groove_bead.position = Vec2(640.0 - 160.0, groove_y)
        self._groove_bead.add_child(CollisionShape2D(shape=CircleShape2D(16.0)))
        self._groove_bead.add_child(_circle(16.0, (0.95, 0.55, 0.20, 1.0)))
        self._root2d.add_child(self._groove_bead)

        self._root2d.add_child(
            GrooveJoint2D(
                name="Groove",
                body_a=carrier,
                body_b=self._groove_bead,
                groove_a=Vec2(-180.0, 0.0),
                groove_b=Vec2(180.0, 0.0),
                anchor_b=Vec2(0.0, 0.0),
            )
        )
        self._groove_y = groove_y
        # Initial slide kick along the groove (+X).
        self._groove_bead.velocity = Vec2(240.0, 0.0)

    def _build_character(self):
        self._char = CharacterBody2D(name="Player", shape=CircleShape2D(24.0))
        self._char.up_direction = _SOLID_UP  # up = -Y in this Y-down world
        self._char.position = Vec2(900.0, 140.0)
        self._char.add_child(_circle(24.0, (1.0, 0.55, 0.15, 1.0)))
        self._root2d.add_child(self._char)

    def _spawn_batch(self):
        for b in self._bodies:
            b.destroy()
        self._bodies = []
        for i in range(8):
            x = 560.0 + (i % 4 - 1.5) * 55.0
            y = 60.0 - (i // 4) * 65.0
            colour = _COLOURS[i % len(_COLOURS)]
            body = PhysicsBody2D(
                name=f"Drop{i}",
                mode=BodyMode.DYNAMIC,
                mass=1.0,
                material=PhysicsMaterial(friction=0.5, restitution=0.1),
            )
            body.position = Vec2(x, y)
            if i % 2 == 0:
                body.add_child(CollisionShape2D(shape=CircleShape2D(22.0)))
                body.add_child(_circle(22.0, colour))
            else:
                body.add_child(CollisionShape2D(shape=RectangleShape2D(half_extents=Vec2(22.0, 22.0))))
                body.add_child(_box(22.0, 22.0, colour))
            self._root2d.add_child(body)
            self._bodies.append(body)

    # -- signals ------------------------------------------------------------

    def _on_trigger_enter(self, node):
        # The payload is a PhysicsObject2D: a falling box, or the character.
        self._inside += 1
        self._last_trigger = type(node).__name__

    def _on_trigger_exit(self, node):
        # Two ways to stop overlapping, and the payload tells them apart. A body
        # that just fell out of the zone is still simulated; a body DESTROYED
        # inside it is handed over detached (``handle is None``), so a scoring or
        # cleanup handler can react to the kill without having cached anything.
        self._inside = max(0, self._inside - 1)
        if node.handle is None:
            self._vaporised += 1
            self._last_exit = f"{node.name} destroyed inside"
        else:
            self._last_exit = f"{node.name} left"

    def _vaporise_inside(self):
        """Destroy every body currently in the trigger (bound to X)."""
        for body in self._area.get_overlapping_bodies():
            body.destroy()

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

    def on_fixed_update(self, dt):
        speed = 300.0  # px/s
        vx = Input.get_axis("move_left", "move_right") * speed
        # Touch / mouse steering: while the left button (or finger) is held and no key
        # is driving, walk toward the pointer's x. Pixel-space identity view, so the
        # mouse screen x is the world x. A small dead zone stops jitter over the body.
        if vx == 0.0 and Input.is_mouse_button_pressed(MouseButton.LEFT):
            dx = float(Input.mouse_position.x) - float(self._char.world_position.x)
            if abs(dx) > 8.0:
                vx = math.copysign(speed, dx)
        # The fall speed lives on the node: move_and_slide writes the deflected
        # post-slide velocity back to self.velocity, so landing on a surface already
        # removes the component into it. Resting on the ground probe (no sweep hit)
        # still needs the clamp, or gravity would keep piling up frame after frame.
        # Y-down world: falling is +Y, so a jump is a -Y kick.
        vy = float(self._char.velocity.y)
        on_floor = self._char.is_on_floor()
        if on_floor and vy > 0.0:
            vy = 0.0
        if on_floor and Input.is_action_just_pressed("jump"):
            vy = -650.0
        vy += _GRAVITY.y * dt
        self._char.velocity = Vec2(vx, vy)
        self._char.move_and_slide(dt)

    def on_update(self, dt):
        if Input.is_action_just_pressed("quit"):
            self.app.quit()
            return
        if Input.is_action_just_pressed("respawn"):
            self._spawn_batch()
        if Input.is_action_just_pressed("vaporise"):
            self._vaporise_inside()
        self._fit_camera()
        # A destroyed body keeps its node but loses its handle, so the list has to
        # drop it or the count below would contradict the trigger line beside it,
        # which has already reported every body it lost.
        self._bodies = [b for b in self._bodies if b.handle is not None]
        rested = sum(1 for b in self._bodies if float(b.world_position.y) > _FLOOR_Y - 80.0)
        self._status.text = f"bodies: {len(self._bodies)} | rested: {rested} | on_floor: {self._char.is_on_floor()}"
        last = f" (last in: {self._last_trigger})" if self._last_trigger else ""
        out = f" | last out: {self._last_exit}" if self._last_exit else ""
        self._trigger_status.text = f"trigger: {self._inside} inside{last}{out} | vaporised: {self._vaporised}"


def _selftest() -> bool:
    """Headless: run a couple of seconds, screenshot, assert bodies fell + rested."""
    from simvx.graphics.testing import assert_not_blank, save_png

    app = App(title="Physics2D", width=_WIDTH, height=_HEIGHT, visible=False)
    scene = Physics2DScene(name="Physics2DScene")
    settled: dict[str, object] = {}

    def on_frame(index: int, _time: float) -> None:
        # Frames 0-179 are the ordinary settle, snapshotted at 179. After that,
        # replay what X does at runtime: respawn the batch, catch it mid-zone and
        # destroy it there, so the trigger has to report each body it lost.
        if index == 179:
            settled["y"] = [float(b.world_position.y) for b in scene._bodies]
            settled["char_y"] = float(scene._char.world_position.y)
            settled["bead"] = (float(scene._groove_bead.world_position.x), float(scene._groove_bead.world_position.y))
        elif index == 180:
            scene._spawn_batch()
        elif index > 180 and "caught" not in settled and scene._inside:
            settled["caught"] = scene._inside
            scene._vaporise_inside()

    frames = app.run_headless(scene, frames=320, on_frame=on_frame, capture_frames=[179])
    frame = frames[0]
    assert_not_blank(frame)
    save_png(frame, "/tmp/physics2d_new_test.png")

    ys = settled["y"]
    # Y-down: bodies START above (smaller y) and FALL toward the floor (larger y).
    # They pile just above the floor segment (within ~one body-height + beam radius).
    rested = [y for y in ys if _FLOOR_Y - 80.0 < y < _FLOOR_Y + 10.0]
    char_y = settled["char_y"]
    bead_x, bead_y = settled["bead"]
    groove_y = scene._groove_y
    print(f"drop body y after 3s: min={min(ys):.1f} max={max(ys):.1f} ; rested-on-floor: {len(rested)}/{len(ys)}")
    print(f"character y={char_y:.1f} on_floor={scene._char.is_on_floor()}")
    print(f"groove bead: x={bead_x:.1f} y={bead_y:.1f} (slid along, pinned to groove line at y={groove_y:.0f})")
    print("screenshot: /tmp/physics2d_new_test.png")
    ok = (
        len(rested) >= len(ys) - 1  # all but at most one drop body settled on the floor
        and char_y < _FLOOR_Y + 30.0  # the character is on / above the floor (did not fall through)
        and abs(bead_y - groove_y) < 12.0  # the groove bead stayed on its line
        and bead_x > 640.0 - 160.0 + 20.0  # the bead slid along the groove from its start (+X)
    )

    # The trigger is owed one body_exited per body destroyed inside it, naming
    # each one, which is what distinguishes "destroyed inside" from "fell out".
    # (Later drops fall through the zone and leave normally, so _last_exit has
    # moved on by now: the count is what pins the destroyed-inside path.)
    caught = settled.get("caught", 0)
    print(f"bodies caught in the trigger: {caught}; destroyed inside: {scene._vaporised}")
    ok = ok and caught > 0 and scene._vaporised == caught

    # And the two HUD lines have to agree: a body count that still includes the
    # ones the trigger just reported destroying is the contradiction a reader sees
    # first, so it is asserted rather than left to the eye.
    alive = sum(1 for b in scene._bodies if b.handle is not None)
    print(f"bodies listed: {len(scene._bodies)}; alive: {alive}; status line: {scene._status.text!r}")
    ok = ok and len(scene._bodies) == alive and scene._status.text.startswith(f"bodies: {alive} ")

    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="2D Physics Playground", width=_WIDTH, height=_HEIGHT)
    app.run(Physics2DScene())