OpenUSDConnect synchronizes live OpenUSD scene edits across DCC applications, USD-native tools, and headless services. Blender, usdview, Unreal Engine, MCP, and Python clients use the same DCC-independent event protocol.
An authoritative server sequences typed USD transactions, stores them in SQLite, and broadcasts or replays them to connected and late-joining clients.
- Atomic, ordered transactions with durable acknowledgements and reconnect replay
- Transforms, geometry, primvars, cameras, lights, visibility, and animation
- References, payloads, variants, instances, point instancers, relationships, metadata, and exact Sdf field changes
- UsdPreviewSurface and MaterialX values, bindings, NodeGraphs, and connections
- Managed collaboration layers and exact shared-stage layer synchronization
- TOFU authentication, rate limiting, playback leadership, log compaction, dashboard administration, and optional live-open snapshots
Each integration supports the subset its host can author or display. The core protocol preserves broader USD state in an authoritative mirror or stage.
Requirements: Git, Python 3.13+,
uv, and preferably the OpenUSD build used by your
project. Clone with --recursive when you also need the USD Working Group
assets used by asset and visual tests.
Use the same compatible OpenUSD build and plugin environment as the clients in your project. This is the recommended path for MaterialX, custom renderers, resolvers, file formats, and shader definitions.
git clone https://github.com/RoboticHuman/OpenUSDConnect.git
cd OpenUSDConnectActivate the build for the current PowerShell terminal, then install the base
library without the bundled-usd group:
.\scripts\openusd_env.ps1 "C:\path\to\OpenUSDInstall"
uv syncPass -RenderManRoot, -PluginPath, or -DllDir when the project needs them.
For automation or other shells, wrap individual commands instead:
uv run python scripts/run_with_openusd.py --usd-root /path/to/OpenUSD -- \
openusdconnect-server --base test_scene.usdaThe CLI reference
covers plugin paths, native libraries, renderer setup, and verification.
Commands below assume that runtime remains active; wrapper users place the
shown command after --.
This bounded, headless first run starts a temporary server and two USD-native clients, verifies replication, and stops everything automatically:
uv run python examples/usd_native_client/run.py --no-usdview --seconds 3A successful run reports local_valid=True and peer_valid=True.
uv run openusdconnect-server --base test_scene.usda --port 7200Use uv run openusdconnect-server --help for all options. Common additions are
--departments animation,lighting,fx, --require-token, and
--dashboard-port 8080.
Use the bundled usd-core runtime only when you do not need MaterialX or
custom renderer, resolver, file-format, or shader plugins. It provides a
renderer-neutral environment for core synchronization, standard USD schemas,
and UsdPreviewSurface.
uv sync --group bundled-usd
uv run python examples/usd_native_client/run.py --no-usdview --seconds 3Do not add bundled-usd when using the project runtime path above.
| Integration | Direction | Start here |
|---|---|---|
| Blender addon | Bidirectional | Blender guide |
| usdview plugin | Receive | usdview guide |
| Unreal Engine plugin | Bidirectional, currently flat receive | Unreal guide |
| Python / OpenUSD | Bidirectional | USD-native API guide |
| MCP server | Author and inspect | uv run --group mcp python -m integrations.mcp; MCP guide |
| Dashboard | Observe and administer | uv run --group dashboard python scripts/demo_layer_dashboard.py |
Build the Blender add-on with uv run python scripts/build_blender_addon.py, or
start a connected usdview session with
uv run python scripts/start_usdview.py test_scene.usda.
See the same live material scene in Blender, usdview, and Unreal Engine:
# Add --download-blender to install a repo-local portable Blender when needed.
uv run python scripts/run_material_zoo.py --viewers blender usdview unrealThe runner discovers the selected applications, starts a temporary server,
connects each integration, and streams a shared camera and environment light.
Select any subset of the three viewers, and add --renderman for a compatible
RenderMan/OpenUSD installation. The
testing guide
documents runtime selection and additional options.
The same synchronized scene in Unreal Engine (left) and usdview with RenderMan (right).
The dashboard shows connected clients, department layers, composed stage data, persisted events, and log maintenance and export controls.
ManagedClient is the usual bidirectional API for an application that owns a
pxr.Usd.Stage:
from pxr import Usd
from openusdconnect import ClientPhase, ManagedClient
stage = Usd.Stage.Open("scene.usda")
with ManagedClient(stage, app_name="my-editor") as client:
if not client.connect(timeout=5):
raise ConnectionError("OpenUSDConnect server is unavailable")
while application_is_running():
client.update()
if client.status.phase is ClientPhase.READY:
edit_scene(stage)Call update() on the stage-owning thread. Use flush(timeout) at save,
publish, or orderly-shutdown boundaries when acknowledgement matters. Receive-
only tools can use UsdReceiver; send-only tools can use UsdPublisher.
The USD-native API guide covers ownership,
replay, reconnection, recovery, and shared-stage clients.
flowchart LR
A["DCC or USD client"] -- "typed USD transactions" --> S["sync server"]
S --> L[("ordered SQLite event log")]
L -- "broadcast and replay" --> R["other clients"]
S --> D["dashboard and snapshots"]
Messages use length-prefixed FlatBuffers over TCP. Managed clients reconstruct the authoritative USD state and let a host adapter project the subset its native scene represents.
| Mode | Use it for | API |
|---|---|---|
managed (default) |
DCC and service integrations that exchange semantic events through server-owned collaboration layers | ManagedClient, UsdPublisher, UsdReceiver |
shared_stage |
Applications synchronizing an existing root and recursive sublayer graph field-for-field | SharedStageClient |
All participants must resolve equivalent base content and assets. Managed layered clients open the original base stage; generated live-open snapshots are continuation baselines only for integrations that support them. Managed clients keep their transient authoring layer selected while active. Shared-stage clients synchronize in-memory authored layer contents but do not save files. See the integration contract and shared-stage architecture before building a custom integration.
Expose the composed managed scene as a normal-looking local USD file while live updates continue through the sync server:
uv sync --group vfs
uv run python scripts/start_live_open.py --base test_scene.usda --openFlat snapshot continuation requires one unmuted collaboration layer and no department policy. Use the original base scene when layer ordering or muting must be preserved. See Server-provided USD files.
uv run openusdconnect-server --base shot.usda --layer-mode shared_stageEvery participant must begin with an equivalent root and sublayer graph. Native
USD hosts can optionally build the exact Sdf notice bridge with
uv run openusdconnect-build-sdf-notice-bridge.
- Documentation index
- Getting started with Blender
- USD-native API guide
- Client recovery
- Blender addon
- Live material editing
- Server-provided USD files and VFS
- Shared-stage architecture
- MCP server
- Command-line reference
- Testing
- Profiling
uv sync --group vfs --group dev
uv run pytest tests/unit/ -v
uv run pytest tests/ -v
uv run ruff checkBlender, Unreal, asset, RenderMan, and visual tiers are opt-in because they need
external runtimes or assets. Add --group bundled-usd only for a
renderer-neutral test environment that does not need MaterialX or custom
plugins. The testing guide lists every tier.
The included image uses the renderer-neutral usd-core runtime:
docker build -t openusdconnect-server .
docker run -p 7200:7200 -v ./scenes:/scenes \
openusdconnect-server --base /scenes/scene.usda- USD Working Group Assets, used by the integration and visual test suites
Licensed under the Apache License 2.0.