Perforce workspace setup for Unreal Engine projects

What a Perforce workspace is, and where setup goes wrong

In Perforce, a workspace (also called a client, or client spec) is a record on the server with three important parts:

• The root: the folder on your disk where files are written, for example D:\Projects\MyGame.
• The view: which part of the depot is mapped into that folder. In a classic depot the view is a mapping such as //depot/MyGame/... //my-client/.... In a stream depot the workspace is bound to a stream, and the stream decides the view.
• The have list: the server's record of which revision of every file this workspace holds. Every sync compares against it and downloads only what changed.

Most setup problems come from these three parts drifting apart from what is really on disk:

• Two workspaces on one folder. If an old P4V workspace and a new one both point at the same root, files checked out in one stay writable on disk. Perforce does not overwrite writable files it has not opened, so the other workspace's syncs skip them, each with a Can't clobber writable file line that is easy to miss in a long sync.
• A have list that does not match the disk. Copying a project folder by hand, or restoring it from a backup, puts files on disk that the have list does not know about (or the reverse). Perforce then believes it is up to date when it is not.
• A workspace bound to one machine. A workspace can carry a Host field that only lets it be used from one computer. Using it from another machine fails until the field is cleared.
• The wrong root. Unreal projects are large. A root on a nearly full system drive, or a very deep path, causes failures later during sync or build.

Perforce documents the client spec fields in its reference for p4 client.

How Gameheim sets up a Perforce workspace for you

In Gameheim, the depot layout is defined once per project by a lead, and each team member only chooses where the files go on their own machine. The Gameheim Agent then creates or reuses the workspace on the Perforce server and runs the sync locally.

What the project defines

When a lead or administrator creates a Perforce project, the Perforce section of the project form has three fields:

What each person chooses

Each team member picks how their workspace is created, through Manage Workspace on the P4 Workspace page:

• Use my existing P4V workspace: Gameheim drives the workspace you already have. Nothing is downloaded, your pending changelists and opened files stay where they are, and P4V keeps working on the same workspace. When a compatible workspace exists, this option is marked Recommended.
• Use the Gameheim workspace: a separate workspace that Gameheim manages for you, named GF-<your user>-<project code>. It is created on the server only if it does not exist yet, and your first sync downloads its files from the depot.
• Import sync state from P4V (marked Advanced): keeps both workspaces, and tells the server that your Gameheim workspace already has the same files as your P4V one, without downloading them.

Gameheim checks the requirements for you. It lists only P4V workspaces that point at the same local folder and map the same depot as the project, and it warns you when another workspace already holds files open in the folder you are about to use.

How to set up a Perforce workspace in Gameheim

1. 1

   Create the project with the depot or stream (lead)

   Click the + button in the sidebar, choose Perforce as the version-control system, and fill in Depot path, Stream if your team works in streams, and Server override with your server address. Check the version-control system before clicking Create Project: changing it later goes through a guided transition to Git.

2. 2

   Install the agent and choose your default folder

   Install the Gameheim Agent on the computer where you work (see Install the Gameheim Agent). During setup you choose a default workspace root. Each project goes into a subfolder named after it, unless you give a project its own folder. By default the root is a Perforce folder in your user profile.

   Tip:For Unreal projects, pick a fast drive with plenty of space and a short path such as D:\Projects. Long paths and nearly full drives are common causes of failed syncs and builds.
3. 3

   Save your Perforce credentials

   Open P4 Workspace. If Gameheim has no Perforce password for you on this project, a banner asks you to set one. Click P4 Credentials, enter your P4 Username and P4 Password, press Test Connection, then Save. The password is stored encrypted and used by your agent to sign in to Perforce.

4. 4

   Open Manage Workspace

   If no workspace is selected yet, the page says No workspace selected with a Manage Workspace button. Later you can reach the same dialog from More actions in the workspace bar. The dialog shows your current workspace and asks How do you want to work?

5. 5

   Choose adopt, create or import

   • If you already work in P4V on this project, choose Use my existing P4V workspace, pick it from Your P4V workspaces and click Adopt. If the workspace is locked to a specific machine, Gameheim tells you that adopting it clears that restriction.
   • If you start fresh, choose Use the Gameheim workspace and click Use the Gameheim workspace. If a workspace with that name already exists, it is reused rather than duplicated.
   • Choose Import sync state from P4V only if you want two separate workspaces on the same files. See the section on migrating below.
6. 6

   Run the first sync

   In the Sync Status panel, click Sync to Latest. The preview lists how many files will be downloaded from the depot. Click Run Sync. A new Gameheim workspace downloads the whole project, which can take a long time for a large Unreal project. An adopted workspace downloads only what changed since your last sync in P4V.

7. 7

   Follow progress and confirm the result

   The sync appears in the Agent Operations drawer with a progress bar and a stop button. When it finishes, the stat cards show Have Revision equal to Server Head and Out of Date reads All synced. If the sync reports files it did not update, read the next sections before forcing anything.

How to set up a Perforce workspace by hand

The steps below create and fill a workspace with the p4 command line; P4V does the same through File > New > Workspace and the workspace form. Knowing them helps even if you never type them, because every setup problem traces back to one of these fields.

1. Connect and sign in

p4 set P4PORT=ssl:perforce.studio.com:1666
p4 set P4USER=alice
p4 trust
p4 login

p4 trust is needed once for an ssl: server: check the fingerprint it shows with your Perforce administrator before accepting it. p4 login asks for your password and stores a ticket that expires after the period the server sets.

2. Check which workspaces you already have

p4 clients -u alice
p4 client -o alice-MyGame-old

Look at the Root, Host and View of each one. If a workspace already points at the folder you plan to use, reuse it or delete it rather than creating a second workspace on the same root.

3. Write the client spec

p4 client alice-MyGame opens the form in your editor with defaults filled in. The fields that matter for an Unreal project:

Client:  alice-MyGame
Owner:   alice
Host:
Root:    D:\Projects\MyGame
Options: noallwrite noclobber nocompress unlocked nomodtime normdir
LineEnd: local
View:
	//depot/MyGame/... //alice-MyGame/...

• Root: a short path on a fast drive with plenty of space.
• Host: leave it empty unless the workspace must only ever be used from this machine.
• Options: keep noclobber, so a sync never overwrites a file you edited without checkout.
• View: one line mapping the project folder of the depot to the whole workspace. For a stream depot, create the workspace with p4 client -S //MyGame/main alice-MyGame instead: the stream fills in the view.

Save the form, then make the workspace your current one with p4 set P4CLIENT=alice-MyGame.

4. Reuse files already on disk

If the project is already on disk in the same folder because an older workspace synced it, you do not need to download it again. The @workspace revision specifier means "the revisions that workspace has", and -k updates the have list without transferring files:

p4 -c alice-MyGame sync -k //depot/MyGame/...@alice-MyGame-old

5. Run the first sync and check it

p4 sync -n //depot/MyGame/...
p4 sync -q //depot/MyGame/...
p4 sync -n //depot/MyGame/...
p4 reconcile -n //depot/MyGame/...

The first preview tells you how much will be downloaded. -q keeps the output to warnings and errors, which makes a Can't clobber writable file line easier to spot. If your administrator allows it, --parallel=threads=4 speeds up large syncs. Afterwards, the second preview should report that everything is up to date, and the reconcile preview should list nothing you did not expect.

By hand and in Gameheim

Stream depot or classic depot: what Gameheim supports

Gameheim publishes its Perforce server requirements under Server Requirements on the P4 Workspace page. The depot types are:

A project has one Stream. Every Gameheim workspace created for it is bound to that stream. Gameheim has been validated against Helix Core Server 2023.1 and newer.

Migrating an existing P4V workspace to Gameheim

There are two ways to bring a P4V workspace over, and they suit different situations.

Adopt: one workspace, used from both tools

Adopting is the simplest path. Gameheim uses your existing workspace as it is: no second workspace, no download, and P4V keeps working on it. Gameheim never rewrites the view of an adopted workspace. A workspace cannot be adopted if it has a custom view or belongs to another user; in that case Gameheim suggests importing its state instead.

Import sync state: two workspaces, no download

Import copies the have list of your P4V workspace into your Gameheim workspace. It downloads nothing and changes nothing on disk, and it takes a few seconds even for large workspaces. It only works when both workspaces point at the same local folder and map the same depot. Two options are available:

• Also import pending changelists and opened files: recreates your pending changelists, reopens the files you had checked out, added or deleted, and transfers shelved changelists.
• Separate plugin files into dedicated changelist: moves files inside plugin folders into their own changelist after the import. It requires the option above.

Troubleshooting a first sync that leaves files behind

Perforce decides whether to overwrite a file by its read-only flag, not by its content. A writable file that is not checked out is left alone during a sync, and Perforce reports it only as a Can't clobber writable file line in the sync output. Gameheim looks for these cases and tells you about them:

• Another workspace holds files in this folder. A banner names the other workspaces and how many files they hold. If the workspace is yours, Release checkouts clears the Perforce records without touching your disk; the next sync must then be forced. If it belongs to someone else, you cannot release it yourself without admin rights on the Perforce server, so Gameheim shows the command to ask its owner to run.
• Files modified without checkout. The Local changes (no checkout) panel lists files the next sync would skip. For each one you choose Skip, Open for edit, Open + resolve or Force sync. Writable files that are identical to the depot are realigned automatically.
• Disk and have list out of step. Verify and Repair (under More actions) compares every file on disk with the server record. The scan is read-only. It reports files that are stale, missing, or left over after a teammate deleted them in the depot, and the repair button realigns them with the depot. It is also the first thing to run after importing a workspace, or when a level looks older than your teammates'.
• Untracked leftovers. Clean Untracked in the Sync Status panel finds files on disk that Perforce does not track at all, such as ghost actors the Unreal Editor created in an earlier session. You choose exactly which ones to delete, and they cannot be recovered afterwards.

Changing the workspace folder or credentials later

• Folder. The workspace bar shows Local root with a Change button (or Set if none is configured). Enter the absolute path of a folder that already exists on this machine, or use Browse, then Apply.
• Password. If Perforce stops accepting your saved password, the page shows Workspace data is not up to date and the figures stay at the last successful check. Open P4 Credentials and sign in again.
• Stale view. Refresh Status asks Perforce for the current state of your opened files, changelists, locks and sync status. Reset Cache clears the copy Gameheim keeps on its side; it does not affect anything in Perforce.

Frequently asked questions