Configuration¶
Kit comes with a very rich and flexible configuration system based on Carbonite settings. Settings is a runtime representation of typical configuration formats (like json, toml, xml), and is basically a nested dictionary of values.
Quick Start¶
When you run a kit app it doesn’t load any kit file:
> kit.exe
That will start kit and exit, without enabling any extensions or applying any configuration, except for built-in config: kit-core.json
.
Note
To see all flags call > kit.exe -h
To see default kit settings pass --/app/printConfig=true
:
> kit.exe --/app/printConfig=true
That will print all settings. This syntax --/
is used to apply settings from the command line. Any setting can be modified in this way. You may notice that the config it printed includes app/printConfig
. You can try adding your own settings to the command line and observing them in the printed config to prove yourself that it works as expected.
Another useful flag to learn early is -v
to enable info logging or -vv
to enable verbose logging. There are settings to control logging more precisely, but this is an easy way to get more logging in console and debug startup routine.
> kit.exe -v
To make kit do something let’s enable some extensions:
> kit.exe --enable omni.kit.window.script_editor
That enables a script editor extension. You may also notice that it enabled a few extensions it depends on. You can stack multiple --enable
keywords to enable more extensions.
You can also add more folders to search for extensions in with --ext-folder
:
> kit.exe --enable omni.kit.window.script_editor --ext-folder ./exts --enable foo.bar
That enables you to create e.g exts/foo.bar/extension.toml
and start hacking your own extension right away.
Those flags, like --enable
, --ext-folder
and many others are just shorthand for commonly-used settings. For example, they just respectively append to /app/exts/enabled
and /app/exts/folders
arrays respectively.
Application Config¶
Settings can also be applied by passing a configuration file as a positional argument to Kit:
> kit.exe my.toml
This kind of config file becomes the “Application config”. It receives special treatment from Kit:
Config name becomes application name.
Separate data, documents and cache folders are created for applications.
The Folder where this config is located becomes the application path.
This allows you to build separate applications with their own data.
Kit File¶
A Kit file is the recommended way to configure applications.
> kit.exe my.kit
Kit files are single file extensions (basically renamed extension.toml
files). Only the [settings]
part of them is applied to settings (as with any extension). Here is an example:
[package]
title = "My Script Editor App"
version = "0.1.0"
keywords = ["app"]
[dependencies]
"omni.kit.window.script_editor" = {}
[settings]
foo.bar = "123"
exts."omni.kit.window.script_editor".windowOpenByDefault = true
As with any extension, it can be named, versioned and even published to the registry. It defines dependencies in the same format to pull in additional extensions.
Notice that the setting windowOpenByDefault
of the script editor extension is being overriden. Any extension can define its own settings and a guideline is to put them in the extension.toml
file of the extension. Check extension.toml
file for omni.kit.window.script_editor
. Another guideline is to use root exts
namespace and the name of extension next.
The goal of the .kit file is to bridge the gap between settings and extensions and have one file that user can click and run Kit-based application (associate .kit
file with kit.exe
in OS).
User Settings¶
You can create system wide configuration files to override any setting. There are 2 places to put them:
To override settings of any kit application in the shared documents folder, typically in (on Windows):
C:\Users\[username]\Documents\Kit\shared\user.toml
To override settings of particular application in the application documents folder, typically in:
C:\Users\[username]\Documents\Kit\apps\[app_name]\user.toml
To override settings of any kit application locally (near the application .kit file), typically in (on Windows):
<app .kit file>\<0 or more levels above>\deps\user.toml
To override settings of particular application locally (near the application .kit file), typically in:
<app .kit file>\<0 or more levels above>\deps\[app_name]\user.toml
To find those folders you can run Kit with info logging enabled and look for [omni.kit.app.plugin] Tokens:
message at the beginning. Look for documents
and shared_documents
tokens. For more info: Tokens.
Special Keys¶
Appending Arrays¶
When configs are merged one value can override another. Sometimes we want instead to append values for array. You can use the special ++
key for that. For example to add additional extension folder to /app/folders
settings you can do:
[app.exts]
folders."++" = ["c:/temp"]
You can put that for instance in user.toml
described above to add more extension folder search paths.
Importing Other Configs¶
You can use the @import@
key to import other config files in that location:
[foo]
"@import@": ["./some.toml"],
That will import config some.toml
under the key foo
. The ./
syntax implies that the config file is in the same folder.
Portable Mode¶
Regular kit-based app installation sets and uses system wide data, cache, logs folders. It also reads global Omniverse config in a known system-specific location. To know which folders where set you can look at tokens, like ${data}
, ${cache}
, ${logs}
. They can be found in the beginning of each log file.
Kit based app can also run in portable mode, to use specified folder as a root for all those folders. First of all that is useful for developers, local builds by default run in portable mode. There are few different ways to run kit in portable mode:
Cmd Args¶
Pass --portable
to run kit in portable mode and optionally pass --portable-root [path]
to specify location of portable root.
Portable Configs (Markers)¶
Kit looks for following configs that force it to run in portable mode. It reads content of a file if it finds one and treats it as a path. If path is relative - it is relative to this config folder. Priority of search is:
App portable config, e.g.
foo.portable
nearfoo.kit
when run with:kit.exe foo.kit
Kit portable config near experience, e.g.
kit.portable
nearfoo.kit
when run with:kit.exe foo.kit
Kit portable config near
kit.exe
, e.g.kit.portable
nearkit.exe
Changing Configuration With Command line¶
Sometimes it is convenient to change some of the settings via command line, as was mentioned at the start you can do it by providing the full path to the parameter separated by the /
and prefixed by the --/
.
For example, if the required option is ignoreUnsavedOnExit
as shown in the printed JSON configuration:
<ISettings root>:
{
"app": {
"hangDetector": {
"enabled": false,
"timeout": 120
},
"file": {
"ignoreUnsavedOnExit": false,
...
},
...
},
...
}
Then to change its value to true
you need to add --/app/file/ignoreUnsavedOnExit=true
to the command line:
> kit.exe --/app/file/ignoreUnsavedOnExit=true
To specify a boolean value true
and false
strings must be used.
Note
The values are case-insensitive and using
--/some/path/to/parameter=false
or--/some/path/to/parameter=FaLsE
produces the same resultIf you need to set the string value
"true"
or"false"
escape it with double quotes:--/some/path/to/text_parameter=\"false\"
It is also possible to use
--/some/path/to/parameter=0
or--/some/path/to/parameter=1
to set a setting totrue
orfalse
correspondingly. In this case the actual value in the settings will be an integer but functions working with settings will correctly convert it to a boolean.
Setting a numeric or string value is straightforward:
> kit.exe --/some/number=7 --/another/number=1.5 --/some/string=test
If you need to set a string value that can be parsed as a number or a boolean or if the string value contains whitespaces use double quotes to escape it:
> kit.exe --/sets/string/value=\"7\" --/sets/string/with/whitespaces=\"string with spaces\"
Note
Do not forget to escape the quotes so the OS doesn’t remove them
To set an array value you can:
Specify individual array elements by adding their index in the array at the end of the path to the value:
> kit.exe --/some/array/1=17
will change... "some": { "array" : [1, 2, 3], }, ...
into
... "some": { "array" : [1, 17, 3], }, ...
Specify all array elements in the form
[value0,value1,...]
:
> kit.exe --/some/array=[8,11]
replaces... "some": { "array" : [1, 2, 3], }, ...
with
... "some": { "array" : [8, 11], }, ...
Note
You can use whitespaces in the square brackets (
[val0, val1, val2]
) if you escape the whole expression with double quotes to prevent the OS from separating it into several command line arguments:> kit.exe --/some/array="[ 8, 11]"
It is also possible to assign a proper JSON as a parameter value:
> kit.exe --/my/json/param={\"num\":1,\"str\":\"test\",\"arr\":[1,2,3],\"obj\":{\"info\":42}}
results in
...
"my": {
"json" : {
"param" : {
"num": 1,
"str": "test",
"arr": [
1,
2,
3
],
"obj": {
"info": 42
}
}
}
},
...
Passing Command Line arguments to extensions¶
Kit ignores all command line arguments after --
. It also writes those in /app/cmdLineUnprocessedArgs
setting. Extensions can use this setting to access them and process as they wish.