Character Presence

a character body is an ordinary kinematic body.

▶ Run in browser

Tags: physics

A CharacterBody3D is a BodyMode.KINEMATIC physics body with a swept move_and_slide helper, not a separate kind of thing. This scene puts every consequence of that on screen at once, so it can be checked by eye:

• a per-frame raycast through the node-level self.physics.raycast reports the player by name when the ray crosses it;

• an Area3D trigger fires body_entered / body_exited with the player node as the payload, and never pushes it;

• a DYNAMIC crate falls and comes to rest on the player’s head, then is left behind when the player walks off (a character does not carry riders);

• a second CharacterBody3D blocks the player’s path;

• walking into the crate stops the player without shoving it, because this player sets push_factor = 0 (the engine’s own push is on by default) and owns the rule itself; the contacts are reported in collisions;

• a ball the player CAN push, because this scene asks for it: every blocking contact comes back in collisions, so the player applies its own impulse to the bodies it lists as pushable. With the engine’s push turned off, WHICH bodies move is entirely the game’s decision, which is why the ball rolls while the crate, just as dynamic and never listed, stays exactly where it is;

• a low step in front of the player is climbed rather than walked into, because step_height is set; anything taller than step_height blocks like a wall, and so does anything too steep to stand on – walk this player into the ball from any angle and it never gets a foothold up the flank. Its collider is a box, and that is part of why: a flat-based character lands squarely on whatever it steps onto, while one with a rounded base mounts a step by perching on the edge, and that perch is harder to tell apart from a grip on a curved surface;

• the player is authored exactly flush with the floor plane, the hardest starting pose for a swept character, and it moves freely from the first frame.

Controls: WASD - move the player (walk into the ball to push it) Left/Right - orbit camera R - reset the crate, the ball and both characters Escape - quit

Run (builtin): uv run python examples/features/physics/character_presence.py Run (Jolt): uv run python examples/features/physics/character_presence.py –jolt Headless check: uv run python examples/features/physics/character_presence.py –test Headless (Jolt): uv run python examples/features/physics/character_presence.py –test –jolt Web export: uv run simvx export web examples/features/physics/character_presence.py

The two backends must behave identically: a character is a kinematic body on both, so the crate rests on the player and the blocker blocks it either way.

Source

"""Character Presence: a character body is an ordinary kinematic body.

A ``CharacterBody3D`` is a ``BodyMode.KINEMATIC`` physics body with a swept
``move_and_slide`` helper, not a separate kind of thing. This scene puts every
consequence of that on screen at once, so it can be checked by eye:

  - a per-frame **raycast** through the node-level ``self.physics.raycast`` reports
    the player by name when the ray crosses it;
  - an **Area3D trigger** fires ``body_entered`` / ``body_exited`` with the player
    node as the payload, and never pushes it;
  - a DYNAMIC **crate** falls and comes to rest on the player's head, then is left
    behind when the player walks off (a character does not carry riders);
  - a second **CharacterBody3D** blocks the player's path;
  - walking into the crate stops the player without shoving it, because this
    player sets ``push_factor = 0`` (the engine's own push is on by default) and
    owns the rule itself; the contacts are reported in ``collisions``;
  - a **ball** the player CAN push, because this scene asks for it: every blocking
    contact comes back in ``collisions``, so the player applies its own impulse to
    the bodies it lists as pushable. With the engine's push turned off, WHICH
    bodies move is entirely the game's decision, which is why the ball rolls while
    the crate, just as dynamic and never listed, stays exactly where it is;
  - a low **step** in front of the player is climbed rather than walked into,
    because ``step_height`` is set; anything taller than ``step_height`` blocks
    like a wall, and so does anything too steep to stand on -- walk this player
    into the ball from any angle and it never gets a foothold up the flank. Its
    collider is a box, and that is part of why: a flat-based character lands
    squarely on whatever it steps onto, while one with a rounded base mounts a
    step by perching on the edge, and that perch is harder to tell apart from a
    grip on a curved surface;
  - the player is authored exactly flush with the floor plane, the hardest
    starting pose for a swept character, and it moves freely from the first frame.

Controls:
    WASD          - move the player (walk into the ball to push it)
    Left/Right    - orbit camera
    R             - reset the crate, the ball and both characters
    Escape        - quit

Run (builtin):    uv run python examples/features/physics/character_presence.py
Run (Jolt):       uv run python examples/features/physics/character_presence.py --jolt
Headless check:   uv run python examples/features/physics/character_presence.py --test
Headless (Jolt):  uv run python examples/features/physics/character_presence.py --test --jolt
Web export:       uv run simvx export web examples/features/physics/character_presence.py

The two backends must behave identically: a character is a kinematic body on both,
so the crate rests on the player and the blocker blocks it either way.
"""

import math

from simvx.core import (
    Area3D,
    BodyMode,
    BoxShape3D,
    Camera3D,
    CharacterBody3D,
    DirectionalLight3D,
    Input,
    Key,
    Material,
    Mesh,
    MeshInstance3D,
    Node3D,
    PhysicsBody3D,
    PhysicsRoot,
    SphereShape3D,
    Text2D,
    Vec3,
    WorldEnvironment,
)

# Geometry. The floor's TOP face is exactly y = 0, and the player's half-height is
# PLAYER_HALF, so authoring the player at y = PLAYER_HALF is bit-exactly flush.
FLOOR_HALF = Vec3(24.0, 0.5, 24.0)
PLAYER_HALF = 0.9
PLAYER_SPEED = 4.0
GRAVITY = 18.0
CRATE_HALF = 0.35
CRATE_SPAWN = Vec3(0.0, 3.2, 0.0)
BALL_RADIUS = 0.45
BALL_MASS = 0.6
BALL_SPAWN = Vec3(3.2, BALL_RADIUS, -2.6)
#: Impulse the player applies per fixed step to each body it is touching. The
#: engine never applies this by itself: see ``Player._push_what_it_touched``.
PUSH_IMPULSE = 0.25
BLOCKER_AT = Vec3(6.0, PLAYER_HALF, 0.0)
WALL_AT = Vec3(0.0, 1.5, -7.0)
TRIGGER_AT = Vec3(-6.0, 1.2, 0.0)
#: A low step the player walks up. Its top is well inside PLAYER_STEP_HEIGHT.
STEP_HALF = Vec3(4.0, 0.15, 2.0)
STEP_AT = Vec3(0.0, STEP_HALF.y, 6.0)
PLAYER_STEP_HEIGHT = 0.5
#: Backend override for the scene's PhysicsRoot. ``None`` means "resolve normally"
#: (project setting, then auto-discovery, then Builtin); ``--jolt`` pins the
#: optional native backend so the two can be compared side by side by hand.
BACKEND: str | None = None
#: The debug ray starts BETWEEN the trigger and the player: a query is
#: observer-decides, so it reports a sensor too, and starting further left would
#: report the trigger's sensor body rather than the character.
_RAY_FROM = Vec3(-3.0, PLAYER_HALF, 0.0)


def _visual(mesh: Mesh, scale: tuple[float, float, float], colour: tuple, *, emissive: float = 0.0):
    """A MeshInstance3D child that inherits its body's transform."""
    return MeshInstance3D(
        mesh=mesh,
        material=Material(
            colour=colour,
            emissive_colour=(colour[0] * emissive, colour[1] * emissive, colour[2] * emissive, 1.0),
            roughness=0.55,
        ),
        scale=scale,
    )


class Player(CharacterBody3D):
    """The WASD-driven character. Gravity is integrated by hand, as always."""

    def __init__(self, **kwargs):
        super().__init__(
            shape=BoxShape3D(half_extents=Vec3(0.4, PLAYER_HALF, 0.4)),
            step_height=PLAYER_STEP_HEIGHT,
            #: Off, so this scene can own the rule: the engine's shove is on by
            #: default and would move the crate as readily as the ball.
            push_factor=0.0,
            **kwargs,
        )
        self.add_child(_visual(Mesh.cube(), (0.8, PLAYER_HALF * 2, 0.8), (0.20, 0.75, 1.0, 1.0), emissive=0.35))
        #: Seam handles this game is willing to shove, filled in by the scene.
        #: ``collisions`` reports handles, so gameplay code that wants to decide
        #: per body keeps its own set rather than resolving nodes every frame.
        self.pushable: set[int] = set()

    def on_fixed_update(self, dt: float):
        vx = Input.is_action_pressed("move_right") - Input.is_action_pressed("move_left")
        vz = Input.is_action_pressed("move_back") - Input.is_action_pressed("move_forward")
        vy = 0.0 if self.is_on_floor() else self.velocity.y - GRAVITY * dt
        self.velocity = Vec3(vx * PLAYER_SPEED, vy, vz * PLAYER_SPEED)
        self.move_and_slide(dt)
        self._push_what_it_touched()

    def _push_what_it_touched(self):
        """Push the bodies this game says are pushable, with the engine's push off.

        ``move_and_slide`` hands back every blocking contact it resolved in
        ``collisions``. Each normal points away from the body that was hit and
        toward the player, so shoving that body means an impulse along
        ``-normal``.

        Which bodies are pushable is a game rule here rather than a physics one,
        so the scene registers them in ``pushable``. That is what turning
        ``push_factor`` off buys: here the ball rolls and the crate, which is just
        as dynamic, stays exactly where it is.
        """
        world = self.world
        if world is None:
            return
        for hit in self.collisions:
            if hit.body in self.pushable:
                world.apply_impulse(hit.body, -hit.normal * PUSH_IMPULSE, at=hit.point)


class Blocker(CharacterBody3D):
    """A second character that never moves. It still blocks the player."""

    def __init__(self, **kwargs):
        super().__init__(shape=BoxShape3D(half_extents=Vec3(0.4, PLAYER_HALF, 0.4)), **kwargs)
        self.add_child(_visual(Mesh.cube(), (0.8, PLAYER_HALF * 2, 0.8), (1.0, 0.45, 0.25, 1.0), emissive=0.3))


class CharacterPresenceScene(Node3D):
    """Floor + player + blocker + wall + crate + trigger, and a HUD reading it all."""

    #: Declared on the ROOT so the tree registers them before enter-tree, which is
    #: also what makes them work on the web export (which never runs ``main()``).
    input_actions = {
        "move_forward": [Key.W],
        "move_back": [Key.S],
        "move_left": [Key.A],
        "move_right": [Key.D],
        "orbit_left": [Key.LEFT],
        "orbit_right": [Key.RIGHT],
        "reset": [Key.R],
        "quit": [Key.ESCAPE],
    }

    def on_ready(self):
        self.add_child(WorldEnvironment(ambient_light_colour=(0.30, 0.33, 0.40, 1.0), ambient_light_energy=0.9))
        sun = DirectionalLight3D(position=(8.0, 14.0, 10.0))
        sun.colour = (1.0, 0.96, 0.86)
        sun.intensity = 1.2
        sun.look_at((0.0, 0.0, 0.0))
        self.add_child(sun)

        self._root = self.add_child(PhysicsRoot(gravity=Vec3(0.0, -GRAVITY, 0.0), backend=BACKEND))
        self._build_world()
        self._build_hud()

        self._cam_yaw = 0.6
        self._camera = self.add_child(Camera3D(fov=55.0))
        self._update_camera()

        self._entered = ""
        self._exited = ""
        self._trigger.body_entered.connect(self._on_trigger_enter)
        self._trigger.body_exited.connect(self._on_trigger_exit)

    # -- scene ---------------------------------------------------------------

    def _build_world(self):
        floor = PhysicsBody3D(name="Floor", mode=BodyMode.STATIC, shape=BoxShape3D(half_extents=FLOOR_HALF))
        floor.position = Vec3(0.0, -FLOOR_HALF.y, 0.0)  # top face exactly at y = 0
        floor.add_child(_visual(Mesh.cube(), tuple(FLOOR_HALF * 2), (0.16, 0.17, 0.20, 1.0)))
        self._root.add_child(floor)

        step = PhysicsBody3D(name="Step", mode=BodyMode.STATIC, shape=BoxShape3D(half_extents=STEP_HALF))
        step.position = STEP_AT
        step.add_child(_visual(Mesh.cube(), tuple(STEP_HALF * 2), (0.22, 0.40, 0.30, 1.0)))
        self._root.add_child(step)

        wall = PhysicsBody3D(name="Wall", mode=BodyMode.STATIC, shape=BoxShape3D(half_extents=Vec3(8.0, 1.5, 0.5)))
        wall.position = WALL_AT
        wall.add_child(_visual(Mesh.cube(), (16.0, 3.0, 1.0), (0.30, 0.28, 0.34, 1.0)))
        self._root.add_child(wall)

        # Authored bit-exactly flush with the floor plane on purpose: this is the
        # pose that starts every sweep at zero separation.
        self._player = Player(name="Player")
        self._player.position = Vec3(0.0, PLAYER_HALF, 0.0)
        self._root.add_child(self._player)

        self._blocker = Blocker(name="Blocker")
        self._blocker.position = BLOCKER_AT
        self._root.add_child(self._blocker)

        self._trigger = Area3D(name="Trigger", shape=BoxShape3D(half_extents=Vec3(1.6, 1.2, 1.6)))
        self._trigger.position = TRIGGER_AT
        self._trigger.add_child(_visual(Mesh.cube(), (3.2, 2.4, 3.2), (0.95, 0.85, 0.20, 0.25), emissive=0.4))
        self._root.add_child(self._trigger)

        self._spawn_crate()
        self._spawn_ball()

    def _spawn_ball(self):
        """A DYNAMIC ball the player may shove, registered as pushable."""
        ball = PhysicsBody3D(
            name="Ball",
            mode=BodyMode.DYNAMIC,
            mass=BALL_MASS,
            shape=SphereShape3D(radius=BALL_RADIUS),
        )
        ball.position = BALL_SPAWN
        ball.add_child(
            _visual(Mesh.sphere(radius=BALL_RADIUS, rings=16, segments=24), (1.0, 1.0, 1.0), (0.55, 0.90, 0.45, 1.0))
        )
        self._root.add_child(ball)
        self._ball = ball
        self._player.pushable = {ball.handle}

    def _spawn_crate(self):
        crate = PhysicsBody3D(
            name="Crate",
            mode=BodyMode.DYNAMIC,
            mass=1.0,
            shape=BoxShape3D(half_extents=Vec3(CRATE_HALF, CRATE_HALF, CRATE_HALF)),
        )
        crate.position = CRATE_SPAWN
        crate.add_child(_visual(Mesh.cube(), (CRATE_HALF * 2,) * 3, (0.85, 0.55, 0.15, 1.0), emissive=0.25))
        self._root.add_child(crate)
        self._crate = crate

    def _build_hud(self):
        self._ray_text = self.add_child(Text2D(text="raycast hit: -", position=(12, 12), font_scale=1.0))
        self._trigger_text = self.add_child(Text2D(text="trigger: -", position=(12, 36), font_scale=1.0))
        self._crate_text = self.add_child(Text2D(text="crate: -", position=(12, 60), font_scale=1.0))
        self._state_text = self.add_child(Text2D(text="player: -", position=(12, 84), font_scale=1.0))
        self._step_text = self.add_child(Text2D(text="step: -", position=(12, 108), font_scale=1.0))
        self._ball_text = self.add_child(Text2D(text="ball: -", position=(12, 132), font_scale=1.0))
        self.add_child(
            Text2D(
                text=(
                    "WASD move (walk into the ball to push it, S climbs the step) | "
                    "Left/Right arrows orbit | R reset | Esc quit"
                ),
                position=(12, 156),
                font_scale=0.9,
            )
        )

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

    def _on_trigger_enter(self, node):
        # The payload is a PhysicsObject3D: here, the CharacterBody3D player.
        self._entered = type(node).__name__

    def _on_trigger_exit(self, node):
        self._exited = type(node).__name__

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

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

        turn = 1.5
        self._cam_yaw += (Input.is_action_pressed("orbit_right") - Input.is_action_pressed("orbit_left")) * turn * dt
        self._update_camera()
        if Input.is_action_just_pressed("reset"):
            self.reset()
        self._update_hud()

    def _update_camera(self):
        radius, height = 14.0, 9.0
        self._camera.position = Vec3(math.sin(self._cam_yaw) * radius, height, math.cos(self._cam_yaw) * radius)
        self._camera.look_at(Vec3(0.0, 1.0, 0.0))

    def _debug_raycast(self):
        """A ray across the arena at the player's chest height, through the NODE API.

        ``self.physics.raycast`` resolves the seam handle back to the scene node, and
        a character joins that registry like any other body, so the hit comes back as
        the ``Player`` node itself rather than as an opaque handle.
        """
        hit = self._player.physics.raycast(_RAY_FROM, Vec3(1.0, 0.0, 0.0), distance=20.0)
        if hit is None:
            return "-"
        name = type(hit.node).__name__
        return f"{name} ({'PLAYER' if hit.node is self._player else 'other'}) at {hit.distance:.2f}"

    def _update_hud(self):
        self._ray_text.text = f"raycast hit: {self._debug_raycast()}"
        inside = [type(b).__name__ for b in self._trigger.get_overlapping_bodies()]
        self._trigger_text.text = (
            f"trigger: inside={inside or '-'}  entered={self._entered or '-'}  exited={self._exited or '-'}"
        )
        crate_y = float(self._crate.world_position.y)
        riding = crate_y > PLAYER_HALF * 2 - 0.2
        self._crate_text.text = f"crate y={crate_y:.2f} {'ON THE PLAYER' if riding else 'on the floor'}"
        hits = (
            ", ".join(
                f"n=({float(c.normal.x):.1f},{float(c.normal.y):.1f},{float(c.normal.z):.1f})"
                for c in self._player.collisions
            )
            or "-"
        )
        self._state_text.text = (
            f"player floor={self._player.is_on_floor()} wall={self._player.is_on_wall()} "
            f"y={float(self._player.world_position.y):.3f} collisions: {hits}"
        )
        pos = self._player.world_position
        step_top = STEP_AT.y + STEP_HALF.y
        on_step = float(pos.z) > STEP_AT.z - STEP_HALF.z and float(pos.y) > PLAYER_HALF + step_top * 0.5
        self._step_text.text = (
            f"step (top y={step_top:.2f}, step_height={PLAYER_STEP_HEIGHT:.2f}): "
            f"{'ON TOP' if on_step else 'below'}  z={float(pos.z):.2f}"
        )
        bp = self._ball.world_position
        moved = (bp - BALL_SPAWN).length()
        self._ball_text.text = (
            f"ball (pushable) at ({float(bp.x):.2f}, {float(bp.z):.2f})  "
            f"{'PUSHED ' + format(moved, '.2f') + 'm' if moved > 0.05 else 'at rest'}"
        )

    def reset(self):
        self._player.position = Vec3(0.0, PLAYER_HALF, 0.0)
        self._player.velocity = Vec3()
        self._blocker.position = BLOCKER_AT
        self._crate.destroy()
        self._spawn_crate()
        self._ball.destroy()
        self._spawn_ball()
        self._entered = ""
        self._exited = ""


def _selftest() -> bool:
    """Headless smoke check: the scene renders, and the three claims easiest to miss hold."""
    from simvx.core.physics.nodes import PhysicsObject3D
    from simvx.graphics import App
    from simvx.graphics.testing import assert_not_blank, save_png

    app = App(title="CharacterPresence", width=1280, height=720, visible=False)
    scene = CharacterPresenceScene(name="CharacterPresenceScene")
    frames = app.run_headless(scene, frames=180, capture_frames=[179])
    assert_not_blank(frames[0])
    save_png(frames[0], "/tmp/character_presence.png")

    player = scene._player
    ok = True
    print(f"backend: {type(player.world).__name__}")

    # A character joins the body registry like anything else, so a node-level
    # query resolves it back to the scene node.
    hit = player.physics.raycast(_RAY_FROM, Vec3(1.0, 0.0, 0.0), distance=20.0)
    ray_ok = hit is not None and hit.node is player and isinstance(hit.node, PhysicsObject3D)
    print(f"raycast resolves the character node: {ray_ok}")
    ok = ok and ray_ok

    # The crate that fell in the first 180 frames is still up on the player's head.
    crate_y = float(scene._crate.world_position.y)
    rest_ok = crate_y > PLAYER_HALF * 2 - 0.2
    print(f"crate rests on the character: {rest_ok} (y={crate_y:.3f}, player top={PLAYER_HALF * 2:.2f})")
    ok = ok and rest_ok

    # Drive the player into the blocker and confirm it stops without pushing.
    blocker_x0 = float(scene._blocker.world_position.x)
    for _ in range(180):
        player.velocity = Vec3(PLAYER_SPEED, 0.0, 0.0)
        player.move_and_slide(1 / 60)
    px = float(player.world_position.x)
    block_ok = px < BLOCKER_AT.x - 0.7 and abs(float(scene._blocker.world_position.x) - blocker_x0) < 0.05
    print(f"blocked by the other character without pushing it: {block_ok} (player x={px:.3f})")
    ok = ok and block_ok
    print(f"blocking contacts reported: {len(player.collisions)}")
    ok = ok and len(player.collisions) >= 1

    # Walk back across the ball on the diagonal two held keys give, which is what
    # grazes its flank rather than meeting it head-on. The step-up probe classifies
    # what it lands on against slope_limit, so for this box-collidered player a ball
    # is not a staircase: it ends at the height it started at instead of ratcheting
    # up the side.
    diagonal = Vec3(-1.0, 0.0, -1.0).normalized() * PLAYER_SPEED
    start_y = float(player.world_position.y)
    peak_y = start_y
    for _ in range(240):
        player.velocity = diagonal
        player.move_and_slide(1 / 60)
        peak_y = max(peak_y, float(player.world_position.y))
    climb_ok = peak_y < start_y + 0.05
    print(f"the ball is not climbable: {climb_ok} (highest y={peak_y:.3f}, standing y={start_y:.3f})")
    ok = ok and climb_ok

    print("screenshot: /tmp/character_presence.png")
    print("SELFTEST:", "PASS" if ok else "FAIL")
    return ok


if __name__ == "__main__":
    import sys

    if "--jolt" in sys.argv:
        # Module scope, so on_ready sees it when the scene is built below.
        BACKEND = "jolt"
    if "--test" in sys.argv:
        sys.exit(0 if _selftest() else 1)

    from simvx.graphics import App

    app = App(title=f"Character Presence ({BACKEND or 'builtin'})", width=1280, height=720)
    app.run(CharacterPresenceScene())