This project is a template for developing apps and extensions for Omniverse Kit.
- Fork and clone this repo, for example in
C:\projects\kit-project-template
- (Optional) Open this cloned repo using Visual Studio Code:
code C:\projects\kit-project-template
. It will suggest installing a few extensions to improve python experience. - In the terminal (CTRL + `) run
pull_kit_kernel.bat
(windows) /pull_kit_kernel.sh
(linux) to pull the Omniverse Kit Kernel.kit
folder link will be created. - Run an example app that includes example extensions:
source/apps/my_name.my_app.bat
(windows) /./source/apps/my_name.my_app.sh
(linux).
The first start will take a while as it will pull all the extensions from the extension registry and build various caches. Subsequent starts will be much faster.
If you look inside a source/apps/my_name.my_app.bat
or any other Omniverse App, they all run Omniverse Kit . Omniverse Kit (kit.exe
) is the Omniverse Application runtime that powers Apps build out of extensions.
Think of it as python.exe
. It is a small runtime, that enables all the basics, like settings, python, logging and searches for extensions. Everything else is an extension.
To start an app we pass a kit
file, which itself is a single file extension. It describes which extensions to pull and load, which settings to apply. One kit file fully desribes an app.
Notice that it includes omni.hello.world
extension, that is a part of this repo. All the other extensions are pulled from the extension registry on first startup.
More info on building kit files: doc
To package an app run tools/package.bat
(or repo package
). The package will be created in the _build/packages
folder.
To use the package, unzip and run pull_kit_kernel.bat
inside the package once before running the app.
App kit
file fully defines all the extensions, but their versions are not locked. By default latest versions will be used. Also, many extensions would bring many other extensions as their dependencies.
However, for the final app it is important that it will will always get the same extensions and the same versions on each run. It provides reliable and reproducible build. This is called a version lock and we have a separate section at the end of kit
file to lock versions of all extensions and all their dependencies.
It is important to update the version lock section when adding new extensions or updating existing ones. To update version look precache_exts
tool is used.
To update version lock run: tools/update_version_lock.bat
.
Commit any changes to a kit file.
Packaging tool will verify that version lock exist and fail if it doesn't.
More info on dependency management: doc
This template includes one simple extension: omni.hello.world
. It is loaded in the example app, but can also be loaded and tested in any other Omniverse App.
- Install Omniverse Launcher: download
- Install and launch one of Omniverse apps in the Launcher. For instance: Code.
If you want to add extensions from this repo to your other existing Omniverse App.
- In the Omniverse App open extension manager: Window → Extensions.
- In the Extension Manager Window open a settings page, with a small gear button in the top left bar.
- In the settings page there is a list of Extension Search Paths. Add cloned repo
source/extensions
subfolder there as another search path:C:/projects/kit-project-template/source/extensions
- Now you can find
omni.hello.world
extension in the top left search bar. Select and enable it. - "My Window" window will pop up. Extension Manager watches for any file changes. You can try changing some code in this extension and see them applied immediately with a hotreload.
- Now that
source/extensions
folder was added to the search you can add new extensions to this folder and they will be automatically found by the App. - Look at the Console window for warnings and errors. It also has a small button to open current log file.
- All the same commands work on linux. Replace
.bat
with.sh
and\
with/
. - Extension name is a folder name in
source/extensions
, in this example:omni.hello.world
. - Most important thing extension has is a config file:
extension.toml
, take a peek. - In the Extensions window, press Bread button near the search bar and select Show Extension Graph. It will show how the current App comes to be: all extensions and dependencies.
- Extensions system documentation can be found here
To get a better understanding and learn a few other things, we recommend following:
- Run bare
kit.exe
withsource/extensions
folder added as an extensions search path and new extension enabled:
> kit\kit.exe --ext-folder source/extensions --enable omni.hello.world
--ext-folder [path]
- adds new folder to the search path--enable [extension]
- enables an extension on startup.
Use -h
for help:
> kit\kit.exe -h
- After the App started you should see:
- new "My Window" window popup.
- extension search paths in Extensions window as in the previous section.
- extension enabled in the list of extensions.
It starts much faster and will only have extensions enabled that are required for this new extension (look at [dependencies]
section of extension.toml
). You can enable more extensions: try adding --enable omni.kit.window.extensions
to have extensions window enabled (yes, extension window is an extension too!):
> kit\kit.exe --ext-folder source/extensions --enable omni.hello.world --enable omni.kit.window.extensions
You should see a menu in the top left. From here you can enable more extensions from the UI.
To run tests we run a new process where only the tested extension (and it's dependencies) is enabled. Like in example above + testing system (omni.kit.test
extension). There are 2 ways to run extension tests:
- Run:
tools\test_ext.bat omni.hello.world
That will run a test process with all tests and exit. For development mode pass --dev
: that will open test selection window. As everywhere, hotreload also works in this mode, give it a try by changing some code!
- Alternatively, in Extension Manager (Window → Extensions) find your extension, click on TESTS tab, click Run Test
For more information about testing refer to: testing doc.
Adding a new extension is as simple as copying and renaming existing one:
- copy
source/extensions/omni.hello.world
tosource/extensions/[new extension name]
- rename python module (namespace) in
source/extensions/[new extension name]/omni/hello/world
tosource/extensions/[new extension name]/[new python module]
- update
source/extensions/[new extension name]/config/extension.toml
, most importantly specify new python module to load:
[[python.module]]
name = "[new python module]"
No restart is needed, you should be able to find and enable [new extension name]
in extension manager.
To make extension available to other users use Github Releases.
- Make sure the repo has omniverse-kit-extension topic set for auto discovery.
- For each new release increment extension version (in
extension.toml
) and update the changelog (indocs/CHANGELOG.md
). Semantic versionning must be used to express severity of API changes.
The source code for this repository is provided as-is and we are not accepting outside contributions.
By using this solution you agree to the terms of this License . The most recent version of the License is available here.