Title: Python Scripting Component - User Manual# URL Source: https://docs.omniverse.nvidia.com/extensions/latest/ext_python-scripting-component/user_manual.html Published Time: Wed, 01 Oct 2025 18:15:36 GMT Markdown Content: 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[#](https://docs.omniverse.nvidia.com/extensions/latest/ext_python-scripting-component/user_manual.html#creating-new-python-scripts "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 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) | ![Image 1: ../_images/ext_python-scripting-component-create-script-menu.png](https://docs.omniverse.nvidia.com/extensions/latest/_images/ext_python-scripting-component-create-script-menu.png) This will open a pop-up dialog where you can specify the name of the Python file to be created. ![Image 2: ../_images/ext_python-scripting-component-create-script-dialog.png](https://docs.omniverse.nvidia.com/extensions/latest/_images/ext_python-scripting-component-create-script-dialog.png) 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[#](https://docs.omniverse.nvidia.com/extensions/latest/ext_python-scripting-component/user_manual.html#adding-python-scripting-components "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 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. ![Image 3: ../_images/ext_python-scripting-component-add-python-scripting.png](https://docs.omniverse.nvidia.com/extensions/latest/_images/ext_python-scripting-component-add-python-scripting.png) Note This can be done with one or more selected USD prims in the USD stage. Script Execution[#](https://docs.omniverse.nvidia.com/extensions/latest/ext_python-scripting-component/user_manual.html#script-execution "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------- Assign Scripts in the _Python Scripting_ component section of the _Property_ window. To assign Scripts, press the **Add Asset…** button. ![Image 4: ../_images/ext_python-scripting-component-add-assets.png](https://docs.omniverse.nvidia.com/extensions/latest/_images/ext_python-scripting-component-add-assets.png) 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. ![Image 5: ../_images/ext_python-scripting-component-select-assets.png](https://docs.omniverse.nvidia.com/extensions/latest/_images/ext_python-scripting-component-select-assets.png) 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[#](https://docs.omniverse.nvidia.com/extensions/latest/ext_python-scripting-component/user_manual.html#script-editing "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------ 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. ![Image 6: ../_images/ext_python-scripting-component-edit-python-script.png](https://docs.omniverse.nvidia.com/extensions/latest/_images/ext_python-scripting-component-edit-python-script.png) 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[#](https://docs.omniverse.nvidia.com/extensions/latest/ext_python-scripting-component/user_manual.html#script-hot-reloading "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ 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[#](https://docs.omniverse.nvidia.com/extensions/latest/ext_python-scripting-component/user_manual.html#script-errors "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------- 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[#](https://docs.omniverse.nvidia.com/extensions/latest/ext_python-scripting-component/user_manual.html#script-debugging "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------- 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](https://docs.omniverse.nvidia.com/extensions/latest/ext_vs-code-link.html) for further information on debugging with VS Code Link. Links/Buttons: - [#](https://docs.omniverse.nvidia.com/extensions/latest/ext_python-scripting-component/user_manual.html#script-debugging) - [VS Code Link documentation](https://docs.omniverse.nvidia.com/extensions/latest/ext_vs-code-link.html)