Perforce for artists and designers: the daily workflow in plain words
This guide is for artists, level designers, animators and producers who work in an Unreal Engine project stored in Perforce. It explains the handful of ideas you actually need (workspace, sync, check out, changelist, submit), why each one exists, and how to do a full day of work from the Gameheim browser interface. Each section links to a deeper article when you want the details.
Why Perforce feels hard for artists and non-programmers
Perforce is the backbone of large Unreal Engine productions for good reasons. It holds every asset and every revision of a project, including multi-gigabyte levels and textures, at a scale few systems match, and Epic builds its own engine on it. It was designed by engineers for engineers, and its model reflects that: workspaces, depots, changelists, revisions, file types. Those words describe the system precisely. They are also a vocabulary an artist has no reason to learn before being able to save a material.
The friction comes from a few rules of the model that are invisible until they bite:
- Files arrive read-only. After a sync, every file on your disk is read-only until you check it out. Checking out tells the server "I am working on this", and only then does the file become writable.
- Your disk is not the truth, the server is. Perforce keeps a record of which revision of each file you have. If you change a file without telling Perforce (for example by clicking "Make Writable" in Unreal), the server does not know, and your change is not part of anything you submit.
- Binary assets cannot be merged. Two people can edit the same C++ file and let Perforce merge their lines. Nobody can merge two versions of a
.uassetor.umap: one of the two sets of work is lost. That is why studios lock these files so only one person edits each one at a time. - Nothing is shared until you submit. Saving in Unreal writes to your disk. Your teammates see your work only after you submit a changelist to the server.
None of these rules is arbitrary. Each one protects a team of dozens or hundreds of people working on the same files. The problem is that the usual tools present them in the terms of the model, so an artist has to translate every dialog before acting on it.
How Gameheim puts the daily Perforce workflow in the browser
Gameheim gives each project a P4 Workspace page (titled Perforce Workspace) where every daily operation lives: sync, check out, lock, reconcile, shelve and submit. The page describes what is happening in plain terms: how many files you are behind the server, which files you changed without checking out, which files a teammate has locked.
The commands themselves run on your own computer through the Gameheim Agent, a small service you install once. The browser sends a request, the agent runs the Perforce command locally against your studio server, and the result comes back to the page. Your depot contents never pass through the Gameheim cloud: it only sees metadata such as file names, statuses and counts. If the agent is offline, the page says Agent offline and queues your commands until it reconnects.
Perforce terms and where you find them in Gameheim
| Perforce term | What it means | Where it is in Gameheim |
|---|---|---|
| Depot | The server copy of the project, with every revision | Shown as Depot in the bar at the top of the P4 Workspace page |
| Workspace (client) | Your local copy, and the server record of what you have | Local root in the same bar; Manage Workspace to choose or create one |
| Sync | Download the latest revisions from the server | Sync to Latest in the Sync Status panel |
| Check out (p4 edit) | Tell the server you are editing a file; the file becomes writable | Checkout in Workspace Changes, or Checkout Files by Path in Advanced Operations |
| Lock | Stop anyone else from submitting (or, with exclusive checkout, even opening) a file | Lock in Opened Files; the Lock Dashboard for the whole team |
| Changelist | A named group of files you will submit together | Pending Changelists panel, New CL |
| Shelve | Store a copy of your pending work on the server without submitting it | Shelve on a changelist; Shelved in Opened Files |
| Reconcile | Find files you added, changed or deleted without telling Perforce | Workspace Changes panel, Scan Now |
| Submit | Publish a changelist to the server for everyone | Submit on a changelist card |
Gameheim does not replace the Perforce model, and it does not change how your server works. A file checked out in Gameheim is checked out in Perforce. A submit from Gameheim is a normal Perforce submit that shows up in every other tool your studio uses.
How to do a day of Perforce work in Gameheim
This is the loop most artists and designers repeat every day. Each step links to the article that covers it in depth.
- You are a member of the project in Gameheim, with a role that includes the P4 Workspace permissions. The Viewer role is read-only and cannot run Perforce operations.
- The Gameheim Agent is installed and signed in on your computer. See Install the Gameheim Agent.
- Your Perforce user name and password are saved for the project (the P4 Credentials button on the P4 Workspace page).
- A workspace is set up for the project. See Perforce workspace setup for Unreal Engine.
Open the P4 Workspace page and read the status
Choose the project and open P4 Workspace in the sidebar. The cards at the top show Have Revision (the latest changelist you have), Server Head (the latest on the server), Opened Files and Out of Date. If Out of Date says Needs sync, you are behind your team.
Close the Unreal Editor before syncing large changes. The editor keeps assets open, and a file in use cannot be replaced on disk.
Sync to the latest version
In the Sync Status panel, click Sync to Latest. Gameheim first shows a preview of the files that will be downloaded, then Run Sync starts the download. Files you have checked out are protected: if a teammate submitted a newer version of one of them, Perforce marks it for resolve instead of overwriting your work.
Progress appears in the Agent Operations drawer, where you can follow or stop a running operation.
Check out before you edit
Before changing an asset, check it out. When you save an asset that is not checked out, Unreal offers to check it out or to make the file writable. Choosing check out keeps Perforce informed. Making it writable edits the file behind the server, and for a locked asset type it means you are working without the lock that protects your changes.
Assets such as
.uassetand.umapare usually configured for exclusive checkout, so only one person can hold each one. See Perforce file locking for Unreal assets.Let Workspace Changes catch what you did outside Perforce
The Workspace Changes panel lists files you modified without checking out, new files Perforce does not track yet, and files missing from disk. Click Scan Now for a full check, then use Checkout, Add or Mark for Delete on each group, or Track All to handle every relevant change at once. Folders the engine generates, such as
IntermediateandSaved, are left out of the scan or collapsed as noise. See Reconcile offline work.Group your work into a changelist
Files you open go into a changelist. Use New CL in the Pending Changelists panel to create one per piece of work (for example "Forest lighting pass"), and Move to… in Opened Files to move files between changelists. Small, focused changelists are easier for your team to review and to roll back.
Submit with a clear description
Click Submit on the changelist card. Write what you changed in Description, optionally link the tasks you worked on with Link tasks, then Gameheim runs a read-only pre-submit check for files that are out of date, locked by someone else or waiting for a resolve. Confirm with Submit. See Submit and shelve changelists.
Release what you no longer need
A submit or a revert releases your locks. If you locked something you did not end up changing, release it from the My Locks panel or the Lock Dashboard so your teammates can work on it. If you need to stop for the day without submitting, Shelve stores a copy of your work on the server.
How Unreal Engine assets map to Perforce
An Unreal project on disk is a mix of files that belong in the depot and files the engine rebuilds on every machine. Knowing which is which explains most of what you see in the Workspace Changes panel.
| Files | What they are | In Perforce |
|---|---|---|
Content/**/*.uasset | Meshes, materials, textures, Blueprints and every other asset | Tracked. Binary: cannot be merged, usually exclusive checkout |
Content/**/*.umap | Levels | Tracked. Binary, usually exclusive checkout |
Content/__ExternalActors__/, __ExternalObjects__/ | With One File Per Actor, each actor placed in a level is its own small file | Tracked. This is real level content, not generated noise |
Config/, Source/, *.uproject, *.uplugin | Settings, C++ code and project descriptors | Tracked. Text: can be merged |
Intermediate/, Saved/, DerivedDataCache/ | Build files, logs, autosaves and caches | Not tracked. Rebuilt locally |
Binaries/ | Compiled editor and game modules | Depends on your studio. Often excluded when everyone compiles locally |
With One File Per Actor, moving three trees in a level changes three small files instead of the whole .umap. That lets more people work in the same level, but it also means a level edit produces many new or changed files. When you submit level work, check that the __ExternalActors__ files are in the changelist together with the map.
Epic documents the recommended Perforce setup for Unreal, including the file types to lock, in Using Perforce as Source Control for Unreal Engine. Your studio may also configure this in Gameheim; see Perforce typemap for Unreal Engine.
What the Gameheim Agent does on your computer
- Runs each Perforce command you start from the browser (sync, checkout, submit and the rest) on your machine, with your Perforce account.
- Reports the state of your workspace back to the page: opened files, pending changelists, locks and how far behind the server you are.
- Scans your workspace folder for files changed outside Perforce, when you click Scan Now and at the intervals you choose in Reconcile settings.
- Picks up the commands queued while it was offline as soon as it reconnects.
Scans are read-only previews: they list what changed and touch nothing. Operations that change files on disk or in the depot start from a button you press, and the ones that throw away local work, such as a forced sync, ask you to confirm first.
Common Perforce mistakes and how to avoid them
- Editing without checking out. Your change is invisible to Perforce and a later sync can skip or overwrite the file. Run Scan Now and check out what the scan finds.
- Submitting a map without its external actors. Teammates get a level that references actors they do not have. Keep level work in one changelist.
- Holding a lock for days. Nobody else can work on that asset. Gameheim reminds you once a lock has been held for 24 hours.
- Using Force sync to "fix" a problem. A forced sync replaces writable files with the server version, and local edits on them are lost for good. Read the sync preview first.
Frequently asked questions
Do artists need to learn P4V to use Perforce?
No single tool is required. P4V, the Unreal Editor, the command line and Gameheim all talk to the same Perforce server, so a studio can let each person use what suits their work. In Gameheim, an artist syncs, checks out, submits and sees team locks from a browser page, and the work is recorded in Perforce exactly as if it had been done in any other client.
Why are my Unreal files read-only after a Perforce sync?
Perforce writes synced files as read-only on purpose. A file becomes writable when you check it out, which tells the server you are editing it and, for locked file types, reserves it for you. If you make a file writable yourself instead, Perforce does not know about the edit. Check out before editing, or run a reconcile scan afterwards to bring the change back under Perforce.
What is the difference between saving and submitting?
Saving in Unreal writes the asset to your own disk. Submitting sends a changelist to the Perforce server, where it becomes a new revision that the rest of the team receives on their next sync. Until you submit, your work exists only on your machine, or on the server as a shelf if you shelved it.
Can two people edit the same Unreal asset at the same time?
Not safely. A .uasset or .umap is a binary file, so Perforce cannot combine two people's edits and one set of changes would be lost. That is why studios mark these files for exclusive checkout: the first person to check the file out holds it until they submit or revert. With One File Per Actor, several people can still work in the same level on different actors.
Does Gameheim upload my assets to the cloud?
No. The Gameheim Agent runs every Perforce command on your own computer against your studio server, so file contents stay inside your network. The Gameheim cloud receives metadata only, such as file names, statuses, counts and changelist descriptions, which it needs to show the workspace page and the team lock dashboard.