Character Push

a character shoves what it walks into, as hard as you say.

▶ Run in browser

Tags: physics 3d character

A character body is position-driven, so nothing about the collision itself moves what it walks into. push_factor is the knob that turns the block into a shove, and it ships ON at 1.0: walk into a crate and the crate goes. Godot’s character body and Unity’s stock controller leave this to the game; Unreal pushes out of the box, and so do we.

The impulse per blocking contact is push_factor * (M * m / (M + m)) * approach_speed, M being the character’s mass and m the mass of what it hit. That middle term is the pair’s reduced mass, and times the approach speed it is the arrest impulse of a perfectly inelastic collision – which is exactly why 1.0 is safe to ship: one contact hands the crate M / (M + m) of your approach speed and never more, so at the 1 kg character here the 1 kg crate leaves its first contact at 2.00 m/s of a 4 m/s walk and the 200 kg one at 0.02 m/s. That is a bound per contact, not a speed limit: catch a light crate up, hit it again, and the kicks stack – the 1 kg one tops out at 5.15 m/s over the walk below. Set the factor to 0 for the pure block; the floor under your feet is exempt at any setting, so jumping onto a crate never drives it into the ground.

The character here weighs 1 kg rather than the 70 kg default, because what a crate takes is M / (M + m) of the approach speed and a light character is what makes three crates of different mass react three different ways.

Walk along the row and watch them: a second and a half of walking at the default sends the 1 kg crate 4.16 m, touching it on only 14 of those 90 frames because it skitters ahead and you have to catch it up; carries the 20 kg one 2.17 m over 44 frames of contact; and moves the 200 kg one 0.03 m while you lean on it for 76, which is a shrug. Drive into the wall instead and nothing happens at all, to the wall or to the character: an immovable body has no finite mass to share, so the push skips it.

The stack at the far end has been left alone long enough to fall asleep. Sleep is per island, so shoving the bottom crate wakes the whole stack rather than sliding one crate out from under two that stay put.

Shows:

• CharacterBody3D.push_factor and .mass: the whole feature, and the factor’s 1.0 default.

• The knob read PER MOVE, not frozen at enter-tree: the +/- keys change it mid-walk, like a “carrying something heavy” state would.

• Mass on both sides of the contact deciding the outcome.

• Floor contacts exempt: standing on a crate imparts nothing to it.

• collisions: the blocking contacts, still handed back, so a game can add physics of its own on top (here: a readout of what was hit last move).

Controls: W A S D - walk the character (arrows also work) Space - jump (land on a crate: standing on it shoves nothing) + / - - raise / lower push_factor (starts at the default, 1.0) 0 - push_factor = 0, the opt-out (pure block) R - rebuild the scene Escape - quit

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

Source

"""Character Push: a character shoves what it walks into, as hard as you say.

A character body is position-driven, so nothing about the collision itself moves
what it walks into. ``push_factor`` is the knob that turns the block into a shove,
and it ships ON at ``1.0``: walk into a crate and the crate goes. Godot's character
body and Unity's stock controller leave this to the game; Unreal pushes out of the
box, and so do we.

The impulse per blocking contact is ``push_factor * (M * m / (M + m)) *
approach_speed``, ``M`` being the character's ``mass`` and ``m`` the mass of what
it hit. That middle term is the pair's reduced mass, and times the approach speed
it is the arrest impulse of a perfectly inelastic collision -- which is exactly
why ``1.0`` is safe to ship: one contact hands the crate ``M / (M + m)`` of your
approach speed and never more, so at the 1 kg character here the 1 kg crate leaves
its first contact at 2.00 m/s of a 4 m/s walk and the 200 kg one at 0.02 m/s. That
is a bound per contact, not a speed limit: catch a light crate up, hit it again,
and the kicks stack -- the 1 kg one tops out at 5.15 m/s over the walk below. Set
the factor to ``0`` for the pure block; the floor under your feet is exempt at any
setting, so jumping onto a crate never drives it into the ground.

The character here weighs 1 kg rather than the 70 kg default, because what a crate
takes is ``M / (M + m)`` of the approach speed and a light character is what makes
three crates of different mass react three different ways.

Walk along the row and watch them: a second and a half of walking at the default
sends the 1 kg crate 4.16 m, touching it on only 14 of those 90 frames because it
skitters ahead and you have to catch it up; carries the 20 kg one 2.17 m over 44
frames of contact; and moves the 200 kg one 0.03 m while you lean on it for 76,
which is a shrug. Drive into the wall instead and nothing happens at all, to the
wall or to the character: an immovable body has no finite mass to share, so the
push skips it.

The stack at the far end has been left alone long enough to fall asleep. Sleep is
per island, so shoving the bottom crate wakes the whole stack rather than sliding
one crate out from under two that stay put.

Shows:
  - ``CharacterBody3D.push_factor`` and ``.mass``: the whole feature, and the
    factor's ``1.0`` default.
  - The knob read PER MOVE, not frozen at enter-tree: the +/- keys change it
    mid-walk, like a "carrying something heavy" state would.
  - Mass on both sides of the contact deciding the outcome.
  - Floor contacts exempt: standing on a crate imparts nothing to it.
  - ``collisions``: the blocking contacts, still handed back, so a game can add
    physics of its own on top (here: a readout of what was hit last move).

Controls:
    W A S D - walk the character (arrows also work)
    Space   - jump (land on a crate: standing on it shoves nothing)
    + / -   - raise / lower push_factor (starts at the default, 1.0)
    0       - push_factor = 0, the opt-out (pure block)
    R       - rebuild the scene
    Escape  - quit

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

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

from __future__ import annotations

from simvx.core import (
    BodyMode,
    BoxShape3D,
    Camera3D,
    CharacterBody3D,
    CollisionShape3D,
    DirectionalLight3D,
    Input,
    InputMap,
    Key,
    Material,
    Mesh,
    MeshInstance3D,
    Node,
    PhysicsBody3D,
    Text2D,
    Vec3,
)
from simvx.graphics import App

#: Walking speed, world units per second, and the take-off speed of a jump:
#: enough to clear a 1 m crate with a little to spare.
_SPEED = 4.0
_JUMP_SPEED = 7.0
#: How much one press of + or - moves the knob, and how far it may travel here.
#: The range brackets the shipped default of 1.0 on both sides.
_PUSH_STEP = 0.1
_PUSH_MAX = 2.0
#: The character's mass, in kg. Deliberately not the 70 kg default: the transfer
#: is ``mass / (mass + crate mass)`` of the approach speed, so a light character
#: is what makes three crates of different mass react three different ways.
_CHAR_MASS = 1.0
#: Half-extents of the character's collider, and the height its centre rides at.
_CHAR_HALF = Vec3(0.35, 0.9, 0.35)
#: The three crates, as (mass, z): identical in every way but their mass, and
#: tinted darker as they get heavier so the row reads without the HUD.
_CRATES = ((1.0, -2.5), (20.0, 0.0), (200.0, 2.5))
_CRATE_HALF = 0.5
_CRATE_X = 2.0
#: Where the sleeping stack sits, and how many crates are in it.
_STACK_X = 6.5
_STACK_Z = -2.5
_STACK_COUNT = 3
#: The wall the character can lean on all day without either of them moving.
_WALL_X = 6.5
_WALL_Z = 2.5

_GROUND = Material(colour=(0.20, 0.22, 0.26, 1.0), roughness=0.95)
_WALL = Material(colour=(0.42, 0.40, 0.46, 1.0), roughness=0.9)
_CRATE_TINTS = (
    Material(colour=(0.95, 0.78, 0.30, 1.0), roughness=0.5),
    Material(colour=(0.85, 0.48, 0.20, 1.0), roughness=0.6),
    Material(colour=(0.55, 0.22, 0.16, 1.0), roughness=0.75),
)
#: Alternating tints down the stack, so three crates read as three and not as one column.
_STACK = (
    Material(colour=(0.35, 0.55, 0.80, 1.0), roughness=0.6),
    Material(colour=(0.55, 0.70, 0.90, 1.0), roughness=0.6),
)
_CHARACTER = Material(colour=(0.45, 0.85, 0.55, 1.0), emissive_colour=(0.08, 0.25, 0.12, 0.6), roughness=0.4)


class CharacterPushScene(Node):
    def on_ready(self):
        InputMap.add_action("walk_forward", [Key.W, Key.UP])
        InputMap.add_action("walk_back", [Key.S, Key.DOWN])
        InputMap.add_action("walk_left", [Key.A, Key.LEFT])
        InputMap.add_action("walk_right", [Key.D, Key.RIGHT])
        InputMap.add_action("jump", [Key.SPACE])
        InputMap.add_action("push_up", [Key.EQUAL, Key.KP_ADD])
        InputMap.add_action("push_down", [Key.MINUS, Key.KP_SUBTRACT])
        InputMap.add_action("push_off", [Key.KEY_0])
        InputMap.add_action("rebuild", [Key.R])
        InputMap.add_action("quit", [Key.ESCAPE])

        cam = self.add_child(Camera3D(position=(-3.5, 7.0, 9.5)))
        cam.look_at((2.5, 0.5, 0.0))

        sun = DirectionalLight3D(position=(6, 12, 8))
        sun.colour = (1.0, 0.96, 0.85)
        sun.intensity = 3.0
        sun.look_at((0, 0, 0))
        self.add_child(sun)
        # A dim fill from the camera side: without it the faces turned toward the
        # viewer are the ones the sun never reaches, and the wall reads as a hole.
        fill = DirectionalLight3D(position=(-6, 6, 10))
        fill.colour = (0.60, 0.68, 0.85)
        fill.intensity = 1.0
        fill.look_at((2, 0, 0))
        self.add_child(fill)

        self._cube = Mesh.cube()
        self._props: list[PhysicsBody3D] = []
        self._crates: list[PhysicsBody3D] = []
        self._stack: list[PhysicsBody3D] = []
        self._character: CharacterBody3D | None = None
        self._push = float(CharacterBody3D.push_factor.default)
        self._build()

        self._hud = self.add_child(
            Text2D(
                text="WASD walk | +/- push_factor | 0 no push | R reset",
                position=(10, 10),
                font_scale=1.3,
            )
        )
        self._status = self.add_child(Text2D(text="", position=(10, 34), font_scale=1.1))
        self._note = self.add_child(Text2D(text="", position=(10, 58), font_scale=1.0))

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

    def _box(self, *, mode, position, half, material, mass=1.0, scale=None) -> PhysicsBody3D:
        body = PhysicsBody3D(mode=mode, position=position, mass=mass)
        body.add_child(CollisionShape3D(shape=BoxShape3D(half_extents=half)))
        body.add_child(MeshInstance3D(mesh=self._cube, material=material, scale=scale or (half * 2)))
        self.add_child(body)
        self._props.append(body)
        return body

    def _build(self):
        for body in self._props:
            body.destroy()
        if self._character is not None:
            self._character.destroy()
        self._props, self._crates, self._stack = [], [], []

        self._box(
            mode=BodyMode.STATIC,
            position=(3.0, -0.5, 0.0),
            half=Vec3(14.0, 0.5, 14.0),
            material=_GROUND,
        )
        self._box(
            mode=BodyMode.STATIC,
            position=(_WALL_X, 1.5, _WALL_Z),
            half=Vec3(0.5, 1.5, 3.0),
            material=_WALL,
        )
        for tint, (mass, z) in zip(_CRATE_TINTS, _CRATES, strict=True):
            crate = self._box(
                mode=BodyMode.DYNAMIC,
                position=(_CRATE_X, _CRATE_HALF, z),
                half=Vec3(_CRATE_HALF, _CRATE_HALF, _CRATE_HALF),
                material=tint,
                mass=mass,
            )
            self._crates.append(crate)
        for i in range(_STACK_COUNT):
            self._stack.append(
                self._box(
                    mode=BodyMode.DYNAMIC,
                    position=(_STACK_X, _CRATE_HALF + i * (_CRATE_HALF * 2 + 0.02), _STACK_Z),
                    half=Vec3(_CRATE_HALF, _CRATE_HALF, _CRATE_HALF),
                    material=_STACK[i % len(_STACK)],
                    mass=2.0,
                )
            )

        character = CharacterBody3D(position=(-2.0, _CHAR_HALF.y, 0.0))
        character.add_child(CollisionShape3D(shape=BoxShape3D(half_extents=_CHAR_HALF)))
        character.add_child(MeshInstance3D(mesh=self._cube, material=_CHARACTER, scale=_CHAR_HALF * 2))
        character.push_factor = self._push
        character.mass = _CHAR_MASS
        self.add_child(character)
        self._character = character
        self._start_x = [float(c.world_position.x) for c in self._crates]

    # -- frame --------------------------------------------------------------

    def on_update(self, dt: float):
        if Input.is_action_just_pressed("quit"):
            self.app.quit()
            return
        if Input.is_action_just_pressed("rebuild"):
            self._build()
            return
        if Input.is_action_just_pressed("push_up"):
            self._push = min(_PUSH_MAX, self._push + _PUSH_STEP)
        if Input.is_action_just_pressed("push_down"):
            self._push = max(0.0, self._push - _PUSH_STEP)
        if Input.is_action_just_pressed("push_off"):
            self._push = 0.0

        character = self._character
        # Written every frame, not only when it changes: the knob is read per move,
        # so this is all a "carrying something heavy" state would have to do.
        character.push_factor = self._push

        x = Input.get_strength("walk_right") - Input.get_strength("walk_left")
        z = Input.get_strength("walk_back") - Input.get_strength("walk_forward")
        # Gravity is the caller's job: move_and_slide never integrates it. Applied
        # every frame, grounded or not, which is the usual character loop: standing
        # on something therefore presses into it at 18 * dt every step, and the
        # crate under your feet still does not sink, because a floor contact takes
        # no push.
        fall = (0.0 if character.is_on_floor() and character.velocity.y < 0.0 else character.velocity.y) - 18.0 * dt
        if Input.is_action_just_pressed("jump") and character.is_on_floor():
            fall = _JUMP_SPEED
        character.velocity = Vec3(x * _SPEED, fall, z * _SPEED)
        character.move_and_slide(dt)

        travel = " ".join(
            f"{mass:g}kg {float(c.world_position.x) - x0:+.2f}m"
            for (mass, _), c, x0 in zip(_CRATES, self._crates, self._start_x, strict=True)
        )
        self._status.text = f"push_factor {self._push:.2f}   crate travel: {travel}"
        asleep = sum(1 for c in self._stack if c.is_sleeping)
        hit = len(character.collisions)
        self._note.text = f"stack asleep {asleep}/{len(self._stack)} | blocking contacts last move: {hit}"


def _selftest() -> bool:
    """Headless: the default shoves by mass, the opt-out shoves nothing, walls do not move."""
    from simvx.graphics.testing import assert_not_blank, save_png

    app = App(title="Character Push", width=1280, height=720, visible=False)
    scene = CharacterPushScene(name="CharacterPushScene")
    frames = app.run_headless(scene, frames=120, capture_frames=[119])
    assert_not_blank(frames[0])
    save_png(frames[0], "/tmp/physics_character_push_test.png")

    world = scene._character.world
    character = scene._character

    def place(x: float, z: float) -> None:
        """Teleport through the seam: nothing is stepping the tree in here, so a
        node-level pose write would not reach the simulated body."""
        pos, rot = world.body_transform(character.handle)
        world.set_body_transform(character.handle, (Vec3(x, _CHAR_HALF.y, z), rot))

    def walk_into(target_z: float, push_factor: float, steps: int = 90) -> None:
        """Put the character behind the crate at ``target_z`` and drive it forwards."""
        character.push_factor = push_factor
        place(_CRATE_X - 1.8, target_z)
        for _ in range(steps):
            character.velocity = Vec3(_SPEED, 0.0, 0.0)
            character.move_and_slide(1.0 / 60.0)
            world.step(1.0 / 60.0)
            world.drain_contact_events()
            world.drain_overlap_events()

    def crate_x(body) -> float:
        """The simulated pose, not the node's: the tree is not syncing in here."""
        return float(world.body_transform(body.handle)[0][0])

    def crate_y(body) -> float:
        return float(world.body_transform(body.handle)[0][1])

    light, medium, heavy = scene._crates
    start = [crate_x(c) for c in scene._crates]

    # Standing on a crate, at the strongest push this example offers, before
    # anything has been shoved: the contact under the feet is classified as floor
    # and exempted, so a 6 m/s landing is not an impulse into the crate. Ends
    # with the crate exactly where it began, so the shoves below are unaffected.
    light_y0 = crate_y(light)
    character.push_factor = _PUSH_MAX
    pos, rot = world.body_transform(character.handle)
    world.set_body_transform(character.handle, (Vec3(start[0], 3.0, _CRATES[0][1]), rot))
    character.velocity = Vec3()
    for _ in range(180):
        # The scene's own loop: gravity every step, so a grounded character keeps
        # pressing down at 18/60 m/s rather than going still.
        grounded = character.is_on_floor() and character.velocity.y < 0.0
        character.velocity = Vec3(0.0, (0.0 if grounded else character.velocity.y) - 18.0 / 60.0, 0.0)
        character.move_and_slide(1.0 / 60.0)
        world.step(1.0 / 60.0)
    stood_moved = crate_y(light) - light_y0
    print(f"landing on the 1 kg crate at push_factor {_PUSH_MAX:g} moved it {stood_moved:+.4f} m vertically")

    walk_into(_CRATES[0][1], 0.0)
    optout_travel = crate_x(light) - start[0]
    print(f"push_factor 0.0 against the 1 kg crate: {optout_travel:+.4f} m")

    # The default, against all three, so the order the intro claims is measured.
    default_factor = float(CharacterBody3D.push_factor.default)
    travel = []
    for (mass, z), crate, x0 in zip(_CRATES, scene._crates, start, strict=True):
        walk_into(z, default_factor)
        travel.append(crate_x(crate) - x0)
        print(f"push_factor {default_factor:g} against {mass:g} kg: {travel[-1]:+.4f} m")
    light_travel, medium_travel, heavy_travel = travel

    # The wall: same shove, into something with infinite mass.
    wall = scene._props[1]
    wall_x = crate_x(wall)
    character.push_factor = default_factor
    place(_WALL_X - 2.0, _WALL_Z)
    for _ in range(180):
        character.velocity = Vec3(_SPEED, 0.0, 0.0)
        character.move_and_slide(1.0 / 60.0)
        world.step(1.0 / 60.0)
    wall_moved = crate_x(wall) - wall_x
    print(f"walking into the wall for three seconds moved it {wall_moved:+.4f} m")

    # The sleeping stack: one island, so shoving the bottom crate wakes all of it.
    stack_asleep = sum(1 for c in scene._stack if c.is_sleeping)
    top_x0 = crate_x(scene._stack[-1])
    character.push_factor = default_factor
    place(_STACK_X - 2.0, _STACK_Z)
    for _ in range(180):
        character.velocity = Vec3(_SPEED, 0.0, 0.0)
        character.move_and_slide(1.0 / 60.0)
        world.step(1.0 / 60.0)
    top_moved = crate_x(scene._stack[-1]) - top_x0
    print(f"stack asleep before the shove: {stack_asleep}/{len(scene._stack)}; top crate moved {top_moved:+.4f} m")

    print("screenshot: /tmp/physics_character_push_test.png")

    ok = (
        abs(optout_travel) < 0.05  # push_factor 0 imparts nothing
        and light_travel > 0.5  # the shipped default shoves
        and heavy_travel < medium_travel < light_travel  # and mass decides how far
        and abs(wall_moved) < 1e-6  # an immovable body absorbs it
        and stack_asleep == len(scene._stack)  # the stack really had settled
        and abs(top_moved) > 0.1  # and the whole island woke, not just the bottom crate
        and abs(stood_moved) < 0.02  # standing on a body is not a shove
    )
    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="Character Push", width=1280, height=720)
    app.run(CharacterPushScene())