3D Physics Playground¶

falling bodies and a walking character.

Tags: physics 3d character

Drop a batch of spheres and boxes onto a static slab, then walk a glowing character through the pile. The character is an ordinary kinematic body, so the falling bodies collide with it and can come to rest on its head; walk out from under a resting box and it is left behind to fall, because a character carries no riders.

Shows:

PhysicsBody3D (mode=DYNAMIC) spheres and boxes falling under gravity and resting or stacking on a PhysicsBody3D (mode=STATIC) slab; the world steps them and writes their poses back to the nodes each fixed step.
CharacterBody3D moved with move_and_slide() and is_on_floor(), with gravity read from the world it lives in and integrated by game code each fixed step. move_and_slide writes the deflected velocity back, so the next step reads its vertical speed straight off the character.
The standard body recipe: a CollisionShape3D child for the physics plus a MeshInstance3D child for the visual, which inherits the body’s transform.
A VirtualJoystick and VirtualButtons that inject the same keys the keyboard uses, so the demo plays with a mouse or a finger as well.

The world is Y-up, so gravity (-Y) and the visuals agree. Movement is camera-relative: pushing the stick (or W) away from you walks the character away from the camera, whichever way it is orbited.

Controls: WASD - move the character (camera-relative) Arrows - orbit the camera R - drop a fresh batch of bodies Escape - quit On-screen stick and buttons - move, orbit, drop (mouse or touch)

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

Source¶

"""3D Physics Playground: falling bodies and a walking character.

Drop a batch of spheres and boxes onto a static slab, then walk a glowing
character through the pile. The character is an ordinary kinematic body, so the
falling bodies collide with it and can come to rest on its head; walk out from
under a resting box and it is left behind to fall, because a character carries
no riders.

Shows:
  - PhysicsBody3D (mode=DYNAMIC) spheres and boxes falling under gravity and
    resting or stacking on a PhysicsBody3D (mode=STATIC) slab; the world steps
    them and writes their poses back to the nodes each fixed step.
  - CharacterBody3D moved with move_and_slide() and is_on_floor(), with gravity
    read from the world it lives in and integrated by game code each fixed step.
    move_and_slide writes the deflected velocity back, so the next step reads its
    vertical speed straight off the character.
  - The standard body recipe: a CollisionShape3D child for the physics plus a
    MeshInstance3D child for the visual, which inherits the body's transform.
  - A VirtualJoystick and VirtualButtons that inject the same keys the keyboard
    uses, so the demo plays with a mouse or a finger as well.

The world is Y-up, so gravity (-Y) and the visuals agree. Movement is
camera-relative: pushing the stick (or W) away from you walks the character away
from the camera, whichever way it is orbited.

Controls:
    WASD    - move the character (camera-relative)
    Arrows  - orbit the camera
    R       - drop a fresh batch of bodies
    Escape  - quit
    On-screen stick and buttons - move, orbit, drop (mouse or touch)

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

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

from __future__ import annotations

import math

from simvx.core import (
    AnchorPreset,
    BodyMode,
    BoxShape3D,
    Camera3D,
    CharacterBody3D,
    CollisionShape3D,
    Control,
    DirectionalLight3D,
    Input,
    InputMap,
    Key,
    Material,
    Mesh,
    MeshInstance3D,
    Node,
    PhysicsBody3D,
    SphereShape3D,
    Text2D,
    Vec2,
    Vec3,
)
from simvx.core.ui import VirtualButton, VirtualJoystick
from simvx.graphics import App

_BODY_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),
]

#: The slab's top face sits at y = 0.5 and the bodies are 1 unit across, so a
#: body resting directly on the slab has its centre at y = 1.0: a centre below
#: this has settled rather than still falling or stacked on another body.
_REST_HEIGHT = 1.7
#: A resting body's centre never drops below this; lower means it sank into the
#: slab, which the self-check reports as a failure rather than a rest.
_MIN_REST_HEIGHT = 0.6
#: Stick tilt at which a digital direction key is considered held.
_STICK_THRESHOLD = 0.35


class PointerControls(Control):
    """On-screen stick and buttons so the demo plays with a mouse or a finger.

    The stick sits bottom-left, the orbit and drop buttons bottom-right. Every
    widget injects the same key the keyboard binds, so there is a single input
    path to reason about, and the widgets scale with the viewport.
    """

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.set_anchor_preset(AnchorPreset.FULL_RECT)

        self._stick = VirtualJoystick(name="MoveStick")
        self._stick.moved.connect(self._on_stick)
        self.add_child(self._stick)

        self._orbit_left = self._add_button("<", Key.LEFT, "OrbitLeft")
        self._orbit_right = self._add_button(">", Key.RIGHT, "OrbitRight")
        self._drop = self._add_button("DROP", Key.R, "Drop")

        #: Direction keys the stick currently holds down, so keys are injected on
        #: edges only and released cleanly when the stick re-centres.
        self._held: set[Key] = set()

    def _add_button(self, label: str, key: Key, name: str) -> VirtualButton:
        button = VirtualButton(label=label, name=name)
        button.pressed.connect(lambda: Input.inject_key(key, True))
        button.released.connect(lambda: Input.inject_key(key, False))
        return self.add_child(button)

    def on_enter_tree(self):
        self._layout(self.tree.screen_size)
        self.tree.screen_resized.connect(self._layout)

    def on_exit_tree(self):
        self.tree.screen_resized.disconnect(self._layout)
        for key in self._held:
            Input.inject_key(key, False)
        self._held = set()

    def _layout(self, size):
        w, h = float(size[0]), float(size[1])
        unit = min(w, h)
        inset = max(20.0, unit * 0.04)  # safe-area margin from the edges

        stick_r = max(56.0, unit * 0.12)
        self._stick.radius = stick_r
        self._stick.size = Vec2(stick_r * 2, stick_r * 2)
        self._stick.position = Vec2(inset, h - inset - stick_r * 2)

        btn_r = max(40.0, unit * 0.075)
        for button in (self._orbit_left, self._orbit_right, self._drop):
            button.button_radius = btn_r
            button.size = Vec2(btn_r * 2, btn_r * 2)

        gap = btn_r * 0.5
        row_y = h - inset - btn_r * 2
        self._orbit_right.position = Vec2(w - inset - btn_r * 2, row_y)
        self._orbit_left.position = Vec2(w - inset - btn_r * 4 - gap, row_y)
        self._drop.position = Vec2(w - inset - btn_r * 3 - gap / 2, row_y - btn_r * 2 - gap)

    def _on_stick(self, nx: float, ny: float):
        """Map the analog tilt onto the movement keys (stick +Y is screen-down)."""
        want: set[Key] = set()
        if nx <= -_STICK_THRESHOLD:
            want.add(Key.A)
        elif nx >= _STICK_THRESHOLD:
            want.add(Key.D)
        if ny <= -_STICK_THRESHOLD:
            want.add(Key.W)
        elif ny >= _STICK_THRESHOLD:
            want.add(Key.S)

        for key in self._held - want:
            Input.inject_key(key, False)
        for key in want - self._held:
            Input.inject_key(key, True)
        self._held = want


class PhysicsScene(Node):
    def on_ready(self):
        InputMap.add_action("move_fwd", [Key.W])
        InputMap.add_action("move_back", [Key.S])
        InputMap.add_action("move_left", [Key.A])
        InputMap.add_action("move_right", [Key.D])
        InputMap.add_action("orbit_left", [Key.LEFT])
        InputMap.add_action("orbit_right", [Key.RIGHT])
        InputMap.add_action("pitch_up", [Key.UP])
        InputMap.add_action("pitch_down", [Key.DOWN])
        InputMap.add_action("respawn", [Key.R])
        InputMap.add_action("quit", [Key.ESCAPE])

        self._cam_angle = 0.6
        self._cam_pitch = 0.5
        self._cam = self.add_child(Camera3D())
        self._update_camera()

        sun = DirectionalLight3D(position=(6, 12, 8))
        sun.colour = (1.0, 0.96, 0.85)
        sun.intensity = 1.0
        sun.look_at((0, 0, 0))
        self.add_child(sun)

        # Ground: a static slab. BoxShape3D half-extents match the visual scale.
        ground = PhysicsBody3D(mode=BodyMode.STATIC, position=(0, 0, 0))
        ground.add_child(CollisionShape3D(shape=BoxShape3D(half_extents=Vec3(12, 0.5, 12))))
        ground.add_child(
            MeshInstance3D(
                mesh=Mesh.cube(),
                material=Material(colour=(0.24, 0.26, 0.30, 1.0), roughness=0.9, metallic=0.0),
                scale=(24, 1, 24),
            )
        )
        self.add_child(ground)

        # A walking character (a sphere collider for the basic tier).
        self._char = CharacterBody3D(position=(0, 1.2, 4))
        self._char.add_child(CollisionShape3D(shape=SphereShape3D(radius=0.6)))
        self._char.add_child(
            MeshInstance3D(
                mesh=Mesh.sphere(radius=0.6, rings=16, segments=24),
                material=Material(colour=(1.0, 0.55, 0.15, 1.0), emissive_colour=(1.0, 0.45, 0.10, 1.5), roughness=0.5),
            )
        )
        self.add_child(self._char)
        # The character integrates gravity itself; take it from the world its body
        # was created in so it falls at exactly the rate the dynamic bodies do.
        self._gravity_y = float(self._char.world.gravity.y)

        self._sphere_mesh = Mesh.sphere(radius=0.5, rings=16, segments=24)
        self._cube_mesh = Mesh.cube()
        self._bodies: list[PhysicsBody3D] = []
        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="WASD move | Arrows orbit | R drop | ESC quit", position=(10, 10), font_scale=1.4)
        self.add_child(self._hud)
        self._hud_touch = Text2D(text="or use the on-screen stick and buttons", position=(10, 38), font_scale=1.4)
        self.add_child(self._hud_touch)
        self._status = Text2D(text="", position=(10, 66), font_scale=1.0)
        self.add_child(self._status)
        self.add_child(PointerControls(name="PointerControls"))

    def _spawn_batch(self):
        for b in self._bodies:
            b.destroy()
        self._bodies = []
        for i in range(8):
            x = (i % 4 - 1.5) * 1.6
            z = (i // 4 - 0.5) * 1.6
            y = 6.0 + (i % 4) * 0.9
            if i % 2 == 0:
                shape, mesh = SphereShape3D(radius=0.5), self._sphere_mesh
            else:
                shape, mesh = BoxShape3D(half_extents=Vec3(0.5, 0.5, 0.5)), self._cube_mesh
            body = PhysicsBody3D(mode=BodyMode.DYNAMIC, position=(x, y, z), mass=1.0)
            body.add_child(CollisionShape3D(shape=shape))
            body.add_child(
                MeshInstance3D(
                    mesh=mesh,
                    material=Material(colour=_BODY_COLOURS[i % len(_BODY_COLOURS)], roughness=0.4, metallic=0.1),
                )
            )
            self.add_child(body)
            self._bodies.append(body)

    def _update_camera(self):
        d, a, p = 22.0, self._cam_angle, self._cam_pitch
        self._cam.position = (d * math.cos(p) * math.sin(a), d * math.sin(p) + 3.0, d * math.cos(p) * math.cos(a))
        self._cam.look_at((0, 1.5, 0), up=(0, 1, 0))

    def on_fixed_update(self, dt):
        # Character: horizontal from input, gravity on Y, slide along the world.
        speed = 6.0
        # get_vector normalises the diagonal, so walking NE is not faster than N.
        move = Input.get_vector("move_left", "move_right", "move_back", "move_fwd")
        # Ground-plane camera basis: forward is where the camera looks, right is
        # a quarter turn from it, so the stick and WASD read as screen directions.
        fwd_x, fwd_z = -math.sin(self._cam_angle), -math.cos(self._cam_angle)
        right_x, right_z = math.cos(self._cam_angle), -math.sin(self._cam_angle)
        vx = (right_x * move.x + fwd_x * move.y) * speed
        vz = (right_z * move.x + fwd_z * move.y) * speed
        # move_and_slide wrote the deflected velocity back last step, so the fall
        # speed is read from the character rather than shadowed in game state.
        vy = float(self._char.velocity.y)
        if self._char.is_on_floor() and vy < 0.0:
            vy = 0.0
        vy += self._gravity_y * dt
        self._char.velocity = Vec3(vx, vy, vz)
        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()
        rot = 1.5
        self._cam_angle += Input.get_axis("orbit_left", "orbit_right") * rot * dt
        self._cam_pitch = max(0.05, min(1.3, self._cam_pitch + Input.get_axis("pitch_down", "pitch_up") * rot * dt))
        self._update_camera()
        resting = sum(1 for b in self._bodies if b.world_position.y < _REST_HEIGHT)
        self._status.text = f"bodies: {len(self._bodies)} | resting: {resting} | on_floor: {self._char.is_on_floor()}"


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

    app = App(title="Physics3D", width=1280, height=720, visible=False)
    scene = PhysicsScene(name="PhysicsScene")
    frames = app.run_headless(scene, frames=180, capture_frames=[179])
    frame = frames[0]
    assert_not_blank(frame)
    save_png(frame, "/tmp/physics3d_new_test.png")
    ys = [float(b.world_position.y) for b in scene._bodies]
    rested = [y for y in ys if _MIN_REST_HEIGHT < y < _REST_HEIGHT]
    print(f"body y after 3s: min={min(ys):.2f} max={max(ys):.2f} ; rested-on-ground: {len(rested)}/{len(ys)}")
    print(f"character y={float(scene._char.world_position.y):.2f} on_floor={scene._char.is_on_floor()}")
    print("screenshot: /tmp/physics3d_new_test.png")
    ok = len(rested) >= len(ys) - 1 and 0.0 < float(scene._char.world_position.y) < 3.0
    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="3D Physics Playground", width=1280, height=720)
    app.run(PhysicsScene())