Perforce typemap for Unreal Engine: a recommended setup

Why an Unreal Engine project needs a Perforce typemap

Perforce holds every asset and every revision of large Unreal productions, and it decides how to store and open each file from its file type. When a file is added, the server picks that type. Without a typemap it guesses from the content: text or binary, nothing more. For Unreal that guess is not enough, because most of a project is binary content that cannot be merged.

Two artists who open the same .uasset at the same time will both be able to submit, and one of them will lose their work: there is no way to merge two versions of a Blueprint or a map. The fix is the +l modifier (exclusive open). A file typed binary+l can be opened for edit by one person at a time, so the second person is stopped before they start, not after they finish.

The opposite problem shows up with compiled code. Perforce syncs files read-only until you check them out. If the team shares compiled editor binaries or plugin DLLs, a teammate who rebuilds the project can hit linker errors such as LNK1104 because the file on disk is read-only. The +w modifier keeps those files writable on every workspace.

The place to set these rules once, for everybody, is the server typemap: a table of file types and depot path patterns that Perforce applies to every new file. The catch is that it only applies to new files, which is why it pays to set it up on day one.

How Gameheim manages the Perforce typemap

Gameheim gives the project a Typemap page inside P4 Administration. It reads the live typemap of the project's Perforce server through the Gameheim agent, shows it as an editable table (Filetype and Depot path, one row per entry), and writes it back when you save. You do not need to edit a spec form in a terminal.

• Insert Unreal Engine recommended entries adds a curated Unreal preset to the rows you already have. It merges: rows that are already present are not duplicated, and nothing you wrote is removed.
• Every row is checked as you type. A filetype must be a Perforce base type with optional modifiers (for example binary+l), and a path must start with //. Invalid rows are highlighted and Save stays disabled until they are fixed.
• Rows can be reordered with the up and down arrows. Order matters in a typemap: when two lines match the same file, the later line wins.
• Saving asks for a reason and a confirmation that the change affects every future p4 add on the server. When your organization has dual approval turned on, the save waits for a second SUPER user to approve it before it is applied.
• History lists previous revisions of the typemap when the server keeps them.

The typemap belongs to the whole Perforce server, not to one project, so the page is available only to users whose Perforce access on that server is super. The rest of the team still benefits: when someone checks out files with the +l type from the P4 Workspace page, Gameheim tells them that opening those files blocks everyone else until they submit or revert. See Perforce file locking for Unreal assets for the day-to-day side of locking.

How to set up the Unreal typemap in Gameheim

1. 1

   Open P4 Administration

   Go to P4 Workspace and click P4 Administration in the links above the workspace. The link only appears once Gameheim has confirmed your Perforce access level. The page header shows the server and Your access:.

2. 2

   Open the Typemap card

   Click Typemap. The page Server typemap loads the current table from the server. If the table is empty, the page says so and suggests inserting the Unreal Engine preset.

3. 3

   Insert the Unreal Engine preset

   Click Insert Unreal Engine recommended entries. The preset rows are added after your existing ones. Review them: if your studio uses extra extensions (source art such as .fbx or .psd, audio, video), add rows for them with Add row.

   Tip:If a later row of yours matches the same files as a preset row, yours wins because it comes later. Use the arrows to put broad patterns first and specific ones after.
4. 4

   Save with a reason

   Click Save. In Save typemap, write the Reason (required) (the approver reads it), tick I understand this change affects every future p4 add server-wide, and click Submit for approval. The save replaces the whole server typemap with the rows on screen.

   If dual approval is on, an Approval requested dialog confirms that the change is waiting and shows when the request expires. The approver finds it on the Dual approval page under Inbox. You can follow your own requests under My requests.

5. 5

   Retype the files that were already in the depot

   The new typemap applies only to files added from now on. For existing assets, change their type with Perforce itself (see the next section). Gameheim does not retype existing files.

The recommended Unreal Engine typemap

This is the preset that Insert Unreal Engine recommended entries adds, written as it appears in a p4 typemap spec. //....uasset means every file ending in .uasset anywhere on the server.

TypeMap:
    binary+l //....uasset
    binary+l //....umap
    binary+l //....upack
    binary+l //....ubulk
    binary+l //....ufeature
    binary+l //....udic
    binary+l //....ubinary
    binary+Sw //....ushaderbytecode
    binary+Sw //....ushadercache
    binary+S //....psym
    binary+w //....dll
    binary+w //....exe
    binary+w //....pdb
    binary+w //....lib
    binary+w //....so
    binary+w //....dylib
    text //....ini
    text //....uproject
    text //....uplugin
    text //....txt
    text //....csv
    text //....json
    text //....xml
    text //....bat
    text //....py
    text //....sh

Epic publishes its own example in Using Perforce as Source Control. The reasoning is the same: lock what cannot be merged, keep text as text, keep build outputs writable.

How to edit the Perforce typemap from the command line

Without a web tool, the typemap is a spec form you edit as text. The procedure is the same on every server, and it needs a Perforce account with administrative rights.

1. Save the current table first: p4 typemap -o > typemap-backup.txt. Saving the form replaces the whole table, so this file is your way back.
2. Write the form to a file with p4 typemap -o > typemap.txt, or run p4 typemap to open it in the editor set by P4EDITOR.
3. Under TypeMap:, write one rule per line, indented: the file type, a space, the depot path. Quote a path that contains spaces. Put broad patterns first and specific ones after, because a later line wins when two lines match the same file.
4. Load the file with p4 typemap -i < typemap.txt, or save and close the editor. If a line is malformed the server rejects the form and nothing changes.
5. Test with a throwaway file: p4 add it, then run p4 opened on it. The type in parentheses, for example (binary+l), is the one the typemap assigned. Remove the test with p4 revert.

p4 typemap -o > typemap-backup.txt
p4 typemap -o > typemap.txt
# edit typemap.txt, then:
p4 typemap -i < typemap.txt

# check what a new file would get
p4 add Content/Test/T_Check.uasset
p4 opened Content/Test/T_Check.uasset
p4 revert Content/Test/T_Check.uasset

Perforce file type modifiers explained

Modifiers combine: binary+Sw stores only the head revision and keeps the file writable. The full list is in the Perforce reference: file type modifiers.

Why the typemap is not retroactive, and how to retype existing files

Perforce records a file type on each revision. The p4 typemap reference is explicit: the table only affects files added after it is created. A .uasset added last year as plain binary stays binary, without +l, after you save the new typemap. This is the most common reason teams think their typemap "does not work".

1. Find out who has the files open: p4 opened -a //depot/Game/Content/....uasset. Retype only what nobody is working on, and tell the team first.
2. To change the type from the next revision on, open the files with the new type and submit them, for example p4 edit -t binary+l //depot/Game/Content/....uasset, then submit the changelist. Files you already have open can be switched with p4 reopen -t binary+l. On a large content folder this creates a new revision of every file, so submit it one folder at a time.
3. To change the type of revisions already stored, without new revisions, a Perforce administrator can use p4 retype -t binary+l on the path. It changes stored revisions in place, so try it on a small path first.
4. Check the result with p4 fstat -T headType on a few files, or look at the file type in P4V.

p4 opened -a //depot/Game/Content/....uasset
p4 edit -t binary+l //depot/Game/Content/Characters/....uasset
p4 submit -d "Retype character assets to binary+l"
p4 fstat -T headType //depot/Game/Content/Characters/....uasset

Troubleshooting the typemap page

• The Typemap card is missing. It is shown only when your effective Perforce access on the server is super. Your access is the lower of what the Perforce server grants you and the ceiling set for you in Gameheim.
• A row is red. The filetype must start with one of text, binary, symlink, apple, resource, unicode, utf8, utf16, followed by optional modifiers; the path must start with // and contain no spaces. A path segment that is exactly .. is refused; the ... wildcard is fine.
• The save did not apply. If dual approval is on, the change waits for a second SUPER. Check My requests on the Dual approval page; an expired request can be resubmitted.
• Plugin DLLs are still read-only after the save. The typemap only covers new adds. Retype the DLLs already in the depot as described above.
• The history is empty. The dialog explains which server setting has to be on for typemap revisions to be recorded.

The P4 Workspace page can also point you here. When the Plugin Changes panel shows Typemap not configured, the server has no binary+w rows for compiled plugin modules; a SUPER user can click it to stage exactly those rows. See Unreal Engine plugins with Perforce.

Frequently asked questions