Python Behavior Scripting - User Manual

This manual describes how to create, assign, and edit Python Behavior Scripting components on USD prims. You create scripts, add components to prims, assign scripts in the Property window, and edit scripts in your system editor.

Workflow overview:

1. Create a new Python script (BehaviorScript).

2. Add Python Scripting components to USD prims in the stage.

3. Assign scripts in the Python Scripting section of the Property window.

4. The application runs assigned scripts in the context of each prim.

5. Edit Python scripts in the editor associated with .py files on your system.

Creating New Python Scripts

From the Content browser, begin by selecting the folder in the left section of the Content window where you want to create a new script.

Right-click in the file area (the right side of the Content window) to open the New Python Script context menu.

Either option creates a new script in the selected folder with the following contents:

Context Menu Option	File Contents
New Python Script (BehaviorScript)	New Behavior class. (Class inherits from BehaviorScript)
New Python Script (Empty)	No file contents. (Typically used for writing new utilities)

A dialog opens where you enter the name of the Python file.

Note

Clear the selection in the right section of the Content window so the New Python Script context menu options appear.

Adding Python Scripting Components

With one or more USD prims selected in the stage, right-click and choose Add > Python Scripting.

A Python Scripting section appears in the Property window for the selected prims.

Note

This can be done with one or more selected USD prims in the USD stage.

Script Execution

Assign Scripts in the Python Scripting component section of the Property window.

To assign scripts, click Add Asset… or drag a script from the Content window onto Add Asset… in the Property window.

An open-file dialog appears. Navigate to the script on your local file system or an Omniverse connection path, then click Select.

The application loads and unloads scripts that are associated with a Python Scripting component on a prim as follows:

• Scripts load when you open the USD stage or when you assign them to USD prims in an open stage.

• Scripts unload when you close the USD stage or when you unassign them from prims in an open stage.

Note

When you open a USD stage, the application checks for scripts assigned to prims. If any are assigned, you receive a warning dialog about script execution risks. You can allow or block script execution.

Script files that contain a class inheriting from omni.behavior.scripting.core.BehaviorScript receive events for each USD prim that has the script assigned. You can override the following methods:

Overridden Method	Event
on_init()	When the script is assigned to a USD prim.
on_destroy()	When the script is unassigned from a USD prim.
on_play()	When you press Play.
on_pause()	When you press Pause.
on_stop()	When you press Stop.
on_update(current_time, delta_time)	When the timeline is playing (update/tick events).

The application invokes these events for each USD prim the script is assigned to.

Script Editing

To edit a script from the Content window, right-click a .py file and choose Open or Edit Python Script. Your system editor for .py files opens.

If no system editor is associated with .py files, the application uses the following default editor:

System	Default Editor
Windows	notepad
Linux	gedit

Note

If you are not sure which Python editor to use, start with Visual Studio Code and enable the Microsoft Python extension. This is supported on both Windows and Linux and provides a full Python environment with auto-completion for Omniverse Kit SDK APIs. Download: https://code.visualstudio.com/download

Script Hot-Reloading

Saving a .py file reloads the script. On reload, each prim that has that script assigned runs on_destroy() and then on_init().

Make iterative changes to the script while it is loaded; changes apply when you save.

Note

Scripts that are being edited from connected Omniverse paths will automatically be downloaded into temporary local files and opened with the default text editor. Any saved changes to the local file get immediately uploaded back to the connected Omniverse script path. This allows for an effective workflow to quickly edit script files in Omniverse.

Script Errors

Errors from your scripts appear as Error in the Console window. Each entry is prefixed with Python Scripting Error: and includes a traceback (script file, line number, and error reason).

Script Debugging

You can debug local and Nucleus-hosted scripts when VS Code is installed and the VS Code Kit Debugger [omni.kit.debug.vscode] extension is loaded in your Omniverse Kit application.

To debug a Python script, right-click a .py file in the Content window and select Open or Edit Python Script.

With VS Code installed, this launches VS Code in the script’s folder and opens the file. A .vscode folder is created with a launch.json that includes a Python: Attach target.

In VS Code, open the Run and Debug menu and choose Python: Attach. Click the Start Debugging button next to the debugger configuration drop-down to start debugging.

Set breakpoints in the script (for example, in on_init, on_destroy, and on_update) or in any code in the script folder or subfolders.

You have an overview of creating scripts, assigning components, execution and lifecycle, editing, hot-reload, errors, and debugging. For enabling the extension and setting up an editor, refer to Python Behavior Scripting - Getting Started. For Kit scripting APIs, refer to Kit Documentation. For VS Code debugging, refer to VS Code Link documentation.