Perforce file locking for Unreal assets: exclusive checkout, locks and stale locks
Two artists editing the same Unreal asset at the same time is the most expensive mistake in a Perforce project, because one of them loses their work. This article explains why .uasset and .umap files cannot be merged, the two kinds of Perforce lock that prevent it, and how to see, release and clean up locks across your team with the Gameheim Lock Dashboard.
Why .uasset and .umap files cannot be merged
With text files, such as C++ source or .ini config, Perforce can combine two people's changes. If you edited lines 10 to 20 and a teammate edited lines 80 to 90, a resolve merges both edits into one file. Only when both people change the same lines does someone have to choose by hand.
Unreal assets are different. A .uasset (a mesh, material, texture, Blueprint, animation) or a .umap (a level) is a binary file: a structured blob that only the engine can read. Perforce cannot look inside it and has no way to combine two versions. When two people edit the same asset in parallel, the resolve offers only two choices: keep their version or keep yours. Whichever you pick, the other person's work is gone.
The Unreal Editor can diff some asset types, such as Blueprints, to show what changed between two versions. Combining two sets of edits is still manual work at best, and for most asset types it is not possible at all. The only reliable protection for binary assets is to prevent parallel editing in the first place. That is what locks are for.
Where locking goes wrong in practice
- Editing without checking out. Clicking "Make Writable" in Unreal edits the file without asking the server, so you never get the lock. Someone else can check the same asset out and submit first.
- Forgotten locks. A lock stays until its holder submits or reverts. A teammate on holiday, or a crashed machine, can hold a key level for days.
- Invisible locks. Without a shared view, people find out a file is locked only when their checkout fails, often after they already started working.
How Gameheim tracks Perforce locks for the whole team
Gameheim does not invent its own locking for files: it shows and manages the locks that exist in Perforce. Your agent asks the Perforce server which files in the project depot are locked and by whom, for every user, and Gameheim keeps that list current as agents report back.
- Lock Dashboard. One page for the whole project: Active Locks, Stale Locks, Users Locking, File Types and Your Locks, a searchable list with All, Mine, Stale and Healthy filters, and a Locks by User chart.
- My Locks on the P4 Workspace page, with an Unlock button next to each file you hold.
- Stale lock detection. A lock held for more than 24 hours is marked stale. The sidebar shows a stale count next to Lock Dashboard, and the holder receives one reminder per lock.
- Pre-submit check. Before every submit, Gameheim checks whether any file in the changelist is locked by someone else and blocks the submit until the lock is released, instead of letting the submit fail on the server.
- Warnings when it matters. Gameheim notifies you in the app when a teammate locks a file you already have open, and when a teammate submits from Gameheim a newer revision of a file you still have open.
- Controlled forced release. A teammate's lock can be released only by someone with admin or super rights on the Perforce server, after an explicit acknowledgement. The action is written to the audit log and the holder is notified.
For Unreal plugins, Gameheim also offers a separate plugin lock that reserves a whole plugin folder for a set time. It is described in Unreal Engine plugins in Perforce.
How to lock, find and release file locks in Gameheim
- The Gameheim Agent is installed and connected, and your workspace is set up.
- Your role includes the P4 Workspace checkout permission (
p4_workspace:checkout) to lock and release your own files. - To force the release of a teammate's lock:
adminorsuperaccess in the Perforce protections table. The Gameheim role alone is not enough.
Check out the asset before editing
If your server marks asset types for exclusive checkout (the
+lfile type modifier, usually set through the typemap), checking the file out is what takes the lock. Nobody else can open it for edit until you submit or revert. When you open files by path from Advanced Operations, Gameheim tells you how many of them have the exclusive-lock file type before you confirm.Lock files that are not exclusive by type
For files without
+l, you can still take a lock on files you have open. In the Opened Files panel, select the files and click Lock. This is a Perforcep4 lock: other people can still open the file, but only you can submit it until you release the lock.Check the Lock Dashboard before you start
Open Lock Dashboard in the sidebar and search for the asset or folder you plan to work on. Each row shows the file, who holds the lock and for how long. If the list looks out of date, click Refresh to ask Perforce for the current lock status through your agent.
Release your locks when you are done
Submitting or reverting a file releases its lock. If you locked something and no longer need it, click Unlock next to it in My Locks on the P4 Workspace page, or in the Lock Dashboard (use the Mine filter), and confirm. Your teammates can check it out straight away.
Deal with a stale lock
Filter the Lock Dashboard by Stale to see locks held for more than 24 hours. The first step is always to ask the holder: they may have unsubmitted work on that file. If they hold the lock by mistake, they can release it in one click.
Force the release only when the holder cannot act
If the holder is unreachable (on holiday, left the studio, broken machine) and the file is blocking the team, a user with Perforce admin rights sees Force Unlock on that row. The dialog explains the consequences, requires ticking the acknowledgement, and runs the release from your own agent with your Perforce privileges.
Important:Forcing the release does not move the holder's local changes anywhere. Any unsubmitted edits they have on that file may become impossible to integrate cleanly. Use it only when waiting costs more than that work.
Exclusive checkout (+l) versus p4 lock
Perforce has two locking mechanisms, and they protect against different things.
Exclusive checkout (+l file type) | p4 lock on an opened file | |
|---|---|---|
| Set by | The file type, usually through the server typemap | The user, on a file already opened |
| Blocks others from | Opening the file for edit at all | Submitting the file (they can still open and edit it) |
| Best for | Binary assets: .uasset, .umap, source art | Occasional protection of a text file during a critical change |
| Released by | Submit or revert | Submit, revert or p4 unlock |
For Unreal binary assets, exclusive checkout is the right tool, because a p4 lock still lets a teammate spend hours on an edit they will never be able to submit. Epic recommends a typemap that gives .uasset and .umap the +l modifier; see Perforce typemap for Unreal Engine and Perforce's reference for p4 lock.
How to find and release Perforce locks by hand
Everything Gameheim shows about locks comes from Perforce, so the same answers are available from the command line or P4V. This is the manual procedure, step by step.
Find out who holds a file
p4 opened -a lists every workspace that has a file open, with the user and workspace name. Files locked with p4 lock are marked *locked* at the end of the line. In P4V, the same information is in the file's details, under the list of users who have it open.
p4 opened -a //depot/MyGame/Content/Maps/Level01.umap
p4 opened -a //depot/MyGame/...On a large project the second command returns every open file of every user, which is a long list to read through. It is also a snapshot: by the time you finish reading it, someone may have checked out the file you were looking for.
Decide whether a lock is stale
Perforce does not record when a file was locked, so by hand you judge from the context around the lock. Two commands help:
Clues about a lock that may be forgottenp4 changes -s pending -u alice
p4 client -o alice-wsThe first lists the holder's pending changelists with their dates. In the second, the Access field shows the last time the workspace was used. A workspace nobody has touched for a week that still holds locks on key assets is the one to ask about.
Release a lock
- Your own lock. Submit or revert the file (
p4 submit,p4 revert). For a lock taken withp4 lock,p4 unlock <file>releases it and keeps the file open. - A teammate's lock. Ask them first: they may have unsubmitted work on the file. If they cannot act, a user with
adminorsuperaccess can runp4 unlock -f <file>. - A teammate's exclusive checkout. With the
+lfile type the lock comes from the open itself. Check the result withp4 opened -a <file>after any forced unlock: if the file is still open by the holder, their open has to be reverted in their workspace, and any unsubmitted edit to it is lost.
By hand and in Gameheim
| Step | By hand | In Gameheim |
|---|---|---|
| Who holds this file | p4 opened -a <file> | Search on the Lock Dashboard |
| Every lock in the project | p4 opened -a //depot/MyGame/..., read through the output | One list with All, Mine, Stale and Healthy filters and a Locks by User chart |
| Spot forgotten locks | Compare pending changelist dates and workspace Access times | Marked stale after 24 hours, counted in the sidebar, holder reminded |
| Release your own lock | p4 unlock, p4 submit or p4 revert | Unlock in My Locks or on the dashboard |
| Release a teammate's lock | An admin runs p4 unlock -f | Force Unlock with acknowledgement, audit log entry and a notification to the holder |
| Avoid submitting into a lock | Run p4 opened -a on the files before submitting | The pre-submit check blocks files locked by other users |
Who can release a lock
| Situation | Who | Button |
|---|---|---|
| Your own lock | You, with the checkout permission | Unlock |
| A teammate's lock | Only users with admin or super access on the Perforce server | Force Unlock |
| A teammate's plugin lock | A Lead or Admin in Gameheim | Force unlock in the plugin view |
The Force Unlock button follows the Perforce protections table, not the Gameheim role, because Perforce itself only accepts a release of another user's lock from an admin. A Gameheim Member who is a Perforce super user can force a release; a Gameheim Lead without Perforce admin access cannot.
Lock notifications and reminders
| Event | Who is notified | Setting |
|---|---|---|
| Your lock has been held for 24 hours or more | You, once per lock | Stale locks |
| Someone force-released your lock | You | File locks |
| A teammate locked a file you already have open | You | Always on |
| A teammate submitted from Gameheim a newer revision of a file you have open | You | Always on |
| Two people have the same file open for edit | Both | Always on |
The Stale locks and File locks switches are in Settings, under Notification Preferences, in the Source Control group. The stale reminder resets when the lock is released: if you lock the same file again later, you get a new reminder after another 24 hours.
Troubleshooting Perforce locks
- The pre-submit check says a file is locked by other users. There is no automatic fix: the holder has to submit, revert or release the lock. Contact them, or remove that file from your changelist and submit the rest.
- A lock stays on the dashboard after it was released. The list updates when an agent reports the current lock state. Click Refresh on the Lock Dashboard to ask Perforce directly.
- Checkout fails because the file is already open. The asset has exclusive checkout and someone holds it. Find them on the Lock Dashboard.
- You edited a locked asset type without a lock. If you made the file writable instead of checking it out, you do not hold the lock. Run a scan in Workspace Changes and check the file out; if someone else has it, talk to them before either of you submits.
Frequently asked questions
How do I enable exclusive checkout for .uasset files in Perforce?
Add the +l modifier to the file type of Unreal binary assets in the server typemap, for example binary+l //....uasset and binary+l //....umap. Editing the typemap needs Perforce admin rights. New files pick up the type when they are added; existing files keep their current type until a new revision is submitted with the new one, so studios often re-type existing assets in one changelist.
What is a stale lock in Perforce?
Perforce itself has no notion of a stale lock: a lock lasts until the holder submits, reverts or releases it. A stale lock is a studio convention for a lock held so long that it is probably forgotten. Gameheim marks a lock as stale after 24 hours, shows it in the Lock Dashboard with its own filter, and sends the holder a reminder.
How do I unlock a file that someone else has locked in Perforce?
Ask the holder first, because they may have unsubmitted work. If they cannot act, a user with admin or super access on the Perforce server can force the release. In Gameheim that user sees a Force Unlock button on the Lock Dashboard, confirms an acknowledgement, and the action is audited and the holder is notified.
Does p4 lock stop other people from checking out a file?
No. A p4 lock only stops other users from submitting the file. They can still open it for edit and work on it, and find out at submit time that they cannot publish their change. To stop others from opening a file at all, give its file type the +l modifier, which enforces exclusive checkout.
Can two people work on the same Unreal level at once?
With a single .umap and exclusive checkout, no: one person holds the level at a time. With World Partition and One File Per Actor, each actor is saved as its own file under __ExternalActors__, so several people can edit different actors in the same level. Each of those files is still locked individually.