Source repositories

Updated October 2026 · Project admins and artists

Describes how to connect a project to a separate Perforce repository for DCC source art, and how artists sync, publish and submit when a project uses one.

Some studios keep DCC source files (Maya, Blender, 3ds Max, Houdini and Substance files) in a large Perforce repository that the Unreal project doesn’t map, sometimes on a different server. If you bind the Dousen project to that repository, artists sync only the files they work on, and nothing syncs in bulk. If your source files are in the Unreal repository, leave Mode at Same as UE repo, the default.

Set up and test a separate source repository

1. In the web portal, sign in as an Admin, click Projects, select your project, and click Project settings. In the Source Repository section (shown only for Perforce projects), set Mode to Separate repo.
2. Enter Source P4PORT and Source Depot Root. Optionally enter a Stream. Choose FBX Location and Client View Mode. If FBX Location is In the UE repo, also enter UE FBX Root. The settings reference describes each field.
3. Click Update.
4. On one artist workstation, create the source workspace and sign in to the source server.
5. In a DCC, click Set Up Asset to create a test asset. In P4V, check that the file’s folder is mapped in the source workspace and that the file is in the source changelist.
6. Publish the asset. Check that the FBX and its sidecar are where FBX Location says, and that Unreal imported and saved the asset. On a second workstation, try Open in DCC and Reimport (sync source) from the Unreal Content Browser.
7. Review the source and Unreal changelists separately, then submit. If only one submit succeeds, see Changelists and the Jira transition.

Setup works when both workspaces contain the test task’s files, the source file opens in the DCC, and the publish saves an Unreal asset without syncing the whole art depot.

Source repository settings

Set these fields in the Source Repository section of Project settings in the portal, or send a source_repo object in PUT /api/projects/:id. The table lists them in the portal’s order.

A project that never sets these fields uses mode: same. Only an Admin can change them.

Create the source workspace (artist, once)

Each artist creates a second Perforce workspace for the source repository, in an optional section of the Workspace step of the DousenDesktop setup wizard. The wizard can’t read the project’s mode from DousenCore before you sign in, so you enter the second server’s details yourself. After you sign in, the Source Repository group of the Edit Project dialog (Settings → Projects, select the project, click Edit) shows the project’s settings from the portal.

1. In the Workspace step, select Source art lives in a separate repository.
2. Enter P4PORT, DEPOT ROOT, P4 USER and LOCAL ROOT. If CLIENT NAME is empty when you choose LOCAL ROOT with Browse, Desktop fills it in as <P4 USER>_<folder>_src. If you click Re-run Setup on the sign-in screen after you’ve used a separate-mode project in the same Desktop session, P4PORT, DEPOT ROOT and the full-view checkbox start with that project’s values. On first run they’re empty.
3. Optionally, select Sync the entire source depot (not narrow) — classic depots only.
4. Click Create Source Workspace.

Desktop then does the following:

1. Checks your login on the source server (p4 -p <source-port> -u <user> login -s). If you need to sign in, Desktop asks for your password and runs p4 login for that server and user. The password goes through standard input and isn’t saved. Desktop shows a connection or character-set error as it is, without a password prompt. If you cancel, nothing changes. For SSO or MFA, sign in with P4V and try again.
2. Detects streams (p4 streams), as it does for the Unreal workspace. A stream depot gets a Stream: client spec with a full view, and a classic depot gets a classic client spec.
3. Checks the workspace name (p4 clients -e <name>). If the workspace exists, Desktop asks before it overwrites its Root and View. If you click No, nothing changes.
4. Creates the workspace (p4 client -i) with the options noallwrite noclobber, so the p4 sync that runs on dcc.open and on Unreal reimport can’t overwrite local edits that aren’t opened. It syncs no files, so the workspace stays empty until you open or create an asset.

You can sign in to either server at any time with Sign in to Perforce or Sign in to source Perforce in the setup wizard, or with Sign in to source Perforce in the Source Repository group of the Edit Project dialog.

Narrow and full client views

Perforce writes a file to disk only when you sync it. Client View Mode sets what the workspace maps.

• Narrow (default, classic depots only). The View starts with a single placeholder line that maps no real files. When you open or create an asset, Dousen adds a View line for that asset’s folder. If someone runs Get Latest on the workspace root in P4V, nothing is mapped, so nothing downloads.
• Full (required for streams, optional for classic depots). The View maps the whole source depot, and Dousen still syncs file by file on demand. A stream workspace can’t have a custom View, so a stream depot always uses Full, and the setup wizard shows this warning: "This depot is a Perforce stream — its client always maps the full view. Do not run "Get Latest" on this workspace root; only open assets are synced on demand." The same advice applies to a classic workspace with a full view.

FBX location

• source (default) writes the FBX next to the DCC scene. Teammates get the imported .uasset through the Unreal project, so they don’t need the FBX. To reimport, you need the FBX and its .dousen_meta.json sidecar, and Reimport (sync source) in the Unreal Content Browser syncs both.
• ue writes the FBX under UE FBX Root in the Unreal repository, so it syncs with everyone’s normal Unreal workspace sync. Use it if teammates or import tools expect the FBX next to or under the Unreal content.

When Dousen syncs files

DousenDesktop syncs files in three cases:

1. You open a scene in a DCC, with Open in DCC from the task panel or the Unreal Content Browser. Dousen syncs the scene and the files in its sync_manifest, which the DCC collects at export time. If Sync the whole scene folder is on, it syncs the scene’s folder too. In narrow mode, it first widens the View for any unmapped folder.
2. You create a new asset. Dousen maps the new file’s folder before the addon runs p4 add. See New assets.
3. You use Reimport (sync source) in Unreal. Dousen syncs one FBX and its sidecar, and nothing else. See Reimport from Unreal.

New assets

On the New Asset tab of a DCC panel, click Set Up Asset to create a convention-named scene. The addon then:

1. Resolves the scene path under the source workspace from the project’s naming conventions. It maps /Game paths the same way as Unreal import paths.
2. Calls the bridge operation source/ensure-mapped on that path, so the file’s folder is mapped even in narrow mode. p4 add has no effect on an unmapped path. If Desktop is an older build without this operation, or the bridge is unreachable, the addon carries on as if there were nothing to map.
3. Runs p4 add on the file, in the changelist of the workspace that owns the path, so a scene in the source repository goes into the source changelist.

The exported FBX goes where FBX Location says. Desktop passes that location to the DCC in DOUSEN_FBX_ROOT when it launches the DCC.

Changelists and the Jira transition

For each task, a project with a separate source repository opens one changelist in the source repository and one in the Unreal repository. DousenCore tracks each by server, user and workspace. Dousen submits the source changelist first.

The Jira issue moves after the last of a task’s changelists is submitted. Before it moves the issue, DousenCore checks for another pending, non-empty changelist for the same task, project and user. The check locks the rows it reads, so two simultaneous submits can’t both skip the transition.

An artist often changes files in only one repository. p4 submit fails on an empty changelist, and an empty pending one would block the Jira transition, so Desktop checks each changelist for opened files before it submits:

• It deletes an empty changelist in Perforce (p4 change -d) and reports it to Core as abandoned (abandoned: true). Core marks it reverted, so it no longer blocks the transition. Abandoning a changelist doesn’t move the issue by itself.
• It submits only the non-empty changelists, source first.
• If every changelist is empty, it shows "Nothing to submit: every changelist for this task is empty."
• If it can’t look up the source changelist, it cancels the whole submit with "Could not look up the source-repository changelist; nothing was submitted." It never submits only the Unreal half.

Submits to two servers aren’t atomic. If the source submit fails, Dousen doesn’t submit the Unreal changelist. If the Unreal submit fails after the source submit succeeded, the Jira issue doesn’t move until you submit the Unreal changelist again.

Reimport from Unreal

In the Unreal Content Browser, right-click an asset that Dousen imported from a project with a separate source repository and choose Reimport (sync source), followed by the asset name. The entry appears when the asset has Dousen.PublishedDepotPath metadata, which Dousen adds at import time whatever fbx_location is.

The command syncs only the FBX and its .dousen_meta.json sidecar, through the bridge operation source/sync, and then reimports from the synced local path. It doesn’t sync the DCC scene, because the reimport doesn’t need it.

Safeguards

• Local edits aren’t overwritten. Before any on-demand sync, Dousen looks for files that differ from your revision but aren’t opened for edit (p4 diff -se). It refuses to sync them and shows "local file has unsubmitted edits (not checked out); check it out or revert before syncing". A workspace that the wizard’s source step creates uses noallwrite noclobber. The Unreal workspace that the wizard created earlier still uses allwrite clobber, so the diff check is the only protection there.
• Mapping is checked in both view modes. Dousen runs p4 where even in full view mode, and widens the View if the path isn’t mapped. It rejects a depot path that isn’t under the configured depot root. The comparison respects folder boundaries (//a/art doesn’t match //a/artwork) and ignores case on Windows. Edits to one workspace’s client spec run one at a time.
• Credentials. Dousen doesn’t pass the ambient P4PASSWD to a server whose P4PORT differs from the ambient one, so the password can’t reach the source server or override that server’s login ticket.
• Bridge timeouts. The Unreal plugin gives source/sync and source/ensure-mapped a 120-second timeout on their own worker, so a slow sync on a remote server doesn’t hit the 15-second default or block other calls. In a DCC, the mapping check blocks the UI for at most 8 seconds. If it times out, the addon carries on.

Limitations

• Texture dependencies aren’t synced. No addon adds texture files to the sync_manifest. Maya adds referenced scenes, Blender adds linked libraries, and 3ds Max adds XRef scenes. Houdini and the Substance addons add nothing. As a workaround, turn on Sync the whole scene folder, which syncs everything under the scene’s depot folder, including files you don’t need.
• A stale changelist on the other server can defer the Jira transition. DousenCore counts any other pending changelist for the same task and user on the other server, even one left over from an old workspace. While one exists, Core defers the transition. You can move the issue in Jira yourself.
• No tool moves existing assets to a new source repository. If you switch a project from same mode to separate mode after assets exist, those assets keep the source repository role ue, because their files are in the Unreal repository.
• Older DCC addon builds put the scene in the Unreal changelist. Separate mode needs a Desktop and addon build that routes the scene through the source workspace. An older addon checks out and adds the scene in the Unreal workspace.

Troubleshooting

"Source Perforce login check failed for <server> as <user>"

Perforce tickets are per server, so a ticket for the Unreal project’s P4PORT doesn’t sign you in to a different source P4PORT. Sign in to each server separately, with Desktop, p4 login or P4V. The setup wizard and the Sign in to source Perforce button in the Edit Project dialog both report this error.

A new asset’s file doesn’t appear in p4 opened

In narrow mode, a folder where you’ve never opened or created an asset isn’t mapped, and p4 add has no effect on an unmapped path. Dousen normally maps the folder first. If it didn’t, for example because Desktop is an older build or the bridge was unreachable, check the binding in the Source Repository group of the Edit Project dialog (Settings → Projects). You can also widen the View yourself: run p4 client -o, add a View line for the folder, and run p4 client -i.

"Do not run Get Latest on this workspace root"

If you run Get Latest or p4 sync //depot/... on the workspace root, Perforce downloads the entire source depot. This applies to every stream workspace, and to a narrow workspace whose View someone widened to the root by hand. Sync only specific files, or let Dousen sync them on demand.

Reimport (sync source) fails or isn’t in the menu

The entry appears only on an asset with Dousen.PublishedDepotPath metadata, so the asset must have been published from a project with a separate source repository after this feature was released. If the command fails, Unreal shows a notification with the bridge error: an unmapped path, a Perforce login problem, or a missing sidecar. Check the Desktop bridge log, and make sure your tickets for both servers are current.