Python Scripting Component - User Manual

The workflow for using Python Scripting Components is as follows:

1. Create a new Python script (BehaviorScript).

2. Add Python Scripting Components to a USD prims in the stage.

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

4. Associated scripts will be executed in context of the USD prim they are assigned to.

5. Edit Python scripts using your system editor that is associated with .py files.

Creating New Python Scripts

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

Then proceed by right clicking in the file area, the right side of the Content window, to see New Python Script context menu options.

Both of these context menu options will create a new script in the folder that is selected and will contain 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)

This will open a pop-up dialog where you can specify the name of the Python file to be created.

Note

Ensure you don’t have any items selected in the right section of the Content window to see the New Script File context menu options.

Adding Python Scripting Components

From any selected USD prim(s) in the USD stage, begin by right clicking Add > Python Scripting.

This will add a new Python Scripting section in the Property window for the selected USD 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, press the Add Asset… button.

This will next present an open file dialog. From here, navigate to the script file that can be on your local file system path or any Omniverse™ connection path. Then press the Select button for the selected script file.

All scripts that are associated with a Python Scripting Component on a prim will be loaded and unloaded based on the following:

• Scripts are loaded when the USD stage is opened or when they are assigned to USD prims in an open stage.

• Scripts are unloaded when the USD stage is closed or when they are unassigned from a prims in an open stage.

Note

When a USD stage is opened, the system checks for any scripts that are assigned to a prims in the USD stage. If any scripts are assigned, the user will receive a warning pop-up dialog regarding of risks associated with script execution. The user can decide if they still want to proceed with script execution or not.

Script files that contain a class that inherits from the base class omni.kit.scripting.BehaviorScript will receive the events for each USD prim that have assigned the script to them for following overridden methods:

Overridden Method	Event Invoked…
on_init()	When a script handles being assigned to a USD prim.
on_destroy()	When a script handles being unassigned from a USD prim.
on_play()	When a script handles the Play button being pressed.
on_pause()	When a script handles the Pause button being pressed.
on_stop()	When a script handles the Stop button being pressed.
on_update()	When a script handles update/tick events when timeline is playing.

These events are invoked for each USD prim they are assigned to.

Script Editing

To edit a script from the Content window, right click any .py script file to use either the Open or Edit Python Script. This will launch the text editor that is currently associated with .py files.

If there has been no System Editor associated with .py files, the following default text editor will be used:

System	Default Editor
Windows	notepad
Linux	gedit

Note

If you are not sure which Python editor to use, you can start using Visual Studio Code and enable the Python extension within the Editor.

Script Hot-Reloading

Any changes saved to a .py file will cause the script to be reloaded. When a script is reloaded, any USD prim with any scripts assigned to them will invoke their on_destroy() followed by on_init() immediately after the script is reloaded.

Therefore, you can make iterative changes to the script file while its loaded and the changes will take effect immediately.

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

Any errors generated from users scripts will be logged as an Error in the Console window. They will be logged as a Python Scripting Error:, which will include a traceback of the most recent call and cause. This will indicate the script file, the line number, and the reason for the error.

Script Debugging

Local and Nucleus hosted scripts can be debugged when you have VS Code installed and the VS Code Link extension loaded.

To debug a Python script, you must edit the script from the Content window by right clicking any .py script file and selecting either Open or Edit Python Script.

When you have VS Code installed, this will launch VS Code from the folder the script file is contained in and open the script file. This will generate a .vscode folder with the appropriate launch.json configuration within it that includes a Python: Attach target.

Then use the Run/Debug menu in VS Code and pick Python: Attach. Then press the Start Debugging arrow, next to the debugger configuration drop-down list, to start debugging.

You can set breakpoints in the code, such as on_init, on_destroy, and on_update. This can also include any other code in this script that is referenced within the script folder or sub-folders.

See VS Code Link documentation for further information on debugging with VS Code Link.