isaacsim.physics.manager#

The standalone physics modules expose two complementary APIs:

  • isaacsim.physics.registration is the engine-facing registration API. Backends publish their simulation callbacks and tensor factories there.

  • isaacsim.physics.manager is the application-facing API. Applications attach stages, step simulation, issue scene queries, subscribe to events, and create tensor views there.

Both C++ APIs use declarations from public headers directly. There are no interface objects to acquire or get_*_interface functions.

Registering a backend#

A backend fills a isaacsim.physics.registration.Simulation with the callback groups it supports, then registers that value under a unique name. Unsupported callbacks may remain unset; manager operations skip backends that do not implement the requested operation.

import isaacsim.physics.registration as registration

simulation = registration.Simulation()
simulation.simulation_fns.initialize = lambda ovstage, usd_identifier: True
simulation.simulation_fns.close = lambda: True
simulation.simulation_fns.get_attached_stage = lambda: 0
simulation.simulation_fns.has_attached_stage = lambda: False
simulation.simulation_fns.simulate = lambda elapsed_time, current_time: None
simulation.simulation_fns.simulate_async = lambda elapsed_time, current_time: None
simulation.simulation_fns.fetch_results = lambda: None
simulation.simulation_fns.check_results = lambda: True

simulation_id = registration.register_simulation(simulation, "MyEngine")
try:
    print(registration.get_simulation_name(simulation_id))
finally:
    registration.unregister_simulation(simulation_id)

The callback groups are simulation_fns, scene_query_fns, interaction_fns, and benchmark_fns.

Driving simulation#

Lifecycle and stepping operations are broadcast to every active registered backend. initialize takes a caller-built native stage handle and the identifier format expected by the selected backend. For example, Newton resolves a numeric pxr.UsdUtils.StageCache identifier encoded as a string, while OvPhysX consumes the supplied ovstage handle. A filesystem path is not a portable stage identifier.

Pass the owning Python stage object through owner when the native handle is caller-owned. The binding keeps it alive until every backend confirms detach.

import isaacsim.physics.manager as manager

# ovstage_handle, usd_identifier, and ovstage_owner are created by the caller.
if not manager.initialize(ovstage_handle, usd_identifier, owner=ovstage_owner):
    raise RuntimeError("physics initialization failed")

try:
    manager.simulate(1.0 / 60.0, 0.0)
    manager.simulate_async(1.0 / 60.0, 1.0 / 60.0)
    manager.fetch_results()
finally:
    if not manager.close():
        raise RuntimeError("a backend did not detach its stage")

Subscriptions#

Registry, step, contact, and profile-stat subscriptions return a Subscription object. Retain it for as long as events are needed and call unsubscribe() for deterministic release.

def on_step(elapsed_time, context):
    print(elapsed_time, int(context.simulation_id))


subscription = manager.subscribe_physics_on_step_events(
    pre_step=False,
    order=0,
    on_update=on_step,
)
try:
    manager.simulate(1.0 / 60.0, 0.0)
finally:
    subscription.unsubscribe()

Scene queries#

Scene queries use value types from the registration module and free functions from the manager module.

import isaacsim.physics.manager as manager
import isaacsim.physics.registration as registration

origin = registration.Float3(0.0, 0.0, 10.0)
direction = registration.Float3(0.0, 0.0, -1.0)
hit_found, hit = manager.raycast_closest(
    origin=origin,
    unit_dir=direction,
    distance=100.0,
    both_sides=False,
)
if hit_found:
    print(hit.distance, hit.position)

The manager provides closest, any, and reporting-callback variants for raycasts, sphere and box sweeps, authored-shape sweeps, and overlaps.

Tensor views#

Engine modules register tensor factories with isaacsim.physics.registration. Applications request the high-level Warp view through the manager:

import isaacsim.physics.manager.impl.tensors as tensors

rigid_bodies = tensors.create_entity("ovphysx", "rigid-body", "/World/envs/*/Cube")
transforms = rigid_bodies.get_data("transforms")

The first argument is the name the simulation registered its entity factories under, and the factory resolves the active simulation of that name. A single pattern is expanded by the engine; pass a list to resolve several patterns and concatenate the matches in the given order.

Reads land on the device the view reports through device_ordinal. An engine that cannot report its own device takes the ordinal from the caller, either at construction or later, since every read re-reads it:

rigid_bodies.device_ordinal = 0

Paths alone cannot describe every view, so construction arguments an engine needs beyond them are passed as options:

contacts = tensors.create_entity(
    "ovphysx",
    "rigid-contact",
    "/World/envs/*/Cube",
    {"filter-patterns": ["/World/ground"], "max-contact-data-count": 128},
)
forces = contacts.get_data("contact-force-matrix")

Each engine documents the option names it reads and ignores the rest, so an option one engine does not recognize is not an error.

C++ usage#

Include only the operation headers needed by the caller and link isaacsim::physics-manager and isaacsim::physics-registration.

#include <isaacsim/physics/manager/PhysicsSimulation.hpp>
#include <isaacsim/physics/registration/Physics.hpp>

isaacsim::physics::registration::Simulation simulation;
// Populate the callback groups supported by this backend.
const auto id =
    isaacsim::physics::registration::registerSimulation(simulation, "MyEngine");

const auto result =
    isaacsim::physics::manager::initialize(ovstageHandle, usdIdentifier);
if (result == isaacsim::physics::manager::InitializeResult::eOk)
{
    isaacsim::physics::manager::simulate(1.0f / 60.0f, 0.0f);
    isaacsim::physics::manager::close();
}

isaacsim::physics::registration::unregisterSimulation(id);