witwin.toml

Reference for the witwin.toml manifest of Projects and Plugins - identity, dependencies, permissions and contributions.

witwin.toml is the Studio manifest. A Project has one at its root; so does every Plugin. Python dependencies live in pyproject.toml; witwin.toml describes what Studio needs to know.

Project manifest#

[project]
id = "00000000-0000-4000-8000-000000000002"
name = "Radar Sim"
format_version = "1.0"
description = "A 77 GHz FMCW radar looking at one box target."
main_scene = "main"
idstringrequired
Stable Project id.
namestringrequired
Display name.
format_versionstring
Manifest format version.
descriptionstring
One-line description.
main_scenestring
Scene id opened by default and used by witwin solve.
template_id / template_versionstring
Set when the Project was created from a template.

Plugin manifest#

Top-level keys:

idstringrequired
Plugin id, for example witwin.radar. Must be unique.
namestringrequired
Display name.
versionstringrequired
Plugin version. A Plugin's setup.py reads its package version from here.
descriptionstring
One-line description.
license / repository / authorstring
Metadata shown on the Plugins page.
dependenciesstring[]
Python requirements. Each must also be in pyproject.toml.
iconstring
A lucide icon name.
enabledbooldefault true
Default enable state.

[engines]#

[engines]
witwin = "^1.0.0"

The Studio plugin API range the Plugin supports.

[permissions]#

[permissions]
tools = ["read", "soft_write", "scene_write", "execute", "file_write"]
frontend = true

What the Plugin uses, shown to the user before they trust it. It is a disclosure, not a sandbox.

[[contributes.tools]]#

[[contributes.tools]]
module = "agent_tools"
register = "register"

A module and the function in it that registers Agent Tools.

[[contributes.solvers]]#

[[contributes.solvers]]
id = "witwin.radar.simulate"
title = "Radar FMCW"
entry = "solver_host.py"
lifecycle = "warm"
idleTimeoutSec = 300
cancelGraceSec = 5
maxParallel = 1
 
[contributes.solvers.runtime]
python = "${project:python}"
 
[contributes.solvers.capabilities]
cancel = true
partials = true
idstringrequired
Solver id used by witwin solve and the Agent.
entrypathrequired
Script that calls witwin.studio.solver.serve.
lifecyclestring
warm keeps the process alive between runs until idleTimeoutSec.
cancelGraceSecint
Seconds a cancelled solve gets to stop before it is killed.
maxParallelint
Concurrent solves per process.
runtime.pythonstring
${project:python} (the Project interpreter), ${backend:python}, or a path. A conda key selects a conda environment instead.
capabilitiestable
cancel, partials (streamed partial results) and query (named queries the viewport can make).

[[contributes.templates]]#

[[contributes.templates]]
id = "radar-sim"
title = "Radar Sim"
description = "A 77 GHz FMCW radar looking at one box target."
icon = "radar"
version = "1.0.0"
dir = "templates/radar-sim"
manifest = "template.manifest.json"
sha256 = "<sha256 of the manifest file>"
preview = "templates/radar-sim.webp"
idstringrequired
Template id. A Studio catalog id (radar-sim, channel-sim, ...) fills that card.
versionstringrequired
Must equal the content manifest's templateVersion.
dirpathrequired
Payload folder, relative to the Plugin root.
manifest / sha256stringrequired
Content manifest file and its pinned sha256.
previewpath
Card image, 1600 x 1000, relative to the Plugin root.

[web] and [contributes.viewport.host]#

[web]
root = "frontend"
 
[contributes.viewport.host]
entry = "viewport.mjs"
sdkVersion = "1.6.0"

Static web assets served for the Plugin, and an ES module that runs in the viewport to draw the Plugin's visualizations.