How to Set Up Perforce Typemap — P4 Typemap
Game development and virtual production studios use game engines to create the unbelievable. But with game engines— like Unreal Engine or Unity — project assets are stored as large binaries. To efficiently collaborate on and manage these assets, version control systems need to treat them differently than other file types.
Most version control companies cannot manage these binary files. But Perforce Helix Core — the version control standard for game and media — is known for being able to manage binary assets and with the speed teams need to move fast. It is important to set up Helix Core to handle binaries correctly. Read this blog to learn how to manage binary assets by creating a Perforce typemap.
What is a Perforce Typemap (P4 Typemap)?
A Perforce typemap tells Helix Core exactly how you want to handle files with specific file extensions or within certain folders. Although Helix Core will attempt to detect file types and store them correctly, a Perforce typemap removes any uncertainty, especially when dealing with modifiers (more on that later).
Looking for Set Up Instructions?
If you are new Helix Core customer, start setting up your depot and stream first.
What to Know — Perforce Typemap
If you are using Helix Core and a game engine, it is critical to your project to set up a typemap BEFORE you start working on files. This is because the typemap will only impact files that are submitted after the typemap created. Once created, your typemap will identify which files to store as binary or text, enable file locking, and more.
There are several specialty filetypes that can be stored in Helix Core. But there are two main types — text and binary.
Note: For international users, review file types for utf-8 and utf-16 information.
Files are stored as text, with revisions as reverse deltas.
Files are stored as binary, with revisions stored as complete files.
File Type Modifiers
Modifiers are what really matters when it comes to your typemap. They allow you to designate different functionality. For example, one of the most important features in Helix Core is exclusive locking. This allows a user to check out a file and prevent other people from overriding their work. It is best practice when working on game engine files to always check it out and lock it. But this feature is not enabled as a default. The modifier is what makes this happen.
We will list a few types of modifiers here, but you can find a more complete list in the documentation. Note: After the filetype you can add flags with a
+ character and then the flags.
Set file to always be writable in workspaces.
For example, certain log files and build files.
Store the file uncompressed on the server.
Set exclusive locking for a file.
Only store the most recent versions of this file. The
These flags are placed immediately after the filetype and can be combined with each other. For example,
binary+FlS4 will store the file as binary, full file (uncompressed), with exclusive locking, and only store the four most recent versions of the file.
You can also specify a flag without a filetype in your typemap. For example,
+w //.../writeable/... will set all files in the
writeable folder to be writable.
The pattern is the depot path of the files that the typemap matches. Patterns start with
// and then contain a path including the depot name, folders, wildcards, and file extensions.
* is a wildcard that matches any number of characters, except slashes.
... is a wildcard that matches any characters through all subdirectories.
For example, set all .obj files inside any folder called “models” to be treated as binary, stored uncompressed, and use exclusive locking. This is a good way to treat 3d models stored in obj format.
Set all .obj files anywhere underneath a folder called “bin” to be treated as binary, always writeable, and only store the latest 3 revisions. When compiling C++ code, linking files are stored in a build directory, also with the .obj extension. They need to stay writeable because users don’t directly check them out.
Git + Different File Types
If you are coming from the world of Git, typemaps are probably a new concept. This is because in Git, you are just storing source code. Some teams do use Git LFS to store large files. You can identify file extensions you want stored separate from Git and then use code to point to the location of the binary asset.
For many teams, this is extremely hard to manage at scale. Even if you only have one project, you must do this for every file and every version. This severely complicates build pipelines, which is why so many teams choose Perforce.
Don’t Ignore P4 Ignore
Another important part of setting up your typemap is to identify what files need to be ignored from version control. These files will not be locked and will be excluded from Helix Core. They will not be picked up when running
Reconcile Offline Work... or
We recommend that all projects have a
.p4ignore file in the root of the project. This should be used to avoid submitting and syncing unnecessary large files (like intermediate build files or baking data), temporary files that change frequently (like log files), and user-specific settings and configuration files. This will let you sync faster, avoid confusion, and avoid accidentally sharing private user data.
Just like with the typemap, p4ignore will only impact files submitted AFTER the ignore file was created. If you added files to the depot before, you would need to manually remove them and reset the file permissions to make them writeable. This is because if certain files are set to read-only, it will cause issues with certain settings and config files that are used by game engines and are specific to each user.
When Something Goes Wrong…
So, you know that to work on game engine assets with Helix core, you need a typemap and an ignore file. But sometimes, things do not go according to plan. Let’s review some common errors.
Unable to Save Files
For example, you are working in Unreal, and you get an error that your Derived Data Cache is not setup correctly. This could happen because you didn’t have your .p4ignore file setup before adding files to the depot, which caused these files to be set to read-only. You will need to remove those files from the depot and then manually enable write permissions on your OS.
Builds are Failing with Permission Errors
If you are trying to build and it says that you do not have permissions, there may be some intermediate files that need the +w modifier on them so the engine can overwrite them when doing a build. You will need to set your typemap and manually change any previously submitted files to always be writeable.
Game Engine or Visual Studio Settings Are Not Saving
If your game engine or Visual Studio settings aren’t being saved, or they are changing to someone else’s, then certain user-specific folders and files are not being ignored. Be sure to check the p4ignore examples and then remove those files from the depot and reset their permissions on your OS.
Not a Helix Core Customer?
Discover why so many customers are using Perforce Helix Core for version control.