Discover the live Isaac Sim MCP runtime and its explicit limitations.

Returns the Isaac Sim version, selected adapter, active physics backend, adapter-owned PhysX/Newton matrix, extension states, sensor warm-up policy, feature flags, and unsupported arguments. This query is read-only and works while the USD stage is still starting.

Read supervisor, crash, restart, and protocol-health state without requiring Isaac Sim.

This local diagnostic remains available when the extension socket is closed. It never starts, stops, or mutates Isaac Sim and never replays a failed command.

List the exact gripper and mobile-base profiles accepted by high-level controller tools.

Set total gripper opening width using an explicit robot profile.

The profile validates exact joint names and types before applying any position target. width_m is the total distance between both fingers.

Open a gripper to the profile's declared open width with immediate target read-back.

Close a gripper to the profile's declared closed width with immediate target read-back.

Apply a profiled differential or holonomic base velocity target.

The timeline must be playing for a non-zero command. Targets persist until replaced, so always call stop_mobile_base at the end of motion. Differential profiles reject non-zero lateral velocity.

Set every profiled wheel velocity target to zero and verify the stop target read-back.

Get size, type, hash, expiry, and producer metadata for a managed artifact.

Read one bounded base64 chunk from a managed artifact.

Delete one managed artifact after validating its opaque handle.

Delete expired managed artifacts and report reclaimed capacity.

Ping the Isaac Sim extension server and return scene information including stage path, assets root, and prim count.

Create a physics scene with ground plane. Call get_scene_info first to verify connection.

Args: gravity: Gravity vector [x, y, z]. Default is standard gravity. scene_name: Name for the physics scene prim.

Remove all prims from the scene.

Also empties any environment loaded by load_environment, so a later create_physics_scene(floor=True) does not stack a second ground under the first. The stage's defaultLight is always kept — a stage with no light renders black, which looks like a broken camera.

Args: keep_physics: If True, keep physics scene prims. keep_environment: If True, keep the loaded environment. Reloading one costs seconds, so pass this when clearing objects between attempts.

List all prims in the scene, optionally filtered by type.

Args: root_path: Root path to start listing from. prim_type: Filter by prim type (e.g. "Mesh", "Xform").

Get detailed information about a specific prim.

Returns type, children, and a transform block holding position, rotation [rx, ry, rz] in degrees (XYZ order, the same convention transform_object accepts), and scale. For geometric prims (Cube, Sphere, Cylinder, Cone, Capsule), also returns actual_size [x, y, z] in meters accounting for scale and default primitive dimensions.

Args: prim_path: The USD prim path to inspect.

List all available environments discovered from the Isaac Sim asset server. Includes warehouses, offices, outdoor scenes, and more.

Load a pre-built environment into the scene. Supports fuzzy matching. Call list_environments first to see available options.

Many shipped environments are authored Y-up and/or in centimeters; those are rotated and rescaled to match the stage, and the response reports what was applied under "corrections". It also returns "bounds" with the environment's extent and floor_height, so objects can be placed on the ground without a second query. Read prim_path from the response rather than assuming it — it defaults to a named child of /Environment.

Args: environment: Environment name or search term (e.g. "warehouse", "hospital", "office"). prim_path: Prim path for the loaded environment. Defaults to /Environment/, which keeps it separate from the stage's default lighting and lets clear_scene remove it.

Preview or create a new empty stage. Requires scratch_stage=true, a scratch_root, stopped timeline, and defaults to preview-only.

Preview or open a local USD stage inside scratch_root. Destructive stage replacement requires explicit scratch_stage=true.

Preview or export the current stage to a different local USD file inside scratch_root. Source overwrite is always rejected.

Read the root layer, full layer stack, prim count, references/payloads, variant selections, semantics, and stage metadata.

Preview or add/remove a root-layer subLayer path with stopped-timeline and exact read-back checks.

Preview or edit a reference/payload arc. Payloads also support load/unload; every mutation is read back and rolled back on failure.

Preview or select an existing USD variant after validating the set and available names.

Read Isaac Sim 6.0.1 LabelsAPI taxonomies and labels, plus any legacy semantic labels.

Preview or apply Isaac Sim 6.0.1 UsdSemantics LabelsAPI labels under one taxonomy with read-back.

Read a USD attribute value, declared type, and authored-value state in JSON-safe form.

Preview or set a finite, explicitly typed USD attribute. Existing attributes require overwrite=true and cannot change type.

Preview or atomically apply up to 100 layer/arc/variant/semantic/attribute edits. Any failed operation restores the stage snapshot.

Create a primitive object (Cube, Sphere, Cylinder, Cone, Capsule, Plane).

Prefer size for absolute sizing: size is the target in METERS (default 1.0), so size=0.3 gives a 0.3 m object regardless of type.

scale is a RAW MULTIPLIER of the primitive's NATIVE size, not meters. Native sizes: Cube/Sphere/Cylinder/Cone/Capsule = 2 m, Plane = 1 m. So scale=0.5 on a Cube -> 1 m, and scale=[0.4,0.4,0.3] -> a 0.8 x 0.8 x 0.6 m box (0.4 * 2 m), which surprises callers who expect 0.4 m. Use scale only for deliberate non-uniform shaping; otherwise use size. If both are given, scale wins and size is ignored.

Returns prim_path, actual_size [x, y, z] in meters, and bounding_box (min/max corners in world coordinates) so you can accurately place other objects relative to this one.

Args: object_type: Type of primitive — Cube, Sphere, Cylinder, Cone, Capsule, or Plane (case-insensitive; "cube" is normalized to "Cube"). position: [x, y, z] world position. rotation: [rx, ry, rz] rotation in degrees. scale: [sx, sy, sz] RAW multiplier of the native size (2 m for most prims, 1 m for Plane). NOT meters. Overrides size. size: Target size in METERS (default 1.0). Absolute; independent of the primitive's native size. Ignored if scale is provided. color: [r, g, b] color values (0-1). physics_enabled: Enable physics on this object. prim_path: Custom prim path. Auto-generated if not provided.

Delete an object; Camera/LiDAR use verified lifecycle teardown.

Args: prim_path: The prim path of the object to delete. post_delete_updates: Camera/LiDAR verification updates, from 1 to 240. Ignored for ordinary prims.

Set the transform (position, rotation, scale) of an existing object.

Args: prim_path: The prim path of the object to transform. position: [x, y, z] new world position. rotation: [rx, ry, rz] new rotation in degrees. scale: [sx, sy, sz] new scale factors.

Duplicate an existing object to a new prim path.

Args: source_path: Prim path of the object to clone. target_path: Prim path for the cloned object. position: [x, y, z] position for the clone. Keeps original position if not set.

Atomically configure rigid/static body, collider approximation and mass.

body_type is dynamic, kinematic, or static. approximation is one of none, convex_hull, convex_decomposition, mesh_simplification, bounding_cube, or bounding_sphere. Mass uses kg and density uses kg/m^3. The timeline must be stopped.

Read authored rigid body, collider, approximation, mass and density.

Create a USD collision group and return relationship read-back.

Read collision group members, filters, inversion and merge name.

Create fixed, revolute, or prismatic joint with explicit local frames.

Positions and prismatic limits are meters; revolute limits are degrees. Quaternion rotations use [w, x, y, z]. Axis is X, Y, or Z.

Read joint type, body targets, frames, axis, limits and units.

Read Replicator extension, orchestrator, job, writer, and trigger state.

Preview or create a bounded manual-trigger BasicWriter SDG job.

Randomizers are typed records. transform accepts prim_paths and optional position/rotation/scale min/max vectors. light accepts prim_paths and optional intensity/color min/max values.

Preview or asynchronously start one configured SDG job.

Read bounded SDG job progress, lifecycle state, and cleanup read-back.

Preview or request cancellation; resources detach at the next safe point.

Return a terminal job manifest and managed artifact handles.

Preview or delete one terminal job record and optionally its artifacts.

Read ROS 2 bridge/core/nodes state, domain source, distro, and workflow count.

List MCP-owned ROS 2 publisher graphs below a USD root.

Preview or create a playback-driven ROS 2 Clock publisher graph.

Preview or create a 6.0-style ComputeTransformTree to ROS 2 TF publisher.

Preview or create an IsaacReadJointState ROS 2 JointState publisher graph.

Preview or create a ROS2CameraHelper publisher for an MCP camera runtime.

The camera prim must first be created with create_camera. Its owned render product is resolved automatically; render_product_path is an explicit override for externally-created render products.

Preview or create a ROS2RtxLidarHelper publisher for an MCP RTX LiDAR runtime.

The LiDAR prim must first be created with create_lidar. Its owned render product is resolved automatically; render_product_path is an explicit override for externally-created render products.

Preview or delete one MCP-owned ROS 2 workflow; foreign graphs are refused.

Spawn animated NVIDIA human characters into the CURRENT USD stage.

Uses Isaac Sim 6.0+'s isaacsim.replicator.agent.core (IRA 1.x) character loader and SimReady assets. Unlike IRA.setup_simulation(), this tool does not reopen the environment USD, so existing scene edits are preserved.

A NavMesh is required. The tool can bake an authored volume and waits up to 2000 update frames for complex factory stages. The extension is enabled automatically, but the tool fails closed when no usable NavMesh or character assets are available. Stop the timeline first.

execute_script remains useful for one-off IRA experiments. reload_script is the better companion for reusable interaction or event logic after characters have been spawned.

Args: count: Number of new characters to add, from 1 to 25. group_name: USD-safe IRA group name. Reusing it appends characters. root_prim_path: Parent prim for all characters. asset_path: Character asset directory. Defaults to Isaac/People/Characters/. motion_library_path: Human motion-library USD. Defaults to the IRA extension setting / Isaac Sim asset root. behavior: wander, patrol, stop, or manual. Use manual when interaction scripts will issue Behavior Agent tasks directly. spawn_areas: Optional NavMesh area names used for spawning. speed_range: Two walking speeds in m/s. distance_range: Two wander-leg distances in meters. idle_time_range: Two idle/stop durations in seconds. patrol_points: Required for patrol; reachable NavMesh points as [[x,y,z], ...]. position: Optional exact world position for one spawned character. The point should lie on the NavMesh. rotation: Optional [rx, ry, rz] degrees; requires count=1. auto_create_navmesh_volume: Create one include-volume when the stage has none. This modifies the current stage and requires navmesh_volume_size. navmesh_volume_center: Center of the new NavMesh volume. Defaults to [0, 0, 1]. navmesh_volume_size: Full [x, y, z] size in stage units. Make it cover the walkable floor and surrounding obstacles. seed: Deterministic 32-bit IRA randomization seed.

List IRA human characters without changing the stage.

Return USD and live Behavior Agent state for one IRA human.

Delete one MCP-owned human. Preview is enabled by default.

Issue a Behavior Agent MoveTo task to exactly one target.

Issue a Behavior Agent LookAt task; zero duration means indefinite.

Cancel the active action by issuing Idle, optionally facing one target.

Update supported live Behavior Agent settings with read-back.

Return Navigation Core, NavMeshVolume, bake and area status.

Bake the current stage NavMesh with a bounded wait; preview by default.

Start an eligible asset or sensor command as a bounded background job.

Motion and SDG starts retain their typed tools; their returned IDs can still be queried and cancelled through the unified job tools.

Read a managed, motion, or SDG job without executing it again.

Request cancellation and return a predictable terminal lifecycle state.

List the bounded retained managed-job registry.

Create a light in the scene.

Args: light_type: Type of light — DistantLight, DomeLight, SphereLight, RectLight, DiskLight, or CylinderLight. position: [x, y, z] world position. intensity: Light intensity. color: [r, g, b] light color (0-1). rotation: [rx, ry, rz] rotation in degrees. prim_path: Custom prim path. Auto-generated if not provided.

Modify properties of an existing light.

Args: prim_path: The prim path of the light to modify. intensity: New intensity value. color: [r, g, b] new light color (0-1).

Create a robot in the scene from the Isaac Sim asset library.

Supports fuzzy matching — e.g. "franka", "spot", "g1", "go1". Call list_available_robots first to see all available robots. Call create_physics_scene before creating robots.

Returns prim_path, robot_key, joint_names, and num_dof so you can immediately use set_joint_positions without a follow-up get_robot_info call.

Args: robot_type: Robot name or search term. Fuzzy matched against available robots. position: [x, y, z] world position. name: Custom name for the robot prim. prim_path: Exact USD prim path (e.g. "/World/Franka"). Overrides name-based path.

List all available robots discovered from the Isaac Sim asset server. Returns robot keys, descriptions, manufacturers, and asset paths. The list is auto-discovered at startup and reflects the actual assets available in your Isaac Sim version.

Force re-scan the asset server for available robots. Use this if new robot assets were added.

Get robot joint information including names, DOF count, joint types, and limits.

Call this after create_robot to understand the robot's kinematic structure. Returns joint names ordered by DOF index, joint types (revolute/prismatic), and joint limits (degrees for revolute, meters for prismatic).

Args: prim_path: The prim path of the robot.

Set target joint positions on a robot via ArticulationAction.

Units: radians for revolute joints, meters for prismatic joints (e.g. gripper fingers). Use get_robot_info to discover joint names, types, and limits first. After calling this, use step_simulation to advance and observe the result — do not use play_simulation + sleep.

Args: prim_path: The prim path of the robot. joint_positions: List of target joint position values. joint_indices: Optional list of joint indices to set. Sets all joints if not provided.

Read current joint positions from a robot.

Units: radians for revolute joints, meters for prismatic joints. Joint order matches the joint_names from get_robot_info. For a combined step-and-read, prefer step_simulation with observe_joints.

Args: prim_path: The prim path of the robot.

Read measured joint state and active command targets.

Returns position, velocity, measured effort, position/velocity/effort targets, joint name/index mapping, joint type, and explicit units. Use either joint_names or joint_indices for a subset; the selectors are mutually exclusive. Revolute units are radians, radians_per_second, and newton_meters. Prismatic units are meters, meters_per_second, and newtons.

Args: prim_path: USD path of the articulation root. joint_names: Optional exact, case-sensitive joint names in requested order. joint_indices: Optional DOF indices in requested order.

Apply an atomic position, velocity, or effort joint command.

All selectors and values are validated before the adapter is called, so an unknown name, invalid index, duplicate selector, non-finite value, or length mismatch applies nothing. Effort commands must be renewed every simulation update; this tool applies one update's effort command.

Args: prim_path: USD path of the articulation root. mode: One of position, velocity, or effort. values: Command values ordered by the selected joints. joint_names: Optional exact, case-sensitive joint subset. joint_indices: Optional DOF-index subset; mutually exclusive with joint_names.

Atomically update drive gains, limits, or drive type for selected joints.

The timeline must be stopped. Numeric fields must be finite and non-negative. Values use runtime SI units: revolute gains are per radian, revolute velocity is radians_per_second, and prismatic velocity is meters_per_second. drive_type is force or acceleration. All inputs are validated before writing, and an apply failure triggers rollback.

Args: prim_path: USD path of the articulation root. stiffness: Optional proportional gain applied to every selected joint. damping: Optional derivative gain applied to every selected joint. max_force: Optional maximum drive effort. max_velocity: Optional maximum joint velocity; PhysX only. drive_type: Optional force or acceleration drive mode. joint_names: Optional exact, case-sensitive joint subset. joint_indices: Optional DOF-index subset; mutually exclusive with joint_names.

Solve bounded Lula inverse kinematics without moving the robot.

Quaternion order is scalar-first [w, x, y, z]. The explicit warm-start and random seed make repeated requests reproducible. The result reports achieved end-effector errors and whether collision checking was done.

Plan a bounded joint trajectory and return an opaque trajectory_id.

planner="rrt" uses NVIDIA Lula RRT and reports collision_checked=true; planner="cspace" creates a deterministic spline and explicitly reports collision_checked=false. start_joint_positions defaults to measured state; pass it explicitly for reproducible offline planning. This call never executes.

Start a trajectory job and return immediately without blocking the MCP worker.

Cancel a running motion job and hold its last commanded position.

Read motion job state, progress, timing, and terminal error details.

Release and delete one Camera or LiDAR, then verify it stays absent.

Args: prim_path: Managed Camera or LiDAR prim path. post_delete_updates: Kit updates used to detect delayed prim or render-product reappearance. Range 1 to 240.

Add a camera sensor to the scene.

Args: prim_path: Prim path for the camera. position: [x, y, z] world position. rotation: [rx, ry, rz] rotation in degrees. resolution: [width, height] image resolution. Default 1280x720.

Capture an RGB image from a camera sensor.

Args: prim_path: Prim path of the camera. output_path: Optional explicit .png path for artifact mode. If omitted, uses the managed artifact root. return_mode: metadata, artifact, or inline. Defaults to artifact. inline_max_bytes: Maximum PNG bytes allowed in inline mode. Maximum configurable value is 4 MiB.

Capture a typed RTX camera annotator output.

Args: prim_path: Prim path of the camera. output_type: depth, distance_to_image_plane, semantic_segmentation, instance_segmentation, instance_id_segmentation, normals, or motion_vectors. output_path: Optional explicit .npy path for artifact mode. return_mode: metadata, artifact, or inline. Defaults to artifact. inline_max_bytes: Maximum raw bytes allowed in inline mode. Maximum is 4 MiB.

Read camera intrinsics, extrinsics, projection, resolution, and units.

Add a lidar sensor to the scene.

Args: prim_path: Prim path for the lidar. position: [x, y, z] world position. rotation: [rx, ry, rz] rotation in degrees. config: Isaac Sim 6 supported preset name, such as Example_Rotary or OS1. variant: Optional preset variant string or variant-set mapping. horizontal_fov_deg: Generic sensor horizontal field of view in degrees. vertical_fov_deg: Generic sensor vertical field of view in degrees. horizontal_resolution_deg: Generic sensor horizontal angular resolution. vertical_resolution_deg: Generic sensor vertical angular resolution. rotation_rate_hz: Integer generic rotary scan rate from 1 to 100 Hz. min_range_m: Generic sensor minimum range in meters. max_range_m: Generic sensor maximum range in meters.

Read effective LiDAR FOV, angular resolution, rate, range, and USD schema values.

Get typed point cloud fields from a lidar sensor.

Args: prim_path: Prim path of the lidar sensor. output_path: Optional explicit .npz path for artifact mode. return_mode: metadata, artifact, or inline. Defaults to artifact. inline_max_bytes: Maximum encoded NPZ bytes allowed in inline mode.

Create a PBR or physics material.

Args: material_type: "pbr" for visual material or "physics" for physics material. prim_path: Prim path for the material. Auto-generated if not set. color: [r, g, b] diffuse color (0-1). PBR only. roughness: Surface roughness (0-1). PBR only. metallic: Metallic value (0-1). PBR only. static_friction: Static friction coefficient (>=0). Physics only. dynamic_friction: Dynamic friction coefficient (>=0 and <= static). Physics only. restitution: Bounciness from 0 to 1. Physics only.

Read PBR or physics material parameters and explicit units.

Bind a material to an object.

Args: material_path: Prim path of the material. target_prim_path: Prim path of the object to apply the material to. material_purpose: auto, physics, or visual. Auto selects from the material schema.

Read the resolved physics or visual material binding on a prim.

List NVIDIA assets that can be spawned through MCP.

Combines a verified Isaac/SimReady/Vegetation prop catalog with the robot library discovered from the running Isaac Sim 6.0 asset root.

Args: category: Optional category: robot_arm, quadruped, agv, robot_other, conveyor, warehouse, factory, or vegetation, lifting, or instrumentation. query: Optional case-insensitive text filter across key, description, manufacturer, and asset path. max_results: Maximum returned entries, from 1 to 250.

Spawn one catalog asset into the CURRENT USD stage.

Call list_nvidia_assets first to obtain an exact asset_key. Robot keys create controllable articulations through the existing robot handler. Props, conveyors, warehouse equipment, and vegetation are referenced from verified NVIDIA USD paths and remain compatible with transform_object, clone_object, and delete_object.

Args: asset_key: Exact key returned by list_nvidia_assets. prim_path: Optional absolute destination prim path. A unique path under /World/Assets is generated when omitted. position: Optional world [x, y, z]. rotation: Optional XYZ Euler degrees [rx, ry, rz]. scale: Optional [sx, sy, sz] multiplier.

Import a robot from a URDF file into the scene.

Args: urdf_path: Path to the URDF file. prim_path: Prim path for the imported robot. position: [x, y, z] world position.

Load a USD asset from a URL or file path into the scene.

Args: usd_url: URL or local path to the USD file. prim_path: Prim path for the loaded asset. position: [x, y, z] world position. scale: [sx, sy, sz] scale factors.

Search the NVIDIA USD asset library by text description, then load the best match.

Args: text_prompt: Text description of the 3D asset to search for. target_path: Prim path for the loaded result. position: [x, y, z] world position. scale: [sx, sy, sz] scale factors.

Generate a 3D model from text or image using Beaver3D, then load it into the scene.

Args: text_prompt: Text description for 3D generation. image_url: URL of an image for 3D generation. position: [x, y, z] world position for the generated model. scale: [sx, sy, sz] scale factors.

Start the physics simulation.

Pause the physics simulation.

Stop the physics simulation and reset to spawn state.

Resets articulations and rigid bodies to their spawn pose (the state captured at first Play), like the Isaac UI Stop button. Call this to return the scene to a clean starting point before another run.

Advance the simulation by exactly N physics frames on a FROZEN timeline.

step is self-contained: it initialises physics on first call and operates on a paused/stopped timeline, so N is always exact and observations correlate to a known frame count.

Do NOT call play_simulation before or during the debug loop; step is for a frozen timeline. If the timeline is already playing, step returns an error (a free run cannot be counted frame-by-frame). Use play_simulation ONLY for a final continuous run / ScriptNode-driven demo, never for debugging.

Typical debug loop (no play):

1. set_joint_positions to command the robot

2. step_simulation with observe_prims and observe_joints

3. get_joint_config if drives are not tracking correctly

4. get_physics_state if objects are not behaving as expected

5. Adjust and repeat

Args: num_steps: Number of simulation frames to step. observe_prims: List of prim paths to observe (returns position + velocity). observe_joints: List of articulation prim paths to observe (returns joint positions).

Atomically configure Isaac Sim 6 PhysX scene parameters.

The timeline must be stopped. time_step must be within [0.0001, 1.0] seconds and map to an integer PhysX steps-per-second value (for example, 1/60 or 1/120). Isaac Sim's Stage time codes and minimum simulation frame-rate are synchronized to that rate. Enabling GPU physics selects GPU dynamics and GPU broadphase; disabling it selects MBP broadphase. This does not change the launcher-controlled physics GPU ordinal. Success includes both USD and runtime read-back; failed application is rolled back as one transaction.

Args: gravity: Gravity vector [x, y, z]. time_step: Physics time step in seconds. gpu_enabled: Enable or disable GPU dynamics and matching broadphase.

Diagnostic tool: recent WARN/ERROR logs plus captured print() output.

Captures carb.log_*/omni.log WARN+ERROR and stdout from execute_script / reload_script (tagged [PRINT]). Plain print() outside those captured contexts may not appear.

Defaults are agent-friendly: non-destructive (clear=False) and scoped to the current run (since_last_play=True) so you see logs from what you just did, not stale entries from previous runs.

Args: clear: If True, empty the buffer after reading. Default False. count: Maximum number of log entries to return. since_last_play: If True (default), return only entries since the last timeline Play. Set False for the full buffer. filter_command_id: Return only structured records for this command. severity: Optional structured-record severity filter. source: Optional structured-record source filter (for example kit or dispatcher).

Get the current simulation state: timeline status (playing/stopped/paused), simulation time, and physics dt. step_simulation does NOT require a running timeline — do not play just to step.

Diagnostic tool: get physics state for a prim.

Returns rigid body status, mass, velocities, kinematic flag, and collision info. Velocity units: linear_velocity in m/s, angular_velocity in rad/s. Velocities are only non-zero once the simulation has advanced — step the simulation (or play) before reading them. Call this when:

• Objects fall through the ground (check collision enabled)

• Objects don't move when expected (check is_kinematic, mass)

• Grasping fails (check collision on gripper fingers and target object)

Args: prim_path: USD path to the prim to inspect.

Diagnostic tool: get joint drive configuration for a robot articulation.

Returns stiffness, damping, limits, target vs actual positions, and position error for each joint. Call this when:

• Joint drives are not tracking targets (check position_error)

• Joints are oscillating or unstable (check stiffness/damping ratio)

• Joints hit limits unexpectedly (check lower_limit/upper_limit)

Args: prim_path: USD path to the robot articulation root.

Escape hatch: execute arbitrary Python code in Isaac Sim.

PREFER named tools over this for: reading/setting joints (set_joint_positions, get_joint_positions), inspecting state (get_prim_info, get_physics_state, get_joint_config), stepping simulation (step_simulation), and checking logs (get_isaac_logs).

USE this only for a trusted operation that no named tool covers. Execution is policy-gated, cooperatively timed, output-bounded, cwd-restricted, and audited by code hash. Background scheduling is denied unless both the request and administrator policy explicitly opt in.

CAUTION: touching an articulation controlled by a running ScriptNode / Action Graph can silently break its control path (no error is raised). While a graph is running, read-only diagnostics (get_prim_info, get_physics_state, get_joint_positions, get_isaac_logs) are safe, but stop_simulation before using execute_script or named write tools on the same articulation.

For persistent controllers (>20 lines), write a .py file and load it with reload_script instead of pasting code here.

Args: code: Python code to execute in the Isaac Sim context. cwd: Optional working directory to add to sys.path before execution. timeout_s: Cooperative Python deadline; capped by extension policy. max_output_bytes: Combined per-stream capture limit; capped by policy. allow_background: Request background scheduling. Default false and rejected unless the extension policy also enables it.

Reload a Python controller from a file on disk.

Two modes, chosen automatically:

• If any Action-Graph ScriptNode references this file (inputs:scriptPath), those ScriptNodes are force-recompiled so your on-disk edits take effect on the running graph. This is how you iterate on a ScriptNode controller.

• Otherwise the file is (re-)executed as a standalone controller, the way you would use execute_script for code longer than ~20 lines.

Workflow:

1. Write the controller as a .py file (attach via create_action_graph script_file=... for ScriptNode use)

2. reload_script to load / recompile it

3. step_simulation to debug (frozen timeline) or play for a ScriptNode demo

4. Edit the file and reload_script again to iterate

The file's directory is auto-added to sys.path.

Args: file_path: Path to the Python file on disk. module_name: Optional module name to reload (e.g. 'my_controller'). timeout_s: Cooperative Python deadline; capped by extension policy. max_output_bytes: Per-stream capture limit; capped by policy.

Return the current execute/reload policy without exposing script source or credentials.

Return bounded script audit metadata. Source code is represented only by SHA-256.

Create and wire an OmniGraph Action Graph.

Builds a complete Action Graph with nodes, connections and attribute values using og.Controller.edit(). This is the programmatic equivalent of creating an Action Graph in the visual editor.

Args: graph_path: USD prim path for the graph (default "/World/ActionGraph"). nodes: List of node definitions. Each dict has: - "path": Node path relative to graph (e.g. "OnPlaybackTick") - "type": OmniGraph node type (e.g. "omni.graph.action.OnPlaybackTick") connections: List of [source_attr, target_attr] pairs for wiring nodes. Each attr is "NodePath.outputs:attrName" or "NodePath.inputs:attrName". values: List of attribute value overrides. Each dict has: - "attr": Full attribute path (e.g. "ScriptNode.inputs:script") - "value": The value to set evaluator: Graph evaluator type (default "execution", what Action Graphs use). "push" evaluates every application update regardless of the timeline, so an OnPlaybackTick-driven ScriptNode would keep running even while the simulation is stopped. script_file: Convenience shortcut — path to a local Python script file. When provided, automatically creates OnPlaybackTick → ScriptNode nodes, wires them, and attaches the script file (sets usePath + scriptPath). The nodes and connections parameters are ignored when script_file is set. RECOMMENDED for anything you will iterate on — edit the file and reload_script "just works", with the better reload story. inline_script: Convenience shortcut — inline Python (must define setup(db)/compute(db)). Auto-creates OnPlaybackTick → ScriptNode, wires them, and sets the script inline (usePath=False). For small, static graphs. For anything you will iterate on, prefer script_file — it has the better reload story (edit the file + reload_script "just works"; inline edits need edit_action_graph).

Example (inline script — one-step): create_action_graph( inline_script="def setup(db): pass\ndef compute(db): return True" )

Example (script file — one-step, recommended for iteration): create_action_graph( script_file="/path/to/controller.py" )

Edit an existing OmniGraph Action Graph: set attribute values or add connections.

Use this to update ScriptNode scripts (inline or file path), change attribute values, or add new connections on an already-created graph.

For ScriptNode with a local file script, set both usePath and scriptPath: values=[ {"attr": "ScriptNode.inputs:usePath", "value": true}, {"attr": "ScriptNode.inputs:scriptPath", "value": "/path/to/script.py"} ]

For ScriptNode with inline script: values=[ {"attr": "ScriptNode.inputs:usePath", "value": false}, {"attr": "ScriptNode.inputs:script", "value": "def compute(db): ..."} ]

Args: graph_path: USD prim path of the existing graph (default "/World/ActionGraph"). values: List of attribute value overrides. Each dict has: - "attr": Attribute path relative to graph (e.g. "ScriptNode.inputs:script") - "value": The value to set connections: List of [source_attr, target_attr] pairs to add.

List Action Graphs below a USD root, including disabled graphs by default.

Args: root_path: USD subtree to inspect. include_disabled: Include graphs whose evaluation is disabled.

Read one Action Graph's nodes, edges, state, and optional values or script source.

Script source is omitted by default because inline source and local file contents may be large or sensitive.

Preview or delete one exact Action Graph, with deletion read-back.

Preview or connect one source output to one target input in an Action Graph.

Preview or remove one exact connection from an Action Graph.

Preview or enable/disable one Action Graph and read back its effective state.

Read one Action Graph's enabled, evaluation, and error status.

Explicitly evaluate one exact Action Graph and return post-evaluation status.

Preview or configure one exact ScriptNode in explicit inline/file mode.

mode='inline' requires inline_script and forbids script_file. mode='file' requires script_file and forbids inline_script. The extension validates the mode before mutating the graph.

Preview or recompile one exact ScriptNode without cross-graph fallback.

Supply mode='inline' with inline_script to replace inline source. For mode='file', script_file may select a new canonical local file; when omitted, the node's existing canonical file path is reloaded. Omitting mode asks the extension to retain and validate the node's current mode.