OpenUSDConnect

OpenUSDConnect replicates USD edits between DCCs, USD-native tools, and headless services. The repository includes reference integrations for Blender, usdview, Unreal Engine, MCP, and Python. They all use the same protocol; the core has no dependency on a DCC.

The server orders typed transactions, commits them to SQLite, and broadcasts them to connected clients. A client that joins late or reconnects replays the same log.

Capabilities

• 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

Host integrations only project the USD features their application can represent. Unsupported state remains in the authoritative USD stage or the client's receive mirror.

Get started

You need:

• Git
• Python 3.13 or newer
• uv
• CMake 3.27 or newer
• A 64-bit C++17 toolchain

These match the common build requirements of OpenUSD 0.26.8. MSVC, GCC, and Clang are supported through CMake. The bundled fallback pins usd-core==26.8. Blender and Unreal use the OpenUSD runtime shipped by the host application. Clone with --recursive only if you need the USD Working Group assets used by asset and visual tests.

uv sync builds the native client extension. Make sure the compiler is available in the current shell before running it. On Windows, install the Desktop development with C++ workload from Visual Studio or Build Tools. On macOS, install the Xcode command-line tools. On Linux, install CMake and the compiler toolchain through the system package manager.

Select an OpenUSD build

Use OpenUSD 0.26.8 for the server, usdview, and USD-native clients. Keep the plugin environment consistent across clients that resolve the same scene: MaterialX and custom renderers, resolvers, file formats, and shader definitions depend on it.

git clone https://github.com/RoboticHuman/OpenUSDConnect.git
cd OpenUSDConnect

The managed builder clones and compiles the exact supported OpenUSD commit. Its default profile includes Python bindings and command-line tools:

uv run python scripts/build_openusd.py

After the build, OpenUSDConnect selects the managed installation automatically; no activation step is required. OpenUSD tools can use the same environment:

uv run python scripts/run_with_openusd.py -- usdview scene.usda

The OpenUSD build guide covers the usdview profile, MaterialX, Embree, RenderMan, compiler discovery, build directories, and external OpenUSD installations. Managed build artifacts are platform-specific, so a checkout shared with WSL does not reuse Windows binaries.

Verify synchronization locally

This command starts a temporary server and two USD-native clients, checks both directions of replication, and exits:

uv run python examples/usd_native_client/run.py --no-usdview --seconds 3

A successful run reports local_valid=True and peer_valid=True.

Run a persistent server

uv run openusdconnect-server --base test_scene.usda --port 7200

Use uv run openusdconnect-server --help for all options. Common additions are --departments animation,lighting,fx, --require-token, and --dashboard-port 8080.

Bundled core fallback

The bundled usd-core runtime is suitable for core synchronization, standard USD schemas, and UsdPreviewSurface. It does not include MaterialX or custom renderer, resolver, file-format, or shader plugins.

uv sync --group bundled-usd
uv run python examples/usd_native_client/run.py --no-usdview --seconds 3

Do not add bundled-usd when using the project runtime path above.

Integrations

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 --blender /path/to/blender, or start a connected usdview session with uv run python scripts/start_usdview.py test_scene.usda. For self-contained server, DCC, Python, C++, and container artifacts, see Packaging and distribution.

Run the cross-application Material Zoo

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 unreal

The runner finds the selected applications, starts a temporary server, and streams a shared camera and environment light. Pass any subset of the three viewers. When usdview is selected, add --renderman to launch it with a compatible hdPrman setup. The testing guide documents runtime selection and additional options.

The same synchronized scene in Unreal Engine (left) and usdview with RenderMan (right).

Inspect collaboration in the dashboard

The dashboard shows connected clients, department layers, composed stage data, persisted events, and log maintenance and export controls.

Python client API

Use ManagedClient for a bidirectional 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.

How it works

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"]

Loading

Messages are length-prefixed FlatBuffers frames over TCP. Managed clients reconstruct the authoritative USD state; host adapters project representable changes into the native scene.

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.

Additional workflows

Live-open snapshots

Expose the composed managed scene as a local USD file while updates continue through the sync server:

uv sync --group vfs
uv run python scripts/start_live_open.py --base test_scene.usda --open

Flat 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.

Shared-stage synchronization

uv run openusdconnect-server --base shot.usda --layer-mode shared_stage

Every 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

• Documentation index
• Getting started with Blender
• Building and selecting OpenUSD
• 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

Development

uv sync --group vfs --group dev
uv run pytest tests/unit/ -v
uv run pytest tests/ -v
uv run ruff check

Blender, 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.

Docker

The default TCP server image uses pinned OpenUSD with MaterialX:

docker compose up --build server

For the smaller usd-core runtime, set USD_PROFILE=core in the environment before running Compose. For a standalone image build, use docker build --build-arg USD_PROFILE=core -t openusdconnect-server ..

Acknowledgments

• USD Working Group Assets, used by the integration and visual test suites

Licensed under the Apache License 2.0.