How to manage Unreal Engine plugins as a team on Perforce
For Unreal teams on Perforce where plugins get updated, added and removed by different people. You will learn why plugins are the part of an Unreal project that breaks most often on a teammate's machine, what to keep out of the depot, and how Gameheim tracks every plugin in the project and keeps plugin changes in their own changelist.
Why Unreal Engine plugins break team builds
An Unreal plugin is a folder under Plugins/ with a .uplugin descriptor, its source, its content and, often, compiled binaries. The .uproject file lists which plugins are enabled. Updating a plugin touches dozens or hundreds of files at once, and each of those files has to end up in the depot in a consistent state. When it does not, the failure shows up on someone else's machine, usually the morning after.
- Two copies of the same plugin. Someone installs version 2 in a new folder and forgets to delete the old one. Unreal refuses to start the project with an error like
Found '<plugin>' plugin in two locations. - A plugin enabled but not installed. The
.uprojectstill references a plugin that nobody submitted, or that was removed from disk. The project fails to open or fails at build time. - Generated files in the depot.
Intermediate/,Saved/andDerivedDataCache/inside a plugin are rebuilt by the engine. Submitted, they bloat the depot and make every sync slower. - Read-only binaries. Plugin DLLs synced read-only from Perforce block a teammate's rebuild with
LNK1104. - Mixed changelists. A plugin update ends up in the same changelist as unrelated gameplay work, so it cannot be reviewed or rolled back on its own.
- Two people updating the same plugin. Both are right about their version; only one of them can win.
None of this is specific to one version control system. It comes from the plugin model itself: a plugin is many files that only make sense together, and the depot sees them one file at a time.
How Gameheim tracks Unreal Engine plugins in a Perforce project
On an Unreal Engine project the Gameheim agent scans the project's Plugins/ folder and the .uproject, compares what it finds with the depot, and reports the result to the P4 Workspace page. Nothing is changed on disk or in the depot by the scan itself: every change is a step you take.
Which plugins are in the project
Plugin Details opens Plugin management. The Plugins tab lists every plugin with its Version, Status (Active, Disabled in the .uproject, or Missing), Source (Marketplace, Engine, Local or Not installed), how many files it has in the depot, and who holds a lock on it. Each row expands to author, category, modules, file counts split into source and generated, size and last update. Versions the plugin author marked as beta carry a BETA badge.
A changelist just for plugins
When you check out, add or delete files inside a plugin folder through Gameheim, those files go into a dedicated pending changelist whose description starts with [Gameheim] Plugin Updates, not into the changelist you were working on. It is an ordinary Perforce changelist: P4V shows it like any other. On the P4 Workspace page it appears in Plugin Changelists, where you can View, Submit or Delete CL.
Plugin changes, conflicts and suggestions
- Plugin Changes lists, per plugin, the files that are modified, new or missing compared with the depot. Sync opens them in the plugin changelist (check out, add or delete as needed); Sync All does it for every plugin. Scan Now forces a full scan.
- When two folders share the same
.upluginname, the panel shows Multiple versions of the same plugin detected. Resolve conflicts lets you pick the folder to keep; the others are marked for delete in the plugin changelist. - When a plugin still exists in the depot but you removed it from disk (or disabled it in the
.uproject), a chip such as 1 removed from disk opens Delete removed plugins from the depot. A folder is proposed only if it was synced to your workspace and is now gone, so a plugin a teammate just added and you have not synced yet is never proposed. - The Suggestions tab groups findings into Critical, Warnings and Info: a plugin referenced but not installed, a broken plugin dependency, generated files or debug symbols in the depot, plugins made mostly of generated files, large or disabled plugins that still take space.
| Step | By hand | In Gameheim |
|---|---|---|
| Spot a duplicate plugin | Search disk and depot for .uplugin files with the same name | Multiple versions of the same plugin detected, then Resolve conflicts |
| See what changed in a plugin | p4 reconcile -n on the plugin folder | Plugin Changes: modified, new and missing files per plugin |
| Keep the update in its own changelist | p4 change, then p4 reconcile -c <number> | Automatic: plugin files go to the [Gameheim] Plugin Updates changelist |
| Stop two people updating it | Ask around, check p4 opened -a | Lock the plugin with a reason and a duration |
| Remove generated files already submitted | .p4ignore plus p4 delete -k | Optimize on the suggestion does both in the plugin changelist |
How to update an Unreal plugin with Gameheim
- An Unreal Engine project on Perforce in Gameheim, with your workspace set up (Perforce workspace setup for Unreal Engine).
- The Gameheim agent running on your machine.
- The Plugins permission
syncin your role (leads and admins have it). Deleting whole plugin folders from the depot needsdelete. See Roles and permissions.
Lock the plugin while you work on it
Open Plugin Details, find the plugin and click Lock. Add a reason (for example the target version) and a Duration: 1, 4, 8, 24 (default) or 48 hours. While it is locked, other members cannot sync, check out, add, delete or submit files inside that plugin through Gameheim, and they see who holds the lock. The lock expires on its own; release it earlier with Unlock.
Replace the plugin files on disk
Install the new version the way you normally would. Remove the old folder rather than leaving it next to the new one.
Scan and review the changes
In Plugin Changes click Scan Now. Check the counts for the plugin (modified, new, missing). If the panel reports multiple versions of the same plugin, click Resolve conflicts and keep the folder you just installed.
Sync the plugin into its changelist
Click Sync on the plugin row. The files are opened in the plugin changelist, separate from your other work. If only part of them is already open, the button reads Sync rest.
Submit and release the lock
In Plugin Changelists review the changelist and click Submit. Then release the lock so the team can sync the new version. Submit is blocked while someone else holds a lock on a plugin in that changelist.
Which Unreal plugin files belong in Perforce
| Folder or file | Keep in the depot? | Why |
|---|---|---|
<Plugin>.uplugin | Yes | The descriptor Unreal reads to load the plugin. |
Source/ | Yes | The code, when the team builds the plugin. |
Content/ | Yes | Plugin assets, like any other content. |
Resources/, Config/ | Yes | Icons and plugin configuration. |
Binaries/ (.dll, .lib and similar) | Team decision | Needed if not everyone compiles; keep them writable with a binary+w typemap. |
Binaries/ (.pdb, .exp) | Usually no | Debug symbols and linker artifacts are not needed to load or link a module. |
Intermediate/, Saved/, DerivedDataCache/ | No | Generated by the build and the editor. |
A .p4ignore stops these files from being added again. The Add to .p4ignore suggestion appends patterns of this shape, one set per plugin (MyPlugin stands for the plugin folder):
# Generated by the build or the editor: never needs to be in the depot
Plugins/MyPlugin/Intermediate/
Plugins/MyPlugin/Saved/
Plugins/MyPlugin/DerivedDataCache/
# Debug symbols and linker artifacts of plugin binaries
Plugins/MyPlugin/Binaries/**/*.pdb
Plugins/MyPlugin/Binaries/**/*.expTwo things catch people out. First, Perforce reads an ignore file only if the P4IGNORE setting names it: run p4 set P4IGNORE and, if it is empty, p4 set P4IGNORE=.p4ignore. Second, a .p4ignore only prevents future adds. Files already submitted stay until they are deleted, and p4 delete -k removes them from the depot while keeping your local copies, which the editor needs:
p4 set P4IGNORE
p4 delete -k //depot/Game/Plugins/MyPlugin/Intermediate/...
p4 delete -k //depot/Game/Plugins/MyPlugin/Binaries/....pdb
p4 submit -d "Remove generated MyPlugin files from the depot"Updating an Unreal plugin on Perforce by hand
Without extra tooling, a clean plugin update is a reconcile scoped to the plugin folder, into a changelist of its own:
- Check that nobody has the plugin open:
p4 opened -a //depot/Game/Plugins/MyPlugin/.... Tell the team you are updating it. - Create a changelist for the update with
p4 changeand note its number. - Replace the plugin folder on disk with the new version. Delete the old folder rather than installing next to it.
- Preview with
p4 reconcile -non the plugin folder, and check that noIntermediate/orSaved/files are listed. If they are, fix.p4ignorefirst. - Run the reconcile into your changelist, review it with
p4 opened -c <number>, and submit it.
p4 opened -a //depot/Game/Plugins/MyPlugin/...
p4 change # description: Update MyPlugin to 2.1
p4 reconcile -n Plugins/MyPlugin/...
p4 reconcile -c 1234 Plugins/MyPlugin/...
p4 opened -c 1234
p4 submit -c 1234Finding duplicate Unreal plugin folders
The error Found '<plugin>' plugin in two locations means two .uplugin files have the same name. To find them by hand, search both your disk and the depot, because the second copy may exist only in one of them:
Get-ChildItem Plugins -Recurse -Filter *.uplugin |
Group-Object Name | Where-Object Count -gt 1 |
ForEach-Object { $_.Group.FullName }p4 files -e //depot/Game/Plugins/....uplugin-e hides files whose head revision is deleted. Compare the list with your disk: a folder that is in the depot but not on disk will come back on the next sync. Keep one copy, delete the other from disk and from the depot, and submit.
Fixing read-only plugin binaries (LNK1104)
If the server typemap has no binary+w rows for compiled modules, the Plugin Changes panel shows Typemap not configured. A user with Perforce super access can click it to open the typemap page with exactly those rows staged, then save them (with approval if the organization requires it). Binaries already in the depot keep their old type until retyped. The details are in Perforce typemap for Unreal Engine.
How often plugins are scanned
Plugin scans are heavier than a normal reconcile, so they have their own schedule. The settings button in Plugin Changes opens Plugin Reconcile Settings, where Auto plugin reconcile can be OFF (manual only) or every 30 minutes, 1, 2 or 4 hours. The setting is yours, for this project. With OFF, plugins are scanned only when you press Scan Now. For the rest of the workspace, see Perforce reconcile for offline work.
Plugin locks and force unlock
- A plugin lock is a Gameheim lock on the whole plugin folder. It governs actions taken through Gameheim; it is not a Perforce
+lfile lock. - A lead or admin can Force unlock a plugin when the owner is away. The reason the owner gave is shown first, and the previous owner is notified.
- Dismiss on a suggestion hides it for the whole project, so one person's decision is not repeated by everyone.
Frequently asked questions
How do I fix "Found plugin in two locations" in Unreal Engine?
Unreal found two folders with the same .uplugin name, usually an old and a new version of one plugin. Keep one folder, delete the other from disk and from the depot, and submit. In Gameheim the Plugin Changes panel detects the duplicate, including folders that exist only in the depot, and Resolve conflicts marks the unwanted copy for delete.
Should Unreal plugin binaries be in Perforce?
If some team members do not compile C++, they need the plugin binaries from the depot, so keep .dll and .lib files and type them binary+w to avoid read-only rebuild errors. Debug symbols (.pdb) and .exp files are not needed to load a module and are usually left out. Intermediate/ and Saved/ never belong in the depot.
How do I stop two people updating the same plugin at once?
Agree that one person owns each plugin update and make it visible. In Gameheim, lock the plugin before you start: teammates see who holds it and why, and cannot sync, check out or submit files inside it through Gameheim until the lock is released or expires. A lead can force unlock if needed.
Why keep plugin updates in a separate changelist?
A plugin update is a unit: it should be reviewed, submitted and, if needed, backed out on its own. Mixed with gameplay work it becomes hard to tell which change broke the build. Gameheim routes plugin files to a dedicated pending changelist automatically, and it is a normal changelist you can also see in P4V.
What happens if a plugin is enabled in the .uproject but missing?
Unreal cannot load a module it cannot find, so the project fails to open or fails at build time. Either submit the plugin, install it from its source, or remove it from the .uproject. Gameheim lists such plugins as Missing and raises a critical suggestion, but leaves the fix to the team.