Bridge API

Updated October 2026 · Studio developers

Describes the local bridge that connects DousenDesktop, the DCC addons and the Unreal plugin on one workstation, and how a studio tool can register with it, publish events and receive them.

The bridge is an authenticated RPyC service inside DousenDesktop. It listens on 127.0.0.1, port 8766 by default, so only programs on the same machine can reach it. Clients send string-keyed requests and receive events over a long-lived push stream. The bridge doesn’t use HTTP. The dousen.bridge.BridgeClient Python class that ships with Desktop handles both. For data on the studio server, use the DousenCore REST API.

Check the normal workflow first

Before you test your tool, check that a normal publish works on the same workstation. Artists publish from the DCC panels described in Publishing assets.

1. Start Desktop, sign in, and select the project. Launch a supported DCC from Desktop, and start Unreal Editor with the DousenUE plugin enabled.
2. In the Publish history tab, check that the DCC and Unreal appear under Connected apps.
3. Publish one instance from the DCC and wait for Imported and saved in Unreal.
4. Run your tool. After it publishes, check Publish history and the asset in Unreal.

Connect and authenticate

BridgeClient() connects to 127.0.0.1 on the port in DOUSEN_BRIDGE_PORT, or on 8766 if the variable isn’t set. You can pass an address instead, such as rpyc://127.0.0.1:8766 or a loopback host and port. The client raises an error for any other host.

Every request carries a bridge token, which is separate from the DousenCore bearer token. Each time Desktop starts, it generates a new 64-character token and saves it in a bridge.token file that only the current user can read. Desktop deletes the file when the bridge stops.

The client reads the token again for every request, so your tool keeps working after Desktop restarts with a new token, unless you set DOUSEN_BRIDGE_TOKEN. Don’t copy the token into scripts or documentation.

Python client example

This example registers a tool called studio_tool, lists the connected apps, and closes the connection. It needs the dousen package and rpyc 6.0.1. The package that ships with Desktop includes rpyc.

PYTHONfrom dousen.bridge import BridgeClient

with BridgeClient() as bridge:
    if not bridge.register("studio_tool", "Studio Tool"):
        raise RuntimeError("Bridge registration failed")
    apps = bridge.list_apps()
    print([app["app_id"] for app in apps])

HttpBridgeClient is an alias for BridgeClient that keeps old imports working. It uses RPyC too.

Client methods

Receive events

PYTHONfrom dousen.bridge import BridgeClient

bridge = BridgeClient()

def on_event(event):
    # Queue work onto the host application's main thread.
    # Don't call Maya, Blender or Houdini scene APIs from this callback.
    print(event.event_type, event.file_path)

bridge.subscribe_async("studio_tool", "mesh.*", on_event)
if not bridge.wait_until_connected():
    bridge.close()
    raise RuntimeError("Subscription handshake failed")

# Keep bridge alive while your tool is running, and call bridge.close()
# when your tool shuts down.

An empty filter matches every event type. A filter that ends in .*, such as mesh.*, matches every event type with that prefix. Any other filter must match the event type exactly. Desktop doesn’t send an app its own events, and it delivers an event that has a target_app only to that app.

Your callback runs on a background thread. Move scene changes to the DCC’s main thread, and Qt UI changes to the Qt main thread through a queued call.

When your stream connects, BridgeClient first calls your handler with an empty task.context event, if your filter matches it. Desktop then sends the latest task.context, if it has one. The same empty event arrives if the stream drops, reconnects or overflows. Each time, discard the task context you cached, and wait for a new one before you do work that depends on the task.

Event fields

Event types

The relay accepts any event_type. The events below are the ones that DousenDesktop, the DCC addons and the Unreal plugin send and act on. Validation rule IDs such as mesh.poly_count look similar, but they belong to asset validation and are never bridge events.

Export events from DCCs

A DCC addon sends one of these events for each instance you publish, and the Unreal plugin reads it to import the asset. The Desktop install defines these fields in python/dousen/addons/_ue_contract.py.

anim.export is an older name for animation.export. Desktop and the plugin still accept it, but new tools should use animation.export. The metadata fields work as follows:

The material_assignment object

material_assignment assigns catalog materials to mesh slots. It is an alternative to the flat textures and master_material fields, and Unreal checks it first. Each entry in assignments describes one material slot:

JSON"material_assignment": {
  "catalog_version": 1,
  "assignments": [
    {
      "mesh_slot": "CrateBody",
      "material_id": "coated_metal",
      "material_path": "/Game/Materials/M_CoatedMetal",
      "textures": {"BaseColor": "C:/Work/Textures/T_Crate_BaseColor.tga"},
      "scalar_params": {"RoughnessMult": 0.6},
      "vector_params": {"Tint": [1, 0.9, 0.9, 1]}
    }
  ]
}

The catalog is created in Unreal. See Materials and textures.

Tracked and untracked exports

An export event (mesh.export, texture.export or animation.export) is a tracked publish when its metadata contains both event_id and instance_id. A tracked publish appears in Publish history and can be retried. It is marked Imported and saved in Unreal only after Desktop receives a matching import receipt from Unreal. Desktop sends a tracked publish to Unreal itself, either to an open editor or through a headless import, so other subscribers never receive it.

An export event without those two keys is untracked. Desktop sends it to subscribers and registers the source asset, but it creates no history entry, so Desktop can’t offer a retry and never reports whether an import worked. Desktop doesn’t import an untracked event in the background. An open Unreal editor that receives it reimports an existing asset, or offers an Import prompt for a new one.

To make a tracked publish, send these metadata fields:

Set file_path to the exported file, and leave target_app empty. Desktop records the file’s size and modification time, and doesn’t offer a retry if the file changes. The whole metadata_json value must be 16 KiB or smaller.

Desktop keeps only the metadata fields below in the history entry and in the event it sends to Unreal, and drops any others. Maps hold at most 128 entries, and lists at most 256.

The event has no field for the target project. Desktop sends a tracked publish to the Unreal project configured in Desktop, and records the publish as unconfirmed if none is configured. Before it sends the import, Desktop checks that the connected editor has that project open.

If your tool can’t export an instance, send a publish.failed event instead of an export event. Use the event_id, instance_id, bundle_id and publish_identity that the export would have used, and leave file_path empty. With BridgeClient.publish(), pass the event_id as the argument and the other three in metadata. Desktop lists the instance as failed in Publish history.

Events from Unreal

When you save an asset in the editor, the Unreal plugin publishes an event with source_app set to unreal. These events reuse the names of DCC export events, but their metadata is different.

All three events carry the same metadata:

They have no suggested_name, source_file or event_id, so they are never tracked. If you handle mesh.export or texture.export, check whether source_app is unreal to tell the two kinds apart.

dcc.open

dcc.open asks an app to open a file. Desktop and Unreal handle it in two forms.

Houdini, Substance Painter and Substance Designer also subscribe to dcc.open. A running session opens the event’s file_path, or metadata.file_path if you set it. Blender, Maya and 3ds Max don’t handle dcc.open.

task.context

Each time you select a different task in My tasks, Desktop publishes task.context with source_app set to dousen_desktop. Other apps use it to tag their output with the active task without asking Jira. task_id and changelist_id are both top-level event fields and metadata keys. The metadata has these fields:

When you sign out, Desktop publishes an empty context. The DCC addons keep the latest context they receive instead of relying on environment variables set when the DCC started.

import.result

After a tracked publish is imported, Desktop gets an import receipt from Unreal. For an open editor, the receipt is the reply to the import that Desktop sends. For a background import, Desktop reads it from the headless import. Desktop uses the receipt to update the history entry. It accepts the same receipt as an import.result event, and doesn’t forward that event to subscribers. Your tool doesn’t need to send it.

Request operations

Send a request with BridgeClient.request(operation, payload). The bridge accepts the operations in the table below. For registration and publishing, use the client methods. The events operation returns a short diagnostic history. Live events arrive on the stream.

Request payload reference

Besides the statuses in the table above, the bridge returns these:

Once Desktop accepts a source/* request, it reports a Perforce or routing failure as status 200 with "ok": false and an error message. A missing path or depot_path returns 400. A request that takes longer than 15 seconds returns 503, but the sync may still finish. Use these operations with the source-repository workflow.

Read an error response

BridgeClient.request returns the response body for any 2xx status. A successful retry returns status 202, so you can read error_code and dispatch_generation from the return value. For any other status it raises dousen.bridge.BridgeError, a subclass of OSError. Its status and body attributes hold the status and the response body, so an existing except OSError handler still catches it.

PYTHONfrom dousen.bridge import BridgeClient, BridgeError

with BridgeClient() as bridge:
    try:
        reply = bridge.request("retry", {"event_id": event_id})
        print(reply.get("error_code"))
    except BridgeError as error:
        print(error.status, error.body)

Limits and failure handling

• A request or response value can be up to 4 MiB of JSON. BridgeClient raises ValueError for a larger request before it sends it. The bridge allows only the operations on this page and the event stream. It doesn’t allow pickle, remote attribute access or remote execution.
• At most 64 apps can be registered, and registrations expire after 90 seconds.
• Each subscriber has a mailbox limited by the number of events and their total size. If it overflows, the subscriber receives a gap marker, which BridgeClient turns into an empty task.context.
• Each stream has a session ID and a sequence number. BridgeClient uses them to skip events it already received.
• A request is sent once. If the response is lost, the result is unknown, and the client doesn’t send the request again.

A True result from publish means that Desktop accepted the event. It doesn’t mean that Unreal imported the asset. After a timeout or a False result, Desktop may still have accepted the event, so don’t publish again automatically. Check Publish history and the destination in Unreal first. See Recover from a failed publish.

If Desktop restarts, it generates a new bridge token and closes the stream. Your subscription reconnects with the new token. Discard any task context you cached.

Source files

The Desktop install includes the Python client, python/dousen/bridge.py, and its RPyC transport, python/dousen/rpc.py. To start a tool with a DCC, see Loading studio tools.