Loading studio tools

Updated October 2026

Describes how to load your studio’s own DCC tools alongside the Dousen addon, with startup scripts for the whole project or launch options for one machine.

Tools you already load, such as menus, shelves, exporters, and render presets, keep working when you launch a DCC from DousenDesktop. Dousen adds its addon to each application’s search paths without replacing them.

Install a startup script for the team

Add the script to your studio’s pipeline repository and submit it. Test it in the DCC version your artists use before you add it to a shared launch.
In the portal, open the project’s Pipeline settings and add the script’s path under app_paths.<dcc>.startup_scripts, using one of the path forms below. Use the DCC’s key, such as maya or blender.
Check that the test workstation can read the script through its source root or Perforce workspace.
Save the document. Close the test DCC and launch it again from DousenDesktop. DousenDesktop reads the script list at launch, so a DCC that is already open doesn’t get the new script.
Check that both your tool and the Dousen panel load. If they don’t, see When a script doesn’t load.
To remove the script, delete its path, save, and relaunch the DCC. Custom validator paths are a separate setting and aren’t affected.

Startup scripts

The app_paths.<dcc>.startup_scripts key in pipeline settings lists Python files for each DCC. Dousen runs them inside the application at every launch, for every artist, so you don’t install anything on individual machines.

YAMLapp_paths:
  maya:
    startup_scripts:
      - //depot/pipeline/maya/studio_menu.py
      - pipeline/maya/shelf_tools.py        # relative to the project source root
  blender:
    startup_scripts:
      - C:\StudioTools\blender\init_presets.py
  houdini:
    startup_scripts:
      - //depot/pipeline/houdini/studio_shelf.py

Startup scripts run like this:

Inside the DCC’s own Python interpreter, so import maya.cmds, import bpy, and import hou work as they do in the application’s script editor.
After Dousen’s addon has initialized, so the bridge, the task context, and the Dousen panels are available.
In list order, from top to bottom.
If a script raises an error, Dousen logs it and runs the next script. The artist isn’t blocked.

Path forms

Form	Example	Notes
Perforce depot	`//depot/pipeline/maya/menu.py`	Resolved through the artist’s workspace mapping (`p4 where`). The file must already be synced. Dousen syncs custom validator paths automatically before each discovery pass, but it doesn’t sync startup script paths.
Relative	`pipeline/maya/menu.py`	Joined to the project’s source root.
Absolute	`C:\StudioTools\maya\menu.py`	For tools in a workstation image or on a network share. Write shares with backslashes (`\\studio-nas\tools\menu.py`), because Dousen reads any path that starts with `//` as a Perforce depot path.

Keep startup scripts and custom validators in Perforce (a //depot/... path). Artists get updates when they sync, and the scripts are versioned with the pipeline.

Python only. Dousen runs each entry as Python source. To run MEL or MAXScript, call it from Python with maya.mel.eval(...) in Maya or pymxs.runtime.execute(...) in 3ds Max.

Environment variables for startup scripts

Dousen sets these variables when it launches the DCC, so your scripts can read the project and task:

Variable	Meaning
`DOUSEN_PROJECT_ID`	The ID (UUID) of the active Dousen project.
`DOUSEN_SOURCE_ROOT`	The project’s source root on this machine.
`DOUSEN_CORE_URL`	The base URL of the Dousen server.
`DOUSEN_TASK_ID` / `DOUSEN_CHANGELIST_ID`	The task and changelist that were active at launch, if the artist had one selected. `DOUSEN_TASK_ID` is Jira’s numeric issue id, not the key such as `DOU-142`.
`DOUSEN_TASK_TITLE`	The title of the task that was active at launch, if the artist had one selected.
`P4PORT` / `P4USER` / `P4CLIENT`	The Perforce server, user and workspace for the project’s source files. If the project uses a separate source repository, these are the source repository’s values (see Source repositories), so a `p4` command in a script targets that server. Dousen sets each variable only when it has a value. Otherwise your machine’s own Perforce settings apply.
`DOUSEN_P4_ROUTES`	A JSON list with one entry for each repository role, `ue` and `source`. Each entry has `role`, `port`, `user`, `client`, `local_root` and `depot_root`. Use it to find the server and workspace for a path when the project has a separate source repository.
`DOUSEN_FBX_ROOT`	The local folder where Dousen writes exported FBX files. It is the project’s source root, unless the project’s FBX location is In the UE repo. Then it is the matching folder in the Unreal workspace.
`DOUSEN_OPEN_FILE`	The file being opened, when the DCC was launched with Open in DCC.
`DOUSEN_BRIDGE_PORT`	The port of the local bridge relay. See Bridge API if your tool needs to publish or subscribe.
`DOUSEN_HOME` / `DOUSEN_PYTHON_PATH`	The DousenDesktop install root and the path of its bundled Python package.
`DOUSEN_ADDONS_PATH`	The folder of the Dousen addon for the DCC you launched, `dousen/addons/<dcc>` inside `DOUSEN_PYTHON_PATH`. Every launch sets it.
`DOUSEN_CREDENTIAL_FILE` / `DOUSEN_CREDENTIAL_ID`	The path of a credential file that DousenDesktop keeps updated with the signed-in artist’s access token, and the ID of that credential. Dousen’s DCC clients read the token from this file for each request, so it stays valid after DousenDesktop refreshes it.
`DOUSEN_TOKEN`	Set only when DousenDesktop has no credential file for the session. It holds a fixed token that isn’t refreshed. A normal signed-in session sets the two credential variables instead.

To call DousenCore’s REST API from a script without asking the artist to sign in again, for example GET /api/projects/:id/settings, read the current token for each request:

PYTHONimport os
from dousen.credentials import credential_state

state = credential_state(os.environ["DOUSEN_CORE_URL"])
headers = {"Authorization": f"Bearer {state.token}"}   # state.token is "" if no valid token is available

PYTHON# //depot/pipeline/maya/studio_menu.py — runs inside Maya's Python
import os
import maya.cmds as cmds

cmds.loadPlugin("studioTools", quiet=True)

task = os.environ.get("DOUSEN_TASK_ID")
if task:
    print(f"[studio] building menu for task {task}")

Existing search paths

If your pipeline sets the DCCs’ standard environment variables, for example from a studio launcher, a machine image, or artist profiles, Dousen keeps your values and adds its addon directory:

DCC	What Dousen changes
Maya	Adds its addon directory to `PYTHONPATH` and `MAYA_SCRIPT_PATH`.
3ds Max	Appends to `ADSK_3DSMAX_STARTUPSCRIPTS_ADDON_DIR`.
Houdini	Appends the addon directory and the `&` marker to `HOUDINI_PATH`, so Houdini’s default paths still load.
Substance Painter	Appends to `SUBSTANCE_PAINTER_PLUGINS_PATH`.
Substance Designer	Appends to `SD_PLUGINS_PATH`.
Blender	No search-path changes. Dousen starts itself with a `--python` argument, so your Blender addon setup is untouched.

Dousen adds its Python package to sys.path after the DCC’s own paths, so it can’t shadow the DCC’s standard library. For Maya and Blender, Dousen also removes an inherited PYTHONHOME so that the DCC uses its own Python.

Per-machine launch arguments and environment variables

For changes that apply to one machine, such as a local sandbox, a farm node, or one artist’s plugin build, open Settings → DCC Apps, select an application, and click Edit. The dialog has two free-form fields:

The DCC Apps tab in DousenDesktop settings. It lists Maya, Blender, Substance Painter, and Unreal Editor with their executable paths. The Add, Edit, and Remove buttons and the Discover DCCs button are below the list. — The **DCC Apps** tab. Select an application and click **Edit** to set its launch arguments and environment variables. The screenshot uses a sample project.

Launch Arguments are extra command-line arguments, one per line. Dousen appends them to the launch.
Environment Variables are key and value pairs (click Add Row to add one) that Dousen sets on the DCC process. If you set a variable that Dousen also sets, your value wins, with these exceptions:
- Dousen always sets DOUSEN_CORE_URL, DOUSEN_TOKEN, DOUSEN_CREDENTIAL_FILE, and DOUSEN_CREDENTIAL_ID itself.
- Dousen sets DOUSEN_STARTUP_SCRIPTS after your variables, so when the project has startup scripts for that DCC, its list replaces yours.
- For Maya and Blender, Dousen always removes PYTHONHOME.
- For the search-path variables above, Dousen adds its directory to your value.

For anything the whole team needs, use startup scripts, so the configuration lives in the project.

Related hooks

Custom validators load from validators.extra_paths. See Asset validation.
Standalone studio tools that run outside a DCC can register on the local relay and exchange events with everything else. See Bridge API.

Keeping the addons up to date

The Dousen addon for every DCC ships inside the DousenDesktop install, at DOUSEN_HOME/python/dousen/addons/<dcc>, so there is no separate package to distribute. A DousenDesktop update installs the app, the bundled Python runtime, every DCC addon, and the Unreal plugin together. See Automatic updates for how updates are checked and verified.

Artists get the new addon code when they accept the update and relaunch a DCC. Updates don’t change your startup scripts or custom validators, because those are set in the project’s pipeline settings on the server.

When a script doesn’t load

Relaunch the DCC from DousenDesktop, because the script list is read at launch.
Look for these messages. DousenDesktop logs Startup script not found when it prepares the launch, and the DCC’s console shows Startup script failed followed by the error when a script raises one.
For depot paths, check that the file is mapped in the artist’s workspace and synced. Dousen logs an unmapped path and skips it.
See Troubleshooting for the general addon checklist.

Previous ← Settings reference Next User and auth management →