Projects

A Project is a folder that is both a Studio Project and an ordinary Python project. What each file is for and what stays local.

A Project is the folder Studio opens. It holds the Scenes, assets, scripts and Plugin dependencies of one piece of work. Each open Project is served by its own background process, so Projects never share state.

A Project is a Python codebase#

Studio creates every new Project as a normal Python project. Its pyproject.toml lists the Plugins the Project uses as dependencies, and the witwin.studio package opens its Scenes, runs its solvers and reads its Results without the editor. The .wtscene files are the source of truth for Scenes: the editor, the Agent and your own scripts are three clients of the same files.

In practice this means:

  • you can review a Scene change in a pull request, because a Scene is text;
  • a script in scripts/ sees exactly what the editor shows;
  • a colleague can clone the repository and run it with uv sync.

Files in a new Project#

<project>/
  .git/
  witwin.toml        # Studio manifest: Project id, name, main scene
  pyproject.toml     # Python identity and dependencies, including Plugins
  README.md          # how to use the Project without Studio
  .gitignore         # ignores .witwin/ and .venv/
  .gitattributes     # *.wtscene text eol=lf
  .witwin/           # local runtime state (hidden, not shared)

New Projects start with a git repository on branch main and one commit, Create project. Studio skips this when git is not installed or the folder is already inside a repository.

Folders appear only when you create content for them:

FolderHolds
scenes/Scene files (*.wtscene, TOML)
assets/Imported meshes, materials, textures and saved volumes
scripts/Scripts you run on demand, for example with witwin run
tests/pytest tests against witwin.studio
src/<package>/Reusable Python code for the Project
plugins/<id>/Plugin source the Project owns, when you author one here
results/Results you explicitly export

What stays local#

.witwin/ holds state that belongs to your machine: Agent Sessions (ai_native.db), the Results history, caches, solver scratch data and the Project's Plugin lock and trust records. It is hidden in the Project panel and ignored by git. Deleting it loses your local Sessions and Result history but not your Scenes or code.

Scenes#

A Scene is the 3D content of a Project: entities with components such as Transform, meshes, materials, sensors and sources. A Project can have several Scenes; witwin.toml names the main one. One Scene can reference another as a sub-scene.

Numeric fields store plain SI values (metres, hertz, seconds, radians). A field can instead be bound to a formula; see Parameters and formulas.

Results#

A Result is an output of a solver run or of the Agent: plots, arrays, images and files. Results are listed in the Results panel and saved under .witwin/results/. Export a Result to keep it in the repository.

Open an existing folder#

Open Project... in the Projects list accepts any folder. A folder with content only gains a witwin.toml; Studio does not add Python files to it until you choose Make Python Project in the Project's menu or in Settings › Project.