Kinematic bodies and per-body gravity

10 · Contact and friction

A kinematic paddle (is_kinematic=True) turns at 1.2 rad/s and sweeps boxes as if it had infinite mass. Steel holds a kinematic body's joint coordinates as given, so the script writes its pose and velocity every step, then runs eval_fk so the collision pipeline sees the new body pose. The box above it was added with disable_gravity=True and tumbles in place.

drag to orbit · scroll to zoom

0.00 s

What to look at

The boxes are pushed outward, and none of them moves the paddle.
The floating box keeps its height.

Key parameter

is_kinematic / disable_gravity

Arguments of add_body. Write a kinematic body's joint_q and joint_qd each step, then call newton.eval_fk so body_q and body_qd match before collide.

Try changing

Leave out the joint_qd write and compare the push.
Make the paddle move along x instead of turning.

Concept

Kinematic bodies

What it is

A kinematic body moves on a prescribed path and is not pushed back by contacts. Steel gives its joint an armature of 1e10, so it has no response, and holds its coordinates as written. The script writes pose and velocity, then runs eval_fk so collision sees the same pose.

In this scene

The paddle sweeps the ring of boxes outward (mean radius 0.32 → 0.40 m) and is not slowed.

Considerations

Accuracy: Contacts use the written velocity; write a consistent velocity or the push is wrong.
Interactions: A kinematic global body may touch every world; a kinematic global articulation with joints may not.
Use it when: Conveyors, robot playback and moving platforms whose motion is known.

The script

cd tutorials && python 10_kinematic_bodies.py prints each variant's final metric; --record out.json also writes the replay. Every tutorial imports replay.py from the same folder.

10_kinematic_bodies.py
replay.py

# SPDX-FileCopyrightText: Copyright (c) 2026 Skild AI and the Steel contributors
# SPDX-License-Identifier: Apache-2.0

"""Kinematic bodies and per-body gravity: a prescribed paddle sweeps boxes."""

import math

import newton
import numpy as np
import warp as wp
from newton.solvers import SolverSteel

from replay import Recorder

DT = 1.0 / 240.0
SUBSTEPS = 8
SPIN = 1.2  # rad/s


def build():
    builder = newton.ModelBuilder()
    builder.add_ground_plane(cfg=newton.ModelBuilder.ShapeConfig(mu=0.5))
    paddle = builder.add_body(
        xform=wp.transform((0.0, 0.0, 0.05), wp.quat_identity()), is_kinematic=True
    )
    builder.add_shape_box(paddle, hx=0.42, hy=0.015, hz=0.04)
    for k in range(10):
        a = 2.0 * math.pi * (k + 0.5) / 10
        box = builder.add_body(
            xform=wp.transform((0.32 * math.cos(a), 0.32 * math.sin(a), 0.03), wp.quat_identity())
        )
        builder.add_shape_box(
            box,
            hx=0.03,
            hy=0.03,
            hz=0.03,
            cfg=newton.ModelBuilder.ShapeConfig(density=300.0, mu=0.5),
        )
    floater = builder.add_body(
        xform=wp.transform((0.0, 0.0, 0.4), wp.quat_identity()), disable_gravity=True
    )
    builder.add_shape_box(
        floater, hx=0.04, hy=0.04, hz=0.04, cfg=newton.ModelBuilder.ShapeConfig(density=300.0)
    )
    model = builder.finalize()
    qd = model.joint_qd.numpy()
    qd[-3:] = (0.3, 0.5, 0.0)  # the floater tumbles in place
    model.joint_qd.assign(qd)
    return model


def move_paddle(model, state, t):
    """Prescribe the paddle's pose at time t; Steel holds kinematic joint coordinates as given."""
    angle = SPIN * t
    q, qd = state.joint_q.numpy(), state.joint_qd.numpy()
    q[0:7] = (0.0, 0.0, 0.05, 0.0, 0.0, math.sin(angle / 2), math.cos(angle / 2))
    qd[0:6] = (0.0, 0.0, 0.0, 0.0, 0.0, SPIN)
    state.joint_q.assign(q)
    state.joint_qd.assign(qd)
    # collision reads body poses, so bring them up to date with the joint coordinates
    newton.eval_fk(model, state.joint_q, state.joint_qd, state)


def simulate(rec, label):
    model = build()
    solver = SolverSteel(model)
    pipeline = newton.CollisionPipeline(model)
    contacts = pipeline.contacts()
    state_0, state_1, control = model.state(), model.state(), model.control()
    newton.eval_fk(model, model.joint_q, model.joint_qd, state_0)

    run = rec.variant(label, model)
    t = 0.0
    for _ in range(rec.frames(5.0)):
        q = state_0.body_q.numpy()
        box_r = np.linalg.norm(q[1:-1, :2], axis=1)
        run.frame(state_0, mean_box_radius=box_r.mean(), floater_z=q[-1, 2])
        for _ in range(SUBSTEPS):
            move_paddle(model, state_0, t + DT)
            pipeline.collide(state_0, contacts)
            solver.step(state_0, state_1, control, contacts, DT)
            state_0, state_1 = state_1, state_0
            t += DT
    run.check(solver)


if __name__ == "__main__":
    rec = Recorder()
    simulate(rec, "kinematic paddle at 1.2 rad/s")
    rec.save()

# SPDX-FileCopyrightText: Copyright (c) 2026 Skild AI and the Steel contributors
# SPDX-License-Identifier: Apache-2.0

"""Record Steel tutorial runs as replay JSON for the tutorials page, or print a summary.

Every tutorial imports this module. ``python NN_name.py`` runs the variants and prints
the final metric of each; ``--record out.json`` also writes body poses, shapes and metric
series that the page replays in 3D.
"""

import argparse
import base64
import json
import os
import subprocess
import sys
import time

import newton
import numpy as np
import warp as wp

from source_hash import source_sha256

_RENDERED_TYPES = {
    newton.GeoType.PLANE,
    newton.GeoType.SPHERE,
    newton.GeoType.CAPSULE,
    newton.GeoType.ELLIPSOID,
    newton.GeoType.CYLINDER,
    newton.GeoType.BOX,
    newton.GeoType.MESH,
    newton.GeoType.CONE,
    newton.GeoType.CONVEX_MESH,
}


class Recorder:
    """Collect the variants of one tutorial; ``fps`` is the replay frame rate."""

    def __init__(self, fps: int = 30):
        parser = argparse.ArgumentParser()
        parser.add_argument(
            "--record", metavar="OUT.json", help="write a replay file for the tutorials page"
        )
        parser.add_argument("--device", default=None, help="Warp device, for example cuda:0")
        self.args = parser.parse_args()
        if self.args.device:
            wp.set_device(self.args.device)
        self.fps = fps
        self.script = os.path.abspath(sys.argv[0])
        self.variants: list[Variant] = []

    def frames(self, seconds: float) -> int:
        """Number of replay frames in ``seconds``, including the first."""
        return int(round(seconds * self.fps)) + 1

    def variant(
        self,
        label: str,
        model: newton.Model,
        *,
        ghost: bool = False,
        slot: int | None = None,
        scene: str | None = None,
    ) -> "Variant":
        """Start one run; ``ghost`` overlays run ``slot``, ``scene`` groups runs for charts."""
        variant = Variant(label, model, self.fps, ghost, slot, scene)
        self.variants.append(variant)
        return variant

    def save(self) -> None:
        """Print a summary and, with ``--record``, write the replay file."""
        for variant in self.variants:
            last = variant.metrics[-1] if variant.metrics else {}
            flag = "  (rows dropped)" if variant.overflow else ""
            print(f"{variant.label:<48} {json.dumps(last)}  {variant.wall:.2f} s{flag}")
        if not self.args.record:
            return
        source_sha = source_sha256(self.script)
        doc = {
            "script": os.path.basename(self.script),
            "script_sha256": source_sha,
            "newton_commit": _newton_commit(),
            "newton_version": newton.__version__,
            "warp_version": wp.config.version,
            "gpu": wp.get_device().name,
            "fps": self.fps,
            "variants": [v.to_json() for v in self.variants],
        }
        with open(self.args.record, "w") as f:
            json.dump(doc, f, separators=(",", ":"))
        print(f"wrote {self.args.record}")


class Variant:
    """One recorded run: a pose per frame for every body, plus named metric values."""

    def __init__(self, label, model, fps, ghost, slot, scene):
        self.label, self.model, self.fps, self.ghost, self.slot = label, model, fps, ghost, slot
        self.scene = scene
        self.poses: list[np.ndarray] = []
        self.metrics: list[dict] = []
        self.awake: list[list[int]] = []
        self.particles: list[np.ndarray] = []
        self.overflow = False
        self.start = time.perf_counter()
        self.wall = 0.0

    def frame(self, state: newton.State, awake=None, particles=None, **metrics) -> None:
        """Record ``state.body_q``, optional awake flags, particle positions and metric values."""
        self.poses.append(state.body_q.numpy().astype(np.float32).copy())
        if particles is not None:
            self.particles.append(particles.numpy().astype(np.float32).copy())
        self.metrics.append({k: _round(v) for k, v in metrics.items()})
        if awake is not None:
            self.awake.append([int(x) for x in awake.numpy()])
        self.wall = time.perf_counter() - self.start

    def check(self, solver) -> None:
        """Note whether the solver dropped rows; call once after the run."""
        try:
            solver.check_constraint_capacity()
        except RuntimeError:
            self.overflow = True

    def to_json(self) -> dict:
        poses = (
            np.stack(self.poses)
            if self.poses
            else np.zeros((0, self.model.body_count, 7), np.float32)
        )
        return {
            "label": self.label,
            "fps": self.fps,
            "ghost": self.ghost,
            "slot": self.slot,
            "scene": self.scene,
            "bodies": int(self.model.body_count),
            "frames": int(poses.shape[0]),
            "poses": base64.b64encode(poses.astype(np.float32).tobytes()).decode(),
            "shapes": _shape_table(self.model),
            "metric": self.metrics,
            "awake": self.awake or None,
            "particles": self._particles_json(),
            "wall_s": round(self.wall, 3),
            "overflow": self.overflow,
        }

    def _particles_json(self):
        if not self.particles:
            return None
        frames = np.stack(self.particles)
        tris = self.model.tri_indices
        radius = self.model.particle_radius.numpy()
        return {
            "count": int(frames.shape[1]),
            "frames": base64.b64encode(frames.astype(np.float32).tobytes()).decode(),
            "radius": round(float(radius.mean()), 5) if radius.size else 0.0,
            "tris": [int(v) for v in tris.numpy().reshape(-1)]
            if tris is not None and tris.shape[0]
            else None,
        }


def _shape_table(model):
    types = model.shape_type.numpy()
    scales = model.shape_scale.numpy()
    xforms = model.shape_transform.numpy()
    bodies = model.shape_body.numpy()
    flags = model.shape_flags.numpy()
    shapes = []
    for i, t in enumerate(types):
        if int(t) not in _RENDERED_TYPES or not flags[i] & int(newton.ShapeFlags.VISIBLE):
            continue
        shape = {
            "b": int(bodies[i]),
            "t": int(t),
            "s": [round(float(v), 5) for v in scales[i]],
            "x": [round(float(v), 6) for v in xforms[i]],
        }
        if int(t) in (newton.GeoType.MESH, newton.GeoType.CONVEX_MESH):
            mesh = model.shape_source[i]
            shape["v"] = [round(float(v), 5) for v in np.asarray(mesh.vertices).reshape(-1)]
            shape["i"] = [int(v) for v in np.asarray(mesh.indices).reshape(-1)]
        shapes.append(shape)
    return shapes


def _round(value):
    value = float(value)
    return round(value, 5) if np.isfinite(value) else None


def _newton_commit():
    if os.environ.get("NEWTON_COMMIT"):
        return os.environ["NEWTON_COMMIT"]
    try:
        root = os.path.dirname(os.path.dirname(newton.__file__))
        return subprocess.check_output(["git", "-C", root, "rev-parse", "HEAD"], text=True).strip()
    except (OSError, subprocess.CalledProcessError):
        return None

Recorded with SolverSteel on Newton 1.9.0.dev0, Warp 1.19.0, NVIDIA RTX PRO 6000 Blackwell Server Edition. Replays read the state back every frame, so they are not a speed benchmark. Script · page text

Steel docs and tutorials are licensed under Apache-2.0. Third-party notices. "Skild", "Skild AI" and the Skild logo are trademarks of Skild AI and are not licensed under Apache-2.0.